sbin/mkinitrd/mkinitrd.8

   1 .\"
   2 .\" Copyright (c) 2010, 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 March 30, 2018
  33 .Dt MKINITRD 8
  34 .Os
  35 .Sh NAME
  36 .Nm mkinitrd
  37 .Nd build an initial ramdisk image for use as early userland
  38 .Sh SYNOPSIS
  39 .Nm
  40 .Op Fl b Ar bootdir
  41 .Op Fl c Ar contentsdir
  42 .Op Fl t Ar tmpdir
  43 .Op Fl s Ar size
  44 .Op Fl S Ar max_size
  45 .Sh DESCRIPTION
  46 The
  47 .Nm
  48 script builds a ramdisk (md) image based on the UFS filesystem containing
  49 only the most basic tools, such as a minimal
  50 .Xr init 8 ,
  51 .Xr sh 1 ,
  52 various
  53 .Xr mount 8
  54 utilities,
  55 .Xr lvm 8 ,
  56 .Xr cryptsetup 8 ,
  57 .Xr tcplay 8 ,
  58 as well as some basic networking tools.
  59 And the ramdisk is required to help mount the encrypted root partition.
  60 .Pp
  61 The contents of
  62 .Pa /usr/share/initrd
  63 will be copied onto the ramdisk, maintaining the same hierarchy.
  64 This directory can be changed with the
  65 .Fl c
  66 option.
  67 .Pp
  68 By default
  69 .Nm
  70 will calculate the contents size and create a ramdisk just big enough.
  71 The
  72 .Fl s
  73 option accepting an integer (number of MB) can specify the required
  74 size of the ramdisk.
  75 The special value of
  76 .Pa 0
  77 can be given to ignore the
  78 .Pa INITRD_SIZE
  79 setting from the configuration file as described below.
  80 The
  81 .Fl S
  82 option also accepts an integer (number of MB) and constrains the maximum
  83 allowed size of the ramdisk.
  84 Specifying a value of
  85 .Pa 0
  86 will ignore the
  87 .Pa INITRD_SIZE_MAX
  88 setting from the configuration file.
  89 .Pp
  90 On completion, the final image will be copied to
  91 .Pa /boot/kernel/initrd.img.gz ,
  92 ready to be used as an early userland.
  93 The base directory for
  94 .Pa kernel/initrd.img.gz
  95 can be changed with the
  96 .Fl b
  97 option to an optional
  98 .Ar bootdir (the default is
  99 .Pa /boot ) .
 100 The temporary directory to be used for setting up the image can be specified
 101 using the
 102 .Fl t
 103 option (the default is
 104 .Pa /tmp ) .
 105 .Pp
 106 The
 107 .Nm
 108 script will read
 109 .Pa /etc/mkinitrd.conf
 110 if it exists and use the configuration from this file to override the
 111 following variables (defaults are in
 112 .Pa /etc/defaults/mkinitrd.conf ) :
 113 .Bd -literal -offset indent
 114 BUILD_DIR
 115 INITRD_SIZE_MAX
 116 INITRD_DIRS
 117 CONTENT_DIRS
 118 .Ed
 119 .Pp
 120 Adding the following lines to
 121 .Pa /boot/loader.conf
 122 will enable the use of the created initrd image:
 123 .Bd -literal -offset indent
 124 initrd.img_load="YES"
 125 initrd.img_type="md_image"
 126 vfs.root.mountfrom="ufs:md0s0"
 127 .Ed
 128 .Pp
 129 The format for vfs.root.realroot in
 130 .Pa /boot/loader.conf
 131 that allows the user to specify what system to mount as the
 132 new root in the initrd is specified in its general form below:
 133 .Bd -literal -offset indent
 134 vfs.root.realroot="<type>:[arg1[:arg2[:argN]]]"
 135 .Ed
 136 .Pp
 137 Currently, three types of real root are supported,
 138 .Pa local ,
 139 .Pa tcplay
 140 and
 141 .Pa crypt .
 142 The
 143 .Pa local
 144 type allows to mount any local file system that does not require any
 145 special setup apart from the initial discovery and calling the
 146 .Pa mount
 147 program. The general format is as follows:
 148 .Bd -literal -offset indent
 149 vfs.root.realroot="local:<FS TYPE>:<DEVICE PATH>[:<OPTIONS>]"
 150 .Ed
 151 .Pp
 152 The
 153 .Pa crypt
 154 type allows to mount volumes supported by cryptsetup. The device will
 155 be set up by prompting the user for his key, and this volume will then
 156 be mounted as the new root.
 157 .Bd -literal -offset indent
 158 vfs.root.realroot="crypt:<FS TYPE>:<DEVICE PATH>:<VOLUME NAME>[:<OPTIONS>]"
 159 .Ed
 160 .Pp
 161 The
 162 .Pa tcplay
 163 type allows to mount volumes supported by
 164 .Xr tcplay 8 .
 165 The device will be set up by prompting the user for his key, and this
 166 volume will then be mounted as the new root.
 167 .Bd -literal -offset indent
 168 vfs.root.realroot="tcplay:<FS TYPE>:<DEVICE PATH>:<VOLUME NAME>[:<OPTIONS>]"
 169 .Ed
 170 .Sh EXAMPLES
 171 .Bd -literal -offset indent
 172 vfs.root.realroot="local:ufs:/dev/vg00/lv0[:OPTIONS]"
 173
 174 vfs.root.realroot="crypt:ufs:/dev/ad0s0a:secvolume[:OPTIONS]"
 175
 176 vfs.root.realroot="crypt:hammer2:/dev/serno/XXXXXX.s1d:root[:OPTIONS]"
 177 .Ed
 178 .Sh SEE ALSO
 179 .Xr md 4 ,
 180 .Xr loader.conf 5
 181 .Sh HISTORY
 182 The
 183 .Nm
 184 command first appeared in
 185 .Dx 2.7 .
 186 .Sh AUTHORS
 187 .Nm
 188 was written by
 189 .An Alex Hornung Aq Mt ahornung@gmail.com .