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