public inbox for pve-devel@lists.proxmox.com
 help / color / mirror / Atom feed
From: Thomas Lamprecht <t.lamprecht@proxmox.com>
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	[thread overview]
Message-ID: <20261117234330.801935-8-t.lamprecht@proxmox.com> (raw)
In-Reply-To: <20261117234330.801935-1-t.lamprecht@proxmox.com>

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 <t.lamprecht@proxmox.com>
---
 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=<address>::<gateway>:<netmask>::<interface>: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@<address>
+# 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 <file system>` once done,
+which also locks the installation again.
+
 [[advanced_network_options]]
 Advanced Network Configuration Options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- 
2.47.3





  parent reply	other threads:[~2026-11-17 23:44 UTC|newest]

Thread overview: 9+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-17 23:42 [PATCH proxmox/installer/docs 0/8] installer: add full-disk encryption of the system disks Thomas Lamprecht
2026-11-17 23:42 ` [PATCH proxmox 1/1] installer-types: add full-disk encryption to the disk setup Thomas Lamprecht
2026-11-17 23:42 ` [PATCH installer 1/5] install: encrypt the system disks with LUKS2 or native ZFS encryption Thomas Lamprecht
2026-11-17 23:42 ` [PATCH installer 2/5] auto: support full-disk encryption in answer files Thomas Lamprecht
2026-11-17 23:42 ` [PATCH installer 3/5] chroot enter: unlock the LUKS containers of an encrypted installation Thomas Lamprecht
2026-11-17 23:42 ` [PATCH installer 4/5] ui: offer full-disk encryption in the graphical and terminal installer Thomas Lamprecht
2026-11-17 23:42 ` [PATCH installer 5/5] assistant: keep the disk passphrase out of prepared ISOs Thomas Lamprecht
2026-11-17 23:42 ` Thomas Lamprecht [this message]
2026-11-17 23:42 ` [PATCH docs 2/2] local-zfs: update the limitations of native encryption Thomas Lamprecht

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20261117234330.801935-8-t.lamprecht@proxmox.com \
    --to=t.lamprecht@proxmox.com \
    --cc=pve-devel@lists.proxmox.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal