Andrew Mercer
on this page

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

  1. Which base-system method are you using?
  2. Built-in: periodic(8) security reporting
  3. Base system with freebsd-update
  4. Base system with pkgbase (FreeBSD 15+)
  5. Third-party packages with pkg
  6. Boot environments: the safety net
  7. A complete unattended update script
  8. Restarting services and rebooting
  9. Jails
  10. Quarterly vs. latest package branches
  11. Mail delivery for reports
  12. Fleet orchestration
  13. 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 kernel from Components, 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 → -p2 style patches within a release. Minor/major release upgrades (freebsd-update -r 15.1-RELEASE upgrade) involve /etc merges and multiple install passes — never automate those.
  • EOL releases stop receiving patches. Unattended updates on an EOL minor release silently do nothing; monitor freebsd-update output or the release's EOL date and plan minor upgrades.
  • Kernel patches need a reboot. Compare freebsd-version -k (installed) with freebsd-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-update for now and use pkgbase on less critical hosts.
  • Always create a boot environment before pkg upgrade on 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 /etc changes: 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 nginx minor, or PHP/Python/Ruby default version changes) can happen at quarterly branch rollovers. Always read /usr/ports/UPDATING or 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/run is 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.pkgng for packages; ansible.builtin.command: freebsd-update --not-running-from-cron fetch install for base; use serial: and a reboot task when freebsd-version -k ≠ -r.
  • Salt / Puppet / CFEngine: all have FreeBSD pkg support.
  • Poudriere + internal repo: the single most effective control point — what you publish is what gets installed.
  • Monitoring: node_exporter runs on FreeBSD; export pkg 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