.Dd October 3, 2026
.Dt TINYRD 8
.Os
.Sh NAME
.Nm tinyrd
.Nd the rawnix initramfs
.Sh SYNOPSIS
.Nm
.Fl o Ar file
.Sh DESCRIPTION
.Nm
is one static binary with two roles.
Run with
.Fl o
it writes a cpio archive whose
.Pa /init
is the binary itself; run as
.Pa /init
by the kernel it unlocks an encrypted root if there is one, mounts
root, and hands over to the real init.
.Pp
The archive carries no kernel modules and no configuration, so one
image serves every kernel: nothing has to be regenerated when a kernel
is installed or removed, and
.Xr limine-sync 8
refers to it by a name with no version in it.
The price is that everything needed before root is mounted must be
built into the kernel; see
.Sx KERNEL REQUIREMENTS .
.Pp
The package ships the finished image as
.Pa /boot/tinyrd.img ,
so building one by hand is only necessary when changing
.Nm
itself.
.Sh THE BOOT PATH
As
.Pa /init ,
.Nm
reads the kernel command line and nothing else.
.Bl -tag -width rootfstype=
.It Li root=
Required: the root filesystem, as
.Pa /dev/ Ns Ar ...
or
.Li UUID= Ns Ar uuid .
The UUID form survives the disk being renamed, which
.Pa /dev/sda2
does not: adding a drive, moving a cable or booting the same image in a
virtual machine is enough to change it.
With
.Li cryptroot=
this must be the mapped device,
.Pa /dev/mapper/ Ns Ar name .
.It Li cryptroot=
Optional: the UUID of the
.Em LUKS partition ,
from
.Ic cryptsetup luksUUID ,
not of the filesystem inside it.
.Nm
asks for the passphrase and creates the mapping under the name taken
from
.Li root= .
Without this key it mounts
.Li root=
directly, so the same image boots an unencrypted system.
.It Li rootfstype=
Default
.Li ext4 .
.It Li rootflags=
Passed to
.Xr mount 2
as its data argument.
.It Li ro | rw
Default
.Li ro ;
the last one on the line wins.
.It Li init=
Default
.Pa /sbin/init .
.El
.Pp
After the switch, the new root sees exactly what the kernel would leave
it with no initramfs at all: devtmpfs on
.Pa /dev ,
root mounted, nothing else.
Stage 1 needs no knowledge of
.Nm .
.Sh KERNEL REQUIREMENTS
Because the image carries no modules, the kernel must have built in:
.Bd -literal -offset indent
BLK_DEV_INITRD DEVTMPFS
BLK_DEV_DM DM_CRYPT CRYPTO_XTS
CRYPTO_AES_NI_INTEL CRYPTO_SHA256 CRYPTO_HMAC
CRYPTO_USER_API_SKCIPHER CRYPTO_USER_API_HASH
.Ed
.Pp
plus the root filesystem itself and whatever the keyboard needs to type
a passphrase: i8042 and atkbd on most machines, xhci and usbhid for USB.
.Pp
libcryptsetup here uses the kernel crypto backend, so every hash goes
through AF_ALG.
Without
.Li CRYPTO_USER_API_HASH
the LUKS header will not load and the message is
.Dq Cannot initialize crypto backend .
.Pp
The rawnix kernels have all of this; a hand-rolled configuration is the
place this goes wrong.
.Sh FILES
.Bl -tag -width Ds -compact
.It Pa /boot/tinyrd.img
The image, staged by the package and copied to the ESP by
.Xr limine-sync 8 .
.El
.Sh EXIT STATUS
.Ex -std
As
.Pa /init
there is nowhere to return to: on a failure it reports what went wrong
and stops, leaving the machine at a point where the message can be
read.
.Sh EXAMPLES
Build an image:
.Dl $ tinyrd -o tinyrd.img
.Pp
A command line for an encrypted root, as
.Xr limine-sync 8
would write it:
.Bd -literal -offset indent
cryptroot=UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \e
    root=/dev/mapper/croot ro quiet
.Ed
.Pp
and for an unencrypted one:
.Bd -literal -offset indent
root=UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx ro quiet
.Ed
.Sh SEE ALSO
.Xr encryption 7 ,
.Xr rawnix 7 ,
.Xr cryptsetup 8 ,
.Xr limine-sync 8
.Sh AUTHORS
.An zorz Aq Mt zorz@rawnix.org
.Sh CAVEATS
The passphrase is typed before any keyboard layout is loaded, so it is
read as if on a US keyboard.