> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://rivet.chrisboulton.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://rivet.chrisboulton.com/_mcp/server.

# Mount

> Converge current mount state and independently manage its fstab entry.

```hcl
mount "data" {
  path              = "/srv/data"
  source            = "LABEL=example-data"
  fstype            = "ext4"
  options           = ["defaults", "nodev", "nosuid"]
  persistent        = true
  at_boot           = true
  create_mountpoint = true
  on_change         = "remount"
}
```

`mount` manages two things independently: whether a filesystem is mounted right now, and its entry in `/etc/fstab`.

| `state`             | Effect                                                                                   |
| ------------------- | ---------------------------------------------------------------------------------------- |
| `mounted` (default) | Mounted now. With `persistent = true`, also has a matching fstab entry.                  |
| `unmounted`         | Not mounted now. The fstab entry, and whether it mounts at boot, are managed separately. |
| `absent`            | Unmounted normally, and its fstab entry removed. Only `path` is needed.                  |

No state formats a device, deletes data, removes directories recursively, or force- or lazy-unmounts a busy filesystem.

## Comparing and changing mounts

Rivet reads current mounts from `findmnt`. Device paths and `UUID=`, `LABEL=`, `PARTUUID=`, and `PARTLABEL=` forms are resolved before comparing, and options the kernel adds by default don't count as drift. `fstype = "auto"` accepts whatever type is mounted. Stacked mounts on one path, symlinked mountpoints or parents, and kernel paths such as `/proc` are refused.

When a mounted filesystem's options drift, `on_change` decides what happens:

* `remount` (default) applies the new options with a remount, where the kernel supports it.
* `unmount_mount` unmounts and mounts again. This is required when the source or type changes.
* `fail` reports an error instead.

If an unmount fails because the filesystem is busy, the fstab entry is left unchanged.

## Fstab entries

Rivet edits only the managed entry and keeps unrelated lines and comments. Spaces, tabs, and backslashes in fields are escaped. Two entries for the same mountpoint are an error. Writes are atomic, and the file is re-read before each one in case it changed. A resource that manages the whole `/etc/fstab` as a file conflicts with mount entries.

Fstab changes reload systemd as part of the same operation. Current-mount drift and fstab drift are handled separately: changing only the fstab entry doesn't remount a filesystem that is already correct.

With `persistent = false`, an existing fstab entry is left alone, except that `state = "absent"` still removes it. `at_boot = false` writes `noauto`, so you can keep a filesystem unmounted now but mounted at boot, or the reverse.

## Attributes

| Attribute           | Default                | Behavior                                                                      |
| ------------------- | ---------------------- | ----------------------------------------------------------------------------- |
| `path`              | Required               | Normalized absolute mountpoint.                                               |
| `state`             | `mounted`              | `mounted`, `unmounted`, or `absent`; there is no ensure alias.                |
| `source`            | Conditionally required | Device, source path, or supported native identity alias.                      |
| `fstype`            | Conditionally required | Filesystem type, including auto for observed type matching.                   |
| `options`           | `["defaults"]`         | List of option strings normalized to a set.                                   |
| `persistent`        | `true`                 | Manage matching fstab entry.                                                  |
| `at_boot`           | `true`                 | Persistent automatic boot mounting; false renders noauto.                     |
| `dump`              | `0`                    | Fstab dump field; 0 or 1.                                                     |
| `fsck_pass`         | `0`                    | Nonnegative native-range fstab fsck pass; conventional values are 0, 1, or 2. |
| `create_mountpoint` | `false`                | Create a missing mountpoint, owned by root with mode 0755.                    |
| `on_change`         | `remount`              | `remount`, `unmount_mount`, or `fail` for active drift.                       |

`source` and `fstype` are required unless `state` is `absent`, or `state` is `unmounted` with `persistent = false`. Options can't be empty or contain commas, whitespace, or control characters, and conflicting pairs such as `ro` with `rw` or `bind` with `rbind` are refused.

If the mountpoint is also declared as a `file`, it must be a directory, or absent when the mount is removed. Rivet orders the mountpoint directory before the mount, and the mount before files beneath it. When both are removed, the mount is removed first. Existing mountpoints keep their ownership and mode; `create_mountpoint` creates a missing one owned by root with mode 0755.

The default timeout is 300 seconds. Mounts need `mount.util_linux.v1`, plus `refresh.journal.v1` when they are persistent or absent. Static exports are `path`, `state`, and `meta.sensitive`. All [common metadata](/language/metadata) applies, but mounts can't be notification targets. Interrupted changes are recovered by re-inspecting and converging again; see [recovery](/reference/recovery).