1.\" Copyright (c) 2013 Marcel Moolenaar 2.\" Copyright (c) 2013 Craig Rodrigues 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" 27.Dd October 17, 2013 28.Dt MOUNT.CONF 5 29.Os 30.Sh NAME 31.Nm mount.conf 32.Nd root file system mount configuration file 33.Sh SYNOPSIS 34.Pa /.mount.conf 35.Sh DESCRIPTION 36During the bootup process, the 37.Fx 38kernel will try to mount the root file system 39using the logic in the 40.Fn vfs_mountroot 41function in 42.Pa src/sys/kern/vfs_mountroot.c . 43The root mount logic can be described as follows: 44.Bl -enum 45.It 46The kernel will synthesize in memory a config file 47with default directives for mounting 48the root file system. 49The logic for this is in 50.Fn vfs_mountroot_conf0 . 51.It 52The kernel will first mount 53.Xr devfs 5 54as the root file system. 55.It 56Next, the kernel will parse the in-memory config file created in step 1 57and try to mount the actual root file system. 58See 59.Sx FILE FORMAT 60for the format of the config file. 61.It 62When the actual root file system is mounted, 63.Xr devfs 5 64will be re-mounted on the 65.Pa /dev 66directory. 67.It 68If a 69.Pa /.mount.conf 70file does not exist in the root file system which was 71just mounted, the root mount logic stops here. 72.It 73If a 74.Pa /.mount.conf 75file exists in the root file system which was just mounted, 76this file will be parsed, and the kernel will use this new config 77file to try to re-mount the root file system. 78See 79.Sx FILE FORMAT 80for the format of the config file. 81.It 82If the new root file system has a 83.Pa /.mount 84directory, the old root file system will be re-mounted 85on 86.Pa /.mount . 87.It 88The root mount logic will go back to step 4. 89.El 90.Pp 91The root mount logic is recursive, and step 8 will 92be repeated as long as each new root file system 93which is mounted has a 94.Pa /.mount.conf 95file. 96.Sh FILE FORMAT 97The kernel parses each line in 98.Pa .mount.conf 99and then tries to perform the action specified on that line as soon as it is parsed. 100.Bl -tag -width "XXXXXXXXXX" 101.It Ic # 102A line beginning with a # is a comment and is ignored. 103.It Ic {FS}:{MOUNTPOINT} {OPTIONS} 104The kernel will try to mount this in an 105operation equivalent to: 106.Bd -literal -offset indent 107mount -t {FS} -o {OPTIONS} {MOUNTPOINT} / 108.Ed 109.Pp 110If this is successfully mounted, 111further lines in 112.Pa .mount.conf 113are ignored. 114If all lines in 115.Pa .mount.conf 116have been processed and no root file system has been successfully 117mounted, then the action specified by 118.Ic .onfail 119is performed. 120.It Ic .ask 121When the kernel processes this line, a 122.Li mountroot> 123command-line prompt is displayed. 124At this prompt, the operator can enter the root mount. 125.It Ic .md Ar file 126Create a memory backed 127.Xr md 4 128virtual disk, using 129.Ar file 130as the backing store. 131.It Ic .onfail Ar [panic|reboot|retry|continue] 132If after parsing all the lines in 133.Pa .mount.conf 134the kernel is unable to mount a root file system, 135the 136.Ic .onfail 137directive tells the kernel what action to perform. 138.It Ic .timeout Ar N 139Before trying to mount a root file system, 140if the root mount device does not exist, wait at most 141.Ar N 142seconds for the device to appear before trying to mount it. 143If 144.Ic .timeout 145is not specified, the default timeout is 3 seconds. 146.El 147.Sh EXAMPLES 148The following example 149.Pa .mount.conf 150will direct the kernel to try mounting the root file system 151first as an ISO CD9660 file system on 152.Pa /dev/cd0 , 153then if that does not work, as an ISO CD9660 file system on 154.Pa /dev/cd1 , 155and then if that does not work, as a UFS file system on 156.Pa /dev/ada0s1a . 157If that does not work, a 158.Li mountroot> 159command-line prompt will be displayed where the operator 160can manually enter the root file system to mount. 161Finally if that does not work, the kernel will panic. 162.Bd -literal -offset indent 163.Li .onfail panic 164.Li .timeout 3 165cd9660:/dev/cd0 ro 166.Li .timeout 0 167cd9660:/dev/cd1 ro 168.Li .timeout 3 169ufs:/dev/ada0s1a 170.Li .ask 171.Ed 172.Pp 173The following example 174.Pa .mount.conf 175will direct the kernel to create a 176.Xr md 4 177memory disk attached to the file 178.Pa /data/OS-1.0.iso 179and then mount the ISO CD9660 file system 180on the md device which was just created. 181The last line is a comment which is ignored. 182.Bd -literal -offset indent 183.Li .timeout 3 184.Li .md /data/OS-1.0.iso 185.Li cd9600:/dev/md# ro 186.Li # Can also use cd9660:/dev/md0 ro 187.Ed 188.Pp 189The following example 190.Pa .mount.conf 191will direct the kernel to create a 192.Xr md 4 193memory disk attached to the file 194.Pa /data/base.ufs.uzip 195and then mount the UFS file system 196on the md uzip device which was just created 197by the 198.Xr geom_uzip 4 199driver. 200.Bd -literal -offset indent 201.Li .md /data/base.ufs.uzip 202.Li ufs:/dev/md#.uzip ro 203.Li # Can also use ufs:/dev/md0.uzip ro 204.Ed 205.Pp 206The following example 207.Pa .mount.conf 208will direct the kernel to do a unionfs 209mount on a directory 210.Pa /jail/freebsd-8-stable 211which has a 212.Xr chroot 2 213environment. 214.Bd -literal -offset indent 215.Li .timeout 3 216.Li unionfs:/jail/freebsd-8-stable 217.Ed 218.Sh NOTES 219For each root file system which is mounted, a 220.Pa /dev 221directory 222.Em must 223exist so that the root mount logic can properly re-mount 224.Xr devfs 5 . 225If this directory does not exist, the system 226may hang during the bootup process. 227.Sh SEE ALSO 228.Xr nmount 2 , 229.Xr md 4 , 230.Xr boot.config 5 , 231.Xr fstab 5 , 232.Xr boot 8 , 233.Xr loader 8 , 234.Xr mount 8 235.Sh HISTORY 236The 237.Nm 238file first appeared in 239.Fx 9.0 . 240.Sh AUTHORS 241.An -nosplit 242The root mount logic in the 243.Fx 244kernel which parses 245.Pa /.mount.conf 246was written by 247.An Marcel Moolenaar Aq Mt marcel@FreeBSD.org . 248This man page was written by 249.An Craig Rodrigues Aq Mt rodrigc@FreeBSD.org . 250