Fix wrong fs type, bad option, bad superblock and configure reliable mounts
The mount error “wrong fs type, bad option, bad superblock” is a summary, not a diagnosis of corruption. Identify the exact storage layer, read the kernel reason, and separate missing helpers or invalid options from real damage before configuring UUID-based systemd mounts.
Identify the actual cause of a failed data-filesystem mount without modifying uncertain storage, then, only for a verified healthy non-root ext4 filesystem, configure and test recoverable UUID-based systemd activation.
- Ubuntu Server 24.04 LTS
- systemd 255
- util-linux 2.39
- Independent recovery path Keep provider console, hypervisor console, serial console, or physical access available until a real reboot has proved the entry. A malformed root-adjacent mount can delay boot or hide expected data.
Record a successful console login before editing /etc/fstab. - Existing filesystem with known ownership This procedure mounts an already-created ext4 filesystem. Confirm the block device is not a member of LVM, RAID, encryption, swap, or another active stack and that its data has a current backup.
sudo lsblk --fs --output NAME,PATH,FSTYPE,UUID,LABEL,MOUNTPOINTS - Stable mount contract Choose a dedicated empty mount point and document which services consume it, whether absence may be tolerated, and whether on-demand latency is acceptable.
sudo findmnt --target {{mountPoint}}; sudo ls -la {{mountPoint}}
OneLiners never runs these steps or stores secrets. Review placeholders, versions, current state, and change-control requirements before using a command.
Full guide
What you will build
- A UUID-addressed ext4 mount contract in `/etc/fstab` that does not depend on volatile kernel device names.
- A generated systemd automount that activates on first access, releases after an idle interval, and limits how long a missing optional device can delay callers.
- A recovery package containing the original fstab, deterministic validation commands, success evidence, and an unavailable-device rehearsal.
- A read of the declared path mounts exactly the planned filesystem and exposes the expected UUID, type, and hardening options.
- A detached optional device does not force the host into emergency mode; the failure is bounded, visible in the journal, and recoverable from console.
- The configuration survives a controlled reboot and can be rolled back without editing an unknown fstab under pressure.
Architecture
How the parts fit together
The filesystem UUID is the durable identity, `/etc/fstab` is the declarative contract, systemd-fstab-generator converts that contract into mount and automount units, and the VFS path is the activation boundary. An access to the path reaches the automount unit, which waits only for the configured device timeout, mounts the ext4 filesystem with constrained options, and returns it to an idle state later. Console recovery and a preserved fstab remain outside that chain.
- The operator resolves the physical device and ext4 metadata to one reviewed UUID and confirms that no active storage layer owns it.
- A stable, non-symlink target is prepared and the original fstab is saved with a checksum.
- The fstab entry declares UUID, path, ext4, hardening, nofail, on-demand activation, bounded device wait, and idle timeout.
- findmnt parses the complete contract before systemd regenerates transient units.
- The `.automount` unit waits at the path; the first directory access starts the `.mount` unit.
- findmnt evaluates the live source back to the planned UUID, while a canary with a missing device proves bounded failure and continued boot.
Assumptions
- The target is an optional non-root ext4 data filesystem. Root, `/usr`, critical database storage, clustered filesystems, encrypted layers, and network mounts need different availability decisions.
- The filesystem already exists and its contents are backed up; this guide does not partition, format, resize, decrypt, or repair it.
- The chosen mount point is not already populated with required files and is not a symlink, bind mount, container-managed path, or namespace-specific mount.
- The consuming service tolerates an on-demand activation delay and a clear I/O error when the device is unavailable; it does not silently write important data into the underlying directory.
- Ubuntu 24.04 uses systemd-generated fstab units and util-linux tools compatible with the shown validation commands.
Key concepts
- Filesystem UUID
- An identifier stored in filesystem metadata. It follows the filesystem when kernel device names change, but cloning a filesystem can duplicate it and therefore still requires inventory review.
- Mount point shadowing
- When a filesystem is mounted over a non-empty directory, the underlying files become hidden until unmount. They are not deleted, which can mislead services and capacity investigations.
- systemd automount
- A kernel autofs trigger represented by a systemd `.automount` unit. First access starts the same-path `.mount` unit without requiring the filesystem at initial boot.
- nofail
- An fstab policy indicating that absence of this optional device must not make local-fs.target fail or hold boot as a required dependency.
- Device timeout
- The maximum wait for the backing UUID device to appear. It limits a failure but does not make lost storage safe for applications.
- fs_passno
- The sixth fstab field that orders filesystem checks. Root conventionally uses 1, other checkable local filesystems use 2, and 0 disables boot-time checking.
Fill these once. Every matching command and configuration block updates immediately; values stay in this page only.
Security and production boundaries
- `nosuid` and `nodev` reduce executable privilege and device-node exposure on general data volumes, but can break workloads that genuinely require those semantics. `noexec` is not used because scripts and interpreters can have nuanced behavior; add it only after application testing.
- An fstab edit is privileged boot policy. Keep it root-owned, avoid secrets in mount options, and never paste network credentials directly into the file.
- UUIDs are stable identifiers, not proof of trusted content. A copied or attacker-controlled filesystem can carry a duplicated UUID; corroborate model, serial, expected content, and change history.
- Automount can make a missing filesystem look like a temporarily empty path to poorly written software. Configure consumers to fail closed and monitor the mount unit rather than treating directory existence as readiness.
Stop before continuing if
- Stop if the device identity is ambiguous, the UUID is duplicated, the filesystem is mounted elsewhere, or another storage manager owns it.
- Stop if `e2fsck -n` reports corruption requiring repair; take a block-level backup and follow filesystem recovery procedures while unmounted.
- Do not write an entry when the target contains unexplained files, is a symlink, or is already consumed by a running service.
- Do not reload or reboot when `findmnt --verify` reports any warning or error anywhere in fstab.
- Abort the rollout if the missing-device canary prevents normal boot, if activation exceeds the declared bound, or if applications write into the uncovered mount point.
command
Capture wrong fs type, bad option, bad superblock without retrying writes
Retain the original error and the kernel lines at the same timestamp. Do not rerun a failing mount repeatedly, especially when storage reports I/O errors. The message groups several different failure classes under one summary; its final words do not establish that a superblock is damaged.
Why this step matters
Userspace mount and the kernel expose different levels of detail. Correlation prevents a generic error from being mistaken for proof of data loss.
What to understand
Record the full device ancestry, size and expected owner. An encrypted container, LVM physical volume, RAID member and the filesystem inside the assembled stack are different objects. A valid signature on the wrong layer is not permission to overwrite or format that object.
If the kernel shows medium errors, reset loops, device disappearance or repeated unreadable sectors, stop extensive scans and involve the storage/recovery owner. A full metadata scan can stress a failing drive even when the tool requests no writes. Preserve a verified image or snapshot under a recovery plan before deeper analysis.
System changes
- Reads existing kernel, device or mount metadata; it does not mount, format or repair a filesystem.
Syntax explained
--since '-15 minutes' | tail -n 100- Limits journal output to a recent interval and at most 100 retained lines; choose the actual incident interval if it differs.
--output- Requests explicit device identity and mount fields for comparison.
date --iso-8601=seconds; sudo journalctl -k --since '-15 minutes' --no-pager | tail -n 100; lsblk --output NAME,PATH,TYPE,SIZE,FSTYPE,UUID,MOUNTPOINTS; findmnt --real --output SOURCE,TARGET,FSTYPE,OPTIONSIllustrative evidence, not an executed recovery: mount: /srv/data: wrong fs type, bad option, bad superblock on /dev/mapper/data, missing codepage or helper program, or other error. Kernel: EXT4-fs (dm-2): Unrecognized mount option "compression" or missing value Interpretation: inspect the option mismatch before considering filesystem repair.
Checkpoint: Failure classified far enough to inspect safely
Continue whenThe original error, timestamp, kernel explanation and intended storage identity agree.
Stop whenThe device is ambiguous, belongs to another workload, is failing physically, or cannot be preserved.
command
Inspect signatures and configuration at the confirmed layer
Inspect the explicitly identified block object and compare its type with the proposed fstab entry. These commands report signatures and parse the mount configuration; they do not erase signatures or activate mounts. Do not add wipefs -a, mkfs, or repair flags to this diagnostic sequence.
Why this step matters
Probing identifies what is actually on disk; an fstab label describes only what somebody intended.
What to understand
A crypto_LUKS, LVM2_member or linux_raid_member result directs the investigation to authorized assembly or unlocking of that layer. Do not try random filesystem drivers on a container. A network filesystem also needs the correct userspace helper and reachable server; absence of a local block signature is expected there.
A known healthy filesystem with an unsupported option should be repaired through its authoritative configuration, with a backup and syntax validation. Unsupported features may instead mean the recovery environment is too old. Choose a supported tool/kernel matching the filesystem rather than deleting feature flags or assuming all filesystems use e2fsck.
System changes
- Reads existing kernel, device or mount metadata; it does not mount, format or repair a filesystem.
Syntax explained
blkid -p- Probes on-device metadata at the chosen object rather than trusting the cached description.
wipefs --no-act- Reports signatures without applying signature erasure.
findmnt --verify --verbose- Checks fstab syntax and usability without mounting its entries.
Values stay on this page and are never sent or saved.
sudo blkid -p '{{devicePath}}'; sudo wipefs --no-act '{{devicePath}}'; findmnt --fstab --evaluate --output SOURCE,TARGET,FSTYPE,OPTIONS; sudo findmnt --verify --verboseIllustrative branch evidence: /dev/mapper/data: UUID="7f3d2c8a-6637-4cb0-a7d4-1c0f71e9be21" TYPE="ext4" /dev/mapper/data 0x438 ext4 fstab: UUID=... /srv/data ext4 compression 0 2 The signatures and option disagree; no format or superblock rewrite is indicated.
Checkpoint: Correct tool family selected
Continue whenDevice layer, actual filesystem, supported tools and configuration mismatch are explicit.
Stop whenMultiple conflicting signatures, unknown filesystem features or a mismatch with the storage inventory remains unexplained.
decision
Choose configuration repair or offline recovery, not a blanket fsck
For a confirmed option or helper problem, correct that one cause and use the existing validation/activation steps below. For suspected metadata corruption, stop the setup workflow. Preserve the original and assess an unmounted recovery copy with the filesystem-specific tool and a recovery owner.
Why this step matters
Configuration correction and data recovery have different risks and different rollback boundaries.
What to understand
Mounting with ro alone is not a universal no-write guarantee: ext4 can replay its journal. A forensic no-replay mount has filesystem-specific options and limitations, and belongs in an approved recovery procedure on a copy. Do not describe a successful read-only mount as proof that every file is intact.
Never run a repairing filesystem check against a mounted filesystem. Even a no-write checker on a changing mounted volume can report inconsistent results. Confirm all namespaces and users are quiesced, retain backups and record tool versions. Do not copy an alternative-superblock number from an unrelated disk or run an automatic yes-to-all repair from a generic tutorial.
After a configuration repair, verify source UUID, expected filesystem, mount options and access by the actual workload. Test a known disposable application operation only when a write test is authorized. Keep recovery images until the owner has accepted data integrity; restoring fstab cannot undo a metadata repair or recover overwritten data.
System changes
- This decision does not execute a repair. Configuration changes and offline data recovery require separate approval and verification.
Decision record example: Cause: unsupported ext4 mount option; no I/O faults in the retained interval. Approved change: remove only that option from the reviewed fstab entry. Alternative: suspected metadata damage → preserved image, offline specialist assessment; no production write repair.
Checkpoint: Repair has an explicit scope
Continue whenEither the healthy-filesystem setup path is approved, or a separate offline recovery plan has taken ownership.
Stop whenThe only proposed fix is mkfs, wipefs -a, fsck -y, an unverified backup superblock or repeated mounting of a failing original.
verification
Inventory the device, filesystem, and current mount state
Resolve the candidate disk from independent facts such as size, model, serial, filesystem type, and an existing label. Do not infer identity from `/dev/sdX`, because enumeration can change after a reboot or hardware event.
Why this step matters
Mount reliability starts with identity. Device paths can be reassigned, while an unexplained duplicate UUID or an already-owned block device can turn a harmless configuration change into data corruption.
What to understand
Compare size, model context, filesystem type, label, UUID, existing targets, and the storage change record. Treat every mismatch as a blocker.
`lsblk` shows the topology, `blkid` reads signatures, and `findmnt --real` shows live kernel mounts. The three views answer different questions and should agree.
Record the source path under `/dev/disk/by-uuid` and verify that it resolves to the reviewed partition.
System changes
- No persistent change; reads udev, filesystem signatures, and the live mount table.
Syntax explained
lsblk --fs- Displays filesystem metadata and block topology without mounting devices.
blkid- Probes recognized filesystem and partition signatures, including UUID and type.
findmnt --real- Restricts output to real filesystems currently mounted by the kernel.
sudo lsblk --fs --output NAME,PATH,SIZE,FSTYPE,UUID,LABEL,MOUNTPOINTS && sudo blkid && sudo findmnt --real --output SOURCE,TARGET,FSTYPE,OPTIONSNAME PATH SIZE FSTYPE UUID LABEL MOUNTPOINTS sdb1 /dev/sdb1 200G ext4 7f3d2c8a-6637-4cb0-a7d4-1c0f71e9be21 data /dev/sdb1: LABEL="data" UUID="7f3d2c8a-6637-4cb0-a7d4-1c0f71e9be21" BLOCK_SIZE="4096" TYPE="ext4" SOURCE TARGET FSTYPE OPTIONS /dev/sda2 / ext4 rw,relatime
Checkpoint: Approve one source identity
Continue whenExactly one reviewed ext4 filesystem owns {{filesystemUuid}} and it has no conflicting live target.
Stop whenThe UUID is absent, duplicated, mounted elsewhere, or belongs to another storage layer.
If this step fails
Two devices report the same filesystem UUID.
Likely causeA disk or VM image was cloned at block level.
sudo blkidls -l /dev/disk/by-uuid/
ResolutionKeep only one clone attached or assign a new filesystem UUID during a controlled offline procedure; never let an ambiguous symlink choose production data.
Security notes
- Inventory output can reveal device serials and data labels; redact it before external sharing.
Alternatives
- Use an approved storage inventory or udev property report when physical serial correlation is required.
Stop conditions
- No change proceeds without a unique, corroborated filesystem identity.
verification
Confirm that the filesystem is idle and internally consistent
Run this check only for the verified ext4 filesystem in the offline, quiesced environment approved above, with a preservation copy already available. The guard stops when findmnt sees a mounted source or returns an inspection error. It does not inspect every namespace or prevent another process from mounting the device; those are operational prerequisites, not guarantees provided by the shell snippet. A no-write e2fsck result on a changing mounted filesystem is not valid evidence.
Why this step matters
A mount policy must not conceal pre-existing filesystem damage. Read-only checking while unmounted establishes that later errors are not incorrectly attributed to systemd or fstab.
What to understand
`findmnt` and `fuser` protect against checking an active filesystem; a nonempty result means the maintenance state is not ready.
`e2fsck -f -n` forces a complete check while answering no to changes. It provides evidence but does not repair damage.
System changes
- No intended write; e2fsck is instructed not to modify the unmounted ext4 filesystem.
Syntax explained
-f- Checks even when the filesystem metadata says it is clean.
-n- Answers no to repair prompts and keeps the inspection read-only.
fuser --mount- Reports processes using the filesystem or mount device.
Values stay on this page and are never sent or saved.
( sudo findmnt --source 'UUID={{filesystemUuid}}'; mount_check=$?; case "$mount_check" in 0) printf '%s\n' 'STOP: filesystem is mounted';; 1) printf '%s\n' 'Continue only after all namespaces are quiesced and preservation is confirmed'; sudo e2fsck -fn '/dev/disk/by-uuid/{{filesystemUuid}}';; *) printf '%s\n' 'STOP: mount-state inspection failed';; esac )e2fsck 1.47.0 (5-Feb-2023) Pass 1: Checking inodes, blocks, and sizes Pass 2: Checking directory structure Pass 3: Checking directory connectivity Pass 4: Checking reference counts Pass 5: Checking group summary information data: 142/13107200 files, 1049123/52428800 blocks
Checkpoint: Accept filesystem health
Continue whenAll five ext4 passes complete without an inconsistency requiring repair.
Stop whenThe filesystem is active, I/O errors appear, or e2fsck requests repair.
If this step fails
e2fsck reports an aborted journal or inode errors.
Likely causeUnclean removal, failing media, or existing corruption.
sudo smartctl -a /dev/sdbjournalctl -k -b | grep -iE 'I/O error|ext4'
ResolutionTake a recoverable image or backup, evaluate hardware health, and perform filesystem repair in a separate approved recovery procedure.
Security notes
- Filesystem checks can expose labels and counts but should never require publishing file contents.
Alternatives
- Use the filesystem vendor's read-only checker for XFS, Btrfs, or another type; do not run e2fsck against them.
Stop conditions
- Do not mount a filesystem whose integrity or device health is unresolved.
command
Create and protect the stable mount point
Create the path before activating any unit, verify it is a real directory rather than a symlink, and set ownership for the service that will use the mounted filesystem. This example leaves the directory root-owned until application ownership is deliberately assigned.
Why this step matters
A stable, empty, non-symlink path is part of the storage interface. Preparing it explicitly prevents path substitution and makes underlying-directory ownership visible before mount shadowing occurs.
What to understand
`install -d` creates the complete path with explicit owner, group, and mode in one auditable operation.
`namei -l` displays every path component so a symlink or unexpectedly writable parent cannot hide in the pathname.
System changes
- Creates {{mountPoint}} and any missing parent directory with declared metadata; it does not mount the filesystem.
Syntax explained
-d- Creates a directory rather than a regular file.
-o root -g root- Sets ownership without relying on the caller's defaults.
-m 0755- Allows traversal while reserving directory modification for root.
Values stay on this page and are never sent or saved.
sudo install -d -o root -g root -m 0755 {{mountPoint}} && sudo namei -l {{mountPoint}}f: /srv/data drwxr-xr-x root root / drwxr-xr-x root root srv drwxr-xr-x root root data
Checkpoint: Approve the target path
sudo namei -l {{mountPoint}} && sudo find {{mountPoint}} -mindepth 1 -maxdepth 1 -printContinue whenEvery component is a real directory with understood ownership and the target has no unexplained entries.
Stop whenThe path is a symlink, crosses another mount, is world-writable, or contains data.
If this step fails
The target contains files.
Likely causeAn application already used the directory before storage was mounted.
sudo findmnt --target /srv/datasudo du -shx /srv/datasudo lsof +D /srv/data
ResolutionStop the owning service, classify and back up the files, and choose a migration or a different empty mount point. Never cover unexplained data.
Security notes
- Do not make the empty directory writable to the application; otherwise it may accept writes when the real filesystem is absent.
Alternatives
- Create a service-specific target under `/srv` or `/var/lib` according to the application's filesystem contract.
Stop conditions
- Stop when path ownership or existing contents cannot be attributed.
command
Back up fstab and record its checksum
Create a timestamped, root-readable copy before changing the boot mount contract. A checksum makes it clear which pre-change version should be restored during console recovery.
Why this step matters
A local, checksum-recorded pre-change copy enables deterministic recovery from console and prevents an operator from reconstructing boot policy from memory during an outage.
What to understand
`cp --archive` preserves metadata and content. The fixed backup name is intentionally visible to the rollback instructions; preserve older change records elsewhere.
Mode 0600 limits accidental disclosure of mount paths or credentials that legacy entries may contain.
System changes
- Creates `/etc/fstab.pre-oneliners` as a protected copy of current fstab.
Syntax explained
--archive- Preserves mode, ownership, timestamps, and content.
sha256sum- Creates a content fingerprint for the change record.
sudo cp --archive /etc/fstab /etc/fstab.pre-oneliners && sudo chmod 0600 /etc/fstab.pre-oneliners && sudo sha256sum /etc/fstab /etc/fstab.pre-oneliners55c899d4c48b878ef6e18679e612d209bb52ca4a71cec1639a306e4e0cf88cf1 /etc/fstab 55c899d4c48b878ef6e18679e612d209bb52ca4a71cec1639a306e4e0cf88cf1 /etc/fstab.pre-oneliners
Checkpoint: Prove a byte-identical backup
Continue whenBoth displayed SHA-256 hashes are identical and the backup is mode 0600 owned by root.
Stop whenThe copy differs, storage is full, or the backup path already holds an unreviewed version.
If this step fails
The destination exists with a different checksum.
Likely causeA previous unfinished mount change used the same recovery filename.
sudo stat /etc/fstab.pre-onelinerssudo diff -u /etc/fstab.pre-oneliners /etc/fstab
ResolutionArchive the earlier change artifact with its ticket, then create and verify a fresh pre-change copy.
Security notes
- Never copy fstab into a world-readable home or chat transcript; legacy network entries may contain sensitive options.
Alternatives
- Use version-controlled configuration management with a tested console rollback, while still retaining a known-good local copy during the first reboot.
Stop conditions
- No edit proceeds without a recoverable pre-change file.
config
Add a bounded UUID-based automount entry
Add exactly one reviewed line. `nofail` prevents this optional data volume from making boot fail, while the automount defers the actual mount until the path is accessed and the two systemd timeouts bound waits for a missing device and idle lifetime.
Why this step matters
The entry encodes identity, activation, failure, hardening, and filesystem-check behavior in one declarative contract that systemd and util-linux can validate consistently.
What to understand
`UUID=` avoids discovery-order names. `nofail` and on-demand activation are appropriate only because this volume is explicitly optional for host boot.
`nosuid,nodev` limit common data-volume attack surfaces. The device and idle timeouts bound waiting but do not guarantee application availability.
The final `0 2` disables dump selection and requests non-root filesystem checking in the standard secondary pass.
System changes
- Adds one persistent line to `/etc/fstab`; generated units change only after daemon reload or reboot.
Syntax explained
rw,nosuid,nodev- Mounts read/write while ignoring set-user-ID semantics and device nodes on this data filesystem.
nofail- Makes this optional device non-required for normal boot completion.
x-systemd.automount- Generates an automount unit that activates the mount on path access.
x-systemd.device-timeout=10s- Bounds the wait for the UUID device to appear.
x-systemd.idle-timeout={{idleTimeout}}- Allows systemd to unmount after the declared period without active references.
0 2- Disables dump selection and assigns the normal non-root fsck pass.
/etc/fstabValues stay on this page and are never sent or saved.
UUID={{filesystemUuid}} {{mountPoint}} ext4 rw,nosuid,nodev,nofail,x-systemd.automount,x-systemd.device-timeout=10s,x-systemd.idle-timeout={{idleTimeout}} 0 2UUID=7f3d2c8a-6637-4cb0-a7d4-1c0f71e9be21 /srv/data ext4 rw,nosuid,nodev,nofail,x-systemd.automount,x-systemd.device-timeout=10s,x-systemd.idle-timeout=5min 0 2
Checkpoint: Review the exact contract
grep -nF 'UUID={{filesystemUuid}} {{mountPoint}}' /etc/fstabContinue whenExactly one line contains the approved UUID, target, ext4 type, hardening, bounded systemd options, and pass number.
Stop whenThe line is duplicated, wraps, contains whitespace escaping errors, or changes another entry.
If this step fails
The editor or deployment creates two matching lines.
Likely causeA non-idempotent append ran more than once.
grep -nF 'UUID=7f3d2c8a-6637-4cb0-a7d4-1c0f71e9be21' /etc/fstab
ResolutionRestore the backup and apply one reviewed idempotent change; do not guess which duplicate systemd will prefer.
Security notes
- Do not put passwords or cloud credentials in fstab. Use protected credential mechanisms for network filesystems.
Alternatives
- Use explicit native units when richer dependency or credential handling is required.
Stop conditions
- Do not save an entry for a critical filesystem under optional `nofail` semantics.
verification
Validate fstab and inspect generated unit names
Parse the complete file before asking systemd to reload it. Resolve the escaped `.mount` and `.automount` names from the path so later operations target the generated units rather than a guessed name.
Why this step matters
Parsing the complete fstab and deriving unit names before reload catches syntax, duplicate target, field, escaping, and unit-naming mistakes while the running mount state is unchanged.
What to understand
`findmnt --verify --verbose` evaluates every fstab entry, not just the new line. Existing warnings must be resolved rather than normalized.
`systemd-escape --path --suffix` produces the canonical unit name for nested and escaped paths, eliminating guessed service names.
System changes
- No persistent change; reads fstab and computes systemd unit identifiers.
Syntax explained
--verify- Checks fstab parsability and mount-point consistency.
--verbose- Reports the entry-level result and warnings needed for review.
systemd-escape --path --suffix- Converts the absolute path to its canonical mount or automount unit name.
Values stay on this page and are never sent or saved.
sudo findmnt --verify --verbose && systemd-escape --path --suffix=mount {{mountPoint}} && systemd-escape --path --suffix=automount {{mountPoint}}Success, no errors or warnings detected srv-data.mount srv-data.automount
Checkpoint: Require zero parser findings
Continue whenValidation reports success with no errors or warnings and unit names match the planned target.
Stop whenAny line in fstab fails validation or an unexpected unit name is produced.
If this step fails
findmnt reports a parse error near the new line.
Likely causeA field is missing, spaces in a path are unescaped, or an option contains invalid whitespace.
sudo nl -ba /etc/fstabsudo diff -u /etc/fstab.pre-oneliners /etc/fstab
ResolutionRestore or correct the single line and repeat full-file validation before daemon reload.
Security notes
- Validation output exposes mount topology; keep captured evidence in the protected change record.
Alternatives
- Run the same validation in CI against the rendered fstab and repeat it on the target host.
Stop conditions
- One warning is sufficient to block activation.
command
Reload systemd and activate only the automount
Regenerate units from the validated fstab, start the automount endpoint, and verify that the path is waiting without mounting the filesystem yet. This separates unit generation from first data access.
Why this step matters
A manager reload creates units from the validated contract, while starting only the automount proves on-demand behavior without immediately touching filesystem contents.
What to understand
`daemon-reload` reruns generators and reconciles generated unit files. It does not itself mount the filesystem.
The first `findmnt` result should be `autofs` from `systemd-1`, showing that the trigger waits at the target before the ext4 source is activated.
System changes
- Regenerates systemd units from fstab and starts the target automount in the live manager.
Syntax explained
systemctl daemon-reload- Reruns generators and reloads unit definitions.
systemctl start ...automount- Installs the kernel autofs trigger at the target path.
systemctl is-active- Returns a machine-readable active-state check.
Values stay on this page and are never sent or saved.
sudo systemctl daemon-reload && sudo systemctl start "$(systemd-escape --path --suffix=automount {{mountPoint}})" && systemctl is-active "$(systemd-escape --path --suffix=automount {{mountPoint}})" && findmnt --target {{mountPoint}} --output SOURCE,TARGET,FSTYPE,OPTIONSactive SOURCE TARGET FSTYPE OPTIONS systemd-1 /srv/data autofs rw,relatime,fd=55,pgrp=1,timeout=300,minproto=5,maxproto=5,direct,pipe_ino=45678
Checkpoint: Observe the waiting automount
Continue whenThe automount is active and findmnt shows systemd-1/autofs, not the ext4 source yet.
Stop whenThe unit fails, an unexpected mount activates, or the target already shows a different source.
If this step fails
The automount unit is not found.
Likely causeThe fstab line was not saved, validation targeted another file, generator reload failed, or the escaped name was guessed.
systemctl list-units --type=automount --allsystemctl cat srv-data.automountjournalctl -b -u srv-data.automount --no-pager
ResolutionRevalidate fstab, rerun daemon-reload, derive the unit with systemd-escape, and inspect the generator-backed unit.
Security notes
- Keep consumers stopped until live source identity is proven.
Alternatives
- Use `systemctl start {{mountPoint}}` only for a normal mount unit; this guide intentionally tests automount first.
Stop conditions
- Stop if any process sees unexpected contents at the target.
verification
Trigger the mount and prove source identity
Read the directory once to trigger activation, then ask `findmnt` for the exact source, target, type, and effective options. Compare the resolved source UUID with the planned value rather than accepting that the path merely contains files.
Why this step matters
A successful path access proves the full automount chain, while evaluated findmnt output proves that success came from the intended filesystem rather than an empty directory or wrong block device.
What to understand
Redirecting `ls` avoids treating file names as proof; the authoritative evidence is the kernel mount table plus evaluated UUID.
Review effective options because filesystem or distribution defaults may add flags beyond the fstab line.
System changes
- Triggers the ext4 mount and updates access time or journal metadata; it does not intentionally modify user files.
Syntax explained
findmnt --target- Selects the filesystem currently covering the exact path.
--evaluate- Resolves UUID/LABEL tags to their device source.
--output SOURCE,UUID,TARGET- Limits evidence to identity and placement fields.
Values stay on this page and are never sent or saved.
sudo ls -la {{mountPoint}} >/dev/null && findmnt --target {{mountPoint}} --output SOURCE,TARGET,FSTYPE,OPTIONS && findmnt --target {{mountPoint}} --evaluate --output SOURCE,UUID,TARGETSOURCE TARGET FSTYPE OPTIONS /dev/sdb1 /srv/data ext4 rw,relatime,nosuid,nodev SOURCE UUID TARGET /dev/sdb1 7f3d2c8a-6637-4cb0-a7d4-1c0f71e9be21 /srv/data
Checkpoint: Prove live identity and options
Continue whenThe exact UUID covers {{mountPoint}} as ext4 with intended hardening options.
Stop whenThe UUID, target, filesystem type, or effective security options differ.
If this step fails
The target remains autofs after access.
Likely causeActivation failed, the access did not cross the trigger, or a nested path/namespace differs.
systemctl status srv-data.mount srv-data.automount --no-pagerjournalctl -b -u srv-data.mount --no-pagerfindmnt -R /srv/data
ResolutionInspect the mount-unit failure and namespace from the same process context; do not let applications proceed on the unresolved path.
Security notes
- Do not inspect or print sensitive file names merely to prove a mount; identity metadata is sufficient.
Alternatives
- Use a dedicated read-only sentinel file whose checksum is documented, if content-level identity is required.
Stop conditions
- Any identity mismatch requires immediate consumer shutdown and rollback.
decision
Rehearse the unavailable-device path in a disposable clone
Before applying the pattern broadly, boot a disposable clone with the optional data device detached. Confirm the host reaches its normal target, access to the mount point fails within the configured device timeout, and the journal identifies the missing UUID without entering emergency mode.
Why this step matters
The value of `nofail` and bounded waits is only known after the device is actually absent. A disposable clone reveals boot dependencies and application assumptions without sacrificing production recovery.
What to understand
Detach only the optional clone device and boot with a console. Record boot completion, system state, automount status, access latency, and journal messages.
The `.automount` may remain waiting while the corresponding `.mount` fails after the device timeout. This is acceptable only when services handle the unavailable path explicitly.
Reattach the device and prove recovery; do not treat a single successful normal boot as failure-path evidence.
System changes
- Temporarily removes a disposable clone device and exercises failure/recovery; production storage is not detached.
Syntax explained
systemctl is-system-running- Summarizes whether the host reached a normal operational state.
journalctl -b -u ...mount- Shows current-boot device wait and mount-unit evidence.
Values stay on this page and are never sent or saved.
systemctl is-system-running; systemctl status "$(systemd-escape --path --suffix=automount {{mountPoint}})" --no-pager; journalctl -b -u "$(systemd-escape --path --suffix=mount {{mountPoint}})" --no-pagerrunning
● srv-data.automount - /srv/data
Loaded: loaded (/etc/fstab; generated)
Active: active (waiting)
Jul 28 03:12:18 storage-canary systemd[1]: Job dev-disk-by\x2duuid-7f3d2c8a...device/start timed out.
Jul 28 03:12:18 storage-canary systemd[1]: Dependency failed for srv-data.mount - /srv/data.Checkpoint: Accept bounded degraded behavior
Continue whenThe clone reaches normal target, access fails near ten seconds with the missing UUID identified, and recovery succeeds after reattachment.
Stop whenThe clone enters emergency mode, hangs beyond the bound, or a service writes into the uncovered directory.
If this step fails
The clone enters emergency mode despite nofail.
Likely causeA service or another mount has an explicit required dependency, the edited entry is not the only failure, or the real target is critical.
systemctl --failed --no-pagerjournalctl -b -p warning --no-pagersystemctl list-dependencies local-fs.target
ResolutionUse console to restore fstab, inspect dependency ownership, and redesign the mount as required or optional consistently.
Security notes
- Use synthetic clone data and keep test console evidence private.
Alternatives
- Use a VM snapshot or storage test environment that faithfully reproduces boot and service dependencies.
Stop conditions
- Never detach a production device to perform the first failure drill.
Finish line
Verification checklist
findmnt --target {{mountPoint}} --evaluate --output SOURCE,UUID,TARGET,FSTYPE,OPTIONSThe UUID equals {{filesystemUuid}}, the target equals {{mountPoint}}, the type is ext4, and effective options contain nosuid and nodev.systemctl status "$(systemd-escape --path --suffix=automount {{mountPoint}})" "$(systemd-escape --path --suffix=mount {{mountPoint}})" --no-pagerThe automount is waiting or active, the mount is active after access, and neither unit has a failed job.sudo findmnt --verify --verboseThe complete file reports `Success, no errors or warnings detected`.Recovery guidance
Common problems and safe checks
The automount is active, but first access returns `No such device` after ten seconds.
Likely causeThe UUID is wrong, duplicated, attached after the timeout, hidden behind encryption/LVM, or the storage controller did not discover the device.
ls -l /dev/disk/by-uuid/sudo lsblk --fs --output NAME,PATH,FSTYPE,UUID,LABEL,MOUNTPOINTSjournalctl -b -u 'srv-data.mount' --no-pager
ResolutionRestore the correct storage layer and verify its UUID independently. If attachment is legitimately slower, measure it and adjust the timeout cautiously rather than replacing the UUID with a volatile device name.
The mount succeeds but the application reports permission denied.
Likely causeFilesystem root ownership, POSIX mode, ACLs, AppArmor policy, or service sandboxing differs from the empty mount-point directory.
findmnt --target /srv/data --output SOURCE,TARGET,OPTIONSsudo namei -om /srv/datasudo getfacl -p /srv/datajournalctl -k --since '-10 minutes' | grep -i denied
ResolutionSet ownership and ACLs on the mounted filesystem for the intended service identity, or update a reviewed confinement policy. Do not weaken the entire filesystem to mode 0777.
A service wrote files to the underlying mount-point directory while the device was unavailable.
Likely causeThe service checked only for directory existence, started before the mount, or treats optional storage as writable fallback.
systemctl show example.service -p RequiresMountsFor -p Aftersudo findmnt --target /srv/datasudo fuser --mount /srv/data
ResolutionStop the consumer, mount the real filesystem, inspect the underlying directory from a recovery namespace, reconcile data explicitly, and add `RequiresMountsFor=/srv/data` plus a readiness assertion to the service.
The filesystem never idles out.
Likely causeA shell, daemon, indexer, monitoring probe, or current working directory keeps an open reference or repeatedly traverses the path.
sudo fuser --mount /srv/datasudo lsof +f -- /srv/datasystemctl status srv-data.automount srv-data.mount --no-pager
ResolutionIdentify and change the consumer or accept that the workload is not idle. Do not force or lazily unmount a filesystem with active writers.
wrong fs type, bad option, bad superblock
Likely causeA generic mount summary covering options, helpers, storage layers, unsupported features or damaged metadata.
Correlate the original mount error with bounded kernel logs.Inspect lsblk, blkid -p and wipefs --no-act on the confirmed object.Validate fstab and determine whether a supported driver/helper is present.
ResolutionRepair only the demonstrated configuration cause. Escalate suspected damage or I/O failure to an offline, copy-first recovery procedure; do not format or run automatic repair.
Reference
Frequently asked questions
Why not use `/dev/sdb1`?
That name reflects discovery order, which can change when disks, controllers, kernels, or virtual hardware change. The filesystem UUID identifies the intended filesystem more reliably.
Does `nofail` mean data loss is harmless?
No. It changes boot dependency only. Applications can still fail or write to the uncovered directory, so service dependencies and monitoring remain necessary.
Should every mount use automount?
No. It fits optional or intermittently used storage. Critical storage should usually be an explicit requirement whose absence blocks dependent services and possibly host readiness.
Can I test with `mount -a` alone?
Parsing and a successful mount are useful but insufficient. Validate the whole fstab, inspect generated units, prove UUID identity, test missing-device behavior in a clone, and perform a controlled reboot.
Does wrong fs type, bad option, bad superblock always mean corruption?
No. It also covers invalid options, missing helpers, the wrong storage layer and unsupported filesystem features. Read the matching kernel reason and inspect the confirmed device before choosing a repair.
Is mount -o ro guaranteed not to change an ext4 filesystem?
No. Journal replay can still write. Forensic work requires a preserved copy and an explicitly reviewed no-replay procedure; ro by itself is not that guarantee.
Should I run fsck -y or copy an alternate superblock number from a forum?
No. First establish the filesystem type, identity, offline state and preservation plan. Different filesystems need different tools, and backup metadata locations are not interchangeable between devices.
Recovery
Rollback
Rollback restores the checksum-recorded fstab, removes the generated automount from the live manager, and unmounts only after consumers have stopped. It does not repair filesystem damage or recover data overwritten while the wrong source was mounted.
- Stop every service and shell whose working directory or open file is below {{mountPoint}}, verify with `sudo fuser --mount {{mountPoint}}`, and do not use force or lazy unmount to hide active consumers.
- Restore `/etc/fstab.pre-oneliners` to `/etc/fstab`, run `sudo findmnt --verify --verbose`, then run `sudo systemctl daemon-reload`.
- If the filesystem is mounted and idle, run `sudo umount {{mountPoint}}`; confirm `findmnt --target {{mountPoint}}` returns no filesystem and the underlying directory is empty.
- Stop and reset the generated `.automount` and `.mount` units, retain the journal and checksum evidence, and investigate identity or timing failures before another attempt.
Evidence