xref: /freebsd/usr.sbin/freebsd-update/freebsd-update.8 (revision 6472ac3d8a86336899b6cfb789a4cd9897e3fab5)
1.\"-
2.\" Copyright 2006, 2007 Colin Percival
3.\" All rights reserved
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted providing that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
15.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
16.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
18.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
22.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
23.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
24.\" POSSIBILITY OF SUCH DAMAGE.
25.\"
26.\" $FreeBSD$
27.\"
28.Dd July 14, 2010
29.Dt FREEBSD-UPDATE 8
30.Os FreeBSD
31.Sh NAME
32.Nm freebsd-update
33.Nd fetch and install binary updates to FreeBSD
34.Sh SYNOPSIS
35.Nm
36.Op Fl b Ar basedir
37.Op Fl d Ar workdir
38.Op Fl f Ar conffile
39.Op Fl k Ar KEY
40.Op Fl r Ar newrelease
41.Op Fl s Ar server
42.Op Fl t Ar address
43.Cm command ...
44.Sh DESCRIPTION
45The
46.Nm
47tool is used to fetch, install, and rollback binary
48updates to the FreeBSD base system.
49Note that updates are only available if they are being built for the
50FreeBSD release and architecture being used; in particular, the
51.Fx
52Security Team only builds updates for releases shipped in binary form
53by the
54.Fx
55Release Engineering Team, e.g.,
56.Fx
577.3-RELEASE and
58.Fx
598.0-RELEASE, but not
60.Fx
616.3-STABLE or
62.Fx
639.0-CURRENT.
64.Sh OPTIONS
65The following options are supported
66.Bl -tag -width "-f conffile"
67.It Fl b Ar basedir
68Operate on a system mounted at
69.Ar basedir .
70(default:
71.Pa / ,
72or as given in the configuration file.)
73.It Fl d Ar workdir
74Store working files in
75.Ar workdir .
76(default:
77.Pa /var/db/freebsd-update/ ,
78or as given in the configuration file.)
79.It Fl f Ar conffile
80Read configuration options from
81.Ar conffile .
82(default:
83.Pa /etc/freebsd-update.conf )
84.It Fl k Ar KEY
85Trust an RSA key with SHA256 of
86.Ar KEY .
87(default: read value from configuration file.)
88.It Fl r Ar newrelease
89Specify the new release to which
90.Nm
91should upgrade (upgrade command only).
92.It Fl s Ar server
93Fetch files from the specified server or server pool.
94(default: read value from configuration file.)
95.It Fl t Ar address
96Mail output of
97.Cm cron
98command, if any, to
99.Ar address .
100(default: root, or as given in the configuration file.)
101.El
102.Sh COMMANDS
103The
104.Cm command
105can be any one of the following:
106.Bl -tag -width "-f conffile"
107.It Cm fetch
108Based on the currently installed world and the configuration
109options set, fetch all available binary updates.
110.It Cm cron
111Sleep a random amount of time between 1 and 3600 seconds,
112then download updates as if the
113.Cm fetch
114command was used.
115If updates are downloaded, an email will be sent
116(to root or a different address if specified via the
117.Fl t
118option or in the configuration file).
119As the name suggests, this command is designed for running
120from
121.Xr cron 8 ;
122the random delay serves to minimize the probability that
123a large number of machines will simultaneously attempt to
124fetch updates.
125.It Cm upgrade
126Fetch files necessary for upgrading to a new release.
127Before using this command, make sure that you read the
128announcement and release notes for the new release in
129case there are any special steps needed for upgrading.
130Note that this command may require up to 500 MB of space in
131.Ar workdir
132depending on which components of the
133.Fx
134base system are installed.
135.It Cm install
136Install the most recently fetched updates or upgrade.
137.It Cm rollback
138Uninstall the most recently installed updates.
139.It Cm IDS
140Compare the system against a "known good" index of the
141installed release.
142.El
143.Sh TIPS
144.Bl -bullet
145.It
146If your clock is set to local time, adding the line
147.Pp
148.Dl 0 3 * * * root /usr/sbin/freebsd-update cron
149.Pp
150to /etc/crontab will check for updates every night.
151If your clock is set to UTC, please pick a random time
152other than 3AM, to avoid overly imposing an uneven load
153on the server(s) hosting the updates.
154.It
155In spite of its name,
156.Nm
157IDS should not be relied upon as an "Intrusion Detection
158System", since if the system has been tampered with
159it cannot be trusted to operate correctly.
160If you intend to use this command for intrusion-detection
161purposes, make sure you boot from a secure disk (e.g., a CD).
162.El
163.Sh FILES
164.Bl -tag -width "/etc/freebsd-update.conf"
165.It /etc/freebsd-update.conf
166Default location of the
167.Nm
168configuration file.
169.It /var/db/freebsd-update/
170Default location where
171.Nm
172stores temporary files and downloaded updates.
173.El
174.Sh SEE ALSO
175.Xr freebsd-update.conf 5
176.Sh AUTHORS
177.An Colin Percival Aq cperciva@FreeBSD.org
178