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.Dd February 2, 2024
27.Dt FREEBSD-UPDATE 8
28.Os
29.Sh NAME
30.Nm freebsd-update
31.Nd fetch and install binary updates to FreeBSD
32.Sh SYNOPSIS
33.Nm
34.Op Fl F
35.Op Fl b Ar basedir
36.Op Fl -currently-running Ar release
37.Op Fl d Ar workdir
38.Op Fl f Ar conffile
39.Op Fl j Ar jail
40.Op Fl k Ar KEY
41.Op Fl -not-running-from-cron
42.Op Fl r Ar newrelease
43.Op Fl s Ar server
44.Op Fl t Ar address
45.Ar command ...
46.Sh DESCRIPTION
47The
48.Nm
49tool is used to fetch, install, and rollback binary
50updates to the
51.Fx
52base system.
53.Sh BINARY UPDATES AVAILABILITY
54Binary updates are not available for every single
55.Fx
56version and architecture.
57.Pp
58In general, binary updates are available for ALPHA, BETA, RC, and RELEASE
59versions of
60.Fx ,
61e.g.:
62.Bl -item -offset indent -compact
63.It
64.Fx 13.1-ALPHA3
65.It
66.Fx 13.1-BETA2
67.It
68.Fx 13.1-RC1
69.It
70.Fx 13.1-RELEASE
71.El
72They are not available for branches such as PRERELEASE, STABLE, and CURRENT,
73e.g.:
74.Bl -item -offset indent -compact
75.It
76.Fx 13.0-PRERELEASE
77.It
78.Fx 13.1-STABLE
79.It
80.Fx 14.0-CURRENT
81.El
82.Pp
83In particular, the
84.Fx
85Security Team only builds updates for releases shipped in binary form by the
86.Fx
87Release Engineering Team.
88.Sh OPTIONS
89The following options are supported:
90.Bl -tag -width "-r newrelease"
91.It Fl b Ar basedir
92Operate on a system mounted at
93.Ar basedir .
94(default:
95.Pa / ,
96or as given in the configuration file.)
97.It Fl d Ar workdir
98Store working files in
99.Ar workdir .
100(default:
101.Pa /var/db/freebsd-update/ ,
102or as given in the configuration file.)
103.It Fl f Ar conffile
104Read configuration options from
105.Ar conffile .
106(default:
107.Pa /etc/freebsd-update.conf )
108.It Fl F
109Force
110.Nm Cm fetch
111to proceed in the case of an unfinished upgrade.
112.It Fl j Ar jail
113Operate on the given jail specified by
114.Va jid
115or
116.Va name .
117(The version of the installed userland is detected and the
118.Fl -currently-running
119option is no more required.)
120.It Fl k Ar KEY
121Trust an RSA key with SHA256 of
122.Ar KEY .
123(default: read value from configuration file.)
124.It Fl r Ar newrelease
125Specify the new release (e.g., 11.2-RELEASE) to which
126.Nm
127should upgrade
128.Pq Cm upgrade No command only .
129.It Fl s Ar server
130Fetch files from the specified server or server pool.
131(default: read value from configuration file.)
132.It Fl t Ar address
133Mail output of
134.Cm cron
135command, if any, to
136.Ar address .
137(default: root, or as given in the configuration file.)
138.It Fl -not-running-from-cron
139Force
140.Nm Cm fetch
141to proceed when there is no controlling
142.Xr tty 4 .
143This is for use by automated scripts and orchestration tools.
144Please do not run
145.Nm Cm fetch
146from
147.Xr crontab 5
148or similar using this flag, see:
149.Nm Cm cron
150.It Fl -currently-running Ar release
151Do not detect the currently-running release; instead, assume that the system is
152running the specified
153.Ar release .
154This is most likely to be useful when upgrading jails.
155.El
156.Sh COMMANDS
157The
158.Cm command
159can be any one of the following:
160.Bl -tag -width "rollback"
161.It Cm fetch
162Based on the currently installed world and the configuration options set, fetch
163all available binary updates.
164.It Cm cron
165Sleep a random amount of time between 1 and 3600 seconds, then download updates
166as if the
167.Cm fetch
168command was used.
169If updates are downloaded, an email will be sent (to root or a different
170address if specified via the
171.Fl t
172option or in the configuration file).
173As the name suggests, this command is designed for running from
174.Xr cron 8 ;
175the random delay serves to minimize the probability that a large number of
176machines will simultaneously attempt to fetch updates.
177.It Cm upgrade
178Fetch files necessary for upgrading to a new release.
179Before using this command, make sure that you read the announcement and release
180notes for the new release in case there are any special steps needed for
181upgrading.
182Note that this command may require up to 500 MB of space in
183.Ar workdir
184depending on which components of the
185.Fx
186base system are installed.
187.It Cm updatesready
188Check if there are fetched updates ready to install.
189Returns exit code 2 if there are no updates to install.
190.It Cm install
191Install the most recently fetched updates or upgrade.
192Returns exit code 2 if there are no updates to install and the
193.Cm fetch
194command wasn't passed as an earlier argument in the same invocation.
195.It Cm rollback
196Uninstall the most recently installed updates.
197.It Cm IDS
198Compare the system against a "known good" index of the installed release.
199.It Cm showconfig
200Show configuration options after parsing conffile and command line options.
201.El
202.Sh TIPS
203.Bl -bullet
204.It
205If your clock is set to local time, adding the line
206.Pp
207.Dl 0 3 * * * root /usr/sbin/freebsd-update cron
208.Pp
209to
210.Pa /etc/crontab
211will check for updates every night.
212If your clock is set to UTC, please pick a random time other than 3AM, to avoid
213overly imposing an uneven load on the server(s) hosting the updates.
214.It
215In spite of its name,
216.Nm
217IDS should not be relied upon as an "Intrusion Detection System", since if the
218system has been tampered with it cannot be trusted to operate correctly.
219If you intend to use this command for intrusion-detection purposes, make sure
220you boot from a secure disk (e.g., a CD).
221.El
222.Sh ENVIRONMENT
223.Bl -tag -width "PAGER"
224.It Ev PAGER
225The pager program used to present various reports during the execution.
226.Po
227Default:
228.Dq Pa /usr/bin/less .
229.Pc
230.Pp
231.Ev PAGER
232can be set to
233.Dq cat
234when a non-interactive pager is desired.
235.El
236.Sh FILES
237.Bl -tag -width "/etc/freebsd-update.conf"
238.It Pa /etc/freebsd-update.conf
239Default location of the
240.Nm
241configuration file.
242.It Pa /var/db/freebsd-update/
243Default location where
244.Nm
245stores temporary files, downloaded updates, and files required for rollback.
246All files under
247.Pa /var/db/freebsd-update/
248may be deleted if an upgrade is not in progress and rollback will not be
249required.
250.El
251.Sh SEE ALSO
252.Xr freebsd-version 1 ,
253.Xr uname 1 ,
254.Xr freebsd-update.conf 5 ,
255.Xr nextboot 8
256.Sh AUTHORS
257.An Colin Percival Aq Mt cperciva@FreeBSD.org
258.Sh BUGS
259In patch level situations – for example, 13.2-RELEASE-p1 up to
26013.2-RELEASE-p2: if any previous modification to a file in
261.Pa /etc/
262will conflict with an available update, then
263.Nm
264will make no attempt to merge.
265Instead:
266.Nm
267will print a list of affected locally-modified files.
268