share/man/man7/initrd.7

   1 .\"
   2 .\" Copyright (c) 2018
   3 .\"     The DragonFly Project.  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 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in
  13 .\"    the documentation and/or other materials provided with the
  14 .\"    distribution.
  15 .\" 3. Neither the name of The DragonFly Project nor the names of its
  16 .\"    contributors may be used to endorse or promote products derived
  17 .\"    from this software without specific, prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  22 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  23 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  24 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  25 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  26 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  27 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  28 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  29 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .Dd June 2, 2018
  33 .Dt INITRD 7
  34 .Os
  35 .Sh NAME
  36 .Nm initrd
  37 .Nd initial ramdisk image as early userland
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 is a small initial ramdisk image that packs a minimal
  42 .Xr init 8 ,
  43 basic
  44 .Xr rc 8
  45 scripts, and many other statically linked tools, such as various
  46 .Xr mount 8
  47 utilities,
  48 .Xr lvm 8 ,
  49 .Xr cryptsetup 8 ,
  50 .Xr tcplay 8 ,
  51 as well as some networking tools.
  52 The
  53 .Nm
  54 is a nice early userland and is required to help mount the root
  55 partition residing on an encrypted device or LVM.
  56 .Pp
  57 The statically linked tools are known as the
  58 .Dq rescue tools
  59 and shipped at
  60 .Pa /rescue .
  61 The inclusion of such rescue tools makes
  62 .Nm
  63 can provide with a powerful rescue environment to fix severe problems,
  64 e.g., the root partition cannot be mounted.
  65 Users can also choose to boot into the rescue mode from the bootloader
  66 menu.
  67 .Pp
  68 The
  69 .Nm
  70 is a
  71 .Xr md 4
  72 image formatted with the
  73 .Xr UFS 5
  74 filesystem.
  75 It is created by the
  76 .Dq initrd
  77 target of the
  78 .Xr build 7
  79 framework, and is compressed and installed at
  80 .Pa /boot/kernel/initrd.img.gz .
  81 The following configurations should be added to
  82 .Pa /boot/loader.conf
  83 to make use of the
  84 .Nm
  85 image:
  86 .Bd -literal -offset indent
  87 initrd.img_load="YES"
  88 initrd.img_type="md_image"
  89 vfs.root.mountfrom="ufs:md0s0"
  90 .Ed
  91 .Pp
  92 Then, the
  93 .Dq vfs.root.realroot
  94 kernel environment variable can be configured to specify how to
  95 mount the real root partition.
  96 Its general syntax is:
  97 .Bd -literal -offset indent
  98 vfs.root.realroot="<type>:[arg1[:arg2[:...]]]"
  99 .Ed
 100 .Pp
 101 Currently, the supported types of real root partition are:
 102 .Pa local ,
 103 .Pa crypt ,
 104 and
 105 .Pa tcplay .
 106 The
 107 .Pa local
 108 type allows to mount any local filesystem that does not require any
 109 special setup apart from the initial discovery and calling the
 110 .Xr mount 8
 111 program.
 112 The general format is as follows:
 113 .Bd -literal -offset indent
 114 vfs.root.realroot="local:<FS-TYPE>:<DEVICE-PATH>[:<OPTIONS>]"
 115 .Ed
 116 .Pp
 117 The
 118 .Pa crypt
 119 and
 120 .Pa tcplay
 121 types allow to mount volumes supported by
 122 .Xr cryptsetup 8
 123 and
 124 .Xr tcplay 8 ,
 125 respectively.
 126 The device will be set up after asking the user for the key,
 127 and this volume will then be mounted as the root.
 128 The general formats are as follows:
 129 .Bd -literal -offset indent
 130 vfs.root.realroot="crypt:<FS-TYPE>:<DEVICE-PATH>:<MAPPING-NAME>[:<OPTIONS>]"
 131
 132 vfs.root.realroot="tcplay:<FS-TYPE>:<DEVICE-PATH>:<MAPPING-NAME>[:<OPTIONS>]"
 133 .Ed
 134 .Sh FILES
 135 .Bl -tag -width "/boot/kernel/initrd.img.gz"
 136 .It Pa /boot/kernel/initrd.img.gz
 137 Location of the compressed
 138 .Nm
 139 image.
 140 .El
 141 .Sh EXAMPLES
 142 .Bd -literal -offset indent
 143 vfs.root.realroot="local:ufs:/dev/vg00/lv0[:OPTIONS]"
 144
 145 vfs.root.realroot="crypt:ufs:/dev/ad0s0a:secvolume[:OPTIONS]"
 146
 147 vfs.root.realroot="crypt:hammer2:/dev/serno/XXXXXX.s1d:root[:OPTIONS]"
 148 .Ed
 149 .Sh SEE ALSO
 150 .Xr md 4 ,
 151 .Xr loader.conf 5 ,
 152 .Xr build 7 ,
 153 .Xr cryptsetup 8 ,
 154 .Xr lvm 8 ,
 155 .Xr tcplay 8
 156 .Sh HISTORY
 157 The
 158 .Nm
 159 manual page first appeared in
 160 .Dx 5.3 .
 161 .Sh AUTHORS
 162 The
 163 .Nm
 164 manual page was written by
 165 .An Aaron LI Aq Mt aly@aaronly.me .
 166 .Sh BUGS
 167 The
 168 .Nm
 169 image occupies about 10-15 MB wired memory and cannot be freed after
 170 chrooting to the real root partition.