Introduction
The installimage script in the Hetzner Rescue System provides an easy way to install various Linux distributions.
This tutorial shows how to use installimage
to install an encrypted Ubuntu 24.04 system. It also explains how to add remote unlocking via SSH (dropbear) in initramfs stored in a separate /boot
partition.
This tutorial will use the following example files:
File | Description |
---|---|
/tmp/setup.conf |
A configuration file that installs Ubuntu 24.04 and sets up an encrypted root partition. |
/tmp/post-install.sh |
A Bash script that is run on the system right after the installation process completed. It will set up dropbear, so that you can connect to it during boot to unlock the encrypted root partition. |
Prerequisites
- Hetzner account
- Server booted into the Rescue System
- RSA, ECDSA or ED25519 SSH public key
- No private networks attached on Hetzner Cloud
Note: This guide is explicitly written for Ubuntu 24.04 only. It might not work on other distributions.
Step 1 - Create or copy SSH public key
You will need an SSH key to remotely unlock the disk during boot. You will also use this key later to login to the booted system. The dropbear SSH daemon included in Ubuntu 24.04 only supports RSA and ECDSA keys.
If you don't have such an SSH key, you need to generate one now on your local system. We recommend the use of ED25519 or ECDSA keys.
For example to generate an ED25519 SSH key, run:
ssh-keygen -t ed25519
You have to save the public key of your SSH key pair in /tmp/authorized_keys
on the server. The server should already be in the rescue system. Either create the file directly on the server, or copy the public key from your local system using scp
:
scp ~/.ssh/id_ed25519.pub root@<your-host>:/tmp/authorized_keys
Step 2 - Create or copy installimage config file
When you run the command installimage
on a server in the rescue system without any option, it starts in interactive mode. You would have to select a distribution image. After that, it would open an editor. When you exit the editor, it would start the installation process and the corresponding configuration would be saved as /installimage.conf
in the installed system.
When you run the command installimage
on a server in the rescue system and add certain options, it starts in automatic mode — meaning it runs the installation without interactive prompts. Below explains how to create a custom configuration file and pass it to the installimage
command for use during the automatic installation process.
Create a new configuration file /tmp/setup.conf
and add the following content:
Note: Replace
secret
with a secure password and adjust drive names and partitioning as needed.
CRYPTPASSWORD secret
DRIVE1 /dev/sda
BOOTLOADER grub
HOSTNAME host.example.com
PART /boot/efi esp 256M
PART /boot ext4 1G
PART / ext4 all crypt
IMAGE /root/images/Ubuntu-2404-noble-amd64-base.tar.gz
SSHKEYS_URL /tmp/authorized_keys
Note: It should also work with Debain 12 (
Debian-1208-bookworm-amd64-base.tar.gz
) — but without guarantee.
This configuration will install Ubuntu on a single encrypted drive (/dev/sda
) with a separate unencrypted /boot
required for remote unlocking.
Example for two drives (RAID1)
Partitions Mount Point RAID Device RAID Level sda1 sdb1 /boot/efi md0 1 sda2 sdb2 /boot md1 1 sda3 sdb3 / md2 1 CRYPTPASSWORD secret DRIVE1 /dev/sda DRIVE2 /dev/sdb SWRAID 1 SWRAIDLEVEL 1 BOOTLOADER grub HOSTNAME host.example.com PART /boot/efi esp 256M PART /boot ext4 1G PART / ext4 all crypt IMAGE /root/images/Ubuntu-2404-noble-amd64-base.tar.gz SSHKEYS_URL /tmp/authorized_keys
Example for four drives (RAID10)
Partitions Mount Point RAID Device RAID Level sda1 sdb1 sdc1 sdd1 /boot/efi md0 1 sda2 sdb2 sdc2 sdd2 /boot md1 1 sda3 sdb3 sdc3 sdd3 / md2 10 CRYPTPASSWORD secret DRIVE1 /dev/sda DRIVE2 /dev/sdb DRIVE3 /dev/sdc DRIVE4 /dev/sdd SWRAID 1 SWRAIDLEVEL 10 BOOTLOADER grub HOSTNAME host.example.com PART /boot/efi esp 256M PART /boot ext4 1G PART / ext4 all crypt IMAGE /root/images/Ubuntu-2404-noble-amd64-base.tar.gz SSHKEYS_URL /tmp/authorized_keys
Step 3 - Create or copy post-install script
In order to remotely unlock the encrypted partition, we need to install and add the dropbear SSH server to the initramfs which is stored on the unencrypted /boot
partition. This will also trigger the inclusion of dhclient
to configure networking, but without any extras. To enable support for Hetzner Cloud, we need to add a hook which includes support for RFC3442 routes.
In order to run these additional steps, we need a post-install script for installimage
Create a file /tmp/post-install.sh
in the rescue system with the following content:
#!/bin/bash
add_rfc3442_hook() {
cat << EOF > /etc/initramfs-tools/hooks/add-rfc3442-dhclient-hook
#!/bin/sh
PREREQ=""
prereqs()
{
echo "\$PREREQ"
}
case \$1 in
prereqs)
prereqs
exit 0
;;
esac
if [ ! -x /sbin/dhclient ]; then
exit 0
fi
. /usr/share/initramfs-tools/scripts/functions
. /usr/share/initramfs-tools/hook-functions
mkdir -p \$DESTDIR/etc/dhcp/dhclient-exit-hooks.d/
cp -a /etc/dhcp/dhclient-exit-hooks.d/rfc3442-classless-routes \$DESTDIR/etc/dhcp/dhclient-exit-hooks.d/
EOF
chmod +x /etc/initramfs-tools/hooks/add-rfc3442-dhclient-hook
}
remove_unwanted_netplan_config() {
cat << EOF > /etc/initramfs-tools/scripts/init-bottom/remove_unwanted_netplan_config
#!/bin/sh
if [ -d "/run/netplan" ]; then
interface=\$(ls /run/netplan/ | cut -d'.' -f1)
if [ \${interface:+x} ]; then
rm -f /run/netplan/"\${interface}".yaml
fi
fi
EOF
chmod +x /etc/initramfs-tools/scripts/init-bottom/remove_unwanted_netplan_config
}
# Install rfc3442 hook
add_rfc3442_hook
# Adding an initramfs-tools script to remove /run/netplan/{interface}.yaml,
# because it is creating unwanted routes
remove_unwanted_netplan_config
# Update system
apt-get update >/dev/null
apt-get -y install cryptsetup-initramfs dropbear-initramfs
# Copy SSH keys for dropbear and change the port
cp /root/.ssh/authorized_keys /etc/dropbear/initramfs/
sed -ie 's/#DROPBEAR_OPTIONS=/DROPBEAR_OPTIONS="-I 600 -j -k -p 2222 -s"/' /etc/dropbear/initramfs/dropbear.conf
dpkg-reconfigure dropbear-initramfs
update-initramfs -u
Important: Make the post-install script executable:
chmod +x /tmp/post-install.sh
Step 4 - Start installation
Before starting the installation, check the content of the following files again:
File | Check |
---|---|
/tmp/authorized_keys |
Your public SSH key (RSA, ECDSA or ED25519) |
/tmp/setup.conf |
installimage config |
/tmp/post-install.sh |
Is executable and contains the post-install script |
Now you are ready to start the installation with the following command:
installimage -a -c /tmp/setup.conf -x /tmp/post-install.sh
Wait until the installation completes and check the debug.txt
for any errors.
Step 5 - Boot installed system
After the installation has finished and any errors are resolved, you can run reboot
to restart the server and boot the newly installed system. You can watch the boot process if you have a KVM attached or via the VNC console in Cloud Console.
After some time, the server should respond to ping. Login to the default SSH port 22 should fail because the disk is still encrypted. Login to the dropbear SSH port 2222 and run cryptroot-unlock
to unlock the encrypted partition(s). When you connect to dropbear, make sure you use the private SSH key corresponding to the public key stored in /tmp/authorized_keys
.
-
With ED25519 or ECDSA key
ssh -p 2222 root@<your-host>
-
With RSA key
In case of RSA, we must explicitly specify that this key is accepted.ssh -o "PubkeyAcceptedKeyTypes +ssh-rsa" -p 2222 root@<your-host> -i ~/.ssh/id_rsa
Example:
$ ssh -o "PubkeyAcceptedKeyTypes +ssh-rsa" -p 2222 root@<your-host> -i ~/.ssh/id_rsa
BusyBox v1.30.1 (Ubuntu 1:1.30.1-7ubuntu3) built-in shell (ash)
Enter 'help' for a list of built-in commands.
# cryptroot-unlock
Please unlock disk luks-80e097ad-c0ab-47ce-9302-02dd316dc45c:
Enter the password that you previously set in /tmp/setup.conf
for CRYPTPASSWORD
. If the password is correct, the boot will continue and you will automatically be disconnected from the temporary SSH session to dropbear.
After a few seconds, you can connect to the server via the default SSH port 22:
ssh -p 22 root@<your-host>