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