DragonFly On-Line Manual Pages

Search: Section:  

INITRD(7)         DragonFly Miscellaneous Information Manual         INITRD(7)


NAME

     initrd - initial ramdisk image as early userland


DESCRIPTION

     The initrd is a small initial ramdisk image that packs a minimal init(8),
     basic rc(8) scripts, and many other statically linked tools, such as
     various mount(8) utilities, lvm(8), cryptsetup(8), tcplay(8), as well as
     some networking tools.  The initrd is a nice early userland and is
     required to help mount the root partition residing on an encrypted device
     or LVM.

     The statically linked tools are known as the "rescue tools" and shipped
     at /rescue.  The inclusion of such rescue tools makes initrd 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.

     The initrd is a md(4) image formatted with the UFS(5) filesystem.  It is
     created by the "initrd" target of the build(7) framework, and is
     compressed and installed at /boot/kernel/initrd.img.gz.  The following
     configurations should be added to /boot/loader.conf to make use of the
     initrd image:

           initrd.img_load="YES"
           initrd.img_type="md_image"
           vfs.root.mountfrom="ufs:md0s0"

     Then, the "vfs.root.realroot" kernel environment variable can be
     configured to specify how to mount the real root partition.  Its general
     syntax is:

           vfs.root.realroot="<type>:[arg1[:arg2[:...]]]"

     The supported types of real root partition are: local, crypt, and tcplay.
     The local type allows to mount any local filesystem that does not require
     any special setup apart from the initial discovery and calling the
     mount(8) program.  The general format is as follows:

           vfs.root.realroot="local:<FS-TYPE>:<DEVICE-PATH>[@LABEL][:<OPTIONS>]"

     where the @LABEL option may be used to specify the PFS label of a
     HAMMER/HAMMER2 filesystem, and the OPTIONS specifies the extra options
     for mount(8).

     The crypt and tcplay types allow to mount volumes supported by
     cryptsetup(8) and tcplay(8), respectively.  The device will be set up
     after asking the user for the key, and then be mounted as the root.  The
     general formats are as follows:

           vfs.root.realroot="crypt:<FS-TYPE>:<DEVICE-PATH>[@LABEL]:<MAPPING-NAME>[:<OPTIONS>]"

           vfs.root.realroot="tcplay:<FS-TYPE>:<DEVICE-PATH>[@LABEL]:<MAPPING-NAME>[:<OPTIONS>]"

     where the MAPPING-NAME specifies the device name to be created under
     /dev/mapper/, which may be further used in /etc/fstab; the OPTIONS is
     passed to cryptsetup(8) and tcplay(8), respectively.


FILES

     /boot/kernel/initrd.img.gz  Location of the compressed initrd image.


EXAMPLES

     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]"

     vfs.root.realroot="crypt:hammer2:/dev/serno/XXXXXX.s3@ROOT:root[:OPTIONS]"

     vfs.root.realroot="crypt:hammer2:/dev/serno/XXXXXX.s3@ROOT.20260616:root[:OPTIONS]"


SEE ALSO

     kenv(1), md(4), loader.conf(5), build(7), cryptsetup(8), lvm(8),
     tcplay(8)


HISTORY

     The initrd manual page first appeared in DragonFly 5.3.


AUTHORS

     The initrd manual page was written by Aaron LI <aly@aaronly.me>.


BUGS

     The initrd image occupies about 10-15 MB wired memory and cannot be freed
     after chrooting to the real root partition.

DragonFly 6.5-DEVELOPMENT        June 16, 2026       DragonFly 6.5-DEVELOPMENT

Search: Section: