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