share/man/man5/freebsd-update.conf.5

   1 .\"-
   2 .\" Copyright 2006 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 February 17, 2022
  29 .Dt FREEBSD-UPDATE.CONF 5
  30 .Os
  31 .Sh NAME
  32 .Nm freebsd-update.conf
  33 .Nd configuration file for
  34 .Xr freebsd-update 8
  35 .Sh DESCRIPTION
  36 The
  37 .Nm
  38 file controls the behaviour of the
  39 .Xr freebsd-update 8
  40 utility.
  41 The file contains lines consisting of a case-sensitive option name and
  42 zero or more parameters.
  43 Empty lines and any part of a line following a
  44 .Ql #
  45 character are ignored.
  46 Unless stated otherwise, specifying an option multiple times is an
  47 error.
  48 .Pp
  49 The possible options and their meanings are as follows:
  50 .Bl -tag -width "BackupKernelSymbolFiles"
  51 .It Cm AllowAdd
  52 The single parameter following this keyword must be
  53 .Dq yes
  54 or
  55 .Dq no
  56 and specifies whether
  57 .Xr freebsd-update 8
  58 is allowed to create new files, directories, and symlinks if
  59 these are part of updates downloaded.
  60 Note that
  61 .Xr freebsd-update 8
  62 will not re-add files which have been deleted from a
  63 .Fx
  64 installation unless those files were previously added as part
  65 of an update.
  66 .It Cm AllowDelete
  67 The single parameter following this keyword must be
  68 .Dq yes
  69 or
  70 .Dq no
  71 and specifies whether
  72 .Xr freebsd-update 8
  73 is allowed to delete files, directories, and symlinks as
  74 part of updates downloaded.
  75 .It Cm BackupKernel
  76 The single parameter following this keyword must be
  77 .Dq yes
  78 or
  79 .Dq no
  80 and specifies whether
  81 .Xr freebsd-update 8
  82 will create a backup of the old kernel before installing a new kernel.
  83 This backup kernel can be used to recover a system where the newly
  84 installed kernel somehow did not work.
  85 Note that the backup kernel is not reverted to its original state by
  86 the
  87 .Xr freebsd-update 8
  88 rollback command.
  89 .It Cm BackupKernelDir
  90 This keyword sets the directory which is used to store a backup
  91 kernel, if the BackupKernel feature is enabled.
  92 If the directory already exist, and it was not created by
  93 .Xr freebsd-update 8 ,
  94 the directory is skipped.
  95 In the case of the primary directory name not being usable, a number
  96 starting with
  97 .Sq 1
  98 is appended to the directory name.
  99 Like with the primary directory name, the constructed directory name is
 100 only used if the path name does not exist, or if the directory was
 101 previously created by
 102 .Xr freebsd-update 8 .
 103 If the constructed directory still exist the appended number is
 104 incremented with 1 and the directory search process restarted.
 105 Should the number increment go above 9,
 106 .Xr freebsd-update 8
 107 will abort.
 108 .It Cm BackupKernelSymbolFiles
 109 The single parameter following this keyword must be
 110 .Dq yes
 111 or
 112 .Dq no
 113 and specifies whether
 114 .Xr freebsd-update 8
 115 will also backup kernel symbol files, if they exist.
 116 The kernel symbol files takes up a lot of disk space and are not
 117 needed for recovery purposes.
 118 If the symbol files are needed, after recovering a system using the
 119 backup kernel, the
 120 .Xr freebsd-update 8
 121 rollback command will recreate the symbol files along with the old
 122 kernel.
 123 .It Cm Components
 124 The parameters following this keyword are the components or
 125 sub-components of
 126 .Fx
 127 which will be updated.
 128 The components are
 129 .Dq src
 130 (source code),
 131 .Dq world
 132 (non-kernel binaries), and
 133 .Dq kernel ;
 134 the sub-components are the individual distribution sets generated as
 135 part of the release process (e.g.,
 136 .Dq src/base ,
 137 .Dq src/sys ,
 138 .Dq world/base ,
 139 .Dq world/catpages ,
 140 .Dq kernel/smp ) .
 141 Note that prior to
 142 .Fx 6.1 ,
 143 the
 144 .Dq kernel
 145 component was distributed as part of
 146 .Dq world/base .
 147 .Pp
 148 This option can be specified multiple times, and the parameters
 149 accumulate.
 150 .It Cm CreateBootEnv
 151 The single parameter following this keyword must be
 152 .Dq yes
 153 or
 154 .Dq no
 155 and specifies whether
 156 .Xr freebsd-update 8
 157 will create a new boot environment using
 158 .Xr bectl 8
 159 when installing patches.
 160 .Pp
 161 The name of the new boot environment consists of the current
 162 .Fx
 163 version:
 164 .Bd -literal -offset indent
 165 freebsd-version -ku | sort -V | tail -n 1
 166 .Ed
 167 .Pp
 168 and a timestamp:
 169 .Bd -literal -offset indent
 170 date +"%Y-%m-%d_%H%M%S"
 171 .Ed
 172 .Pp
 173 separated by a single dash, e.g.:
 174 .Bd -literal -offset indent
 175 13.0-RELEASE-p7_2022-02-16_141502
 176 .Ed
 177 .Pp
 178 .Xr freebsd-update 8
 179 does not attempt to create a boot environment
 180 if any of the following applies:
 181 .Pp
 182 .Bl -dash -compact
 183 .It
 184 ZFS is not used.
 185 .It
 186 The ZFS root is not set up for boot environments
 187 .Po see the check command of
 188 .Xr bectl 8
 189 for details
 190 .Pc .
 191 .It
 192 .Xr freebsd-update 8
 193 is running in a
 194 .Xr jail 8 .
 195 .It
 196 .Xr freebsd-update 8
 197 is updating a root directory selected via
 198 the basedir
 199 .Pq Fl b
 200 or jail
 201 .Pq Fl j
 202 flags.
 203 .El
 204 .It Cm IDSIgnorePaths
 205 The parameters following this keyword are regular expressions;
 206 paths which start with a string matching one of these regular
 207 expressions will be ignored by
 208 .Xr freebsd-update 8
 209 IDS.
 210 .Pp
 211 This option can be specified multiple times, and the parameters
 212 accumulate.
 213 .It Cm IgnorePaths
 214 The parameters following this keyword are regular expressions;
 215 updates to paths which start with a string matching one of
 216 these regular expressions will be ignored.
 217 .Pp
 218 This option can be specified multiple times, and the parameters
 219 accumulate.
 220 .It Cm KeepModifiedMetadata
 221 The single parameter following this keyword must be
 222 .Dq yes
 223 or
 224 .Dq no
 225 and specifies whether
 226 .Xr freebsd-update 8
 227 should keep existing file ownership, permissions, and flags
 228 when installing updates if these have been modified locally.
 229 .It Cm KeyPrint
 230 The single parameter following this keyword is the SHA256 hash
 231 of the RSA key which will be trusted to sign updates.
 232 .It Cm MailTo
 233 The single parameter following this keyword is the address
 234 to which
 235 .Xr cron 8
 236 output will be mailed.
 237 .It Cm MergeChanges
 238 The parameters following this keyword are regular expressions;
 239 updates to paths which start with a string matching one of
 240 these regular expressions will be merged with local modifications.
 241 .Pp
 242 This option can be specified multiple times, and the parameters
 243 accumulate.
 244 .It Cm ServerName
 245 The single parameter following this keyword is the name of the
 246 server or server pool from which updates will be downloaded.
 247 .It Cm StrictComponents
 248 The single parameter following this keyword must be
 249 .Dq yes
 250 or
 251 .Dq no
 252 and specifies whether
 253 .Xr freebsd-update 8
 254 should interpret the list of components of
 255 .Fx
 256 specified via the
 257 .Cm Components
 258 option strictly as a list of components installed which
 259 should be upgraded when the
 260 .Cm upgrade
 261 command is used ("yes"), or merely as a list of components
 262 which might be installed, of which
 263 .Xr freebsd-update 8
 264 should identify which in fact are present ("no").
 265 .It Cm UpdateIfUnmodified
 266 The parameters following this keyword are regular expressions;
 267 updates to paths which start with a string matching one of
 268 these regular expressions will be ignored if the files have
 269 been modified locally (unless they are merged \(em see the
 270 .Cm MergeChanges
 271 option).
 272 .Pp
 273 This option can be specified multiple times, and the parameters
 274 accumulate.
 275 .It Cm WorkDir
 276 The single parameter following this keyword is the directory
 277 in which temporary files and downloaded updates will be stored.
 278 .El
 279 .Sh FILES
 280 .Bl -tag -width "/etc/freebsd-update.conf"
 281 .It Pa /etc/freebsd-update.conf
 282 Default location of the
 283 .Xr freebsd-update 8
 284 configuration file.
 285 .El
 286 .Sh SEE ALSO
 287 .Xr sha256 1 ,
 288 .Xr bectl 8 ,
 289 .Xr freebsd-update 8
 290 .Sh AUTHORS
 291 .An Colin Percival Aq Mt cperciva@FreeBSD.org