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