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