FREEBSD-UPDATE.CONF(5)

💅 FREEBSD-UPDATE.CONF — the manual page, but make it make sense ✨

okay bestie, so this is freebsd-update.conf(5), a File Formats Manual page, and it's literally the settings file for freebsd-update(8). it's not scary, i promise. come sit with me 🫶

---

🌸 NAME 🌸

freebsd-update.conf — the configuration file for freebsd-update(8) 💖

---

✨ DESCRIPTION ✨

so the freebsd-update.conf file is what controls how freebsd-update(8) behaves. that's it, that's the vibe. 👑

inside it you've got lines, and each line is an option name (and it's case-sensitive, so don't get cute with capitalization, she WILL notice 😭) followed by zero or more parameters.

couple of ground rules, no cap:

• empty lines are ignored, they're just there for aesthetic 💅
• anything on a line after a # character is ignored too — that's your comment zone, go off
• unless stated otherwise, listing the same option multiple times is an error. periodt. three options are the exception and they accumulate — i'll flag them when we get there 🎀

here are all the possible options and what they actually mean:

• AllowAdd — the one parameter after this must be yes or no, and it says whether freebsd-update(8) is allowed to create new files, directories, and symlinks when those are part of the updates you downloaded. lowkey important caveat though: freebsd-update(8) will not re-add files that have been deleted from a FreeBSD installation — unless those files were previously added as part of an update. so like, it's not a resurrection service 🙈
• AllowDelete — the one parameter after this must be yes or no, and it says whether freebsd-update(8) is allowed to delete files, directories, and symlinks as part of the downloaded updates. yes this is the "can it actually remove stuff" switch 💀
• BackupKernel — the one parameter after this must be yes or no, and it says whether freebsd-update(8) will make a backup of the old kernel before installing a new one. that backup kernel is your safety net, your ride-or-die — it's what you use to recover a system where the shiny new kernel somehow did not work 😭 heads up though: the backup kernel is not reverted to its original state by the freebsd-update(8) rollback command. so don't expect time travel on that one.
• BackupKernelDir — this keyword sets the directory used to store a backup kernel, if the BackupKernel feature is enabled. now the rules, because there are rules:
  • if the directory already exists and it was not created by freebsd-update(8), the directory is skipped.
  • if the primary directory name isn't usable, a number starting with 1 gets appended to the directory name.
  • same deal as the primary name: the constructed directory name is only used if the path name doesn't exist, or if the directory was previously created by freebsd-update(8).
  • if the constructed directory still exists, the appended number goes up by 1 and the whole directory search process restarts. 🔁
  • should that number increment go above 9, freebsd-update(8) will abort. straight up. no more tries. 💀
• BackupKernelSymbolFiles — the one parameter after this must be yes or no, and it says whether freebsd-update(8) will also back up kernel symbol files, if they exist. genuine warning here: the kernel symbol files take up a lot of disk space and are not needed for recovery purposes. so like, they're kind of a lot. 🫠 but if you do need them — after recovering a system using the backup kernel — the freebsd-update(8) rollback command will recreate the symbol files along with the old kernel. slay.
• Components — the parameters after this keyword are the components or sub-components of FreeBSD that will be updated. let's break it down:
  • components are src (source code), world (non-kernel binaries), and kernel
  • sub-components are the individual distribution sets generated as part of the release process, e.g. src/base, src/sys, world/base, world/catpages, kernel/smp

little history moment 🕰️: prior to FreeBSD 6.1, the kernel component was distributed as part of world/base.

this option can be specified multiple times, and the parameters accumulate. see, i told you some of them stack 💖

• CreateBootEnv — the one parameter after this must be yes or no, and it says whether freebsd-update(8) will create a new boot environment using bectl(8) when installing patches.

the name of the new boot environment is made of the current FreeBSD version:

freebsd-version -ku | sort -V | tail -n 1

and a timestamp:

date +"%Y-%m-%d_%H%M%S"

separated by a single dash. so it looks like this, for example:

13.0-RELEASE-p7_2022-02-16_141502

now, freebsd-update(8) does not attempt to create a boot environment if any of the following applies — vibe check failed, basically:

• ZFS is not used.
• The ZFS root is not set up for boot environments (see the check command of bectl(8) for details).
• freebsd-update(8) is running in a jail(8).
• freebsd-update(8) is updating a root directory selected via the basedir (-b) or jail (-j) flags.

• IDSIgnorePaths — the parameters after this keyword are regular expressions; paths which start with a string matching one of these regular expressions will be ignored by freebsd-update(8) IDS.

this option can be specified multiple times, and the parameters accumulate. ✨

• IgnorePaths — the parameters after this keyword are regular expressions; updates to paths which start with a string matching one of these regular expressions will be ignored.

this option can be specified multiple times, and the parameters accumulate. ✨

• KeepModifiedMetadata — the one parameter after this must be yes or no, and it says whether freebsd-update(8) should keep existing file ownership, permissions, and flags when installing updates, if these have been modified locally. your local tweaks, preserved 🎀
• KeyPrint — the one parameter after this keyword is the SHA256 hash of the RSA key which will be trusted to sign updates. trust issues, but make it cryptographic 🔐
• MailTo — the one parameter after this keyword is the address to which cron(8) output will be mailed.
• MergeChanges — the parameters after this keyword are regular expressions; updates to paths which start with a string matching one of these regular expressions will be merged with local modifications.

this option can be specified multiple times, and the parameters accumulate. ✨

• ServerName — the one parameter after this keyword is the name of the server or server pool from which updates will be downloaded. where we're getting the goods 📦
• StrictComponents — the one parameter after this must be yes or no, and it says whether freebsd-update(8) should interpret the list of components of FreeBSD specified via the Components option:
  • strictly as a list of components installed which should be upgraded when the upgrade command is used (yes), or
  • merely as a list of components which might be installed, of which freebsd-update(8) should identify which in fact are present (no). 🔍
• UpdateIfUnmodified — the parameters after this keyword are regular expressions; updates to paths which start with a string matching one of these regular expressions will be ignored if the files have been modified locally — unless they are merged, see the MergeChanges option. 👀

this option can be specified multiple times, and the parameters accumulate. ✨

• WorkDir — the one parameter after this keyword is the directory in which temporary files and downloaded updates will be stored. the lil staging area 🧚

---

🎀 FILES 🎀

• /etc/freebsd-update.conf — default location of the freebsd-update(8) configuration file. that's the one, that's the home base 💖

---

🦋 SEE ALSO 🦋

sha256(1), bectl(8), freebsd-update(8)

go read your friends, bestie, they're all iconic 👑

---

🌈 AUTHORS 🌈

Colin Percival <cperciva@FreeBSD.org> — founder of this whole situation, we stan 🫶

---

and that's the page!! 💜 it's from Debian, dated February 17, 2022, and it rides under the FREEBSD-UPDATE.CONF(5) name with File Formats Manual as its section bestie. mwah, go configure something beautiful 💅✨