Stop Booting Into a Dead Mount: Practical systemd.mount Units on Linux

You add a secondary disk for /data, drop a line in /etc/fstab, and reboot. One of three things happens:

1. Everything mounts cleanly.
2. Boot stalls for the default start timeout while systemd waits on a missing UUID.
3. The machine comes up, but a critical path is empty and services write into the underlying directory instead of the volume you meant to attach.

fstab is still the right human-facing format. Under systemd it is not “just mount(8) at boot” — systemd-fstab-generator turns each entry into a native .mount (and sometimes .automount / .swap) unit with real dependency edges, timeouts, and failure semantics.

This guide is operational. Behavior comes from systemd.mount(5), systemd-fstab-generator(8), systemd-mount(1), systemd-escape(1), and stock units on systemd 257 (verified on Debian 13).

What a mount unit is (and is not)

A mount unit does not replace:

• LUKS unlock (crypttab / systemd-cryptenroll) or integrity layers (dm-verity, dm-integrity),
• volume managers deciding which block device is the source,
• NFS-only “stop blocking boot with remote shares” workflows that live primarily on .automount (covered separately).

It does replace “hope mount -a in a boot script is enough,” and it makes every mount visible to systemctl, the journal, and ordering against local-fs.target / remote-fs.target.

Mental model

• Unit name must match the mount point, escaped: /data/backup → data-backup.mount.
• [Mount] needs at least What= and Where=. Optional: Type=, Options=, TimeoutSec=, DirectoryMode=, …
• Local mounts order into local-fs.target. Network mounts (by FS type or _netdev) order into remote-fs.target and pull network-online.target.
• nofail turns the dependency into a weak Wants= and drops ordering before the fs target — boot continues if the volume is gone.
• noauto means nothing pulls the mount at boot unless another unit does.
• Parent mounts imply child requirements automatically (hierarchy edges).
• Runtime mounts (USB sticks, manual mount) still show up as mount units via /proc/self/mountinfo.

Prerequisites

systemctl --version | head -n 1 # systemd 257 (… Debian 13) man systemd.mount man systemd-fstab-generator man systemd-mount man systemd-escape systemctl list-units --type=mount --all --no-pager 

Stock examples already on a typical host:

systemctl cat tmp.mount # [Mount] # What=tmpfs # Where=/tmp # Type=tmpfs # Options=mode=1777,strictatime,nosuid,nodev,size=50%%,nr_inodes=1m 

Note the doubled %% in unit files — percent is a specifier character; a literal % must be written %% (systemd.mount(5)).

Naming: always use systemd-escape

Hand-rolling unit names is how you get not-found units and silent mismatches.

# Mount unit for a path systemd-escape -p --suffix=mount "/data/backup" # data-backup.mount systemd-escape -p --suffix=mount "/mnt/My Disk" # mnt-My\x20Disk.mount # Undo systemd-escape -u --path 'data-backup' # data/backup 

Rules that matter in practice (systemd.unit(5) / systemd-escape(1)):

• Leading / is dropped; remaining / become -.
• Use -p / --path so ., //, and trailing slashes are normalized first.
• Mount units cannot be templated and cannot gain extra names via symlinks.
• Where= must be an absolute path and must not be a symlink (the generator resolves fstab symlink targets for compatibility; native units refuse symlink destinations).

Anatomy of a .mount unit

# /etc/systemd/system/data-lyra.mount [Unit] Description=Lyra data volume Documentation=man:systemd.mount(5) # Optional explicit ordering beyond the defaults: # After=local-fs-pre.target # Before=local-fs.target  [Mount] What=/dev/disk/by-uuid/11111111-2222-3333-4444-555555555555 Where=/data/lyra Type=ext4 Options=defaults,noatime # DirectoryMode=0755 # TimeoutSec=30s # ReadWriteOnly=no # LazyUnmount=no # ForceUnmount=no # SloppyOptions=no  [Install] WantedBy=local-fs.target 

User= / Group= are not useful here: systemd invokes mount(8) with What and Where as UID 0 and does not re-read fstab inside that call.

fstab is still fine — learn the x-systemd knobs

Humans often prefer /etc/fstab. Tooling and image builders often prefer unit files under /etc. Precedence (systemd.mount(5)):

• Unit in /etc wins over fstab.
• fstab wins over units shipped under /usr.

Generator: /usr/lib/systemd/system-generators/systemd-fstab-generator (also on daemon-reload).

Options that change boot behavior

Example — secondary data disk that must not stall boot if unplugged:

UUID=11111111-2222-3333-4444-555555555555 /data/lyra ext4 defaults,noatime,nofail,x-systemd.device-timeout=5s,x-systemd.mount-timeout=15s 0 2 

Example — image appliance partition that should format once and grow forever after repart:

