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 39The 40.Nm 41is a small initial ramdisk image that packs a minimal 42.Xr init 8 , 43basic 44.Xr rc 8 45scripts, and many other statically linked tools, such as various 46.Xr mount 8 47utilities, 48.Xr lvm 8 , 49.Xr cryptsetup 8 , 50.Xr tcplay 8 , 51as well as some networking tools. 52The 53.Nm 54is a nice early userland and is required to help mount the root 55partition residing on an encrypted device or LVM. 56.Pp 57The statically linked tools are known as the 58.Dq rescue tools 59and shipped at 60.Pa /rescue . 61The inclusion of such rescue tools makes 62.Nm 63can provide with a powerful rescue environment to fix severe problems, 64e.g., the root partition cannot be mounted. 65Users can also choose to boot into the rescue mode from the bootloader 66menu. 67.Pp 68The 69.Nm 70is a 71.Xr md 4 72image formatted with the 73.Xr UFS 5 74filesystem. 75It is created by the 76.Dq initrd 77target of the 78.Xr build 7 79framework, and is compressed and installed at 80.Pa /boot/kernel/initrd.img.gz . 81The following configurations should be added to 82.Pa /boot/loader.conf 83to make use of the 84.Nm 85image: 86.Bd -literal -offset indent 87initrd.img_load="YES" 88initrd.img_type="md_image" 89vfs.root.mountfrom="ufs:md0s0" 90.Ed 91.Pp 92Then, the 93.Dq vfs.root.realroot 94kernel environment variable can be configured to specify how to 95mount the real root partition. 96Its general syntax is: 97.Bd -literal -offset indent 98vfs.root.realroot="<type>:[arg1[:arg2[:...]]]" 99.Ed 100.Pp 101Currently, the supported types of real root partition are: 102.Pa local , 103.Pa crypt , 104and 105.Pa tcplay . 106The 107.Pa local 108type allows to mount any local filesystem that does not require any 109special setup apart from the initial discovery and calling the 110.Xr mount 8 111program. 112The general format is as follows: 113.Bd -literal -offset indent 114vfs.root.realroot="local:<FS-TYPE>:<DEVICE-PATH>[:<OPTIONS>]" 115.Ed 116.Pp 117The 118.Pa crypt 119and 120.Pa tcplay 121types allow to mount volumes supported by 122.Xr cryptsetup 8 123and 124.Xr tcplay 8 , 125respectively. 126The device will be set up after asking the user for the key, 127and this volume will then be mounted as the root. 128The general formats are as follows: 129.Bd -literal -offset indent 130vfs.root.realroot="crypt:<FS-TYPE>:<DEVICE-PATH>:<MAPPING-NAME>[:<OPTIONS>]" 131 132vfs.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 137Location of the compressed 138.Nm 139image. 140.El 141.Sh EXAMPLES 142.Bd -literal -offset indent 143vfs.root.realroot="local:ufs:/dev/vg00/lv0[:OPTIONS]" 144 145vfs.root.realroot="crypt:ufs:/dev/ad0s0a:secvolume[:OPTIONS]" 146 147vfs.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 157The 158.Nm 159manual page first appeared in 160.Dx 5.3 . 161.Sh AUTHORS 162The 163.Nm 164manual page was written by 165.An Aaron LI Aq Mt aly@aaronly.me . 166.Sh BUGS 167The 168.Nm 169image occupies about 10-15 MB wired memory and cannot be freed after 170chrooting to the real root partition. 171