xref: /freebsd/usr.sbin/freebsd-update/freebsd-update.8 (revision 13ea0450a9c8742119d36f3bf8f47accdce46e54)
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 June 14, 2017
29.Dt FREEBSD-UPDATE 8
30.Os
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 F
40.Op Fl k Ar KEY
41.Op Fl r Ar newrelease
42.Op Fl s Ar server
43.Op Fl t Ar address
44.Op Fl -not-running-from-cron
45.Cm command ...
46.Sh DESCRIPTION
47The
48.Nm
49tool is used to fetch, install, and rollback binary
50updates to the
51.Fx
52base system.
53Note that updates are only available if they are being built for the
54.Fx
55release and architecture being used; in particular, the
56.Fx
57Security Team only builds updates for releases shipped in binary form
58by the
59.Fx
60Release Engineering Team, e.g.,
61.Fx
6211.2-RELEASE and
63.Fx
6412.0-RELEASE, but not
65.Fx
6611.2-STABLE or
67.Fx
6813.0-CURRENT.
69.Sh OPTIONS
70The following options are supported:
71.Bl -tag -width "-r newrelease"
72.It Fl b Ar basedir
73Operate on a system mounted at
74.Ar basedir .
75(default:
76.Pa / ,
77or as given in the configuration file.)
78.It Fl d Ar workdir
79Store working files in
80.Ar workdir .
81(default:
82.Pa /var/db/freebsd-update/ ,
83or as given in the configuration file.)
84.It Fl f Ar conffile
85Read configuration options from
86.Ar conffile .
87(default:
88.Pa /etc/freebsd-update.conf )
89.It Fl F
90Force
91.Nm Cm fetch
92to proceed in the case of an unfinished upgrade.
93.It Fl k Ar KEY
94Trust an RSA key with SHA256 of
95.Ar KEY .
96(default: read value from configuration file.)
97.It Fl r Ar newrelease
98Specify the new release (e.g. 11.2-RELEASE) to which
99.Nm
100should upgrade (upgrade command only).
101.It Fl s Ar server
102Fetch files from the specified server or server pool.
103(default: read value from configuration file.)
104.It Fl t Ar address
105Mail output of
106.Cm cron
107command, if any, to
108.Ar address .
109(default: root, or as given in the configuration file.)
110.It Fl -not-running-from-cron
111Force
112.Nm Cm fetch
113to proceed when there is no controlling tty.
114This is for use by automated scripts and orchestration tools.
115Please do not run
116.Nm Cm fetch
117from crontab or similar using this flag, see:
118.Nm Cm cron
119.It Fl -currently-running Ar release
120Do not detect the currently-running release; instead, assume that the
121system is running the specified
122.Ar release .
123This is most likely to be useful when upgrading jails.
124.El
125.Sh COMMANDS
126The
127.Cm command
128can be any one of the following:
129.Bl -tag -width "rollback"
130.It Cm fetch
131Based on the currently installed world and the configuration
132options set, fetch all available binary updates.
133.It Cm cron
134Sleep a random amount of time between 1 and 3600 seconds,
135then download updates as if the
136.Cm fetch
137command was used.
138If updates are downloaded, an email will be sent
139(to root or a different address if specified via the
140.Fl t
141option or in the configuration file).
142As the name suggests, this command is designed for running
143from
144.Xr cron 8 ;
145the random delay serves to minimize the probability that
146a large number of machines will simultaneously attempt to
147fetch updates.
148.It Cm upgrade
149Fetch files necessary for upgrading to a new release.
150Before using this command, make sure that you read the
151announcement and release notes for the new release in
152case there are any special steps needed for upgrading.
153Note that this command may require up to 500 MB of space in
154.Ar workdir
155depending on which components of the
156.Fx
157base system are installed.
158.It Cm install
159Install the most recently fetched updates or upgrade.
160.It Cm rollback
161Uninstall the most recently installed updates.
162.It Cm IDS
163Compare the system against a "known good" index of the
164installed release.
165.El
166.Sh TIPS
167.Bl -bullet
168.It
169If your clock is set to local time, adding the line
170.Pp
171.Dl 0 3 * * * root /usr/sbin/freebsd-update cron
172.Pp
173to /etc/crontab will check for updates every night.
174If your clock is set to UTC, please pick a random time
175other than 3AM, to avoid overly imposing an uneven load
176on the server(s) hosting the updates.
177.It
178In spite of its name,
179.Nm
180IDS should not be relied upon as an "Intrusion Detection
181System", since if the system has been tampered with
182it cannot be trusted to operate correctly.
183If you intend to use this command for intrusion-detection
184purposes, make sure you boot from a secure disk (e.g., a CD).
185.El
186.Sh FILES
187.Bl -tag -width "/etc/freebsd-update.conf"
188.It Pa /etc/freebsd-update.conf
189Default location of the
190.Nm
191configuration file.
192.It Pa /var/db/freebsd-update/
193Default location where
194.Nm
195stores temporary files and downloaded updates.
196.El
197.Sh SEE ALSO
198.Xr freebsd-update.conf 5
199.Sh AUTHORS
200.An Colin Percival Aq Mt cperciva@FreeBSD.org
201