path: root/usr.sbin/portsnap/portsnap/portsnap.8

.\"-
.\" Copyright 2004-2005 Colin Percival
.\" All rights reserved
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted providing that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd September 15, 2008
.Dt PORTSNAP 8
.Os FreeBSD
.Sh NAME
.Nm portsnap
.Nd fetch and extract compressed snapshots of the ports tree
.Sh SYNOPSIS
.Nm
.Op Fl I
.Op Fl d Ar workdir
.Op Fl f Ar conffile
.Op Fl k Ar KEY
.Op Fl l Ar descfile
.Op Fl p Ar portsdir
.Op Fl s Ar server
.Cm command ...
.Op Ar path
.Sh DESCRIPTION
The
.Nm
tool is used to fetch and update compressed snapshots
of the
.Fx
ports tree, and extract and update an
uncompressed ports tree.
.Pp
In a normal update operation,
.Nm
will routinely restore modified files to their unmodified state and
delete unrecognized local files.
This behavior is different to
.Xr cvs 1
and
.Xr cvsup 1 .
.Sh OPTIONS
The following options are supported:
.Bl -tag -width "-f conffile"
.It Fl d Ar workdir
Store working files (e.g.\& downloaded updates) in
.Ar workdir .
(default:
.Pa /var/db/portsnap ,
or as given in the configuration file.)
.It Fl f Ar conffile
Read the configuration from
.Ar conffile .
(default:
.Pa /etc/portsnap.conf )
.It Fl I
For the
.Cm update
command, update INDEX files, but not the rest of the ports tree.
.It Fl k Ar KEY
Expect a public key with given SHA256 hash.
(default: read value from configuration file.)
.It Fl l Ar descfile
Merge the specified local describes file into the INDEX files being
built.
The
.Ar descfile
should be generated by running
.Cm make describe
in each of the local port directories.
.It Fl p Ar portsdir
When extracting or updating an uncompressed snapshot,
operate on the directory
.Ar portsdir .
(default:
.Pa /usr/ports/ ,
or as given in the configuration file.)
.It Fl s Ar server
Fetch files from the specified server or server pool.
(default: portsnap.FreeBSD.org, or as given in the
configuration file.)
.It path
For
.Cm extract
command only, operate only on parts of the ports tree starting with
.Ar path .
(e.g.\&
.Nm
.Cm extract
.Ar sysutils/port
would extract sysutils/portsman, sysutils/portsnap,
sysutils/portupgrade, etc.)
.El
.Sh COMMANDS
The
.Cm command
can be any one of the following:
.Pp
.Bl -tag -width "-f conffile"
.It 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
.Cm cron
command.
.It cron
Sleep a random amount of time between 1 and 3600 seconds,
then operate as if the
.Cm fetch
command was specified.
As the name suggests, this command is designed for running
from
.Xr cron 8 ;
the random delay serves to minimize the probability that
a large number of machines will simultaneously attempt to
fetch updates.
.It 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.
.Pp
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
.Ar path
option).
.It update
Update a ports tree extracted using the
.Cm extract
command.
You must run this command to apply changes to your ports tree
after downloading updates via the
.Cm fetch
or
.Cm cron
commands.
Again, note that in the parts of the ports tree which are being
updated, any local changes or additions will be removed.
.El
.Sh TIPS
.Bl -bullet
.It
If your clock is set to local time, adding the line
.Pp
.Dl 0 3 * * * root /usr/sbin/portsnap cron
.Pp
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
.Pa /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.
.It
Running
.Nm
.Cm update
from
.Xr 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
.Nm
updates or removes files which are being used by the port
build.
However, running
.Nm
.Fl I
.Cm update
is probably safe, and can be used together with
.Xr portversion 1
to identify installed software which is out of date.
.It
If you wish to use
.Nm
to keep a large number of machines up to date, you may wish
to set up a caching HTTP proxy.
Since
.Nm
uses
.Xr fetch 1
to download updates, setting the
.Ev HTTP_PROXY
environment variable will direct it to fetch updates from
the given proxy.
This is much more efficient than
.Em mirroring
the files on the portsnap server, since the vast majority
of files are not needed by any particular client.
.El
.Sh PRIVACY NOTICE
As an unavoidable part of its operation, a machine running
.Nm
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
.Pa portsnap.conf .
In addition, the FreeBSD release level is transmitted to the server.
.Pp
Statistical data generated from information collected in this manner
may be published, but only in aggregate and after anonymizing the
individual systems.
.Sh FILES
.Bl -tag -width "/etc/portsnap.conf"
.It /etc/portsnap.conf
Default location of the portsnap configuration file.
.It /var/db/portsnap
Default location where compressed snapshots are stored.
.It /usr/ports
Default location where the ports tree is extracted.
.El
.Sh SEE ALSO
.Xr fetch 1 ,
.Xr sha256 1 ,
.Xr fetch 3 ,
.Xr portsnap.conf 5
.Sh AUTHORS
.An Colin Percival Aq cperciva@FreeBSD.org