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] [-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.  This
     behavior is different to cvs(1) and cvsup(1).

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.  (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 extract sysutils/port
		  would   extract  sysutils/portsman,  sysutils/portsnap,  sysu-
		  tils/portupgrade, 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  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 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), sha256(1), fetch(3), portsnap.conf(5)

AUTHORS
     Colin Percival <cperciva@FreeBSD.org>

FreeBSD 		       September 15, 2008		     PORTSNAP(8)
home | help