home | help 
PORTSNAP(8)		     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] [-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.

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   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.)

     -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.   (de-
		  fault: 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 sysutils/port  would
		  extract sysutils/portsman, sysutils/portsnap, sysutils/portup-
		  grade, etc.)

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	interac-
		  tively;  for non-interactive use, you should use the cron com-
		  mand.

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

     extract	  Extract a ports tree, replacing existing  files  and	directo-
		  ries.   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  af-
		  ter  downloading  updates  via  the  fetch  or  cron commands.
		  Again, note that in the parts of the ports tree which are  be-
		  ing updated, any local changes or additions will be removed.

TIPS
     *	 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  ex-
	 tracted  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.

     *	 Running  portsnap  update  from cron(8) is a bad idea -- if you're ever
	 installing or updating a port at the time the	cron  job  runs,  you'll
	 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 iden-
	 tify installed software which is out of date.

     *	 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  vari-
	 able  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 particular
	 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 available 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 individual sys-
     tems.

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) fetch(3) portsnap.conf(5) sha256(8)

AUTHORS
     Colin Percival <cperciva@FreeBSD.org>

FreeBSD 			 August 13, 2005		     PORTSNAP(8)
home | help