From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [45.144.208.40]) by lore.proxmox.com (Postfix) with ESMTPS id 330641FF0C0 for ; Wed, 18 Nov 2026 00:44:25 +0100 (CET) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id C859A2170E; Wed, 18 Nov 2026 00:43:47 +0100 (CET) From: Thomas Lamprecht To: pve-devel@lists.proxmox.com Subject: [PATCH docs 1/2] installation: describe full-disk encryption Date: Wed, 18 Nov 2026 00:42:30 +0100 Message-ID: <20261117234330.801935-8-t.lamprecht@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20261117234330.801935-1-t.lamprecht@proxmox.com> References: <20261117234330.801935-1-t.lamprecht@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1794959018647 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.043 Adjusted score from AWL reputation of From: address DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment (newer systems) POISEN_SPAM_PILL 0.1 Meta: its spam POISEN_SPAM_PILL_1 0.1 random spam to be learned in bayes POISEN_SPAM_PILL_3 0.1 random spam to be learned in bayes RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: WAYINQDSY6XNUPW5THKZEVKYFLE7TDMP X-Message-ID-Hash: WAYINQDSY6XNUPW5THKZEVKYFLE7TDMP X-MailFrom: t.lamprecht@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: The installer can encrypt the installation disks with a passphrase that has to be entered at every boot. Describe what that covers and what it does not, what to consider before enabling it, and the tasks that come after the installation: managing passphrases with cryptsetup, unlocking over SSH with dropbear-initramfs, and accessing an encrypted installation from the installation medium, whose Rescue Boot entry cannot boot one. Signed-off-by: Thomas Lamprecht --- pve-installation.adoc | 222 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 222 insertions(+) diff --git a/pve-installation.adoc b/pve-installation.adoc index 7fe109a..36b8801 100644 --- a/pve-installation.adoc +++ b/pve-installation.adoc @@ -166,6 +166,9 @@ settings can be changed under xref:advanced_zfs_options[`Advanced Options`]. WARNING: ZFS on top of any hardware RAID is not supported and can result in data loss. +The `Options` dialog also offers to encrypt the installation disks, see +xref:installation_disk_encryption[Full-Disk Encryption]. + [thumbnail="screenshot/pve-select-location.png"] The next page asks for basic configuration options like your location, time @@ -190,6 +193,10 @@ recommended to use a stronger password. Some guidelines are: (current or past), and biographical information (for example ID numbers, ancestors' names or dates). +If you enabled disk encryption, this step also asks for the disk passphrase. +It is typed with the keyboard layout selected in the previous step, like at the +boot prompt. + The email address is used to send notifications to the system administrator. For example: @@ -380,6 +387,221 @@ Defines the total hard disk size to be used. This is useful to save free space on the hard disk(s) for further partitioning (for example, to create a swap partition). +[[installation_disk_encryption]] +Full-Disk Encryption +~~~~~~~~~~~~~~~~~~~~ + +The installer can encrypt the installation disks, so that the data of a +powered-off or removed server cannot be read, for example after a disk was +replaced under warranty, decommissioned or stolen. The system then asks for a +passphrase at every boot. + +To enable it, boot the installer in UEFI mode, open the `Options` dialog of the +target disk step and check *Passphrase at boot* next to *Encryption*. In the +terminal UI, the option is called *Encryption (passphrase at boot)*. The +password step then also asks for the disk passphrase. + +How the disks are encrypted depends on the file system: + +`ext4` and `xfs`:: + +The partition holding the LVM volume group `pve` is a LUKS2 container named +`luks-rpv`. This covers the `root`, `swap` and `data` volumes. + +`btrfs`:: + +Each disk holds its own LUKS2 container, named `luks-rfs0`, `luks-rfs1` and so +on, all with the same passphrase. The passphrase is normally asked only once at +boot. + +`zfs`:: + +The pool `rpool` is the encryption root of native ZFS encryption. All datasets +inherit it, including those created later, such as the one of the `local-zfs` +storage. The `copies` option allows at most 2, as ZFS stores encryption metadata +where a third copy would go. ++ +Native ZFS encryption leaves the names, properties and space usage of datasets +and snapshots readable. It derives the key from the passphrase with PBKDF2, +which makes guessing a short passphrase cheaper than with the Argon2id that +LUKS2 uses. + +The EFI system partitions, which hold the boot loader, the kernels and the +initial RAM disks, stay unencrypted. Disks that are not part of the +installation, and storages added later on them, are not encrypted either. + +NOTE: The encryption protects data at rest. It does not protect against someone +who can modify the unencrypted boot files, for example to capture the passphrase +at the next boot. Secure Boot does not prevent this either, as it does not +verify the initial RAM disk. + +The passphrase must have at least 8 characters, must not be longer than 512 +bytes and must not contain control characters. The boot prompt uses the +keyboard layout selected in the installer. Prefer characters that can be typed +on every keyboard and remote console you may need to use. + +Consider the following before enabling encryption: + +* A host can only boot once someone enters the passphrase, either on its console + or over SSH, see xref:installation_disk_encryption_ssh[Unlocking Over SSH]. + This also applies to the automatic restart of a fenced node in an HA cluster. + +* Without the passphrase, or another key added later, the data cannot be + recovered. Store it in a safe place. With LUKS2, consider adding a recovery + passphrase, see xref:installation_disk_encryption_keys[Managing Passphrases]. + +* Unlocking with a TPM or a FIDO2 token is not supported. + +* The installation does not erase data left on the disks from before. If they + held sensitive data, erase them completely before the installation, for + example with the secure erase function of the drive. + +* The LUKS2 containers pass discard requests on, so that SSDs and thin + storage can reclaim unused space. This reveals which blocks are in use, but + not their content. + +* The underlying storage cannot compress or deduplicate encrypted data, for + example the storage of a virtual disk. + +For automated installations, the passphrase is set in the +`[disk-setup.encryption]` section of the answer file. The +`proxmox-auto-install-assistant` refuses to embed such an answer file into the +ISO, as every copy would contain the passphrase. Fetch it over the network, +preferably over HTTPS, or from a separate partition instead. See +https://pve.proxmox.com/wiki/Automated_Installation[the wiki] for details. + +[[installation_disk_encryption_keys]] +Managing Passphrases +^^^^^^^^^^^^^^^^^^^^ + +A LUKS2 container has up to 32 key slots, each holding a passphrase that +unlocks it. The installer sets up one. Use `cryptsetup` to manage them, on +every container of a `btrfs` installation: + +---- +# cryptsetup luksAddKey /dev/disk/by-label/luks-rpv +# cryptsetup luksChangeKey /dev/disk/by-label/luks-rpv +# cryptsetup luksRemoveKey /dev/disk/by-label/luks-rpv +---- + +`luksAddKey` adds a passphrase, for example a long, random recovery passphrase +that you store offline. `luksChangeKey` replaces a passphrase and +`luksRemoveKey` removes one. Each command first asks for an existing +passphrase. + +If another disk holds a container with the same label, for example from an +older installation, use the device that `cryptsetup status luks-rpv` lists +instead. + +NOTE: On hosts with less than 4 GiB of memory, limit the memory that unlocking +with a new passphrase needs to a quarter of the memory, as the installer does, +for example `--pbkdf-memory 524288` (in KiB) on a host with 2 GiB. Otherwise, +`cryptsetup` chooses a value for the running system, which the initial RAM disk +may not be able to provide at boot. + +To guard against a damaged LUKS header, keep a backup of it in a safe place: + +---- +# cryptsetup luksHeaderBackup /dev/disk/by-label/luks-rpv --header-backup-file luks-rpv.img +---- + +CAUTION: A header backup still opens the container with every passphrase that +was valid when the backup was made, even after that passphrase was changed or +removed. + +Native ZFS encryption has exactly one passphrase. To change it, run: + +---- +# zfs change-key rpool +---- + +CAUTION: `zfs change-key` does not overwrite the copy of the encryption key +that the old passphrase protects, which can remain on the disks for an +indeterminate time. With access to the disks, the old passphrase may therefore +still decrypt the data. + +[[installation_disk_encryption_ssh]] +Unlocking Over SSH +^^^^^^^^^^^^^^^^^^ + +The `dropbear-initramfs` package adds an SSH server to the initial RAM disk, +which allows entering the passphrase remotely. + +. Install the package: ++ +---- +# apt install dropbear-initramfs +---- + +. Add the public SSH keys that may unlock the host to + `/etc/dropbear/initramfs/authorized_keys`. Password logins are not possible. + +. Choose a port other than 22 in `/etc/dropbear/initramfs/dropbear.conf`, so + that SSH clients do not report a changed host key when switching between the + boot-time server and the running host: ++ +---- +DROPBEAR_OPTIONS="-p 2222" +---- + +. Configure the network of the initial RAM disk with `IP=` in + `/etc/initramfs-tools/initramfs.conf`, either `IP=dhcp` or a static address: ++ +---- +IP=
::::::off +---- ++ +The interface name is the one the kernel assigns, for example `enp1s0`, not a +name pinned by the installer such as `nic0`. Only IPv4 on a plain network +interface is possible, not on a bond or a VLAN. + +. Rebuild the initial RAM disks: ++ +---- +# update-initramfs -u -k all +---- + +At the next boot, log in on the configured port and enter the passphrase with +`cryptroot-unlock` for LUKS, or `zfsunlock` for ZFS: + +---- +$ ssh -p 2222 root@
+# cryptroot-unlock +---- + +The console prompt stays available at the same time. + +NOTE: The host keys of the boot-time SSH server are stored in the unencrypted +initial RAM disk. + +[[installation_disk_encryption_rescue]] +Rescue +^^^^^^ + +The *Rescue Boot* entry of the installation medium cannot boot an encrypted +installation. To access one from the installation medium instead: + +. Boot *Advanced Options -> Install {pve} (Terminal UI, Debug Mode)*. + +. Leave the first shell with `exit`. The second one opens before the installer + starts. + +. The shell uses the US keyboard layout. To enter the passphrase with another + layout, load it first, for example the German one with `ckbcomp de | loadkeys`. + +. Use `proxmox-chroot` with the file system of the installation, `ext4`, `xfs`, + `btrfs` or `zfs`, to unlock it and mount it under `/target`: ++ +---- +# proxmox-chroot prepare -f ext4 +# chroot /target +---- ++ +It asks for the passphrase, with `btrfs` once for every disk. + +Leave the chroot and run `proxmox-chroot cleanup -f ` once done, +which also locks the installation again. + [[advanced_network_options]] Advanced Network Configuration Options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 2.47.3