Add the initrd.7 man page
authorAaron LI <aly@aaronly.me>
Sun, 1 Jul 2018 05:23:59 +0000 (13:23 +0800)
committerAaron LI <aly@aaronly.me>
Mon, 2 Jul 2018 09:08:45 +0000 (17:08 +0800)
This man page is partly based on the removed mkinitrd.8 man page
written by Alex Hornung.

Reviewed-by: Sascha Wildner
share/man/man7/Makefile
share/man/man7/initrd.7 [new file with mode: 0644]

index c5289cf..af8739e 100644 (file)
@@ -1,7 +1,6 @@
 #      @(#)Makefile    8.1 (Berkeley) 6/5/93
 # $FreeBSD: src/share/man/man7/Makefile,v 1.10.2.7 2002/12/28 19:09:50 dillon Exp $
 
-#MISSING: eqnchar.7 ms.7 term.7
 MAN=   ascii.7 \
        build.7 \
        clocks.7 \
@@ -12,6 +11,7 @@ MAN=  ascii.7 \
        firewall.7 \
        hier.7 \
        hostname.7 \
+       initrd.7 \
        intro.7 \
        nls.7 \
        operator.7 \
diff --git a/share/man/man7/initrd.7 b/share/man/man7/initrd.7
new file mode 100644 (file)
index 0000000..3dcd56a
--- /dev/null
@@ -0,0 +1,170 @@
+.\"
+.\" Copyright (c) 2018
+.\"    The DragonFly Project.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\" 3. Neither the name of The DragonFly Project nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific, prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
+.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
+.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd June 2, 2018
+.Dt INITRD 7
+.Os
+.Sh NAME
+.Nm initrd
+.Nd initial ramdisk image as early userland
+.Sh DESCRIPTION
+The
+.Nm
+is a small initial ramdisk image that packs a minimal
+.Xr init 8 ,
+basic
+.Xr rc 8
+scripts, and many other statically linked tools, such as various
+.Xr mount 8
+utilities,
+.Xr lvm 8 ,
+.Xr cryptsetup 8 ,
+.Xr tcplay 8 ,
+as well as some networking tools.
+The
+.Nm
+is a nice early userland and is required to help mount the root
+partition residing on an encrypted device or LVM.
+.Pp
+The statically linked tools are known as the
+.Dq rescue tools
+and shipped at
+.Pa /rescue .
+The inclusion of such rescue tools makes
+.Nm
+can provide with a powerful rescue environment to fix severe problems,
+e.g., the root partition cannot be mounted.
+Users can also choose to boot into the rescue mode from the bootloader
+menu.
+.Pp
+The
+.Nm
+is a
+.Xr md 4
+image formatted with the
+.Xr UFS 5
+filesystem.
+It is created by the
+.Dq initrd
+target of the
+.Xr build 7
+framework, and is compressed and installed at
+.Pa /boot/kernel/initrd.img.gz .
+The following configurations should be added to
+.Pa /boot/loader.conf
+to make use of the
+.Nm
+image:
+.Bd -literal -offset indent
+initrd.img_load="YES"
+initrd.img_type="md_image"
+vfs.root.mountfrom="ufs:md0s0"
+.Ed
+.Pp
+Then, the
+.Dq vfs.root.realroot
+kernel environment variable can be configured to specify how to
+mount the real root partition.
+Its general syntax is:
+.Bd -literal -offset indent
+vfs.root.realroot="<type>:[arg1[:arg2[:...]]]"
+.Ed
+.Pp
+Currently, the supported types of real root partition are:
+.Pa local ,
+.Pa crypt ,
+and
+.Pa tcplay .
+The
+.Pa local
+type allows to mount any local filesystem that does not require any
+special setup apart from the initial discovery and calling the
+.Xr mount 8
+program.
+The general format is as follows:
+.Bd -literal -offset indent
+vfs.root.realroot="local:<FS-TYPE>:<DEVICE-PATH>[:<OPTIONS>]"
+.Ed
+.Pp
+The
+.Pa crypt
+and
+.Pa tcplay
+types allow to mount volumes supported by
+.Xr cryptsetup 8
+and
+.Xr tcplay 8 ,
+respectively.
+The device will be set up after asking the user for the key,
+and this volume will then be mounted as the root.
+The general formats are as follows:
+.Bd -literal -offset indent
+vfs.root.realroot="crypt:<FS-TYPE>:<DEVICE-PATH>:<MAPPING-NAME>[:<OPTIONS>]"
+
+vfs.root.realroot="tcplay:<FS-TYPE>:<DEVICE-PATH>:<MAPPING-NAME>[:<OPTIONS>]"
+.Ed
+.Sh FILES
+.Bl -tag -width "/boot/kernel/initrd.img.gz"
+.It Pa /boot/kernel/initrd.img.gz
+Location of the compressed
+.Nm
+image.
+.El
+.Sh EXAMPLES
+.Bd -literal -offset indent
+vfs.root.realroot="local:ufs:/dev/vg00/lv0[:OPTIONS]"
+
+vfs.root.realroot="crypt:ufs:/dev/ad0s0a:secvolume[:OPTIONS]"
+
+vfs.root.realroot="crypt:hammer2:/dev/serno/XXXXXX.s1d:root[:OPTIONS]"
+.Ed
+.Sh SEE ALSO
+.Xr md 4 ,
+.Xr loader.conf 5 ,
+.Xr build 7 ,
+.Xr cryptsetup 8 ,
+.Xr lvm 8 ,
+.Xr tcplay 8
+.Sh HISTORY
+The
+.Nm
+manual page first appeared in
+.Dx 5.3 .
+.Sh AUTHORS
+The
+.Nm
+manual page was written by
+.An Aaron LI Aq Mt aly@aaronly.me .
+.Sh BUGS
+The
+.Nm
+image occupies about 10-15 MB wired memory and cannot be freed after
+chrooting to the real root partition.