slzs

Alpine Linux initramfs builder with remote SSH unlock support for encrypted ZFS rootfs.

Overview

slzs extends the standard Alpine mkinitfs to produce an initramfs that:

• Starts SSH at boot (before the rootfs is mounted)
• Unlocks LUKS-encrypted devices and imports a ZFS pool remotely
• Loads ZFS native encryption key
• Shuts down network access after unlock

Components

File	Location	Description
slzs	/usr/sbin/slzs	Main builder — generates the initramfs
slzs-enc	/usr/sbin/slzs-enc	Generates and encrypts keys.enc
safego	/sbin/safego	Initramfs script — decrypts keys, unlocks LUKS, imports ZFS
go	/sbin/go	Initramfs shortcut — runs safego then gameover
gameover	/sbin/gameover	Initramfs script — wipes keys and shuts down network/SSH
bootup	/sbin/bootup	Initramfs script — continues normal boot after unlock
ssh.files	/etc/mkinitfs/slzs/features.d/	mkinitfs feature — includes sshd and openssl

Requirements

• Alpine Linux with mkinitfs, zstd, cpio
• ZFS pool as rootfs (root=ZFS=poolname/dataset in kernel cmdline)
• LUKS-encrypted devices under the ZFS pool
• keygen in PATH
• openssh installed on the host

Setup

1. Generate keys.enc

Run on the live system before building the initramfs:

slzs-enc -p <passphrase> -d /etc/mkinitfs/slzs/keys.enc

This generates a keys.enc file containing:

• One line per LUKS device: keygen(uuid) uuid
• One line for the ZFS pool: keygen(guid) poolname

All encrypted with AES-256-CBC using the provided passphrase.

2. Add authorized SSH key

Place the public key in /etc/ssh/authorized_keys:

cat ~/.ssh/id_ed25519.pub >> /etc/ssh/authorized_keys

Or let slzs prompt for it interactively if the file does not exist.

3. Build the initramfs

slzs

This will:

1. Detect the NIC module and network configuration
2. Build the initramfs via mkinitfs
3. Inject SSH host key, authorized_keys, keys.enc and unlock scripts
4. Repackage and replace /boot/initramfs-<type>

Usage

slzs [options]

Options:
  -v                  Verbose mode
  -a, --all           Process all kernels in /lib/modules
  --keep              Keep initramfs backup after update
  -k KERNEL_VERSION   Specify kernel version manually
  -i INIT_FILE        Specify custom initramfs-init script
  -c COMPRESSION      Compression type (default: zstd)
  -m MKINITFS_CONF    Path to mkinitfs.conf
  -s SSH_KEY          SSH host key (default: /etc/ssh/ssh_host_ed25519_key)
  -p PASSPHRASE       Passphrase for keys.enc
  --save              Save passphrase to /etc/mkinitfs/slzs/passphrase
  -V                  Show version
  -h                  Show help

Remote Unlock

At boot, connect via SSH and run:

go <passphrase>

Or interactively (passphrase hidden):

go

go runs safego (unlock) then gameover (wipe keys + kill network/SSH).

What safego does

1. Decrypts /etc/keys.enc using the passphrase → /dev/shm/keys
2. Unlocks each LUKS device with its derived key
3. Imports the ZFS pool
4. Loads the ZFS native encryption key
5. Calls bootup to continue normal boot

What gameover does

1. Wipes /dev/shm/keys
2. Kills sshd
3. Flushes all network interfaces
4. Kills busybox (ends the initramfs shell)

Configuration

slzs generates /etc/slzs.conf on first run with commented defaults:

# DEFAULT_MKINITFS_CONF=/etc/mkinitfs/mkinitfs.conf
# DEFAULT_ENCRYPT_SCRIPT=/usr/sbin/slzs-enc
# DEFAULT_SCRIPTS_DIR=/etc/mkinitfs/slzs/scripts
# DEFAULT_SSH_KEY=/etc/ssh/ssh_host_ed25519_key
# DEFAULT_AUTHORIZED_KEYS=/etc/ssh/authorized_keys
# DEFAULT_COMPRESSION=zstd
# BACKUP_KEEP=n

License

GPL-3.0-or-later