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