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

FreeBSD Manual Pages


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

     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.	 (de-
		  fault:, or as given in the configura-
		  tion 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.)

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

     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 ex-
		  ample, 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.

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

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

	 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	pkg-version(8)
	 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 the snapshots and create the	ports(7) tree under /usr/ports:
	   portsnap fetch extract

     Update the	ports tree:
	   portsnap fetch update

     fetch(1), sha256(1), fetch(3), portsnap.conf(5), pkg(7), pkg-version(8)

     Colin Percival <>

FreeBSD				 July 1, 2018			       FreeBSD


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

home | help