Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
PORTSNAP(8)		FreeBSD	System Manager's Manual		   PORTSNAP(8)

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

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

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

     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

     -f	conffile  Read the configuration from conffile.	 (default:

     -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 run-
		  ning make describe in	each of	the local port directories.

     -p	portsdir  When extracting or updating an uncompressed snapshot,	oper-
		  ate 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:, or as	given in the configu-
		  ration 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, sysu-
		  tils/portsnap, sysutils/portupgrade, etc.)

     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 inter-
		  actively; for	non-interactive	use, you should	use the	cron

     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 loca-
		  tion where files or directories are being extracted; in par-
		  ticular, 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 com-
		  mands.  Again, note that in the parts	of the ports tree
		  which	are being updated, any local changes or	additions will
		  be removed.

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

     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

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

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

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

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

     Colin Percival <>

FreeBSD			      September	28, 2012		       FreeBSD


Want to link to this manual page? Use this URL:

home | help