PORTSNAP(8)						    BSD System Manager's Manual 					       PORTSNAP(8)

NAME

     portsnap -- fetch and extract compressed snapshots of the ports tree

SYNOPSIS

     portsnap [-I] [-d workdir] [-f conffile] [-k KEY] [-l descfile] [-p portsdir] [-s server] command ... [path]

DESCRIPTION

     The portsnap tool is used to fetch and update compressed snapshots of the FreeBSD ports tree, and extract and update an uncompressed ports
     tree.

     In a normal update operation, portsnap will routinely restore modified files to their unmodified state and delete unrecognized local files.

OPTIONS

     The following options are supported:

     -d workdir   Store working files (e.g. downloaded updates) in workdir.  (default: /var/db/portsnap, or as given in the configuration file.)

     -f conffile  Read the configuration from conffile.  (default: /etc/portsnap.conf)

     -I 	  For the update command, update INDEX files, but not the rest of the ports tree.

     -k KEY	  Expect a public key with given SHA256 hash.  (default: read value from configuration file.)

     -l descfile  Merge the specified local describes file into the INDEX files being built.  The descfile should be generated by running make
		  describe in each of the local port directories.

     -p portsdir  When extracting or updating an uncompressed snapshot, operate on the directory portsdir.  (default: /usr/ports/, or as given in
		  the configuration file.)

     -s server	  Fetch files from the specified server or server pool.  (default: portsnap.FreeBSD.org, or as given in the configuration file.)

     path	  For extract command only, operate only on parts of the ports tree starting with path.  (e.g. portsnap extract sysutils/port
		  would extract sysutils/portsman, sysutils/portsnap, sysutils/portupgrade, etc.)

     --interactive
		  override auto-detection of calling process.  Only use this when calling portsnap from an interactive, non-terminal application.
		  (Cron jobs are particularly bad since they cause load spikes on the Portsnap mirrors.)

COMMANDS

     The command can be any one of the following:

     fetch	  Fetch a compressed snapshot of the ports tree, or update the existing snapshot.  This command should only be used interactively;
		  for non-interactive use, you should use the cron command.

     cron	  Sleep a random amount of time between 1 and 3600 seconds, then operate as if the fetch command was specified.  As the name sug-
		  gests, this command is designed for running from cron(8); the random delay serves to minimize the probability that a large num-
		  ber of machines will simultaneously attempt to fetch updates.

     extract	  Extract a ports tree, replacing existing files and directories.  NOTE: This will remove anything occupying the location where
		  files or directories are being extracted; in particular, any changes made locally to the ports tree (for example, adding new
		  patches) will be silently obliterated.

		  Only run this command to initialize your portsnap-maintained ports tree for the first time, if you wish to start over with a
		  clean, completely unmodified tree, or if you wish to extract a specific part of the tree (using the path option).

     update	  Update a ports tree extracted using the extract command.  You must run this command to apply changes to your ports tree after
		  downloading updates via the fetch or cron commands.  Again, note that in the parts of the ports tree which are being updated,
		  any local changes or additions will be removed.

     auto	  Run fetch or cron depending on whether stdin is a terminal; then run update or extract depending on whether portsdir exists.

TIPS

     o	 If your clock is set to local time, adding the line

	       0 3 * * * root /usr/sbin/portsnap cron

	 to /etc/crontab is a good way to make sure you always have an up-to-date snapshot of the ports tree available which can quickly be
	 extracted into /usr/ports.  If your clock is set to UTC, please pick a random time other than 3AM, to avoid overly imposing an uneven
	 load on the server(s) hosting the snapshots.

	 Note that running portsnap cron or portsnap fetch does not apply the changes that were received: they only download them.  To apply the
	 changes, you must follow these commands with portsnap update.	The portsnap update command is normally run by hand at a time when you are
	 sure that no one is manually working in the ports tree.

     o	 Running portsnap update from cron(8) is a bad idea -- if you are ever installing or updating a port at the time the cron job runs, you
	 will probably end up in a mess when portsnap updates or removes files which are being used by the port build.	However, running portsnap
	 -I update is probably safe, and can be used together with portversion(1) to identify installed software which is out of date.

     o	 If you wish to use portsnap to keep a large number of machines up to date, you may wish to set up a caching HTTP proxy.  Since portsnap
	 uses fetch(1) to download updates, setting the HTTP_PROXY environment variable will direct it to fetch updates from the given proxy.
	 This is much more efficient than mirroring the files on the portsnap server, since the vast majority of files are not needed by any par-
	 ticular client.

PRIVACY NOTICE

     As an unavoidable part of its operation, a machine running portsnap will make its public IP address and the list of files it fetches avail-
     able to the server from which it fetches updates.	Using these it may be possible to recognize a machine over an extended period of time,
     determine when it is updated, and identify which portions of the FreeBSD ports tree, if any, are being ignored using "REFUSE" directives in
     portsnap.conf.  In addition, the FreeBSD release level is transmitted to the server.

     Statistical data generated from information collected in this manner may be published, but only in aggregate and after anonymizing the indi-
     vidual systems.

FILES

     /etc/portsnap.conf  Default location of the portsnap configuration file.

     /var/db/portsnap	 Default location where compressed snapshots are stored.

     /usr/ports 	 Default location where the ports tree is extracted.

SEE ALSO

     fetch(1), sha256(1), fetch(3), portsnap.conf(5)

AUTHORS

     Colin Percival <cperciva@FreeBSD.org>

FreeBSD 							 October 22, 2013							   FreeBSD