A.6 Using Portsnap

A.6.1 Introduction

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.

A.6.2 Installation

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.

A.6.3 Portsnap Configuration

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.

A.6.4 Running Portsnap for the First Time

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

A.6.5 Updating the Ports Tree

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

A.6.6 Running Portsnap from cron

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=