FreeBSD 15.0-RELEASE Upgrade Notes

Overview
Quick Reference Checklist
Upgrade Process
Recovery: If Broken (libsys.so.7 error)
Key Lesson
Verify 15.0 Features
New Features in 15.0
Issues Encountered
- Issue 1: libsys.so.7 Library Ordering Bug
- Issue 2: Unpatched 14.3 Missing EN-25:18 Fix
References
Timeline

Overview

Upgrade notes for FreeBSD 15.0-RELEASE from 14.x.

The 2am upgrade saga: libsys.so.7 error in rescue shell (AI-generated)

Quick Reference Checklist

Step	Action	Time	Notes
1	Patch current system	~5 min	Gets EN-25:18 fix
2	Create ZFS snapshot	~1 min	Recovery point
3	Upgrade kernel	~10 min	Downloads + installs
4	Userland install	10-30 min	DO NOT INTERRUPT
5	Package rebuild	~1 hour	Large installs
6	Finalize	~5 min	Final reboot

Upgrade Process

Step 1: Patch First (Critical)

# Gets EN-25:18 fix - required before upgrade
freebsd-update fetch install
reboot

Step 2: Backup with ZFS Boot Environment

# Create recovery snapshot
bectl create pre-15-upgrade-$(date +%Y%m%d)

# Verify it exists
bectl list

Step 3: Upgrade

freebsd-update -r 15.0-RELEASE upgrade
freebsd-update install
freebsd-update install   # yes, run twice
reboot

Step 4: Userland Installation

WARNING: DO NOT INTERRUPT - takes 10-30 minutes

freebsd-update install

Step 5: Package Rebuild

# Reinstall pkg first
pkg-static install -f pkg

# Force upgrade all packages (~1 hour for large installs)
pkg upgrade -f

Step 6: Finalize

freebsd-update install
reboot

Recovery: If Broken (libsys.so.7 error)

If the system fails to boot or shows libsys.so.7 errors:

# Boot to single user or rescue
/rescue/sh

# Rollback to pre-upgrade snapshot
/rescue/bectl activate pre-15-upgrade-YYYYMMDD

# Reboot to recovered system
/rescue/reboot

Key Lesson

Always patch before major upgrades. EN-25:18 fixes the library ordering bug that bricks systems mid-upgrade.

Verify 15.0 Features

After successful upgrade, verify new features are working:

# 1. Native inotify (Linux-compatible file watches)
kldstat | grep inotify
python3 -c "import inotify; print('inotify works')" 2>/dev/null || \
  echo "Install py311-inotify to test"

# 2. OpenZFS 2.4.0
zpool get version zroot
zfs get all zroot | grep -E "feature@|version"
# New features: fast_dedup, raidz_expansion
zpool get feature@fast_dedup zroot

# 3. OpenSSL 3.5 (post-quantum crypto)
openssl version
openssl list -kem-algorithms | grep -i kyber  # ML-KEM/Kyber

# 4. libsys separation (already working if you're running)
ldd /bin/ls | grep libsys
# Should show: libsys.so.7 => /lib/libsys.so.7

# 5. Check kernel features
sysctl -a | grep -i inotify
dmesg | grep -i "15.0"

# 6. New DRM/GPU drivers (if applicable)
kldstat | grep drm
sysctl hw.dri.0.info 2>/dev/null

New Features in 15.0

Feature	Description
Native inotify	Linux-compatible file notification API
OpenZFS 2.4.0	`fast_dedup`, `raidz_expansion`
OpenSSL 3.5	Post-quantum crypto (~ML-KEM~/Kyber)
`libsys` separation	Cleaner syscall interface
`pkgbase`	Base system installable via `pkg`

Native inotify Support

Linux-compatible file system event notification. Enables tools like inotifywait and improves compatibility with Linux applications expecting inotify.

OpenZFS 2.4.0

fast_dedup - More efficient deduplication
raidz_expansion - Add disks to existing RAID-Z vdevs

OpenSSL 3.5 with Post-Quantum Crypto

Includes ML-KEM (Kyber) key encapsulation for quantum-resistant TLS.

libsys Separation

System call interface separated into libsys.so.7 for cleaner ABI.

pkgbase

Base system components now installable and upgradeable via pkg.

Issues Encountered

Issue 1: libsys.so.7 Library Ordering Bug

Symptom: All binaries fail with "Shared object libsys.so.7 not found"

Cause: Interrupted upgrade or missing EN-25:18 patch

Solution: Patch system BEFORE upgrade (EN-25:18), or recover manually:

/rescue/tar xf base.txz lib/libsys.so.7
/rescue/cp lib/libsys.so.7 /lib/
/rescue/ldconfig /lib /usr/lib

Issue 2: Unpatched 14.3 Missing EN-25:18 Fix

Symptom: Upgrade hangs/fails even without interruption

Solution: Always run freebsd-update fetch install and reboot before major upgrades

References

Timeline

Date	Action	Status
2026-01-11	Upgrade attempt #1 (Ctrl-C broke)	Failed
2026-01-24	Upgrade attempt #2 (bug hit)	Failed
2026-01-25	Manual recovery + package rebuild	Complete