PORTSNAP(8) FreeBSD System Manager's Manual PORTSNAP(8)
NAME
portsnap - fetch and extract compressed snapshots of the ports tree
SYNOPSIS
portsnap [-I] [-d workdir] [-f conffile] [-k KEY] [-l descfile]
[-p portsdir] [-s server] command ... [path]
DESCRIPTION
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.
OPTIONS
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
file.)
-f conffile Read the configuration from conffile. (default:
/etc/portsnap.conf)
-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
running make describe in each of the local port directories.
-p portsdir When extracting or updating an uncompressed snapshot,
operate 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.
(default: portsnap.FreeBSD.org, or as given in the
configuration 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,
sysutils/portsnap, sysutils/portupgrade, etc.)
--interactive
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.)
COMMANDS
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
interactively; for non-interactive use, you should use the
cron command.
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
directories. NOTE: This will remove anything occupying the
location where files or directories are being extracted; in
particular, any changes made locally to the ports tree (for
example, 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
commands. 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
exists.
TIPS
• 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
extracted 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.
• 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.
• 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
particular client.
PRIVACY NOTICE
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
systems.
FILES
/etc/portsnap.conf Default location of the portsnap configuration file.
/var/db/portsnap Default location where compressed snapshots are
stored.
/usr/ports Default location where the ports tree is extracted.
EXAMPLES
Fetch the snapshots and create the ports(7) tree under /usr/ports:
portsnap fetch extract
Update the ports tree:
portsnap fetch update
SEE ALSO
fetch(1), sha256(1), fetch(3), portsnap.conf(5), pkg(7), pkg-version(8)
AUTHORS
Colin Percival <cperciva@FreeBSD.org>
FreeBSD July 1, 2018 FreeBSD
man2web Home...