.Dd Dec 1, 2003
.Dt FREEBSD-UPDATE 8
.Os FreeBSD
.Sh NAME
.Nm freebsd-update
.Nd fetch and install binary security updates to FreeBSD
.Sh SYNOPSIS
.Nm
.Op Fl qv
.Op Fl b Ar basedir
.Op Fl -branch Ar branchname
.Op Fl d Ar workdir
.Op Fl f Ar conffile
.Op Fl k Ar KEY
.Cm command
.Op Ar URL
.Sh DESCRIPTION
The
.Nm
tool is used to fetch, install, and rollback
binary security updates to the FreeBSD base system, 
and to compare the system against a list of files
installed by a binary install.
.Sh OPTIONS
The following options are supported:
.Bl -tag -width "--branch branchname"
.It Fl b Ar basedir
Act on a FreeBSD world based at the directory
.Ar basedir .
This is suitable for updating jails, but note
that the usual rules about updating locally
modified (or compiled) files apply, and the
jail must belong to the same release version
as the running kernel.
.It Fl -branch Ar branchname
Force updated files to be downloaded from the
specified distribution branch, even if the MD5 hashes of
files on disk do not match the MD5 hashes of
official -RELEASE files.  This is useful if you
have recompiled the system locally.  At present,
the distribution branches are "nocrypto" (no
cryptographic files), "crypto" (cryptographic
files, but not Kerberos), "krb4" (Kerberos 4),
and "krb5" (Kerberos 5).
.Pp
WARNING: This will also download updates for
files which you have modified locally -- if you
use this option, make sure you examine the list
of downloaded files carefully before you
install them!
.It Fl d Ar workdir
Store working files (eg, downloaded updates) in
.Ar workdir .
The default location is
.Pa $PREFIX/freebsd-update .
.It Fl f Ar conffile
Read the configuration from from
.Ar conffile.
The default location is
.Pa $PREFIX/etc/freebsd-update.conf .
.It Fl k Ar KEY
Expect a public key with given MD5 hash.
.It Fl q
Suppress some useful information.
.It Fl v
Act verbosely.  See below for how this affects
each command.
.It URL
Fetch updates from URL (eg. http://update.example.com/ ).
.El
.Sh COMMANDS
The
.Cm command
can be any one of the following:
.Pp
.Bl -tag -width "-f conffile"
.It fetch
Based on the currently installed world, fetch all available
binary updates.  Any updates previously fetched but not
installed will be fetched again.  If a distribution branch
is specified with the 
.Fl -branch
option, updates will be
fetched from that branch even if the files in question
have been modified locally.  If the
.Fl q
flag is not passed, a list of locally modified files
affected by security updates (if any) will be shown,
whether updates are fetched or not.
.It install
Install the most recently fetched updates.
.It rollback
Uninstall the most recently installed updates.  Note:
While it is possible to rollback a set of updates and
then re-install them, only one set of non-installed
updates are retained; if two sets of updates are
rolled back in sequence, the first set will be deleted.
.It cron
If any binary updates are available, fetch them and
send an email to root; otherwise, exit silently. As
the name suggests, this is intended for usage via
cron(8).  If the 
.Fl v
flag is passsed, an email will be 
sent to root even if no updates were fetched.
.It IDS
For every file which can be installed as part of the
binary release, compare the local file to a list of
"known good" hashes.  Normally, certain excessively
mutable files are ignored when producing this list; the
.Fl v
option disables this filtering.
.El
.Sh TIPS
.Bl -bullet
.It
If your clock is set to local time, adding the line
.Pp
.Dl 0 3 * * * root /usr/local/sbin/freebsd-update cron
.Pp
to /etc/crontab will check for updates every night.  If your
clock is set to UTC, please pick a random time instead of
3AM, or the server hosting the updates will be very unhappy.
.It
.Nm
cron waits a random amount of time, up to an hour, before contacting
the server in order to reduce the risk of "flash crowds" resulting
from cron jobs.
.It
.Nm
IDS can only identify locally modified files if the commands
it uses have not been tampered with.  If you intend to
use this command for intrusion-detection purposes, make
sure you boot from a secure disk (a write-protected floppy
or a CD).
.El
.Sh FILES
.Bl -tag -width "$PREFIX/etc/freebsd-update.conf"
.It $PREFIX/etc/freebsd-update.conf
Default location of the freebsd-update configuration file.
.El
.Sh SEE ALSO
.Xr freebsd-update.conf 5
.Sh AUTHORS
.An Colin Percival Aq cperciva@daemonology.net