Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

MFC 253433:

    In this GRN, Marcel Moolenaar overhauled the logic for mounting
    the root file system on bootup:

       |------------------------------------------------------------------------
       |r214006 | marcel | 2010-10-17 22:01:53 -0700 (Sun, 17 Oct 2010) | 20 lines
       |
       | Re-implement the root mount logic using a recursive approach, whereby each
       |root file system (starting with devfs and a synthesized configuration) can
       |contain directives for mounting another file system as root.
       |------------------------------------------------------------------------

    This commit adds a mount.conf(8) man page which documents
    the root mount logic.  mount.conf(8) also provides some examples
    for the /.mount.conf file, which can be used to change the root mount behavior.

    Reviewed by: marcel bjk

MFC: 253445:

    Minor mdoc fixes

Approved by: re (gjb)
  • Loading branch information...
commit 20f53230ae6a153eda9adeead7eb6783f8499e93 1 parent c75fcd5
Craig Rodrigues rodrigc authored

Showing 2 changed files with 253 additions and 1 deletion. Show diff stats Hide diff stats

  1. +1 1  sbin/mount/Makefile
  2. +252 0 sbin/mount/mount.conf.8
2  sbin/mount/Makefile
@@ -3,7 +3,7 @@
3 3
4 4 PROG= mount
5 5 SRCS= mount.c mount_fs.c getmntopts.c vfslist.c
6   -MAN= mount.8
  6 +MAN= mount.8 mount.conf.8
7 7 # We do NOT install the getmntopts.3 man page.
8 8
9 9 DPADD= ${LIBUTIL}
252 sbin/mount/mount.conf.8
... ... @@ -0,0 +1,252 @@
  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 July 7, 2013
  30 +.Dt MOUNT.CONF 8
  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 8
  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
  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
  127 +the root mount.
  128 +.It Ic .md Ar file
  129 +Create a memory backed
  130 +.Xr md 4
  131 +virtual disk, using
  132 +.Ar file
  133 +as the backing store.
  134 +.It Ic .onfail Ar [panic|reboot|retry|continue]
  135 +If after parsing all the lines in
  136 +.Pa .mount.conf
  137 +the kernel is unable to mount a root file system,
  138 +the
  139 +.Ic .onfail
  140 +directive tells the kernel what action to perform.
  141 +.It Ic .timeout Ar N
  142 +Before trying to mount a root file system,
  143 +if the root mount device does not exist, wait at most
  144 +.Ar N
  145 +seconds for the device to appear before trying to mount it.
  146 +If
  147 +.Ic .timeout
  148 +is not specified, the default timeout is 3 seconds.
  149 +.El
  150 +.Sh EXAMPLES
  151 +The following example
  152 +.Pa .mount.conf
  153 +will direct the kernel to try mounting the root file system
  154 +first as an ISO CD9660 file system on
  155 +.Pa /dev/cd0 ,
  156 +then if that does not work, as an ISO CD9660 file system on
  157 +.Pa /dev/acd0 ,
  158 +and then if that does not work, as a UFS file system on
  159 +.Pa /dev/ada0s1a .
  160 +If that does not work, a
  161 +.Li mountroot>
  162 +command-line prompt will be displayed where the operator
  163 +can manually enter the root file system to mount.
  164 +Finally if that does not work, the kernel will panic.
  165 +.Bd -literal -offset indent
  166 +.Li .onfail panic
  167 +.Li .timeout 3
  168 +cd9660:/dev/cd0 ro
  169 +.Li .timeout 0
  170 +cd9660:/dev/acd0 ro
  171 +.Li .timeout 3
  172 +ufs:/dev/ada0s1a
  173 +.Li .ask
  174 +.Ed
  175 +.Pp
  176 +The following example
  177 +.Pa .mount.conf
  178 +will direct the kernel to create a
  179 +.Xr md 4
  180 +memory disk attached to the file
  181 +.Pa /data/OS-1.0.iso
  182 +and then mount the ISO CD9660 file system
  183 +on the md device which was just created.
  184 +The last line is a comment which is ignored.
  185 +.Bd -literal -offset indent
  186 +.Li .timeout 3
  187 +.Li .md /data/OS-1.0.iso
  188 +.Li cd9600:/dev/md# ro
  189 +.Li # Can also use cd9660:/dev/md0 ro
  190 +.Ed
  191 +.Pp
  192 +The following example
  193 +.Pa .mount.conf
  194 +will direct the kernel to create a
  195 +.Xr md 4
  196 +memory disk attached to the file
  197 +.Pa /data/base.ufs.uzip
  198 +and then mount the UFS file system
  199 +on the md uzip device which was just created
  200 +by the
  201 +.Xr geom_uzip 4
  202 +driver.
  203 +.Bd -literal -offset indent
  204 +.Li .md /data/base.ufs.uzip
  205 +.Li ufs:/dev/md#.uzip ro
  206 +.Li # Can also use ufs:/dev/md0.uzip ro
  207 +.Ed
  208 +.Pp
  209 +The following example
  210 +.Pa .mount.conf
  211 +will direct the kernel to do a unionfs
  212 +mount on a directory
  213 +.Pa /jail/freebsd-8-stable
  214 +which has a
  215 +.Xr chroot 2
  216 +environment.
  217 +.Bd -literal -offset indent
  218 +.Li .timeout 3
  219 +.Li unionfs:/jail/freebsd-8-stable
  220 +.Ed
  221 +.Sh NOTES
  222 +For each root file system which is mounted, a
  223 +.Pa /dev
  224 +directory
  225 +.Em must
  226 +exist so that the root mount logic can properly re-mount
  227 +.Xr devfs 8 .
  228 +If this directory does not exist, the system
  229 +may hang during the bootup process.
  230 +.Sh SEE ALSO
  231 +.Xr nmount 2 ,
  232 +.Xr md 4 ,
  233 +.Xr boot.config 5 ,
  234 +.Xr fstab 5 ,
  235 +.Xr boot 8 ,
  236 +.Xr loader 8 ,
  237 +.Xr mount 8
  238 +.Sh HISTORY
  239 +The
  240 +.Nm
  241 +file first appeared in
  242 +.Fx 9.0 .
  243 +.Sh AUTHORS
  244 +.An -nosplit
  245 +The root mount logic in the
  246 +.Fx
  247 +kernel which parses
  248 +.Pa /.mount.conf
  249 +was written by
  250 +.An Marcel Moolenaar Aq marcel@FreeBSD.org .
  251 +This man page was written by
  252 +.An Craig Rodrigues Aq rodrigc@FreeBSD.org .

0 comments on commit 20f5323

Please sign in to comment.
Something went wrong with that request. Please try again.