Unattended Updates on FreeBSD¶
FreeBSD splits updates into two independent streams, and you automate them separately:
| Stream | What it covers | Tool |
|---|---|---|
| Base system | Kernel + userland (/bin, /sbin, /usr/bin, /lib, /etc defaults…) |
freebsd-update (traditional) or pkg with pkgbase (FreeBSD 15+) |
| Third-party packages | Everything from ports/packages in /usr/local |
pkg |
FreeBSD's culture is "notify by default, install deliberately" — the built-in tooling is designed to fetch and email, not to silently install. Fully unattended installs are possible, but you build them yourself, ideally with ZFS boot environments as a safety net.
Contents¶
- Which base-system method are you using?
- Built-in: periodic(8) security reporting
- Base system with freebsd-update
- Base system with pkgbase (FreeBSD 15+)
- Third-party packages with pkg
- Boot environments: the safety net
- A complete unattended update script
- Restarting services and rebooting
- Jails
- Quarterly vs. latest package branches
- Mail delivery for reports
- Fleet orchestration
- Quick reference
Which base-system method are you using?¶
FreeBSD 15.0 introduced pkgbase — the base system shipped as packages managed by pkg — as a technology preview, alongside the traditional distribution sets updated with freebsd-update. Systems installed with distribution sets keep using freebsd-update, which remains supported for the life of the 15.x branch; distribution sets are planned to go away in FreeBSD 16.
Check:
pkg info -x '^FreeBSD-' | head # lists FreeBSD-* packages -> pkgbase system
freebsd-version -kru # installed kernel, running kernel, userland
If pkg info lists FreeBSD-runtime, FreeBSD-kernel-generic, etc., you're on pkgbase and must not use freebsd-update (it will refuse). Otherwise, use freebsd-update.
FreeBSD 13.x and 14.x systems always use freebsd-update.
Built-in: periodic(8) security reporting¶
Before automating installs, make sure the system tells you about vulnerabilities. These run from the daily periodic job and land in root's mail.
/etc/periodic.conf:
# Check installed packages against the VuXML vulnerability database (daily)
security_status_pkgaudit_enable="YES"
security_status_pkgaudit_quiet="NO" # report even if clean? set YES to stay quiet
# Note base-system vulns too (pkg audit understands base on 14+ / pkgbase)
security_status_baseaudit_enable="YES"
# Report package changes since the last run
daily_status_pkg_changes_enable="YES"
# Back up the pkg database daily
daily_backup_pkgdb_enable="YES"
# Show the output of the daily security run in the mail
daily_status_security_enable="YES"
daily_status_security_inline="YES"
Manual equivalents:
pkg audit -F # fetch fresh vuln DB and audit installed packages
pkg audit -Fr # same, recursive: also show what depends on vulnerable pkgs
freebsd-version -kru
Also subscribe to [email protected] for Security Advisories (SAs) and Errata Notices (ENs).
Base system with freebsd-update¶
Fetch-and-notify (the officially intended unattended mode)¶
freebsd-update cron sleeps a random 0–3600 seconds (to spread load on the update mirrors), fetches any available patches, and mails root — but does not install.
/etc/crontab:
# minute hour mday month wday who command
0 3 * * * root freebsd-update cron
When the mail arrives, install by hand:
freebsd-update install
Configuration: /etc/freebsd-update.conf¶
KeyPrint 800651ef4b4c71c27e60786d7b487188970f4b4169cc055784e21eb71d410cc5
ServerName update.FreeBSD.org
# Drop "src" if /usr/src isn't installed; drop "kernel" if you build your own
Components src world kernel
# Paths not to touch
IgnorePaths
# Paths whose local modifications are discarded / kept
IDSIgnorePaths /usr/share/man/cat
IDSIgnorePaths /usr/share/man/whatis
IDSIgnorePaths /var/db/locate.database
IDSIgnorePaths /var/log
UpdateIfUnmodified /etc/ /var/ /root/ /.cshrc /.profile
MergeChanges /etc/ /boot/device.hints
MailTo root
KeepModifiedMetadata yes
StrictComponents no
BackupKernel yes
BackupKernelDir /boot/kernel.old
CreateBootEnv yes # 13.2+: auto-create a ZFS boot environment before install
CreateBootEnv yes (default on ZFS root) means every freebsd-update install creates a boot environment you can roll back to — this is what makes unattended base installs reasonable.
Custom kernels: if you run a custom kernel, remove
kernelfromComponents, or freebsd-update will replace it with GENERIC.
Fully unattended install¶
freebsd-update normally refuses to run non-interactively from cron except via the cron subcommand. Use --not-running-from-cron to let a script run fetch + install:
#!/bin/sh
# /usr/local/sbin/base-update
set -eu
PAGER=cat freebsd-update --not-running-from-cron fetch
if freebsd-update updatesready >/dev/null 2>&1; then
freebsd-update --not-running-from-cron install
logger -t base-update "Base updates installed: $(freebsd-version -u)"
fi
freebsd-update updatesready returns 0 when fetched updates are waiting to be installed (FreeBSD 12.1+), which avoids pointless runs.
Notes:
- Patch-level updates only. This handles
-p1 → -p2style patches within a release. Minor/major release upgrades (freebsd-update -r 15.1-RELEASE upgrade) involve/etcmerges and multiple install passes — never automate those. - EOL releases stop receiving patches. Unattended updates on an EOL minor release silently do nothing; monitor
freebsd-updateoutput or the release's EOL date and plan minor upgrades. - Kernel patches need a reboot. Compare
freebsd-version -k(installed) withfreebsd-version -r(running).
Base system with pkgbase (FreeBSD 15+)¶
On a pkgbase system, the base system comes from the FreeBSD-base repository and is patched with ordinary pkg operations.
Patch-level updates (unattended-safe)¶
Within a release (e.g. 15.1-RELEASE-p1 → -p2), a plain upgrade picks up base and package updates together:
pkg update
pkg upgrade -y # base + ports packages
# or base only:
pkg upgrade -y -r FreeBSD-base
The repository config lives in /etc/pkg/FreeBSD.conf (and any overrides in /usr/local/etc/pkg/repos/); the base repo is enabled per release branch.
Minor/major release upgrades (manual)¶
Moving between releases (15.0 → 15.1) currently requires overriding ABI/OSVERSION or pointing at the new release's repository, then updating kernel modules (FreeBSD-ports-kmods) and the EFI loader. The procedure is still evolving while pkgbase is a technology preview — follow the release's upgrade notes and do not automate it.
Recommendations for pkgbase in production¶
- Because pkgbase is still labelled a technology preview in 15.x, many admins keep production on
freebsd-updatefor now and use pkgbase on less critical hosts. - Always create a boot environment before
pkg upgradeon a pkgbase system (see below) — a broken base package set is otherwise much harder to recover than a broken/usr/local. - Keep an eye on
/etcchanges: pkgbase installs new defaults as.pkgsave/.pkgnew-style files or merges them; review after each run.
Third-party packages with pkg¶
Notify only¶
# /etc/crontab
30 3 * * * root pkg update -q && pkg version -vRL= | mail -E -s "$(hostname) pkg updates available" root
(pkg version -vRL= lists packages whose installed version differs from the remote repository; mail -E skips sending if the body is empty.)
Unattended upgrade¶
pkg update -q
pkg upgrade -y
pkg autoremove -y
pkg clean -ay
Useful pkg controls:
pkg lock -y postgresql16-server # never upgrade this package
pkg lock -l # list locked
pkg unlock postgresql16-server
pkg upgrade -n # dry run: show what would change
pkg upgrade -y -r FreeBSD-ports # only from a specific repo
Settings in /usr/local/etc/pkg.conf:
ASSUME_ALWAYS_YES = false; # leave false; pass -y explicitly in scripts
AUTOCLEAN = true; # clean cache after upgrade
REPO_AUTOUPDATE = true;
Major version bumps in packages (e.g. a new
nginxminor, or PHP/Python/Ruby default version changes) can happen at quarterly branch rollovers. Always read/usr/ports/UPDATINGor https://cgit.freebsd.org/ports/plain/UPDATING before the first upgrade of a new quarter, and consider locking critical packages.
Boot environments: the safety net¶
On ZFS root (the default since FreeBSD 13), every update should be preceded by a boot environment (BE). If the update breaks the system, select the old BE in the loader menu or with bectl activate.
bectl list
bectl create pre-update-$(date +%Y%m%d-%H%M)
# ... run updates ...
# Roll back:
bectl activate pre-update-20261110-0300 && shutdown -r now
# Prune old BEs (keep the newest 5)
bectl list -H -c creation | awk '{print $1}' | grep '^pre-update-' \
| tail -r | tail -n +6 | xargs -n1 bectl destroy -o
freebsd-update creates its own BE automatically when CreateBootEnv yes is set, but pkg does not — so create one yourself before pkg upgrade (packages in /usr/local live on the root dataset by default and are captured in the BE).
UFS systems have no BEs; use a hypervisor snapshot or dump(8) instead, and be more conservative about automatic installs.
A complete unattended update script¶
Combines everything: BE snapshot, base patches, package upgrades, audit, service-restart hints, reboot decision, and pruning.
/usr/local/sbin/auto-update:
#!/bin/sh
# Unattended FreeBSD updater: base (freebsd-update or pkgbase) + packages
set -u
PATH=/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin
LOG=/var/log/auto-update.log
KEEP_BES=5
AUTO_REBOOT=${AUTO_REBOOT:-no} # yes | no
TAG="auto-update"
log() { echo "$(date '+%F %T') $*" | tee -a "$LOG" | logger -t "$TAG"; }
# Random delay up to 30 min to spread mirror load across a fleet
sleep $(jot -r 1 0 1800)
# 1. Boot environment (ZFS only)
if command -v bectl >/dev/null 2>&1 && bectl list >/dev/null 2>&1; then
BE="pre-update-$(date +%Y%m%d-%H%M)"
bectl create "$BE" && log "Created BE $BE"
fi
# 2. Base system
if pkg info -e FreeBSD-runtime 2>/dev/null; then
log "pkgbase system: upgrading FreeBSD-base"
pkg update -q -r FreeBSD-base
pkg upgrade -y -r FreeBSD-base >>"$LOG" 2>&1 || log "ERROR: base upgrade failed"
else
log "freebsd-update: fetching"
PAGER=cat freebsd-update --not-running-from-cron fetch >>"$LOG" 2>&1
if freebsd-update updatesready >/dev/null 2>&1; then
freebsd-update --not-running-from-cron install >>"$LOG" 2>&1 \
&& log "Base updates installed" || log "ERROR: freebsd-update install failed"
else
log "No base updates"
fi
fi
# 3. Packages
pkg update -q
if pkg upgrade -n 2>/dev/null | grep -qE 'to be (upgraded|installed|reinstalled)'; then
pkg upgrade -y >>"$LOG" 2>&1 && log "Packages upgraded" || log "ERROR: pkg upgrade failed"
pkg autoremove -y >>"$LOG" 2>&1
pkg clean -ay >/dev/null 2>&1
else
log "No package updates"
fi
# 4. Audit what's still vulnerable
pkg audit -Fq >>"$LOG" 2>&1 && log "pkg audit: clean" || log "WARN: vulnerable packages remain"
# 5. Processes still using replaced files (needs sysutils/lsof)
if command -v lsof >/dev/null 2>&1; then
STALE=$(lsof +L1 2>/dev/null | awk 'NR>1 {print $1}' | sort -u | tr '\n' ' ')
[ -n "$STALE" ] && log "Processes holding deleted files (restart candidates): $STALE"
fi
# 6. Reboot decision
INSTALLED_K=$(freebsd-version -k)
RUNNING_K=$(freebsd-version -r)
if [ "$INSTALLED_K" != "$RUNNING_K" ]; then
log "Kernel changed ($RUNNING_K -> $INSTALLED_K): reboot required"
touch /var/run/reboot-required
if [ "$AUTO_REBOOT" = "yes" ]; then
log "Rebooting in 5 minutes"
shutdown -r +5 "auto-update: rebooting for kernel $INSTALLED_K"
fi
fi
# 7. Prune old BEs
if command -v bectl >/dev/null 2>&1; then
bectl list -H -c creation | awk '{print $1}' | grep '^pre-update-' \
| tail -r | tail -n +$((KEEP_BES + 1)) | while read -r old; do
bectl destroy -o "$old" && log "Pruned BE $old"
done
fi
log "Done"
chmod 700 /usr/local/sbin/auto-update
Schedule it (/etc/crontab):
# Nightly: install updates, don't reboot
0 3 * * * root /usr/local/sbin/auto-update
# Sunday: reboot window
30 4 * * 0 root [ -f /var/run/reboot-required ] && rm -f /var/run/reboot-required && shutdown -r now "weekly reboot window"
Rotate the log with newsyslog (/etc/newsyslog.conf.d/auto-update.conf):
/var/log/auto-update.log 600 7 * @T00 JC
/var/runis cleared at boot on FreeBSD, so the reboot sentinel naturally disappears after the reboot.
Restarting services and rebooting¶
After a userland or package update, daemons keep the old binaries/libraries until restarted.
Find them:
# Requires sysutils/lsof: open files with link count 0 (deleted/replaced)
lsof +L1 | awk 'NR>1 {print $1, $2}' | sort -u
Restart selectively:
service nginx restart
service -R # restart ALL enabled services (blunt, but effective on simple hosts)
Kernel or base-library updates (libc, libssl in base) are best handled with a reboot.
Jails¶
Jails share the host kernel but have their own userland and packages.
Thin jails / jails managed by a tool¶
| Tool | Update command |
|---|---|
| Bastille | bastille update TARGET (base release), bastille pkg ALL upgrade -y |
| iocage | iocage update -a / iocage update <jail> |
| pot | rebuild from updated base / flavour |
| AppJail | appjail fetch + per-jail appjail pkg jail <jail> upgrade -y |
Plain jails with freebsd-update¶
freebsd-update -j web01 fetch install # jail running on the same release
pkg -j web01 update && pkg -j web01 upgrade -y
service jail restart web01 # only if userland libs changed
For a jail on a different release than the host, use -b /path/to/jail --currently-running 14.3-RELEASE-p6.
In the unattended script, loop over jails:
for j in $(jls name); do
freebsd-update --not-running-from-cron -j "$j" fetch install >>"$LOG" 2>&1
pkg -j "$j" upgrade -y >>"$LOG" 2>&1
done
Kernel updates for jails come from the host — reboot the host and all jails restart on the new kernel.
Quarterly vs. latest package branches¶
| Branch | Updates | Use for |
|---|---|---|
quarterly (default on RELEASE) |
Security and build fixes only, branch rolls every 3 months | Servers, unattended upgrades |
latest |
Everything, continuously | Desktops, dev boxes |
Switch by overriding the repo:
mkdir -p /usr/local/etc/pkg/repos
cat > /usr/local/etc/pkg/repos/FreeBSD.conf <<'EOF'
FreeBSD: {
url: "pkg+https://pkg.FreeBSD.org/${ABI}/quarterly"
}
EOF
For full control, run your own repository with poudriere, build exactly the packages and options you need, and point clients at it. Clients then auto-upgrade only to what you've published — the FreeBSD equivalent of a content view or WSUS approval.
Mail delivery for reports¶
periodic, freebsd-update cron and cron jobs all mail root. Make sure that mail goes somewhere:
# /etc/mail/aliases
root: [email protected]
newaliases
FreeBSD 14+ ships dma (DragonFly Mail Agent) as the default MTA, which can relay through a smarthost (/etc/dma/dma.conf: SMARTHOST, PORT 587, AUTHPATH /etc/dma/auth.conf, SECURETRANSFER, STARTTLS). Test with:
echo test | mail -s "$(hostname) mail test" root
Fleet orchestration¶
- Ansible:
community.general.pkgngfor packages;ansible.builtin.command: freebsd-update --not-running-from-cron fetch installfor base; useserial:and a reboot task whenfreebsd-version -k≠-r. - Salt / Puppet / CFEngine: all have FreeBSD
pkgsupport. - Poudriere + internal repo: the single most effective control point — what you publish is what gets installed.
- Monitoring:
node_exporterruns on FreeBSD; exportpkg audit -q | wc -l, pending updates (pkg version -vRL= | wc -l) and a reboot-required flag via the textfile collector.
Quick reference¶
| Task | Command |
|---|---|
| Show installed/running kernel and userland | freebsd-version -kru |
| Fetch base patches + mail root (cron-safe) | freebsd-update cron |
| Fetch/install base patches from a script | freebsd-update --not-running-from-cron fetch install |
| Are fetched base updates waiting? | freebsd-update updatesready |
| Roll back last base update | freebsd-update rollback (or activate the BE) |
| pkgbase: upgrade base only | pkg upgrade -y -r FreeBSD-base |
| Upgrade packages | pkg update && pkg upgrade -y |
| Dry run | pkg upgrade -n |
| Lock / unlock a package | pkg lock -y NAME / pkg unlock NAME |
| Vulnerability audit | pkg audit -F |
| Create / list / activate BE | bectl create NAME / bectl list / bectl activate NAME |
| Update a jail | freebsd-update -j JAIL fetch install, pkg -j JAIL upgrade -y |
| Daily vuln reports | security_status_pkgaudit_enable="YES" in /etc/periodic.conf |