Skip to content

/etc/fstab

Checked against util-linux 2.40 and later (fstab(5), mount(8) and findmnt(8); the labs carry 2.40.2 to 2.42.4), systemd 259 (systemd.mount(5), systemd-fstab-generator(8)) on Ubuntu 26.04 and systemd 257 on Debian 13, and OpenRC 0.63.3 on Gentoo.

Synopsis

# <device>                                 <mount point>  <type>  <options>          <dump>  <pass>
UUID=0a1b2c3d-1111-4222-8333-444455556666  /srv/data      ext4    defaults,noatime   0       2

Description

/etc/fstab is a plain-text table of filesystems the system knows how to mount, and of swap areas it can enable. Each non-blank line that doesn't start with # describes one filesystem in six fields separated by spaces or tabs. No tool edits it as part of normal operation: you change it by hand (or with configuration management), and other programs only consult it.

The file is read by mount(8) (for example mount -a, or mount /srv/data with only the mount point given), umount(8), swapon(8), fsck(8) and findmnt(8), and at boot by the init system: systemd-fstab-generator on systemd distributions, and the fsck, root, localmount, netmount and swap services on OpenRC.

Spaces and tabs inside a field are written as the octal escapes \040 and \011, for example /srv/shared\040files.

Fields

No. Name in fstab(5) Content If omitted
1 fs_spec The device or source: a device path, an identifier such as UUID=, a network source such as server.example.com:/export, or a free-form name (for example tmpfs) for filesystems without a device Required
2 fs_file The mount point, an absolute path. none for swap Required
3 fs_vfstype The filesystem type, for example ext4, or swap. A comma-separated list is tried in order. Subtypes use a dot, for example fuse.sshfs Required
4 fs_mntops Comma-separated mount options; see Mount options defaults
5 fs_freq Whether dump(8) backs up the filesystem: 0 (no) or 1 (yes) 0
6 fs_passno Order of filesystem checks at boot: 0 (don't check), 1 (check first; the root filesystem), 2 (check after the root filesystem) 0

Entries are processed in file order by mount -a, so a mount point inside another mount point (for example /srv/data/logs inside /srv/data) must come after it. systemd orders mounts by their paths and doesn't depend on file order.

Device identifiers

Form Refers to Stable when Find it with
/dev/sdb1, /dev/vdb1 A kernel device name Not stable: names follow detection order and can change when disks are added or removed lsblk
UUID=<uuid> The filesystem (or swap area) UUID, written by mkfs or mkswap Until the device is reformatted lsblk -f, blkid
LABEL=<label> The filesystem label Until relabelled or reformatted; must be unique on the system lsblk -f, blkid
PARTUUID=<uuid> The GPT partition's unique GUID (on MBR disks, a disk signature plus partition number) Until the partition is recreated; survives reformatting lsblk -o +PARTUUID, blkid
PARTLABEL=<name> The GPT partition name Until renamed; survives reformatting lsblk -o +PARTLABEL
ID=<id> The hardware ID that udev uses under /dev/disk/by-id/ Depends on hardware, driver and udev rules; mount(8) doesn't recommend it for general use ls /dev/disk/by-id/
/dev/disk/by-uuid/…, by-label/…, by-partuuid/…, by-partlabel/…, by-id/…, by-path/… udev symbolic links to the same devices As for the matching tag; by-path changes if the disk moves to another port or controller ls -l /dev/disk/by-*/
/dev/<VG>/<LV>, /dev/mapper/<VG>-<LV> An LVM logical volume Stable: the names come from LVM metadata lvs
/dev/mapper/<name> Another device-mapper device, such as an unlocked LUKS volume named in /etc/crypttab Stable while the mapping name is unchanged dmsetup ls

mount(8) recommends the tag forms (UUID=, LABEL= and so on) over the equivalent /dev/disk/by-* links: tags are easier to read, more robust and more portable, and a link gains nothing over its tag. The ID= tag is documented in mount(8), not in fstab(5). UUIDs are compared as strings and are written in lower case, except for the short volume IDs of FAT and NTFS, which are upper case (for example UUID=D779-42D2).

Filesystem types

Common values of the third field:

Type Notes
ext4 Default on Debian and Ubuntu
xfs Default on AlmaLinux, Rocky Linux and RHEL; can be grown online, but not shrunk in practice (since Linux 5.12, only unused space at the very end can be removed)
btrfs Subvolumes are selected with the subvol= option
vfat EFI system partition; usually mounted with umask=0077
swap A swap partition or file; the mount point is none
tmpfs Memory-backed filesystem; size set with size=
nfs, nfs4 NFS; the source is host:/path
cifs SMB/CIFS share; the source is //host/share
none Used with the bind option for bind mounts
auto Detect the type from the device

Mount options

Options are comma-separated, without spaces. Options that the kernel doesn't understand are either handled by mount(8) and the init system (as with nofail and _netdev) or passed to the filesystem. Options beginning with x- are for userspace programs only and are never passed to the kernel.

Filesystem-independent options

Option Meaning
defaults A placeholder meaning "no special options", used to fill the field. What it amounts to is decided by the kernel and the filesystem, not by a list in mount(8); in effect, a read-write mount that honours set-user-ID bits, device files and executables, is mounted at boot, can't be mounted by ordinary users, and uses asynchronous writes
rw, ro Mount read-write (the default) or read-only
auto, noauto Mount, or don't mount, with mount -a and at boot. noauto entries can still be mounted by name, for example mount /srv/data
nofail Don't treat a missing device or failed mount as an error. At boot, the system continues without waiting for the mount
_netdev The filesystem needs the network. It is mounted after the network is up, as network filesystem types (nfs, cifs) already are
relatime Update a file's access time only if it is older than its modification or change time, or more than a day old. The kernel default since Linux 2.6.30
noatime Never update access times; implies nodiratime. Saves writes on read-heavy filesystems
strictatime Update the access time on every access
nodev Don't interpret device files on this filesystem
nosuid Ignore set-user-ID and set-group-ID bits
noexec Don't allow programs on this filesystem to be executed directly
user, users Allow an unprivileged user to mount the filesystem (user: only that user can unmount it; users: any user can). Implies noexec, nosuid and nodev unless overridden
owner Allow the owner of the device file to mount the filesystem. Implies nosuid and nodev unless overridden
bind Mount a directory (the first field) at a second location
discard Send TRIM or discard requests to the device as blocks are freed. Many systems use a periodic fstrim timer instead

Filesystem-specific options

Option Filesystems Meaning
errors=continue, errors=remount-ro, errors=panic ext2, ext3, ext4 What to do when the filesystem detects an error: carry on, remount read-only, or halt the system. Without the option, the behaviour stored in the superblock applies (tune2fs -e changes it)
subvol=<path>, subvolid=<id> btrfs Mount a subvolume instead of the top level
compress=<algorithm> btrfs Compress newly written data, for example compress=zstd
umask=, uid=, gid= vfat Permissions and ownership, which FAT can't store
size= tmpfs Maximum size, for example size=2G or size=20%

The full lists are in mount(8) (section "FILESYSTEM-SPECIFIC MOUNT OPTIONS") and in the man page of each filesystem, such as ext4(5) and xfs(5).

systemd options

These options are read by systemd-fstab-generator. mount(8) ignores them, so on Gentoo with OpenRC they have no effect.

Option Meaning
x-systemd.automount Create an automount unit: the filesystem is mounted on first access to the mount point, instead of at boot
x-systemd.idle-timeout=<time> Unmount an automounted filesystem after it has been unused for this long, for example 10min
x-systemd.device-timeout=<time> How long to wait for the device to appear at boot (default 90 s)
x-systemd.mount-timeout=<time> How long to wait for the mount command to complete
x-systemd.requires=<unit or path> Add Requires= and After= dependencies on another unit, device or mount point
x-systemd.after=<unit>, x-systemd.before=<unit> Add ordering dependencies
x-systemd.requires-mounts-for=<path> Require the mounts needed for another path
x-systemd.makefs Create the filesystem at boot if the device carries no signature
x-systemd.growfs Grow the filesystem to fill its device at boot
x-systemd.rw-only Fail instead of falling back to a read-only mount
x-initrd.mount Mount the filesystem in the initramfs, before switching to the real root

Dump and pass

The fifth field is read only by the dump(8) backup program for ext⅔/4 filesystems, which few systems install; it is normally 0.

The sixth field controls fsck at boot:

  • 1 for the root filesystem, which is checked first.
  • 2 for other filesystems that should be checked. With fsck -A, filesystems on the same disk are checked one after another, and filesystems on different disks in parallel.
  • 0 for filesystems that aren't checked: network filesystems, tmpfs, swap, vfat where no check is wanted, and usually XFS and Btrfs. Their fsck helpers (fsck.xfs, fsck.btrfs) do nothing at boot, because XFS replays its log at mount time and both have their own repair tools (xfs_repair, btrfs check).

systemd-fstab-generator treats the field as a yes/no value: any non-zero value adds a systemd-fsck@.service check before the mount, and only the root filesystem is ordered before the others.

Boot-time handling

systemd. See How systemd uses fstab.

systemd. See How systemd uses fstab.

systemd. See How systemd uses fstab.

With OpenRC, these services read /etc/fstab:

Service Runlevel Role
fsck boot Checks filesystems with a non-zero pass field
root boot Remounts the root filesystem read-write
localmount boot Mounts local filesystems with mount -a, excluding network types and _netdev entries
swap boot Enables swap entries with swapon -a
netmount default Mounts network filesystems and _netdev entries once the network is up

The lvm and dmcrypt services, which activate LVM volumes and unlock devices listed in /etc/crypttab, aren't added to any runlevel when lvm2 or cryptsetup is installed. Unless an initramfs activates them, filesystems on those devices can be mounted at boot only if the matching service is in the boot runlevel; localmount is ordered after lvm when it is.

After editing the file, mount -a mounts any new entries. The x-systemd.* options are ignored: mount accepts them and mounts the filesystem as if they weren't there.

With a systemd profile (not verified), Gentoo behaves as described in How systemd uses fstab.

How systemd uses fstab

At boot, and on every systemctl daemon-reload, systemd-fstab-generator converts each entry into a unit in /run/systemd/generator/:

  • A mount unit for every filesystem, named after the escaped mount point: / becomes -.mount, /srv/data becomes srv-data.mount, and /srv/my-data becomes srv-my\x2ddata.mount. systemd-escape --path --suffix=mount <PATH> prints the name for <PATH>.
  • A swap unit for every swap entry.
  • An automount unit in addition to the mount unit when x-systemd.automount is set.

The generated unit records its origin with SourcePath=/etc/fstab, and systemctl cat srv-data.mount shows it. Each mount unit depends on the unit for its device, so it waits for the device to appear (up to x-systemd.device-timeout), including devices created by LVM, md or LUKS.

Local filesystems are pulled in by local-fs.target, and network filesystems (by type, or with _netdev) by remote-fs.target, after network-online.target. Without nofail, a mount is required by its target; with nofail, it's only wanted, and the boot doesn't wait for it. A required local filesystem that fails to mount fails local-fs.target, which puts the system into emergency mode. If a required network filesystem fails, remote-fs.target fails too, but the boot continues. With noauto, the unit isn't pulled in by either target.

Changes to /etc/fstab don't affect the running system's units until systemctl daemon-reload runs; mount warns about this when it detects an outdated unit.

Checking the file

findmnt --verify parses /etc/fstab and checks every entry: that the source exists (or can be resolved), the mount point exists and is a directory, the type is known, and the options are valid. It exits non-zero if it finds errors. On systemd distributions it also warns when /etc/fstab has changed since the units were generated, as a reminder to run systemctl daemon-reload. --tab-file <FILE> checks another file, and --verbose prints each check. mount(8) describes findmnt --verify as the recommended way to check the file, rather than mount -a.

$ findmnt --verify
/srv/data
   [E] unreachable on boot required target: No such file or directory
   [E] unreachable on boot required source: UUID=0a1b2c3d-1111-4222-8333-444455556666

0 parse errors, 2 errors, 0 warnings

Examples

# Root filesystem, checked first.
UUID=0a1b2c3d-1111-4222-8333-444455556666  /            ext4   errors=remount-ro               0  1
# EFI system partition, identified by its GPT partition GUID.
PARTUUID=5c1f0e7a-2222-4333-8444-555566667777  /boot/efi  vfat   umask=0077                      0  2
# LVM logical volume, not checked (XFS), without access-time updates.
/dev/vg_data/lv_data                       /srv/data    xfs    defaults,noatime                0  0
# Removable backup disk: boot doesn't wait for it, mounted on first access (systemd).
LABEL=backup                               /srv/backup  ext4   nofail,x-systemd.automount      0  2
# NFS export, mounted after the network is up.
nfs.example.com:/export/home               /home        nfs4   defaults,_netdev                0  0
# Bind mount.
/srv/data/www                              /var/www     none   bind                            0  0
# Swap partition and memory-backed /tmp.
UUID=1e2d3c4b-3333-4444-8555-666677778888  none         swap   defaults                        0  0
tmpfs                                      /tmp         tmpfs  size=2G,mode=1777,nosuid,nodev  0  0

Files

Path Purpose
/etc/fstab The static filesystem table
/proc/self/mounts The filesystems currently mounted, in the same field layout (/etc/mtab is a symbolic link to it)
/run/systemd/generator/ Units generated from /etc/fstab on systemd distributions
/etc/crypttab LUKS and other encrypted devices to unlock at boot, before their filesystems are mounted
/etc/init.d/localmount, /etc/init.d/netmount OpenRC services that mount /etc/fstab entries

See also