---
name: "mount.conf"
section: "5"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/mount.conf/5"
---

# mount.conf(5)

root file system mount configuration file

## NAME

**mount.conf** – root file system mount configuration file

## SYNOPSIS

*/.mount.conf*

## DESCRIPTION

During the bootup process, the FreeBSD kernel will try to mount the root file system using the logic in the **vfs\_mountroot**() function in *src/sys/kern/vfs\_mountroot.c*. The root mount logic can be described as follows:

1. The kernel will synthesize in memory a config file with default directives for mounting the root file system. The logic for this is in **vfs\_mountroot\_conf0**().

2. The kernel will first mount [devfs(4)](/devfs/4.md) as the root file system.

3. Next, the kernel will parse the in-memory config file created in step 1 and try to mount the actual root file system. See FILE FORMAT for the format of the config file.

4. When the actual root file system is mounted, [devfs(4)](/devfs/4.md) will be re-mounted on the */dev* directory.

5. If a */.mount.conf* file does not exist in the root file system which was just mounted, the root mount logic stops here.

6. If a */.mount.conf* file exists in the root file system which was just mounted, this file will be parsed, and the kernel will use this new config file to try to re-mount the root file system. See FILE FORMAT for the format of the config file.

7. If the new root file system has a */.mount* directory, the old root file system will be re-mounted on */.mount*.

8. The root mount logic will go back to step 4.

The root mount logic is recursive, and step 8 will be repeated as long as each new root file system which is mounted has a */.mount.conf* file.

## FILE FORMAT

The kernel parses each line in *.mount.conf* and then tries to perform the action specified on that line as soon as it is parsed.

- **#**

  A line beginning with a # is a comment and is ignored.

- **{FS}:{MOUNTPOINT}** **{OPTIONS}**

  The kernel will try to mount this in an operation equivalent to:

  ```
  mount -t {FS} -o {OPTIONS} {MOUNTPOINT} /
  ```

  If this is successfully mounted, further lines in *.mount.conf* are ignored. If all lines in *.mount.conf* have been processed and no root file system has been successfully mounted, then the action specified by **.onfail** is performed.

- **.ask**

  When the kernel processes this line, a mountroot\> command-line prompt is displayed. At this prompt, the operator can enter the root mount.

- **.md** *file*

  Create a memory backed [md(4)](/md/4.md) virtual disk, using *file* as the backing store.

- **.onfail** *\[panic\|reboot\|retry\|continue\]*

  If after parsing all the lines in *.mount.conf* the kernel is unable to mount a root file system, the **.onfail** directive tells the kernel what action to perform.

- **.timeout** *N*

  Before trying to mount a root file system, if the root mount device does not exist, wait at most *N* seconds for the device to appear before trying to mount it. If **.timeout** is not specified, the default timeout is 3 seconds.

## EXAMPLES

The following example *.mount.conf* will direct the kernel to try mounting the root file system first as an ISO CD9660 file system on */dev/cd0*, then if that does not work, as an ISO CD9660 file system on */dev/cd1*, and then if that does not work, as a UFS file system on */dev/ada0s1a*. If that does not work, a mountroot\> command-line prompt will be displayed where the operator can manually enter the root file system to mount. Finally if that does not work, the kernel will panic.

```
.onfail panic
.timeout 3
cd9660:/dev/cd0 ro
.timeout 0
cd9660:/dev/cd1 ro
.timeout 3
ufs:/dev/ada0s1a
.ask
```

The following example *.mount.conf* will direct the kernel to create a [md(4)](/md/4.md) memory disk attached to the file */data/OS-1.0.iso* and then mount the ISO CD9660 file system on the md device which was just created. The last line is a comment which is ignored.

```
.timeout 3
.md /data/OS-1.0.iso
cd9600:/dev/md# ro
# Can also use cd9660:/dev/md0 ro
```

The following example *.mount.conf* will direct the kernel to create a [md(4)](/md/4.md) memory disk attached to the file */data/base.ufs.uzip* and then mount the UFS file system on the md uzip device which was just created by the [geom\_uzip(4)](/geom_uzip/4.md) driver.

```
.md /data/base.ufs.uzip
ufs:/dev/md#.uzip ro
# Can also use ufs:/dev/md0.uzip ro
```

The following example *.mount.conf* will direct the kernel to do a unionfs mount on a directory */jail/freebsd-8-stable* which has a [chroot(2)](/chroot/2.md) environment.

```
.timeout 3
unionfs:/jail/freebsd-8-stable
```

## NOTES

For each root file system which is mounted, a */dev* directory *must* exist so that the root mount logic can properly re-mount [devfs(4)](/devfs/4.md). If this directory does not exist, the system may hang during the bootup process.

## SEE ALSO

[nmount(2)](/nmount/2.md), [md(4)](/md/4.md), [boot.config(5)](/boot.config/5.md), [fstab(5)](/fstab/5.md), [boot(8)](/boot/8.md), [loader(8)](/loader/8.md), [mount(8)](/mount/8.md)

## HISTORY

The **mount.conf** file first appeared in FreeBSD 9.0.

## AUTHORS

The root mount logic in the FreeBSD kernel which parses */.mount.conf* was written by Marcel Moolenaar ⟨*marcel@FreeBSD.org*⟩. This man page was written by Craig Rodrigues ⟨*rodrigc@FreeBSD.org*⟩.