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.

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

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.

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

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

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.

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

Note: Some older versions of portsnap do not support this syntax; if it fails, try instead the following:

# portsnap fetch
# portsnap 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=

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.


若有 FreeBSD 方面疑問,請先閱讀 FreeBSD 相關文件,如不能解決的話,再洽詢 <questions@FreeBSD.org>。
關於本文件的問題,請洽詢 <doc@FreeBSD.org>。