/dev/disk/by-partuuid/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee /var/lib/myapp ext4 defaults,x-systemd.makefs,x-systemd.growfs 0 2 

x-systemd.makefs / growfs / device-timeout / mount-timeout / pcrfs are fstab-only — putting them in a unit file’s Options= is ignored. In unit files, use the native settings (TimeoutSec=, companion services, etc.).

Network mounts and the old NFS bg flag

Network FS types get remote-fs-pre.target → network-online.target → remote-fs.target edges. _netdev forces that path for “local-looking” network block devices.

Classic NFS bg is rewritten by the generator roughly as:

• prepend x-systemd.mount-timeout=infinity,retry=10000
• append fg,nofail

For on-demand remote shares, x-systemd.automount is usually clearer than bg.

Inspect what the generator actually built

systemctl daemon-reload # Generated unit text (when the unit is known) systemctl cat data-lyra.mount # Or peek at generator output directly ls /run/systemd/generator/*.mount 2>/dev/null systemctl show -p Where,What,Options,Type,TimeoutUSec,Requires,Wants,After,Before data-lyra.mount findmnt /data/lyra journalctl -u data-lyra.mount -b --no-pager 

Kernel cmdline escapes for one-off/extra mounts without editing fstab (systemd-fstab-generator(8), 254+):

systemd.mount-extra=/dev/sda1:/mnt/extra:ext4:rw,noatime 

Credential fstab.extra can carry additional fstab-format lines (254+).

Lab 1 — Local ext4 mount unit on a loop file

Safe on any host with free space under /var/tmp. No real disks required.

sudo mkdir -p /var/tmp/lyra-mount-lab /mnt/lyra-lab sudo fallocate -l 512M /var/tmp/lyra-mount-lab/disk.img sudo mkfs.ext4 -F -L lyra-lab /var/tmp/lyra-mount-lab/disk.img # Stable What= via loop + label after first attach, or mount the file via Type=ext4: UNIT=$(systemd-escape -p --suffix=mount /mnt/lyra-lab) echo "$UNIT" # mnt-lyra-lab.mount sudo tee /etc/systemd/system/mnt-lyra-lab.mount >/dev/null <<'EOF' [Unit] Description=Lyra lab ext4 mount (loop file) [Mount] What=/var/tmp/lyra-mount-lab/disk.img Where=/mnt/lyra-lab Type=ext4 Options=loop,defaults,noatime TimeoutSec=20s [Install] WantedBy=multi-user.target EOF sudo systemctl daemon-reload sudo systemctl enable --now mnt-lyra-lab.mount systemctl status mnt-lyra-lab.mount --no-pager findmnt /mnt/lyra-lab echo 'hello from lyra mount lab' | sudo tee /mnt/lyra-lab/hello.txt 

Stop and prove the unit owns the lifecycle:

sudo systemctl stop mnt-lyra-lab.mount findmnt /mnt/lyra-lab || echo 'unmounted' sudo systemctl start mnt-lyra-lab.mount cat /mnt/lyra-lab/hello.txt 

Lab 2 — nofail vs required: don’t stall boot on optional media

Simulate “device missing” without rebooting by pointing What= at a nonexistent UUID:

sudo tee /etc/systemd/system/mnt-lyra-optional.mount >/dev/null <<'EOF' [Unit] Description=Lyra optional mount (nofail-style) DefaultDependencies=no Conflicts=umount.target Before=local-fs.target umount.target After=local-fs-pre.target # Weak pull-in — same idea as fstab nofail: Wants=local-fs.target # Intentionally NOT: RequiredBy=local-fs.target / Before hard-require [Mount] What=/dev/disk/by-uuid/00000000-0000-0000-0000-000000000000 Where=/mnt/lyra-optional Type=ext4 Options=defaults TimeoutSec=5s [Install] WantedBy=local-fs.target EOF sudo mkdir -p /mnt/lyra-optional sudo systemctl daemon-reload sudo systemctl start mnt-lyra-optional.mount echo exit:$? systemctl status mnt-lyra-optional.mount --no-pager || true journalctl -u mnt-lyra-optional.mount -n 20 --no-pager 

You should see a failed mount unit quickly (device timeout / mount failure), not a multi-minute hang. With fstab nofail, local-fs.target still reaches active even when that mount fails; without nofail, a missing required disk can hold the boot transaction until timeouts cascade.

Equivalent fstab form:

UUID=00000000-0000-0000-0000-000000000000 /mnt/lyra-optional ext4 defaults,nofail,x-systemd.device-timeout=5s,x-systemd.mount-timeout=5s 0 0 

Lab 3 — Transient mounts with systemd-mount

For USB sticks, one-off images, and scripts, skip unit files:

