usr.sbin/freebsd-update/freebsd-update.8

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