FreeBSD 12 – Common Problem 009 – ZFS Datasets Mount at Wrong Paths

📖 ~1 min read

Table of contents

1. Symptom & Impact
2. Environment & Reproduction
3. Root Cause Analysis
4. Quick Triage
5. Step-by-Step Diagnosis
6. Solution – Primary Fix
7. Solution – Alternative Approaches
8. Verification & Acceptance Criteria
9. Rollback Plan
10. Prevention & Hardening
11. Related Errors & Cross-Refs
12. References & Further Reading

Symptom & Impact

Applications read or write to unexpected directories, causing service failures.

Environment & Reproduction

After clone/import operations, dataset properties differ from intended layout.

Root Cause Analysis

Incorrect `mountpoint` or `canmount` values lead to mount collisions.

Quick Triage

List active mounts and dataset properties.

mount | grep zfs
zfs list -o name,mountpoint,canmount
zfs get -r mountpoint tank

Step-by-Step Diagnosis

Identify inherited properties and conflicting paths.

zfs get -r canmount,mountpoint tank
ls -ld /srv /var/db
service zfs status

Solution – Primary Fix

Set explicit properties and remount datasets cleanly.

zfs set mountpoint=/srv tank/apps
zfs set canmount=on tank/apps
zfs mount -a

Solution – Alternative Approaches

Use `canmount=noauto` for stage datasets and mount from service scripts only when needed.

Verification & Acceptance Criteria

Mount table matches design and application paths resolve correctly after reboot.

Rollback Plan

Reapply prior property values from change log and remount datasets.

Prevention & Hardening

Document dataset hierarchy and enforce property checks in deployment pipelines.

Related Errors & Cross-Refs

`dataset is busy`, path shadowing, services writing into root filesystem.

Related tutorial: View the step-by-step tutorial for freebsd-12.

View all freebsd-12 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

`zfsprops(7)`, `zfs-mount-generator` notes, FreeBSD ZFS handbook sections.