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