Portsnap is a system for securely distributing the FreeBSD
ports tree. Approximately once an hour, a “snapshot” of the ports tree is
generated, repackaged, and cryptographically signed. The resulting files are then
distributed via HTTP.
Like CVSup, Portsnap uses a
pull model of updating: The
packaged and signed ports trees are placed on a web server which waits passively for
clients to request files. Users must either run portsnap(8) manually
to download updates or set up a cron(8) job to
download updates automatically on a regular basis.
For technical reasons, Portsnap does not update the
“live” ports tree in /usr/ports/ directly; instead,
it works via a compressed copy of the ports tree stored in /var/db/portsnap/ by default. This compressed copy is then used to
update the live ports tree.
Note: If Portsnap is installed from the FreeBSD
Ports Collection, then the default location for its compressed snapshot will be /usr/local/portsnap/ instead of /var/db/portsnap/.
On FreeBSD 6.0 and more recent versions, Portsnap is
contained in the FreeBSD base system. On older versions of FreeBSD, it can be installed
using the ports-mgmt/portsnap port.
Portsnap's operation is controlled by the /etc/portsnap.conf configuration file. For most users, the default
configuration file will suffice; for more details, consult the portsnap.conf(5)
manual page.
Note: If Portsnap is installed from the FreeBSD
Ports Collection, it will use the configuration file /usr/local/etc/portsnap.conf instead of /etc/portsnap.conf. This configuration file is not created when the
port is installed, but a sample configuration file is distributed; to copy it into place,
run the following command:
# cd /usr/local/etc && cp portsnap.conf.sample portsnap.conf
The first time portsnap(8) is run, it
will need to download a compressed snapshot of the entire ports tree into /var/db/portsnap/ (or /usr/local/portsnap/ if Portsnap was
installed from the Ports Collection). For the beginning of 2006 this is approximately a
41 MB download.
# portsnap fetch
Once the compressed snapshot has been downloaded, a “live” copy of the
ports tree can be extracted into /usr/ports/. This is necessary
even if a ports tree has already been created in that directory (e.g., by using CVSup), since it establishes a baseline from which portsnap can determine which parts of the ports tree need to be
updated later.
# portsnap extract
Note: In the default installation /usr/ports is not
created. If you run FreeBSD 6.0-RELEASE, it should be created before portsnap is used. On more recent versions of FreeBSD or Portsnap, this operation will be done automatically at first use
of the portsnap command.
After an initial compressed snapshot of the ports tree has been downloaded and
extracted into /usr/ports/, updating the ports tree consists of
two steps: fetching updates to the
compressed snapshot, and using them to update the live ports tree. These two steps can be specified
to portsnap as a single command:
# portsnap fetch update
Note: Some older versions of portsnap do not support
this syntax; if it fails, try instead the following:
# portsnap fetch
# portsnap update
In order to avoid problems with “flash crowds” accessing the Portsnap servers, portsnap fetch will
not run from a cron(8) job. Instead,
a special portsnap cron command exists, which waits for a random
duration up to 3600 seconds before fetching updates.
In addition, it is strongly recommended that portsnap update
not be run from a cron job, since it is liable to cause major
problems if it happens to run at the same time as a port is being built or installed.
However, it is safe to update the ports' INDEX files, and this
can be done by passing the -I flag to portsnap. (Obviously, if portsnap -I update
is run from cron, then it will be necessary to run portsnap update without the -I flag at a
later time in order to update the rest of the tree.)
Adding the following line to /etc/crontab will cause portsnap to update its compressed snapshot and the INDEX files in /usr/ports/, and will send
an email if any installed ports are out of date:
0 3 * * * root portsnap -I cron update && pkg_version -vIL=
Note: If the system clock is not set to the local time zone, please replace 3 with a random value between 0 and 23, in order to spread the load
on the Portsnap servers more evenly.
Note: Some older versions of portsnap do not support
listing multiple commands (e.g., cron update) in the same
invocation of portsnap. If the line above fails, try replacing
portsnap -I cron update with portsnap cron
&& portsnap -I update.
