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.
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 sysutils/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.
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
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
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=
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.
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
.
All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.