share/man/man5/mount.conf.5

   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 .\" $FreeBSD$
  27 .\"
  28 .\"
  29 .Dd October 17, 2013
  30 .Dt MOUNT.CONF 5
  31 .Os
  32 .Sh NAME
  33 .Nm mount.conf
  34 .Nd root file system mount configuration file
  35 .Sh SYNOPSIS
  36 .Pa /.mount.conf
  37 .Sh DESCRIPTION
  38 During the bootup process, the
  39 .Fx
  40 kernel will try to mount the root file system
  41 using the logic in the
  42 .Fn vfs_mountroot
  43 function in
  44 .Pa src/sys/kern/vfs_mountroot.c .
  45 The root mount logic can be described as follows:
  46 .Bl -enum
  47 .It
  48 The kernel will synthesize in memory a config file
  49 with default directives for mounting
  50 the root file system.
  51 The logic for this is in
  52 .Fn vfs_mountroot_conf0 .
  53 .It
  54 The kernel will first mount
  55 .Xr devfs 5
  56 as the root file system.
  57 .It
  58 Next, the kernel will parse the in-memory config file created in step 1
  59 and try to mount the actual root file system.
  60 See
  61 .Sx FILE FORMAT
  62 for the format of the config file.
  63 .It
  64 When the actual root file system is mounted,
  65 .Xr devfs 5
  66 will be re-mounted on the
  67 .Pa /dev
  68 directory.
  69 .It
  70 If a
  71 .Pa /.mount.conf
  72 file does not exist in the root file system which was
  73 just mounted, the root mount logic stops here.
  74 .It
  75 If a
  76 .Pa /.mount.conf
  77 file exists in the root file system which was just mounted,
  78 this file will be parsed, and the kernel will use this new config
  79 file to try to re-mount the root file system.
  80 See
  81 .Sx FILE FORMAT
  82 for the format of the config file.
  83 .It
  84 If the new root file system has a
  85 .Pa /.mount
  86 directory, the old root file system will be re-mounted
  87 on
  88 .Pa /.mount .
  89 .It
  90 The root mount logic will go back to step 4.
  91 .El
  92 .Pp
  93 The root mount logic is recursive, and step 8 will
  94 be repeated as long as each new root file system
  95 which is mounted has a
  96 .Pa /.mount.conf
  97 file.
  98 .Sh FILE FORMAT
  99 The kernel parses each line in
 100 .Pa .mount.conf
 101 and then tries to perform the action specified on that line as soon as it is parsed.
 102 .Bl -tag -width "XXXXXXXXXX"
 103 .It Ic #
 104 A line beginning with a # is a comment and is ignored.
 105 .It Ic {FS}:{MOUNTPOINT} {OPTIONS}
 106 The kernel will try to mount this in an
 107 operation equivalent to:
 108 .Bd -literal -offset indent
 109 mount -t {FS} -o {OPTIONS} {MOUNTPOINT} /
 110 .Ed
 111 .Pp
 112 If this is successfully mounted,
 113 further lines in
 114 .Pa .mount.conf
 115 are ignored.
 116 If all lines in
 117 .Pa .mount.conf
 118 have been processed and no root file system has been successfully
 119 mounted, then the action specified by
 120 .Ic .onfail
 121 is performed.
 122 .It Ic .ask
 123 When the kernel processes this line, a
 124 .Li mountroot>
 125 command-line prompt is displayed.
 126 At this prompt, the operator can enter the root mount.
 127 .It Ic .md Ar file
 128 Create a memory backed
 129 .Xr md 4
 130 virtual disk, using
 131 .Ar file
 132 as the backing store.
 133 .It Ic .onfail Ar [panic|reboot|retry|continue]
 134 If after parsing all the lines in
 135 .Pa .mount.conf
 136 the kernel is unable to mount a root file system,
 137 the
 138 .Ic .onfail
 139 directive tells the kernel what action to perform.
 140 .It Ic .timeout Ar N
 141 Before trying to mount a root file system,
 142 if the root mount device does not exist, wait at most
 143 .Ar N
 144 seconds for the device to appear before trying to mount it.
 145 If
 146 .Ic .timeout
 147 is not specified, the default timeout is 3 seconds.
 148 .El
 149 .Sh EXAMPLES
 150 The following example
 151 .Pa .mount.conf
 152 will direct the kernel to try mounting the root file system
 153 first as an ISO CD9660 file system on
 154 .Pa /dev/cd0 ,
 155 then if that does not work, as an ISO CD9660 file system on
 156 .Pa /dev/cd1 ,
 157 and then if that does not work, as a UFS file system on
 158 .Pa /dev/ada0s1a .
 159 If that does not work, a
 160 .Li mountroot>
 161 command-line prompt will be displayed where the operator
 162 can manually enter the root file system to mount.
 163 Finally if that does not work, the kernel will panic.
 164 .Bd -literal -offset indent
 165 .Li .onfail panic
 166 .Li .timeout 3
 167 cd9660:/dev/cd0 ro
 168 .Li .timeout 0
 169 cd9660:/dev/cd1 ro
 170 .Li .timeout 3
 171 ufs:/dev/ada0s1a
 172 .Li .ask
 173 .Ed
 174 .Pp
 175 The following example
 176 .Pa .mount.conf
 177 will direct the kernel to create a
 178 .Xr md 4
 179 memory disk attached to the file
 180 .Pa /data/OS-1.0.iso
 181 and then mount the ISO CD9660 file system
 182 on the md device which was just created.
 183 The last line is a comment which is ignored.
 184 .Bd -literal -offset indent
 185 .Li .timeout 3
 186 .Li .md /data/OS-1.0.iso
 187 .Li cd9600:/dev/md# ro
 188 .Li # Can also use cd9660:/dev/md0 ro
 189 .Ed
 190 .Pp
 191 The following example
 192 .Pa .mount.conf
 193 will direct the kernel to create a
 194 .Xr md 4
 195 memory disk attached to the file
 196 .Pa /data/base.ufs.uzip
 197 and then mount the UFS file system
 198 on the md uzip device which was just created
 199 by the
 200 .Xr geom_uzip 4
 201 driver.
 202 .Bd -literal -offset indent
 203 .Li .md /data/base.ufs.uzip
 204 .Li ufs:/dev/md#.uzip ro
 205 .Li # Can also use ufs:/dev/md0.uzip ro
 206 .Ed
 207 .Pp
 208 The following example
 209 .Pa .mount.conf
 210 will direct the kernel to do a unionfs
 211 mount on a directory
 212 .Pa /jail/freebsd-8-stable
 213 which has a
 214 .Xr chroot 2
 215 environment.
 216 .Bd -literal -offset indent
 217 .Li .timeout 3
 218 .Li unionfs:/jail/freebsd-8-stable
 219 .Ed
 220 .Sh NOTES
 221 For each root file system which is mounted, a
 222 .Pa /dev
 223 directory
 224 .Em must
 225 exist so that the root mount logic can properly re-mount
 226 .Xr devfs 5 .
 227 If this directory does not exist, the system
 228 may hang during the bootup process.
 229 .Sh SEE ALSO
 230 .Xr nmount 2 ,
 231 .Xr md 4 ,
 232 .Xr boot.config 5 ,
 233 .Xr fstab 5 ,
 234 .Xr boot 8 ,
 235 .Xr loader 8 ,
 236 .Xr mount 8
 237 .Sh HISTORY
 238 The
 239 .Nm
 240 file first appeared in
 241 .Fx 9.0 .
 242 .Sh AUTHORS
 243 .An -nosplit
 244 The root mount logic in the
 245 .Fx
 246 kernel which parses
 247 .Pa /.mount.conf
 248 was written by
 249 .An Marcel Moolenaar Aq Mt marcel@FreeBSD.org .
 250 This man page was written by
 251 .An Craig Rodrigues Aq Mt rodrigc@FreeBSD.org .