# List candidate filesystems systemd-mount --list # Mount lab image to an explicit path (two-arg form: no probe required) sudo systemd-mount \ --type=ext4 \ --options=loop,noatime \ --description='Lyra transient lab' \ --collect \ /var/tmp/lyra-mount-lab/disk.img \ /mnt/lyra-transient findmnt /mnt/lyra-transient systemctl status "$(systemd-escape -p --suffix=mount /mnt/lyra-transient)" --no-pager # Automount + idle unmount (stays clean until first access) sudo systemd-umount /mnt/lyra-transient sudo systemd-mount -A --timeout-idle-sec=30s --collect \ --type=ext4 --options=loop \ /var/tmp/lyra-mount-lab/disk.img \ /mnt/lyra-auto # First access triggers the real mount: ls /mnt/lyra-auto # After idle, systemd detaches the backing FS again. # tmpfs helper (255+) sudo systemd-mount --tmpfs lyra-tmp /mnt/lyra-tmpfs sudo systemd-umount /mnt/lyra-tmpfs 

Useful flags from systemd-mount(1):

udev pattern from the man page for auto USB mounts:

ACTION=="add", SUBSYSTEMS=="usb", SUBSYSTEM=="block", ENV{ID_FS_USAGE}=="filesystem", \ RUN{program}+="/usr/bin/systemd-mount --no-block --automount=yes --collect $devnode" 

Dependencies services should declare

Prefer path-based deps over hard-coding generated unit names:

# in myapp.service [Unit] RequiresMountsFor=/data/lyra # or softer: # WantsMountsFor=/data/lyra 

That pulls the right .mount units (and parents) without fragile string coupling. Hierarchy still adds implicit Requires/After between nested mounts.

Failure modes worth memorizing

1. Wrong unit name — Where=/data/lyra but file named data.lyra.mount → unit never matches the path.
2. Symlink mount point — rejected; generator tries to resolve fstab symlinks, native units do not accept symlink Where=.
3. Missing disk without nofail — boot waits on device + mount timeouts.
4. Services start against an empty under-mount — declare RequiresMountsFor= or order After= the mount unit.
5. x-systemd.* in unit Options= — several fstab-only keys are silently ignored outside fstab.
6. Literal % in options — write size=50%% not size=50% in unit files (tmp.mount does this).
7. Nested automounts — unsupported; the inner pin defeats the outer.
8. API filesystems — some kernel API mounts cannot be disabled via mount units (systemd.io/API_FILE_SYSTEMS).
9. Volume manager paths — consider x-systemd.device-bound=false so teardown does not race the VM stack.

Cleanup the labs

sudo systemctl disable --now mnt-lyra-lab.mount mnt-lyra-optional.mount 2>/dev/null || true sudo rm -f /etc/systemd/system/mnt-lyra-lab.mount /etc/systemd/system/mnt-lyra-optional.mount sudo systemctl daemon-reload sudo systemd-umount /mnt/lyra-transient /mnt/lyra-auto /mnt/lyra-tmpfs 2>/dev/null || true sudo umount /mnt/lyra-lab 2>/dev/null || true sudo rm -rf /var/tmp/lyra-mount-lab /mnt/lyra-lab /mnt/lyra-optional /mnt/lyra-transient /mnt/lyra-auto /mnt/lyra-tmpfs sudo systemctl reset-failed 'mnt-lyra-*' 2>/dev/null || true 

What this is not

• Not a deep dive on NFS automount idle unmounts as the primary workflow (.automount + remote shares).
• Not LUKS/TPM unlock, multipath, LVM thin, or Btrfs send/receive.
• Not systemd-gpt-auto-generator Discoverable Partitions policy (sibling of fstab generation).
• Not tmpfiles path creation policy (systemd-tmpfiles) — mounts attach filesystems; tmpfiles lays out directories inside them.

References

• systemd.mount(5) — mount unit settings, fstab x-systemd.* options, default dependencies
• systemd.automount(5) — companion on-demand units, TimeoutIdleSec=
• systemd-fstab-generator(8) — fstab → units, systemd.mount-extra=, fstab.extra, volatile modes
• systemd-mount(1) / systemd-umount — transient mount/automount helpers
• systemd-escape(1) — path → unit name escaping
• systemd.unit(5) — RequiresMountsFor=, specifiers, unit naming
• fstab(5), mount(8), umount(8)
• Stock tmp.mount on systemd 257 (Debian 13)
• API file systems notes: https://systemd.io/API_FILE_SYSTEMS

Treat mounts as first-class units: named, ordered, timed, and observable. Keep fstab for the simple cases, reach for native .mount files and systemd-mount when tooling or transient workflows need a sharper edge — and put nofail + device timeouts on every volume that should not be allowed to hold the boot hostage.