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