* [PATCH proxmox/installer/docs 0/8] installer: add full-disk encryption of the system disks
@ 2026-11-17 23:42 Thomas Lamprecht
2026-11-17 23:42 ` [PATCH proxmox 1/1] installer-types: add full-disk encryption to the disk setup Thomas Lamprecht
` (7 more replies)
0 siblings, 8 replies; 9+ messages in thread
From: Thomas Lamprecht @ 2026-11-17 23:42 UTC (permalink / raw)
To: pve-devel
This series lets the installer encrypt the system disks with a
passphrase that has to be entered at every boot, so that the data of a
powered-off or removed server cannot be read. It covers all products,
the graphical and the terminal installer, and answer files.
ext4 and xfs installations put the LVM volume group into a LUKS2
container, Btrfs installations get one container per disk, and ZFS
installations use native ZFS encryption with the pool as encryption
root. All of them boot through proxmox-boot-tool, and the stock
initramfs asks for the passphrase. The option is only offered if the
installer was booted in UEFI mode.
ZFS uses its native encryption rather than a LUKS2 container under
every disk, so that data is encrypted once instead of once per mirror
or RAIDZ member, and replacing a disk works as without encryption. In
return, dataset names, properties and space usage stay readable, and
the key is derived with PBKDF2 instead of Argon2id. The second docs
patch drops the experimental label from native ZFS encryption, as the
issues it cited are fixed.
ZFS installations get a single passphrase for now, as native encryption
has one key per encryption root. A recovery passphrase or TPM2 and
FIDO2 unlocking can come later without a reinstall: `zfs change-key`
can switch an installed pool in place to a random key kept in a small
LUKS2 key store, whose key slots then provide them.
In the mid/long term I'd also like to add support to setup unlocking
with a TPM or FIDO2 token directly here, and likely also allowing UKIs
for a full measured boot [0]. But this is not supported yet, as among
other things Debian's initramfs-tools cannot use such key slots at boot,
so we'd need to switch to dracut and also need to sign systemd-boot.
For now the docs describe adding a recovery passphrase and unlocking
over SSH after the installation.
[0]: https://0pointer.de/blog/brave-new-trusted-boot-world.html
The installer patches need a proxmox-installer-types release with the
proxmox patch, and the ISO needs cryptsetup and cryptsetup-initramfs
in its package pool, plus keyutils for PDM. PDM gets its own patch on
pdm-devel.
I tested all four products in VMs: every file system, single and
multi-disk, with and without Secure Boot, interactive and automated,
including a non-ASCII passphrase with a German keyboard layout,
reinstalling over an existing LUKS container and the rescue procedure
from the docs.
Sending them mostly to give them some early exposure, while this
MVP is rather polished, there is no need to rush this.
proxmox:
Thomas Lamprecht (1):
installer-types: add full-disk encryption to the disk setup
proxmox-installer-types/src/answer.rs | 141 ++++++++++++++++++++++-
proxmox-installer-types/src/lib.rs | 22 ++++
proxmox-installer-types/src/post_hook.rs | 5 +-
3 files changed, 165 insertions(+), 3 deletions(-)
installer:
Thomas Lamprecht (5):
install: encrypt the system disks with LUKS2 or native ZFS encryption
auto: support full-disk encryption in answer files
chroot enter: unlock the LUKS containers of an encrypted installation
ui: offer full-disk encryption in the graphical and terminal installer
assistant: keep the disk passphrase out of prepared ISOs
Cargo.toml | 2 +-
Proxmox/Install.pm | 254 ++++++++++++-
Proxmox/Install/Config.pm | 15 +
Proxmox/Sys/Block.pm | 2 +-
debian/control | 3 +-
html/ack_template.htm | 2 +
html/pbs/passwd.htm | 1 +
html/pdm/passwd.htm | 1 +
html/pmg/passwd.htm | 1 +
html/pve/passwd.htm | 1 +
proxinstall | 99 ++++-
proxmox-auto-install-assistant/src/main.rs | 93 ++++-
proxmox-auto-installer/src/utils.rs | 13 +-
proxmox-auto-installer/tests/parse-answer.rs | 5 +
.../parse_answer/encryption_luks.json | 26 ++
.../parse_answer/encryption_luks.toml | 17 +
.../parse_answer/encryption_zfs.json | 36 ++
.../parse_answer/encryption_zfs.toml | 24 ++
.../encryption_empty_passphrase.json | 3 +
.../encryption_empty_passphrase.toml | 17 +
.../encryption_passphrase_control_char.json | 3 +
.../encryption_passphrase_control_char.toml | 17 +
.../encryption_passphrase_too_short.json | 3 +
.../encryption_passphrase_too_short.toml | 17 +
proxmox-chroot/src/main.rs | 351 ++++++++++++++++--
proxmox-installer-common/src/options.rs | 3 +
proxmox-installer-common/src/setup.rs | 17 +
proxmox-post-hook/src/main.rs | 8 +-
proxmox-tui-installer/src/main.rs | 68 +++-
proxmox-tui-installer/src/options.rs | 19 +-
proxmox-tui-installer/src/setup.rs | 9 +-
proxmox-tui-installer/src/views/bootdisk.rs | 49 ++-
proxmox-tui-installer/src/views/mod.rs | 6 +
test/Makefile | 7 +-
test/fde-preflight.pl | 143 +++++++
35 files changed, 1257 insertions(+), 78 deletions(-)
create mode 100644 proxmox-auto-installer/tests/resources/parse_answer/encryption_luks.json
create mode 100644 proxmox-auto-installer/tests/resources/parse_answer/encryption_luks.toml
create mode 100644 proxmox-auto-installer/tests/resources/parse_answer/encryption_zfs.json
create mode 100644 proxmox-auto-installer/tests/resources/parse_answer/encryption_zfs.toml
create mode 100644 proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_empty_passphrase.json
create mode 100644 proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_empty_passphrase.toml
create mode 100644 proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_passphrase_control_char.json
create mode 100644 proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_passphrase_control_char.toml
create mode 100644 proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_passphrase_too_short.json
create mode 100644 proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_passphrase_too_short.toml
create mode 100755 test/fde-preflight.pl
docs:
Thomas Lamprecht (2):
installation: describe full-disk encryption
local-zfs: update the limitations of native encryption
local-zfs.adoc | 23 +++--
pve-installation.adoc | 222 ++++++++++++++++++++++++++++++++++++++++++
2 files changed, 233 insertions(+), 12 deletions(-)
--
2.47.3
^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCH proxmox 1/1] installer-types: add full-disk encryption to the disk setup
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 ` Thomas Lamprecht
2026-11-17 23:42 ` [PATCH installer 1/5] install: encrypt the system disks with LUKS2 or native ZFS encryption Thomas Lamprecht
` (6 subsequent siblings)
7 siblings, 0 replies; 9+ messages in thread
From: Thomas Lamprecht @ 2026-11-17 23:42 UTC (permalink / raw)
To: pve-devel
Let answer files request full-disk encryption of the system disks with
a `[disk-setup.encryption]` section holding the passphrase that unlocks
the system at boot. The filesystem determines how: LUKS2 for ext4, xfs
and Btrfs, native ZFS encryption for ZFS. Further unlock methods, such
as additional passphrases or a recovery key, can be added to LUKS
containers on the installed system.
verify_encryption() rejects what could only fail after the disks were
wiped or could not be entered when unlocking: passphrases with control
characters or longer than the 512 bytes that cryptsetup and OpenZFS
read, and more than 2 ZFS copies, since OpenZFS stores encryption
metadata where a third copy would go. Like the root password, a
passphrase needs at least 8 characters, which also covers the minimum
of 8 bytes of ZFS. The passphrase rules are available on their own, so
that the interactive installers can check a passphrase where it is
entered.
Installers built against this version report answer fetch schema 1.2,
which answers with encryption require, so answer servers do not send
them to installers that would reject the unknown section.
The post-installation webhook data reports the encryption mode, which
follows from the filesystem.
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
proxmox-installer-types/src/answer.rs | 141 ++++++++++++++++++++++-
proxmox-installer-types/src/lib.rs | 22 ++++
proxmox-installer-types/src/post_hook.rs | 5 +-
3 files changed, 165 insertions(+), 3 deletions(-)
diff --git a/proxmox-installer-types/src/answer.rs b/proxmox-installer-types/src/answer.rs
index 81b10255..07d49a90 100644
--- a/proxmox-installer-types/src/answer.rs
+++ b/proxmox-installer-types/src/answer.rs
@@ -94,7 +94,7 @@ pub mod fetch {
}
impl AnswerFetchDataSchema {
- const SCHEMA_VERSION: &str = "1.1";
+ const SCHEMA_VERSION: &str = "1.2";
/// Returns the version as `(major, minor)` tuple, or `None` if it is malformed.
///
@@ -173,6 +173,9 @@ impl AutoInstallerConfig {
/// this with [`fetch::AnswerFetchDataSchema::version()`] of the request to avoid sending an
/// answer the installer cannot use.
pub fn required_fetch_schema_version(&self) -> (u32, u32) {
+ if self.disks.encryption.is_some() {
+ return (1, 2);
+ }
if self.network.bond().is_some() || self.network.vlan().is_some() {
return (1, 1);
}
@@ -936,9 +939,29 @@ pub struct DiskSetup {
#[serde(skip_serializing_if = "Option::is_none")]
/// Btrfs-specific filesystem options.
pub btrfs: Option<BtrfsOptions>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ /// Full-disk encryption of the system disks.
+ pub encryption: Option<DiskEncryption>,
}
impl DiskSetup {
+ /// Checks the encryption options against what can be set up and unlocked at boot.
+ pub fn verify_encryption(&self) -> Result<()> {
+ let Some(encryption) = &self.encryption else {
+ return Ok(());
+ };
+ if let Err(reason) = DiskEncryption::check_passphrase(&encryption.passphrase) {
+ bail!("'disk-setup.encryption.passphrase' {reason}");
+ }
+ // OpenZFS stores encryption metadata where the third copy of a block would go.
+ let copies = self.zfs.as_ref().and_then(|zfs| zfs.copies).unwrap_or(1);
+ if self.filesystem == Filesystem::Zfs && copies > 2 {
+ bail!("'disk-setup.zfs.copies' must be at most 2 with disk encryption");
+ }
+
+ Ok(())
+ }
+
/// Returns the concrete disk selection made in the setup.
pub fn disk_selection(&self) -> Result<DiskSelection> {
if self.disk_list.is_empty() && self.filter.is_empty() {
@@ -1039,6 +1062,44 @@ impl DiskSetup {
}
}
+#[cfg_attr(feature = "api-types", api)]
+#[derive(Clone, Deserialize, Serialize, PartialEq)]
+#[serde(rename_all = "kebab-case", deny_unknown_fields)]
+/// Full-disk encryption of the system disks, LUKS2 for ext4, xfs and Btrfs, native encryption for
+/// ZFS.
+pub struct DiskEncryption {
+ /// Passphrase that unlocks the system at boot.
+ pub passphrase: String,
+}
+
+impl DiskEncryption {
+ /// Checks a passphrase against what can be set up and entered at the boot prompt. The error
+ /// completes a sentence about the passphrase, like "must not contain control characters".
+ pub fn check_passphrase(passphrase: &str) -> Result<(), &'static str> {
+ // The minimum of the root password, which also covers the 8 bytes that ZFS requires.
+ if passphrase.chars().count() < 8 {
+ return Err("must be at least 8 characters long");
+ }
+ // Neither can be typed at the boot prompt, and OpenZFS stops reading a key file at a newline.
+ if passphrase.chars().any(char::is_control) {
+ return Err("must not contain control characters");
+ }
+ // cryptsetup's own prompt, as used for unlocking from a rescue system, reads at most 512
+ if passphrase.len() > 512 {
+ return Err("must not be longer than 512 bytes");
+ }
+ Ok(())
+ }
+}
+
+impl fmt::Debug for DiskEncryption {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ f.debug_struct("DiskEncryption")
+ .field("passphrase", &"<redacted>")
+ .finish()
+ }
+}
+
#[cfg_attr(feature = "api-types", api)]
#[derive(Copy, Clone, Deserialize, Serialize, Debug, PartialEq)]
#[serde(rename_all = "lowercase", deny_unknown_fields)]
@@ -1637,7 +1698,7 @@ mod tests {
assert_eq!(
fetch::AnswerFetchDataSchema::default().version(),
- Some((1, 1))
+ Some((1, 2))
);
assert_eq!(schema("1.0").version(), Some((1, 0)));
assert_eq!(schema("2.10").version(), Some((2, 10)));
@@ -1678,6 +1739,18 @@ mod tests {
"#;
let answer: AutoInstallerConfig = toml::from_str(&with_network(bond)).unwrap();
assert_eq!(answer.required_fetch_schema_version(), (1, 1));
+
+ let encryption = r#"
+ [disk-setup.encryption]
+ passphrase = "secret-passphrase"
+ "#;
+ let answer: AutoInstallerConfig =
+ toml::from_str(&format!("{MINIMAL_ANSWER}{encryption}")).unwrap();
+ assert_eq!(answer.required_fetch_schema_version(), (1, 2));
+
+ let answer: AutoInstallerConfig =
+ toml::from_str(&format!("{}{encryption}", with_network(&vlan))).unwrap();
+ assert_eq!(answer.required_fetch_schema_version(), (1, 2));
}
fn disks(n: usize) -> Vec<String> {
@@ -1696,6 +1769,7 @@ mod tests {
}),
lvm: None,
btrfs: None,
+ encryption: None,
}
}
@@ -1711,6 +1785,7 @@ mod tests {
raid: Some(raid),
..Default::default()
}),
+ encryption: None,
}
}
@@ -1774,10 +1849,72 @@ mod tests {
}),
lvm: None,
btrfs: None,
+ encryption: None,
};
assert!(setup.filesystem_details().is_ok());
}
+ #[test]
+ fn encryption_passphrase_rules() {
+ let check = |filesystem, passphrase: &str| {
+ let mut setup = zfs(ZfsRaidLevel::Raid0, 1);
+ setup.filesystem = filesystem;
+ setup.encryption = Some(DiskEncryption {
+ passphrase: passphrase.to_string(),
+ });
+ setup.verify_encryption().map_err(|err| err.to_string())
+ };
+
+ assert!(zfs(ZfsRaidLevel::Raid0, 1).verify_encryption().is_ok());
+ assert!(check(Filesystem::Ext4, "password").is_ok());
+ assert!(check(Filesystem::Zfs, &"\u{e4}".repeat(8)).is_ok());
+ assert!(check(Filesystem::Zfs, &"x".repeat(512)).is_ok());
+
+ for filesystem in [Filesystem::Ext4, Filesystem::Zfs] {
+ for short in ["", "passwor", "\u{e4}\u{e4}\u{e4}\u{e4}\u{e4}\u{e4}\u{e4}"] {
+ let err = check(filesystem, short).unwrap_err();
+ assert!(err.contains("at least 8 characters"), "{err}");
+ }
+ }
+ for control in ["\n", "\t", "\0", "\u{7f}", "\u{85}"] {
+ let err = check(Filesystem::Btrfs, &format!("pass{control}word")).unwrap_err();
+ assert!(err.contains("control characters"));
+ }
+ assert!(
+ check(Filesystem::Zfs, &"x".repeat(513))
+ .unwrap_err()
+ .contains("512 bytes")
+ );
+ assert!(check(Filesystem::Ext4, &"x".repeat(512)).is_ok());
+ assert!(
+ check(Filesystem::Ext4, &"x".repeat(513))
+ .unwrap_err()
+ .contains("512 bytes")
+ );
+
+ let copies = |filesystem, copies| {
+ let mut setup = zfs(ZfsRaidLevel::Raid0, 1);
+ setup.filesystem = filesystem;
+ setup.zfs.as_mut().unwrap().copies = Some(copies);
+ setup.encryption = Some(DiskEncryption {
+ passphrase: "password".to_string(),
+ });
+ setup.verify_encryption().map_err(|err| err.to_string())
+ };
+ assert!(copies(Filesystem::Zfs, 2).is_ok());
+ assert!(
+ copies(Filesystem::Zfs, 3)
+ .unwrap_err()
+ .contains("at most 2")
+ );
+ assert!(copies(Filesystem::Ext4, 3).is_ok());
+
+ let encryption = DiskEncryption {
+ passphrase: "secret".to_string(),
+ };
+ assert!(!format!("{encryption:?}").contains("secret"));
+ }
+
#[test]
fn network_bond_requires_at_least_two_members() {
let mut bond = NetworkBondOptions::default();
diff --git a/proxmox-installer-types/src/lib.rs b/proxmox-installer-types/src/lib.rs
index df1f7944..e0822f6d 100644
--- a/proxmox-installer-types/src/lib.rs
+++ b/proxmox-installer-types/src/lib.rs
@@ -32,6 +32,28 @@ pub enum BootType {
Efi,
}
+#[cfg_attr(feature = "api-types", api)]
+#[derive(Copy, Clone, Debug, Eq, Deserialize, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+/// How the system disks of an installation are encrypted.
+pub enum EncryptionMode {
+ /// LUKS2, for ext4, xfs and Btrfs installations.
+ Luks,
+ /// Native ZFS encryption, for ZFS installations.
+ ZfsNative,
+}
+
+impl EncryptionMode {
+ /// Returns how an installation with the given filesystem gets encrypted.
+ pub fn for_filesystem(filesystem: answer::FilesystemType) -> Self {
+ use answer::FilesystemType::*;
+ match filesystem {
+ Ext4 | Xfs | Btrfs(_) => Self::Luks,
+ Zfs(_) => Self::ZfsNative,
+ }
+ }
+}
+
/// Uses a BTreeMap to have the keys sorted
pub type UdevProperties = BTreeMap<String, String>;
diff --git a/proxmox-installer-types/src/post_hook.rs b/proxmox-installer-types/src/post_hook.rs
index 8047a7f8..325ca830 100644
--- a/proxmox-installer-types/src/post_hook.rs
+++ b/proxmox-installer-types/src/post_hook.rs
@@ -7,7 +7,7 @@ use proxmox_network_types::{MacAddress, ip_address::Cidr};
use proxmox_schema::api;
use crate::{
- BootType, IsoInfo, ProxmoxProduct, SystemDMI, UdevProperties,
+ BootType, EncryptionMode, IsoInfo, ProxmoxProduct, SystemDMI, UdevProperties,
answer::{FilesystemType, RebootMode},
};
@@ -197,6 +197,9 @@ pub struct PostHookInfo {
pub dmi: SystemDMI,
/// Filesystem used for boot disk(s)
pub filesystem: FilesystemType,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ /// Encryption of the boot disk(s), if any.
+ pub encryption: Option<EncryptionMode>,
/// Fully qualified domain name of the installed system
pub fqdn: String,
/// Unique systemd-id128 identifier of the installed system (128-bit, 16 bytes)
--
2.47.3
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [PATCH installer 1/5] install: encrypt the system disks with LUKS2 or native ZFS encryption
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 ` Thomas Lamprecht
2026-11-17 23:42 ` [PATCH installer 2/5] auto: support full-disk encryption in answer files Thomas Lamprecht
` (5 subsequent siblings)
7 siblings, 0 replies; 9+ messages in thread
From: Thomas Lamprecht @ 2026-11-17 23:42 UTC (permalink / raw)
To: pve-devel
Full-disk encryption keeps the data of a powered-off or removed system
unreadable, for example after a disk was returned for warranty,
decommissioned or stolen. Implement it in the low-level installer, for
an encryption block in the installation config with the passphrase,
which the frontends and answer files get to set in follow-up commits.
The file system determines how the disks are encrypted.
ext4 and xfs installs put LVM, and with it root, swap and the guest
data thin pool, inside a LUKS2 container on the OS partition. Btrfs
installs get one container per member, all with the same passphrase,
which the decrypt_keyctl keyscript asks for once at boot and caches for
the other members. ZFS installs make the pool the encryption root of
native ZFS encryption, so every dataset on the rpool inherits it.
The installer hands the passphrase to cryptsetup and zfs in a key file
on tmpfs that only root can read and that is removed right after, so it
shows up neither in the installation log nor in the command lines of
processes. The file holds the passphrase encoded as UTF-8, as the
console sends it that way when it is typed at boot, so that non-ASCII
passphrases unlock as well.
Encrypted LVM installs get their ESPs managed by proxmox-boot-tool, like
ZFS and Btrfs installs, as GRUB cannot read the kernel from the
encrypted root anymore. With Secure Boot that is GRUB through shim,
otherwise systemd-boot, and the initramfs asks for the passphrase.
Everything that can be checked without the disks is checked before any
of them is wiped: UEFI boot, the passphrase rules, at most 2 ZFS
copies (as OpenZFS keeps encryption metadata where a third copy would
go), cryptsetup in the installer environment and the package pool, and
that no device is open under a name of the new LUKS containers, as
after unlocking an installation from a debug shell.
The passphrase needs at least 8 characters, like the root password,
which also covers the 8 bytes that ZFS requires. The memory cost of the
LUKS2 key slots is capped at a quarter of the memory, as unlocking in
the initramfs warns about, and can fail on, a key slot that needs more
than half of the memory free there, which formatting cannot measure
from the installer environment on hosts with little memory. As the
cryptsetup initramfs hook only warns if it leaves out a container, for
example when its keyscript is missing, the installation fails unless
the initramfs unlocks all of them.
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
Proxmox/Install.pm | 254 +++++++++++++++++++++++++++++++++++---
Proxmox/Install/Config.pm | 15 +++
Proxmox/Sys/Block.pm | 2 +-
debian/control | 1 +
test/Makefile | 7 +-
test/fde-preflight.pl | 143 +++++++++++++++++++++
6 files changed, 403 insertions(+), 19 deletions(-)
create mode 100755 test/fde-preflight.pl
diff --git a/Proxmox/Install.pm b/Proxmox/Install.pm
index 08860cd4..363deb63 100644
--- a/Proxmox/Install.pm
+++ b/Proxmox/Install.pm
@@ -5,6 +5,7 @@ use warnings;
use Cwd 'abs_path';
use Encode;
+use Fcntl qw(O_WRONLY O_CREAT O_EXCL);
use POSIX ":sys_wait_h";
use Proxmox::Install::ISOEnv;
@@ -170,6 +171,59 @@ sub btrfs_create {
syscmd($cmd);
}
+# Secrets reach cryptsetup and zfs only through a key file on tmpfs that only root can read, which
+# keeps them out of the command log and of /proc/<pid>/cmdline. They are written as UTF-8, as the
+# console sends a passphrase typed at boot that way. Calls $code with the path of the key file,
+# which is removed afterwards.
+my sub with_secret_keyfile {
+ my ($secret, $code) = @_;
+
+ my $path = "/run/proxmox-installer-key.$$";
+ my $bytes = Encode::encode('UTF-8', $secret, Encode::FB_CROAK() | Encode::LEAVE_SRC());
+ sysopen(my $fh, $path, O_WRONLY | O_CREAT | O_EXCL, 0600)
+ or die "unable to create key file '$path' - $!\n";
+ eval {
+ print {$fh} $bytes or die "unable to write key file '$path' - $!\n";
+ close($fh) or die "unable to write key file '$path' - $!\n";
+ $code->($path);
+ };
+ my $err = $@;
+ unlink($path);
+ die $err if $err;
+}
+
+sub luks_format_and_open {
+ my ($dev, $name) = @_;
+
+ # pinned, so that changed cryptsetup defaults do not silently change new installations
+ my @format_opts = qw(
+ --batch-mode --type luks2 --cipher aes-xts-plain64 --key-size 512 --hash sha256
+ --pbkdf argon2id
+ );
+ # Unlocking in the initramfs warns about, and can fail on, a key slot that needs more than half
+ # of the memory free there, which luksFormat cannot measure from the installer. So use at most a
+ # quarter of the memory, and at most cryptsetup's default of 1 GiB.
+ my $total_kib = Proxmox::Install::RunEnv::get('total_memory') * 1024;
+ my $pbkdf_kib = int($total_kib / 4);
+ $pbkdf_kib = 1024 * 1024 if $pbkdf_kib > 1024 * 1024;
+ push @format_opts, '--pbkdf-memory', $pbkdf_kib, '--label', $name;
+
+ my $enc = Proxmox::Install::Config::get_encryption();
+ with_secret_keyfile(
+ $enc->{passphrase},
+ sub {
+ my ($keyfile) = @_;
+ my $format =
+ ['cryptsetup', 'luksFormat', @format_opts, '--key-file', $keyfile, $dev];
+ syscmd($format) == 0 || die "unable to set up encryption on '$dev'\n";
+ syscmd(['cryptsetup', 'open', '--key-file', $keyfile, $dev, $name]) == 0
+ || die "unable to open encrypted device '$dev'\n";
+ },
+ );
+
+ return "/dev/mapper/$name";
+}
+
sub zfs_ask_existing_zpool_rename {
my ($pool_name) = @_;
@@ -216,7 +270,24 @@ sub zfs_create_rpool {
my $cmd = "zpool create -f -o cachefile=none";
$cmd .= " -o ashift=$zfs_opts->{ashift}" if defined($zfs_opts->{ashift});
- syscmd("$cmd $pool_name $vdev") == 0 || die "unable to create zfs root pool\n";
+ if (my $enc = Proxmox::Install::Config::get_encryption()) {
+ # the pool is the encryption root, so all datasets inherit its key
+ with_secret_keyfile(
+ $enc->{passphrase},
+ sub {
+ my ($keyfile) = @_;
+ my $opts = "-O encryption=aes-256-gcm -O keyformat=passphrase"
+ . " -O keylocation=file://$keyfile";
+ syscmd("$cmd $opts $pool_name $vdev") == 0
+ || die "unable to create zfs root pool\n";
+ # before the key file goes away, so the pool never points to a missing file
+ syscmd("zfs set keylocation=prompt $pool_name") == 0
+ || die "unable to make zfs root pool ask for its passphrase at boot\n";
+ },
+ );
+ } else {
+ syscmd("$cmd $pool_name $vdev") == 0 || die "unable to create zfs root pool\n";
+ }
syscmd("zfs create $pool_name/ROOT") == 0
|| die "unable to create zfs $pool_name/ROOT volume\n";
@@ -947,6 +1018,95 @@ sub generate_ifupdown2_config {
return $ifaces;
}
+# OpenZFS stores encryption metadata where the third copy of a block would go.
+sub assert_zfs_encryption_copies {
+ my $copies = Proxmox::Install::Config::get_zfs_opt('copies') // 1;
+ die "native ZFS encryption allows at most 2 copies\n"
+ if $copies > 2 && defined(Proxmox::Install::Config::get_encryption());
+}
+
+sub assert_disk_passphrase {
+ my ($passphrase) = @_;
+
+ # the minimum of the root password, which also covers the 8 bytes that ZFS requires
+ die "the disk passphrase must be at least 8 characters long\n" if length($passphrase) < 8;
+ # neither can be typed at the boot prompt, and OpenZFS stops reading a key file at a newline
+ die "the disk passphrase must not contain control characters\n"
+ if $passphrase =~ m/[\x00-\x1f\x7f-\x9f]/;
+ my $bytes = Encode::encode('UTF-8', $passphrase, Encode::FB_CROAK() | Encode::LEAVE_SRC());
+ # cryptsetup's own prompt, as used for unlocking from a rescue system, reads at most 512
+ die "the disk passphrase must not be longer than 512 bytes\n" if length($bytes) > 512;
+}
+
+# Names of the LUKS containers that an installation creates, which are already in use.
+sub open_luks_container_names {
+ return grep { m/^luks-r(?:pv|fs\d+)$/ } map { s!^/dev/mapper/!!r } glob('/dev/mapper/luks-r*');
+}
+
+# Everything about the encryption setup that can be checked without the disks, so that a problem is
+# reported before any of them is wiped.
+sub fde_preflight_check {
+ my ($run_env, $pkgdir) = @_;
+
+ my $enc = Proxmox::Install::Config::get_encryption() // return;
+ my $luks = Proxmox::Install::Config::get_encryption_mode() eq 'luks';
+
+ die "full-disk encryption requires booting the installer in UEFI mode\n"
+ if $run_env->{boot_type} ne 'efi';
+ assert_zfs_encryption_copies() if !$luks;
+ assert_disk_passphrase($enc->{passphrase} // '');
+
+ return if is_test_mode();
+
+ if ($luks) {
+ die "this installer environment lacks cryptsetup, required for full-disk encryption\n"
+ if system('command -v cryptsetup >/dev/null 2>&1') != 0;
+ # unlocking at boot happens in the target's initramfs, installed from the package pool
+ my @missing = grep {
+ my @debs = glob("${pkgdir}/${_}_*.deb");
+ !@debs
+ } qw(cryptsetup-initramfs keyutils);
+ die "this installer image lacks packages required for full-disk encryption: @missing\n"
+ if @missing;
+ # opening a container under a name in use fails only after the disks were formatted
+ if (my ($name) = open_luks_container_names()) {
+ die "encrypted device '$name' is open, unmount or deactivate what is on it and close"
+ . " it with 'cryptsetup close $name'\n";
+ }
+ }
+}
+
+# The cryptsetup initramfs hook only warns if it leaves out a container, for example when its
+# keyscript is missing, so check that the initramfs unlocks all of them at boot.
+sub assert_initramfs_unlocks_luks {
+ my ($targetdir, $initrd, $bootdevinfo) = @_;
+
+ # on the target's disk, as its /tmp is a tmpfs during the installation
+ my $dir = '/var/tmp/initramfs-check';
+ eval {
+ syscmd(['chroot', $targetdir, 'unmkinitramfs', $initrd, $dir]) == 0
+ || die "unable to unpack initramfs '$initrd'\n";
+ # an initramfs with early microcode has its main archive in a subdirectory
+ my $root = -d "$targetdir$dir/main" ? "$targetdir$dir/main" : "$targetdir$dir";
+
+ my $crypttab = "$root/cryptroot/crypttab";
+ my %options = map { m/^(\S+)\s+\S+\s+\S+\s+(\S+)/ ? ($1 => $2) : () }
+ split(/\n/, -f $crypttab ? file_read_all($crypttab) : '');
+ my @missing =
+ grep { !defined($options{$_}) } map { $_->{luks_name} // () } @$bootdevinfo;
+ die "initramfs does not unlock the encrypted devices @missing at boot\n" if @missing;
+
+ if (grep { m/(?:^|,)keyscript=decrypt_keyctl(?:,|$)/ } values %options) {
+ for my $path ('lib/cryptsetup/scripts/decrypt_keyctl', 'bin/keyctl') {
+ die "initramfs lacks '/$path', needed to unlock at boot\n" if !-x "$root/$path";
+ }
+ }
+ };
+ my $err = $@;
+ syscmd(['rm', '-rf', "$targetdir$dir"]);
+ die $err if $err;
+}
+
sub extract_data {
my $iso_env = Proxmox::Install::ISOEnv::get();
my $run_env = Proxmox::Install::RunEnv::get();
@@ -961,6 +1121,8 @@ sub extract_data {
die "target '$targetdir' does not exist\n" if !-d $targetdir;
+ fde_preflight_check($run_env, $proxmox_pkgdir);
+
my $starttime = [Time::HiRes::gettimeofday];
my $bootdevinfo = [];
@@ -984,6 +1146,11 @@ sub extract_data {
$use_btrfs = 1;
}
+ my $encrypted = defined(Proxmox::Install::Config::get_encryption());
+ my $luks = (Proxmox::Install::Config::get_encryption_mode() // '') eq 'luks';
+ # ESPs managed by proxmox-boot-tool hold the kernels, as GRUB cannot read an encrypted root
+ my $use_proxmox_boot_tool = $use_zfs || $use_btrfs || $encrypted;
+
if ($use_zfs) {
my $i;
for ($i = 5; $i > 0; $i--) {
@@ -1006,6 +1173,7 @@ sub extract_data {
syscmd("vgchange -an") if !is_test_mode(); # deactivate all detected VGs
if (is_test_mode()) {
+ die "LUKS encryption is not supported in test mode\n" if $luks;
my $test_images = Proxmox::Install::ISOEnv::get_test_images();
$rootdev = abs_path($test_images->[0]); # FIXME: use all selected for test too!
@@ -1049,18 +1217,25 @@ sub extract_data {
my $logical_bsize = @$hd[4];
my ($size, $osdev, $efidev) =
- partition_bootable_disk($devname, $hdsize, '8300');
- $rootdev = $osdev if !defined($rootdev); # simply point to first disk
+ partition_bootable_disk($devname, $hdsize, $luks ? '8309' : '8300');
my $by_id = Proxmox::Sys::Block::get_disk_by_id_path($devname);
- push @$bootdevinfo,
- {
- esp => $efidev,
- devname => $devname,
- osdev => $osdev,
- by_id => $by_id,
- logical_bsize => $logical_bsize,
- };
- push @$btrfs_partitions, $osdev;
+ my $di = {
+ esp => $efidev,
+ devname => $devname,
+ osdev => $osdev,
+ by_id => $by_id,
+ logical_bsize => $logical_bsize,
+ };
+ push @$bootdevinfo, $di;
+
+ # each member gets its own LUKS container, all with the same passphrase
+ my $member = $osdev;
+ if ($luks) {
+ $di->{luks_name} = 'luks-rfs' . (scalar(@$bootdevinfo) - 1);
+ $member = luks_format_and_open($osdev, $di->{luks_name});
+ }
+ $rootdev = $member if !defined($rootdev); # simply point to first disk
+ push @$btrfs_partitions, $member;
}
Proxmox::Sys::Block::udevadm_trigger_block();
@@ -1132,7 +1307,7 @@ sub extract_data {
my $logical_bsize = Proxmox::Sys::Block::logical_blocksize($target_hd);
my ($os_size, $osdev, $efidev) =
- partition_bootable_disk($target_hd, $hdsize, '8E00');
+ partition_bootable_disk($target_hd, $hdsize, $luks ? '8309' : '8E00');
Proxmox::Sys::Block::udevadm_trigger_block();
@@ -1146,10 +1321,22 @@ sub extract_data {
logical_bsize => $logical_bsize,
};
+ # LVM goes inside the LUKS container, so root, swap and guest data are all encrypted
+ my ($pvdev, $pv_size) = ($osdev, $os_size);
+ if ($luks) {
+ update_progress(0, 0.025, $maxper, "set up encryption");
+ $bootdevinfo->[0]->{luks_name} = 'luks-rpv';
+ $pvdev = luks_format_and_open($osdev, 'luks-rpv');
+ # smaller than the partition by the LUKS2 header, in KiB like the partition size
+ my $bytes = run_command(['blockdev', '--getsize64', $pvdev]);
+ die "unable to get size of '$pvdev'\n" if $bytes !~ m/^(\d+)\s*$/;
+ $pv_size = int($1 / 1024);
+ }
+
update_progress(0, 0.03, $maxper, "create LVs");
- my $swap_size = compute_swapsize($os_size);
- ($rootdev, $swapfile, $datadev) = create_lvm_volumes($osdev, $os_size, $swap_size);
+ my $swap_size = compute_swapsize($pv_size);
+ ($rootdev, $swapfile, $datadev) = create_lvm_volumes($pvdev, $pv_size, $swap_size);
# trigger udev to create /dev/disk/by-uuid
Proxmox::Sys::Block::udevadm_trigger_block(1);
@@ -1329,6 +1516,24 @@ sub extract_data {
my $resolvconf = "search $domain\nnameserver $dnsserver\n";
file_write_all("$targetdir/etc/resolv.conf", $resolvconf);
+ # configure crypttab, native ZFS encryption is unlocked by the ZFS initramfs scripts
+ my @luks = grep { defined($_->{luks_name}) } @$bootdevinfo;
+ if (scalar(@luks)) {
+ # 'initramfs' makes cryptsetup-initramfs unlock all of them, not only the root device
+ my $opts = 'luks,discard,initramfs';
+ # asks once and passes the passphrase on to the other Btrfs members
+ $opts .= ',keyscript=decrypt_keyctl' if scalar(@luks) > 1;
+
+ my $crypttab = "# <target name> <source device> <key file> <options>\n";
+ for my $di (@luks) {
+ my $uuid = run_command(['cryptsetup', 'luksUUID', $di->{osdev}]);
+ die "unable to get LUKS UUID of '$di->{osdev}'\n"
+ if $uuid !~ m/^([0-9a-f-]+)\s*$/i;
+ $crypttab .= "$di->{luks_name} UUID=$1 none $opts\n";
+ }
+ file_write_all("$targetdir/etc/crypttab", $crypttab);
+ }
+
# configure fstab
my $fstab = "# <file system> <mount point> <type> <options> <dump> <pass>\n";
@@ -1374,7 +1579,7 @@ sub extract_data {
# Note: this is required by current grub, but really dangerous, because
# vfat does not have journaling, so it triggers manual fsck after each crash
# so we only mount /boot/efi if really required (efi systems).
- if ($run_env->{boot_type} eq 'efi' && !($use_zfs || $use_btrfs)) {
+ if ($run_env->{boot_type} eq 'efi' && !$use_proxmox_boot_tool) {
if (scalar(@$bootdevinfo)) {
my $di = @$bootdevinfo[0]; # simply use first disk
@@ -1471,6 +1676,8 @@ _EOD
next if ($deb =~ /^proxmox-grub/ && $run_env->{boot_type} ne 'efi');
next if ($deb =~ /^proxmox-secure-boot-support_/ && !$run_env->{secure_boot});
next if $deb =~ /^proxmox-first-boot/ && !needs_first_boot_package();
+ # only needed for LUKS, and the cryptsetup initramfs hook complains about a ZFS root
+ next if $deb =~ /^cryptsetup(?:-initramfs|-bin)?_/ && !$luks;
# CPU microcode packages are x86-only
next if $deb =~ /^amd64-microcode_/ && $run_env->{cpu_vendor_id} ne 'AuthenticAMD';
@@ -1614,6 +1821,16 @@ _EOD
);
}
+ if ($luks && !$use_btrfs) {
+ # encrypted LVM installs boot through proxmox-boot-tool, like ZFS and Btrfs ones
+ my ($vg, $lv) = $rootdev =~ m|^/dev/([^/]+)/([^/]+)$|
+ or die "unexpected root device '$rootdev'\n";
+ file_write_all(
+ "$targetdir/etc/kernel/cmdline",
+ "root=/dev/mapper/$vg-$lv $target_cmdline\n",
+ );
+ }
+
# Always write zfs module parameter - even if the user did not select ZFS-on-root.
# It still makes sense to provide a sensible default for zfs_arc_max, in case a
# separate zfs pool is created afterwards.
@@ -1641,6 +1858,9 @@ _EOD
eval {
syscmd("chroot $targetdir /usr/sbin/update-initramfs -c -k $kapi") == 0
|| die "unable to install initramfs\n";
+ assert_initramfs_unlocks_luks(
+ $targetdir, "/boot/initrd.img-$kapi", $bootdevinfo,
+ ) if $luks;
my $native_4k_disk_bootable = 0;
foreach my $di (@$bootdevinfo) {
@@ -1649,7 +1869,7 @@ _EOD
foreach my $di (@$bootdevinfo) {
my $dev = $di->{devname};
- if ($use_zfs || $use_btrfs) {
+ if ($use_proxmox_boot_tool) {
prepare_proxmox_boot_esp(
$di->{esp},
$targetdir,
diff --git a/Proxmox/Install/Config.pm b/Proxmox/Install/Config.pm
index dc0b0f63..11d6302c 100644
--- a/Proxmox/Install/Config.pm
+++ b/Proxmox/Install/Config.pm
@@ -84,6 +84,9 @@ my sub init_cfg {
btrfs_opts => {
compress => 'off',
},
+ # full-disk encryption, LUKS2 or native ZFS encryption as per the file system, disabled if
+ # undef, otherwise a hash with the passphrase that unlocks the system at boot
+ encryption => undef,
# TODO: single disk selection config
target_hd => undef,
disk_selection => {},
@@ -219,6 +222,15 @@ sub get_btrfs_opt {
return defined($k) ? $opts->{$k} : $opts;
}
+sub set_encryption { set_key('encryption', $_[0]); }
+sub get_encryption { return get('encryption'); }
+
+# 'luks' for ext4, xfs and btrfs, 'zfs-native' for ZFS, undef without encryption
+sub get_encryption_mode {
+ return undef if !defined(get_encryption());
+ return get_filesys() =~ m/^zfs/ ? 'zfs-native' : 'luks';
+}
+
sub set_target_hd { set_key('target_hd', $_[0]); }
sub get_target_hd { return get('target_hd'); }
@@ -231,6 +243,9 @@ sub get_redacted {
$r->{root_password} = { '<redacted>' => '<redacted>' };
}
$r->{subscription_key} = '<redacted>' if defined($r->{subscription_key});
+ if (defined($r->{encryption}) && defined($r->{encryption}->{passphrase})) {
+ $r->{encryption}->{passphrase} = '<redacted>';
+ }
return $r;
}
diff --git a/Proxmox/Sys/Block.pm b/Proxmox/Sys/Block.pm
index 89b01c96..aa012482 100644
--- a/Proxmox/Sys/Block.pm
+++ b/Proxmox/Sys/Block.pm
@@ -222,7 +222,7 @@ sub partition_bootable_disk {
die "too dangerous" if is_test_mode();
die "unknown partition type '$ptype'"
- if !($ptype eq '8E00' || $ptype eq '8300' || $ptype eq 'BF01');
+ if !($ptype eq '8E00' || $ptype eq '8300' || $ptype eq '8309' || $ptype eq 'BF01');
my $hdsize = hd_size($target_dev); # size in KB (1024 bytes)
diff --git a/debian/control b/debian/control
index 8fa134b1..7371908c 100644
--- a/debian/control
+++ b/debian/control
@@ -45,6 +45,7 @@ Homepage: https://www.proxmox.com
Package: proxmox-installer
Architecture: any
Depends: chrony,
+ cryptsetup-bin,
e2fsprogs,
geoip-bin,
iproute2,
diff --git a/test/Makefile b/test/Makefile
index c095fec8..2749cc2c 100644
--- a/test/Makefile
+++ b/test/Makefile
@@ -5,7 +5,8 @@ export PERLLIB=..
.PHONY: check
check: test-zfs-arc-max test-run-command test-parse-fqdn test-ui2-stdio \
test-zfs-get-pool-list test-parse-kernel-cmdline \
- test-validate-link-pin-map test-generate-ifupdown2-config test-live-vlan-links
+ test-validate-link-pin-map test-generate-ifupdown2-config test-live-vlan-links \
+ test-fde-preflight
.PHONY: test-zfs-arc-max
test-zfs-arc-max:
@@ -42,3 +43,7 @@ test-generate-ifupdown2-config:
.PHONY: test-live-vlan-links
test-live-vlan-links:
./live-vlan-links.pl
+
+.PHONY: test-fde-preflight
+test-fde-preflight:
+ ./fde-preflight.pl
diff --git a/test/fde-preflight.pl b/test/fde-preflight.pl
new file mode 100755
index 00000000..4a838184
--- /dev/null
+++ b/test/fde-preflight.pl
@@ -0,0 +1,143 @@
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+
+use File::Temp;
+use Test::More;
+use Test::MockModule qw(strict);
+
+use Proxmox::Install;
+use Proxmox::Log;
+use Proxmox::UI;
+
+my $log_file = File::Temp->new();
+Proxmox::Log::init($log_file->filename);
+Proxmox::UI::init_stdio();
+
+my ($enc, $filesys, $test_mode);
+my $zfs_opts = {};
+my $open_luks = [];
+
+my $config = Test::MockModule->new('Proxmox::Install::Config');
+$config->redefine(
+ get_encryption => sub { return $enc },
+ get_filesys => sub { return $filesys },
+ get_zfs_opt => sub { return defined($_[0]) ? $zfs_opts->{ $_[0] } : $zfs_opts },
+);
+my $install = Test::MockModule->new('Proxmox::Install');
+$install->redefine(
+ is_test_mode => sub { return $test_mode },
+ open_luks_container_names => sub { return @$open_luks },
+);
+
+my $run_env = { boot_type => 'efi' };
+
+sub preflight {
+ my ($pkgdir) = @_;
+ eval { Proxmox::Install::fde_preflight_check($run_env, $pkgdir) };
+ return $@;
+}
+
+$test_mode = 1;
+
+is(preflight(), '', 'no encryption configured');
+
+my $passphrases = {
+ ascii => 'password',
+ latin1 => "p\x{e4}ssword",
+ 'non-latin1' => "\x{2603}" x 8,
+};
+for my $kind (sort keys %$passphrases) {
+ my $passphrase = $passphrases->{$kind};
+
+ $filesys = 'zfs (RAID0)';
+ $enc = { passphrase => $passphrase };
+ is(preflight(), '', "ZFS accepts the $kind passphrase");
+ is($enc->{passphrase}, $passphrase, "ZFS check keeps the $kind passphrase intact");
+
+ $filesys = 'ext4';
+ $enc = { passphrase => $passphrase };
+ is(preflight(), '', "ext4 accepts the $kind passphrase");
+ is($enc->{passphrase}, $passphrase, "ext4 check keeps the $kind passphrase intact");
+}
+
+for my $fs ('zfs (RAID0)', 'ext4') {
+ $filesys = $fs;
+ # 8 bytes encoded, although only 7 characters
+ $enc = { passphrase => "p\x{e4}sswor" };
+ like(preflight(), qr/at least 8 characters/, "$fs rejects a passphrase under 8 characters");
+ is($enc->{passphrase}, "p\x{e4}sswor", 'rejected passphrase is kept intact');
+}
+
+$filesys = 'zfs (RAID0)';
+$enc = { passphrase => 'x' x 513 };
+like(preflight(), qr/longer than 512 bytes/, 'ZFS rejects a passphrase over 512 bytes');
+
+$filesys = 'ext4';
+$enc = { passphrase => 'x' x 512 };
+is(preflight(), '', 'ext4 accepts a passphrase of 512 bytes');
+$enc = { passphrase => "\x{e4}" x 257 };
+like(preflight(), qr/longer than 512 bytes/, 'ext4 rejects a passphrase over 512 bytes');
+
+$filesys = 'btrfs (RAID1)';
+for my $ctrl ("\n", "\t", "\x00", "\x7f", "\x{85}") {
+ $enc = { passphrase => "pass${ctrl}word" };
+ like(
+ preflight(),
+ qr/control characters/,
+ sprintf('rejects control character 0x%02x', ord($ctrl)),
+ );
+}
+
+$enc = { passphrase => '' };
+like(preflight(), qr/at least 8 characters/, 'rejects an empty passphrase');
+
+$filesys = 'zfs (RAID1)';
+$enc = { passphrase => 'password' };
+$zfs_opts->{copies} = 2;
+is(preflight(), '', 'ZFS accepts 2 copies');
+$zfs_opts->{copies} = 3;
+like(preflight(), qr/at most 2 copies/, 'ZFS rejects 3 copies');
+$filesys = 'ext4';
+is(preflight(), '', 'ext4 ignores the ZFS copies');
+$zfs_opts = {};
+
+$filesys = 'xfs';
+$enc = { passphrase => 'password' };
+$run_env->{boot_type} = 'bios';
+like(preflight(), qr/UEFI/, 'requires UEFI boot');
+$run_env->{boot_type} = 'efi';
+
+SKIP: {
+ skip 'cryptsetup not available', 4 if system('command -v cryptsetup >/dev/null 2>&1') != 0;
+
+ $test_mode = 0;
+ my $pool = File::Temp->newdir();
+ like(
+ preflight("$pool"),
+ qr/lacks packages .*: cryptsetup-initramfs keyutils$/m,
+ 'reports missing pool packages',
+ );
+
+ for my $name ('cryptsetup-initramfs_2%3a2.7.5-2_all.deb', 'keyutils_1.6.3-6_amd64.deb') {
+ open(my $deb, '>', "$pool/$name") or die "open: $!\n";
+ close($deb);
+ }
+ is(preflight("$pool"), '', 'accepts a pool with the needed packages');
+
+ $open_luks = ['luks-rfs1'];
+ like(
+ preflight("$pool"),
+ qr/^encrypted device 'luks-rfs1' is open, .* 'cryptsetup close luks-rfs1'$/m,
+ 'refuses a container name that is in use',
+ );
+
+ $filesys = 'zfs (RAID0)';
+ my $empty = File::Temp->newdir();
+ is(preflight("$empty"), '', 'ZFS needs no extra packages and ignores LUKS containers');
+ $open_luks = [];
+ $test_mode = 1;
+}
+
+done_testing();
--
2.47.3
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [PATCH installer 2/5] auto: support full-disk encryption in answer files
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 ` Thomas Lamprecht
2026-11-17 23:42 ` [PATCH installer 3/5] chroot enter: unlock the LUKS containers of an encrypted installation Thomas Lamprecht
` (4 subsequent siblings)
7 siblings, 0 replies; 9+ messages in thread
From: Thomas Lamprecht @ 2026-11-17 23:42 UTC (permalink / raw)
To: pve-devel
Pass the `[disk-setup.encryption]` section of answer files on to the
low-level installer, which picks LUKS2 or native ZFS encryption based
on the filesystem. The encryption options are checked along with the
rest of the answer file, before any disk is touched.
The post-installation webhook reports the encryption mode, as schema
version 1.4. proxmox-chroot loads the key of a natively encrypted pool
from the saved installation config, so that the post-installation hook
sees the installed system and not a pool imported with all its
datasets locked and unmounted. In a rescue shell, where no such config
exists, it asks for the passphrase on the terminal, and it exports the
pool again if unlocking fails, so that it can be retried.
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
Cargo.toml | 2 +-
debian/control | 2 +-
proxmox-auto-installer/src/utils.rs | 13 ++-
proxmox-auto-installer/tests/parse-answer.rs | 5 +
.../parse_answer/encryption_luks.json | 26 +++++
.../parse_answer/encryption_luks.toml | 17 ++++
.../parse_answer/encryption_zfs.json | 36 +++++++
.../parse_answer/encryption_zfs.toml | 24 +++++
.../encryption_empty_passphrase.json | 3 +
.../encryption_empty_passphrase.toml | 17 ++++
.../encryption_passphrase_control_char.json | 3 +
.../encryption_passphrase_control_char.toml | 17 ++++
.../encryption_passphrase_too_short.json | 3 +
.../encryption_passphrase_too_short.toml | 17 ++++
proxmox-chroot/src/main.rs | 95 +++++++++++++++++++
proxmox-installer-common/src/setup.rs | 17 ++++
proxmox-post-hook/src/main.rs | 8 +-
proxmox-tui-installer/src/setup.rs | 1 +
18 files changed, 300 insertions(+), 6 deletions(-)
create mode 100644 proxmox-auto-installer/tests/resources/parse_answer/encryption_luks.json
create mode 100644 proxmox-auto-installer/tests/resources/parse_answer/encryption_luks.toml
create mode 100644 proxmox-auto-installer/tests/resources/parse_answer/encryption_zfs.json
create mode 100644 proxmox-auto-installer/tests/resources/parse_answer/encryption_zfs.toml
create mode 100644 proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_empty_passphrase.json
create mode 100644 proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_empty_passphrase.toml
create mode 100644 proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_passphrase_control_char.json
create mode 100644 proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_passphrase_control_char.toml
create mode 100644 proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_passphrase_too_short.json
create mode 100644 proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_passphrase_too_short.toml
diff --git a/Cargo.toml b/Cargo.toml
index 90ee0415..c3abf84b 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -28,7 +28,7 @@ toml = "0.8"
proxmox-auto-installer.path = "./proxmox-auto-installer"
proxmox-installer-common.path = "./proxmox-installer-common"
proxmox-network-types = "1.2"
-proxmox-installer-types = { version = "0.3.1", features = ["legacy"] }
+proxmox-installer-types = { version = "0.4", features = ["legacy"] }
# Local path overrides
# NOTE: You must run `cargo update` after changing this for it to take effect!
diff --git a/debian/control b/debian/control
index 7371908c..8de90ba4 100644
--- a/debian/control
+++ b/debian/control
@@ -19,7 +19,7 @@ Build-Depends: cargo:native,
librust-native-tls-dev,
librust-pico-args-0.5-dev,
librust-pretty-assertions-1.4-dev,
- librust-proxmox-installer-types-0.3+legacy-dev (>= 0.3.1-~~),
+ librust-proxmox-installer-types-0.4+legacy-dev,
librust-proxmox-network-types-1-dev (>= 1.2-~~),
librust-proxmox-sys+crypt-dev,
librust-regex-1+default-dev (>= 1.7~~),
diff --git a/proxmox-auto-installer/src/utils.rs b/proxmox-auto-installer/src/utils.rs
index 9813f56e..bfa54e4e 100644
--- a/proxmox-auto-installer/src/utils.rs
+++ b/proxmox-auto-installer/src/utils.rs
@@ -23,8 +23,8 @@ use proxmox_installer_common::{
is_bond_mode_unsuitable_for_bridge,
},
setup::{
- InstallBtrfsOption, InstallConfig, InstallFirstBootSetup, InstallRootPassword,
- InstallZfsOption, LocaleInfo, NetworkInfo, RuntimeInfo, SetupInfo,
+ InstallBtrfsOption, InstallConfig, InstallEncryption, InstallFirstBootSetup,
+ InstallRootPassword, InstallZfsOption, LocaleInfo, NetworkInfo, RuntimeInfo, SetupInfo,
},
};
use proxmox_network_types::MacAddress;
@@ -615,6 +615,8 @@ pub fn verify_disks_settings(answer: &AutoInstallerConfig) -> Result<()> {
_ => {}
}
+ answer.disks.verify_encryption()?;
+
Ok(())
}
@@ -745,6 +747,7 @@ pub fn parse_answer(
maxvz: None,
zfs_opts: None,
btrfs_opts: None,
+ encryption: None,
target_hd: None,
disk_selection: BTreeMap::new(),
existing_storage_auto_rename: 1,
@@ -820,6 +823,12 @@ pub fn parse_answer(
}
}
+ if let Some(encryption) = &answer.disks.encryption {
+ config.encryption = Some(InstallEncryption {
+ passphrase: encryption.passphrase.clone(),
+ });
+ }
+
if let Some(first_boot) = &answer.first_boot {
config.first_boot.enabled = true;
config.first_boot.ordering_target =
diff --git a/proxmox-auto-installer/tests/parse-answer.rs b/proxmox-auto-installer/tests/parse-answer.rs
index 1923bf84..c4652225 100644
--- a/proxmox-auto-installer/tests/parse-answer.rs
+++ b/proxmox-auto-installer/tests/parse-answer.rs
@@ -121,6 +121,8 @@ mod tests {
disk_match_all,
disk_match_all_missing_property,
disk_match_any,
+ encryption_luks,
+ encryption_zfs,
first_boot,
fqdn_from_dhcp,
fqdn_from_dhcp_empty_dhcp_domain_setting,
@@ -156,6 +158,9 @@ mod tests {
both_password_and_hashed_set,
btrfs_raid_single_disk,
duplicate_disk,
+ encryption_empty_passphrase,
+ encryption_passphrase_control_char,
+ encryption_passphrase_too_short,
fqdn_from_dhcp_no_default_domain,
fqdn_hostname_only,
ipv4_and_subnet_mask_33,
diff --git a/proxmox-auto-installer/tests/resources/parse_answer/encryption_luks.json b/proxmox-auto-installer/tests/resources/parse_answer/encryption_luks.json
new file mode 100644
index 00000000..f161ee7f
--- /dev/null
+++ b/proxmox-auto-installer/tests/resources/parse_answer/encryption_luks.json
@@ -0,0 +1,26 @@
+{
+ "autoreboot": 1,
+ "cidr": "192.168.1.114/24",
+ "country": "at",
+ "dns": "192.168.1.254",
+ "domain": "testinstall",
+ "filesys": "ext4",
+ "gateway": "192.168.1.1",
+ "hdsize": 223.57088470458984,
+ "existing_storage_auto_rename": 1,
+ "hostname": "pveauto",
+ "keymap": "de",
+ "mailto": "mail@no.invalid",
+ "mngmt_nic": "eno1",
+ "root_password": {
+ "plain": "12345678"
+ },
+ "target_hd": "/dev/sda",
+ "timezone": "Europe/Vienna",
+ "first_boot": {
+ "enabled": 0
+ },
+ "encryption": {
+ "passphrase": "pässphrase"
+ }
+}
diff --git a/proxmox-auto-installer/tests/resources/parse_answer/encryption_luks.toml b/proxmox-auto-installer/tests/resources/parse_answer/encryption_luks.toml
new file mode 100644
index 00000000..3cfa43e1
--- /dev/null
+++ b/proxmox-auto-installer/tests/resources/parse_answer/encryption_luks.toml
@@ -0,0 +1,17 @@
+[global]
+keyboard = "de"
+country = "at"
+fqdn = "pveauto.testinstall"
+mailto = "mail@no.invalid"
+timezone = "Europe/Vienna"
+root-password = "12345678"
+
+[network]
+source = "from-dhcp"
+
+[disk-setup]
+filesystem = "ext4"
+disk-list = ["sda"]
+
+[disk-setup.encryption]
+passphrase = "p\u00e4ssphrase"
diff --git a/proxmox-auto-installer/tests/resources/parse_answer/encryption_zfs.json b/proxmox-auto-installer/tests/resources/parse_answer/encryption_zfs.json
new file mode 100644
index 00000000..d284edc8
--- /dev/null
+++ b/proxmox-auto-installer/tests/resources/parse_answer/encryption_zfs.json
@@ -0,0 +1,36 @@
+{
+ "autoreboot": 1,
+ "cidr": "192.168.1.114/24",
+ "country": "at",
+ "dns": "192.168.1.254",
+ "domain": "testinstall",
+ "disk_selection": {
+ "6": "6",
+ "7": "7"
+ },
+ "existing_storage_auto_rename": 1,
+ "filesys": "zfs (RAID1)",
+ "gateway": "192.168.1.1",
+ "hdsize": 80.0,
+ "hostname": "pveauto",
+ "keymap": "de",
+ "mailto": "mail@no.invalid",
+ "mngmt_nic": "eno1",
+ "root_password": {
+ "plain": "12345678"
+ },
+ "timezone": "Europe/Vienna",
+ "zfs_opts": {
+ "arc_max": 2048,
+ "ashift": 12,
+ "checksum": "on",
+ "compress": "lz4",
+ "copies": 2
+ },
+ "first_boot": {
+ "enabled": 0
+ },
+ "encryption": {
+ "passphrase": "zfs passphrase"
+ }
+}
diff --git a/proxmox-auto-installer/tests/resources/parse_answer/encryption_zfs.toml b/proxmox-auto-installer/tests/resources/parse_answer/encryption_zfs.toml
new file mode 100644
index 00000000..9b6baf79
--- /dev/null
+++ b/proxmox-auto-installer/tests/resources/parse_answer/encryption_zfs.toml
@@ -0,0 +1,24 @@
+[global]
+keyboard = "de"
+country = "at"
+fqdn = "pveauto.testinstall"
+mailto = "mail@no.invalid"
+timezone = "Europe/Vienna"
+root-password = "12345678"
+
+[network]
+source = "from-dhcp"
+
+[disk-setup]
+filesystem = "zfs"
+zfs.raid = "raid1"
+zfs.ashift = 12
+zfs.checksum = "on"
+zfs.compress = "lz4"
+zfs.copies = 2
+zfs.hdsize = 80
+zfs.arc-max = 2048
+disk-list = ["sda", "sdb"]
+
+[disk-setup.encryption]
+passphrase = "zfs passphrase"
diff --git a/proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_empty_passphrase.json b/proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_empty_passphrase.json
new file mode 100644
index 00000000..6ad207d7
--- /dev/null
+++ b/proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_empty_passphrase.json
@@ -0,0 +1,3 @@
+{
+ "error": "'disk-setup.encryption.passphrase' must be at least 8 characters long"
+}
diff --git a/proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_empty_passphrase.toml b/proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_empty_passphrase.toml
new file mode 100644
index 00000000..3e02c3f6
--- /dev/null
+++ b/proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_empty_passphrase.toml
@@ -0,0 +1,17 @@
+[global]
+keyboard = "de"
+country = "at"
+fqdn = "pveauto.testinstall"
+mailto = "mail@no.invalid"
+timezone = "Europe/Vienna"
+root-password = "12345678"
+
+[network]
+source = "from-dhcp"
+
+[disk-setup]
+filesystem = "ext4"
+disk-list = ["sda"]
+
+[disk-setup.encryption]
+passphrase = ""
diff --git a/proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_passphrase_control_char.json b/proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_passphrase_control_char.json
new file mode 100644
index 00000000..36414984
--- /dev/null
+++ b/proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_passphrase_control_char.json
@@ -0,0 +1,3 @@
+{
+ "error": "'disk-setup.encryption.passphrase' must not contain control characters"
+}
diff --git a/proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_passphrase_control_char.toml b/proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_passphrase_control_char.toml
new file mode 100644
index 00000000..39c02370
--- /dev/null
+++ b/proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_passphrase_control_char.toml
@@ -0,0 +1,17 @@
+[global]
+keyboard = "de"
+country = "at"
+fqdn = "pveauto.testinstall"
+mailto = "mail@no.invalid"
+timezone = "Europe/Vienna"
+root-password = "12345678"
+
+[network]
+source = "from-dhcp"
+
+[disk-setup]
+filesystem = "ext4"
+disk-list = ["sda"]
+
+[disk-setup.encryption]
+passphrase = "pass\nphrase"
diff --git a/proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_passphrase_too_short.json b/proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_passphrase_too_short.json
new file mode 100644
index 00000000..6ad207d7
--- /dev/null
+++ b/proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_passphrase_too_short.json
@@ -0,0 +1,3 @@
+{
+ "error": "'disk-setup.encryption.passphrase' must be at least 8 characters long"
+}
diff --git a/proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_passphrase_too_short.toml b/proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_passphrase_too_short.toml
new file mode 100644
index 00000000..ef00995b
--- /dev/null
+++ b/proxmox-auto-installer/tests/resources/parse_answer_fail/encryption_passphrase_too_short.toml
@@ -0,0 +1,17 @@
+[global]
+keyboard = "de"
+country = "at"
+fqdn = "pveauto.testinstall"
+mailto = "mail@no.invalid"
+timezone = "Europe/Vienna"
+root-password = "12345678"
+
+[network]
+source = "from-dhcp"
+
+[disk-setup]
+filesystem = "ext4"
+disk-list = ["sda"]
+
+[disk-setup.encryption]
+passphrase = "p\u00e4sswor"
diff --git a/proxmox-chroot/src/main.rs b/proxmox-chroot/src/main.rs
index bcba1ce5..d6cd48b7 100644
--- a/proxmox-chroot/src/main.rs
+++ b/proxmox-chroot/src/main.rs
@@ -240,10 +240,105 @@ fn mount_zpool(pool_id: Option<u64>) -> Result<()> {
Ok(s) if !s.success() => bail!("Could not import ZFS pool. Abort!"),
_ => (),
}
+
+ // A natively encrypted pool imports with its datasets locked and unmounted, so import success
+ // alone does not mean that the target is mounted.
+ if let Err(err) = unlock_zpool() {
+ // exported again, so that a retry can import it
+ umount_zpool();
+ return Err(err);
+ }
+
println!("successfully imported ZFS pool to {TARGET_DIR}");
Ok(())
}
+fn unlock_zpool() -> Result<()> {
+ if !zpool_keystatus_unavailable()? {
+ return Ok(());
+ }
+
+ load_zpool_key()?;
+ // Only this pool, other pools may be imported in the installer environment.
+ let status = Command::new("zfs")
+ .args(["mount", "-R", ZPOOL_NAME])
+ .status()
+ .map_err(|err| anyhow::anyhow!("failed to run 'zfs mount -R {ZPOOL_NAME}': {err}"))?;
+ if !status.success() {
+ bail!("could not mount the datasets of '{ZPOOL_NAME}' after loading its key");
+ }
+ let mounted = Command::new("mountpoint")
+ .args(["-q", TARGET_DIR])
+ .status()
+ .map_err(|err| anyhow::anyhow!("failed to run 'mountpoint': {err}"))?;
+ if !mounted.success() {
+ bail!("{TARGET_DIR} is not mounted after unlocking '{ZPOOL_NAME}'");
+ }
+ Ok(())
+}
+
+/// Whether the pool's encryption root still needs its key loaded. An unencrypted pool reports `-`.
+fn zpool_keystatus_unavailable() -> Result<bool> {
+ let out = Command::new("zfs")
+ .args(["get", "-H", "-o", "value", "keystatus", ZPOOL_NAME])
+ .output()
+ .map_err(|err| anyhow::anyhow!("failed to query ZFS keystatus: {err}"))?;
+ if !out.status.success() {
+ bail!(
+ "failed to query the keystatus of '{ZPOOL_NAME}': {}",
+ String::from_utf8_lossy(&out.stderr).trim()
+ );
+ }
+ match String::from_utf8_lossy(&out.stdout).trim() {
+ "unavailable" => Ok(true),
+ "available" | "-" => Ok(false),
+ other => bail!("unexpected keystatus '{other}' for '{ZPOOL_NAME}'"),
+ }
+}
+
+/// Right after an installation, the passphrase comes from the 0600 low-level config on the
+/// installer's tmpfs, as the caller may be the unattended post-installation hook. Otherwise, for
+/// example in a rescue shell, `zfs` asks for it on the terminal.
+fn load_zpool_key() -> Result<()> {
+ use std::io::{IsTerminal, Write};
+
+ let passphrase = get_low_level_config()
+ .ok()
+ .and_then(|config| config.encryption)
+ .map(|encryption| encryption.passphrase);
+ let Some(passphrase) = passphrase else {
+ if !io::stdin().is_terminal() {
+ bail!(
+ "cannot unlock ZFS pool '{ZPOOL_NAME}' - its passphrase can only be entered on a terminal"
+ );
+ }
+ let status = Command::new("zfs")
+ .args(["load-key", ZPOOL_NAME])
+ .status()
+ .map_err(|err| anyhow::anyhow!("failed to run 'zfs load-key': {err}"))?;
+ if !status.success() {
+ bail!("could not load the key of ZFS pool '{ZPOOL_NAME}'");
+ }
+ return Ok(());
+ };
+
+ let mut child = Command::new("zfs")
+ .args(["load-key", "-L", "prompt", ZPOOL_NAME])
+ .stdin(process::Stdio::piped())
+ .spawn()
+ .map_err(|err| anyhow::anyhow!("failed to run 'zfs load-key': {err}"))?;
+ child
+ .stdin
+ .as_mut()
+ .ok_or_else(|| anyhow::anyhow!("could not write to 'zfs load-key' stdin"))?
+ .write_all(format!("{passphrase}\n").as_bytes())?;
+
+ if !child.wait()?.success() {
+ bail!("'zfs load-key' failed for pool '{ZPOOL_NAME}'");
+ }
+ Ok(())
+}
+
fn umount_zpool() {
match Command::new("zpool").arg("export").arg(ZPOOL_NAME).status() {
Ok(s) if !s.success() => println!("failure on exporting {ZPOOL_NAME}"),
diff --git a/proxmox-installer-common/src/setup.rs b/proxmox-installer-common/src/setup.rs
index 3882f892..9e041e4c 100644
--- a/proxmox-installer-common/src/setup.rs
+++ b/proxmox-installer-common/src/setup.rs
@@ -546,6 +546,20 @@ pub fn spawn_low_level_installer(test_mode: bool) -> io::Result<process::Child>
.spawn()
}
+/// See Proxmox::Install::Config
+#[derive(Clone, Deserialize, Serialize)]
+pub struct InstallEncryption {
+ pub passphrase: String,
+}
+
+impl fmt::Debug for InstallEncryption {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ f.debug_struct("InstallEncryption")
+ .field("passphrase", &"<redacted>")
+ .finish()
+ }
+}
+
/// See Proxmox::Install::Config
#[derive(Debug, Deserialize, Serialize)]
pub struct InstallConfig {
@@ -568,6 +582,9 @@ pub struct InstallConfig {
#[serde(skip_serializing_if = "Option::is_none")]
pub btrfs_opts: Option<InstallBtrfsOption>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub encryption: Option<InstallEncryption>,
+
#[serde(skip_serializing_if = "Option::is_none")]
pub target_hd: Option<String>,
diff --git a/proxmox-post-hook/src/main.rs b/proxmox-post-hook/src/main.rs
index 4b24b16a..55ca515f 100644
--- a/proxmox-post-hook/src/main.rs
+++ b/proxmox-post-hook/src/main.rs
@@ -20,7 +20,7 @@ use proxmox_installer_common::http::{self, header::HeaderMap};
use proxmox_installer_types::answer::{AutoInstallerConfig, PostNotificationHookInfo};
/// Current version of the schema sent by this implementation.
-const POST_HOOK_SCHEMA_VERSION: &str = "1.3";
+const POST_HOOK_SCHEMA_VERSION: &str = "1.4";
mod detail {
use anyhow::{Context, Result, anyhow, bail};
@@ -39,7 +39,7 @@ mod detail {
setup::{InstallConfig, RuntimeInfo, SetupInfo, load_installer_setup_files},
};
use proxmox_installer_types::{
- ProxmoxProduct, SystemDMI, UdevInfo,
+ EncryptionMode, ProxmoxProduct, SystemDMI, UdevInfo,
answer::{AutoInstallerConfig, FqdnConfig, FqdnFromDhcpConfig, FqdnSourceMode},
post_hook::{
BootInfo, CpuInfo, DiskInfo, KernelVersionInformation, NetworkInterfaceInfo,
@@ -154,6 +154,10 @@ mod detail {
}
}),
filesystem: answer.disks.filesystem_details()?.to_type(),
+ encryption: config
+ .encryption
+ .as_ref()
+ .map(|_| EncryptionMode::for_filesystem(config.filesys)),
fqdn,
machine_id: read_file("/etc/machine-id").unwrap_or_else(|e| {
eprintln!("could not gather machine-id: {e:#}");
diff --git a/proxmox-tui-installer/src/setup.rs b/proxmox-tui-installer/src/setup.rs
index b8a990fd..fc3c43df 100644
--- a/proxmox-tui-installer/src/setup.rs
+++ b/proxmox-tui-installer/src/setup.rs
@@ -21,6 +21,7 @@ impl From<InstallerOptions> for InstallConfig {
maxvz: None,
zfs_opts: None,
btrfs_opts: None,
+ encryption: None,
target_hd: None,
disk_selection: BTreeMap::new(),
existing_storage_auto_rename: 0,
--
2.47.3
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [PATCH installer 3/5] chroot enter: unlock the LUKS containers of an encrypted installation
2026-11-17 23:42 [PATCH proxmox/installer/docs 0/8] installer: add full-disk encryption of the system disks Thomas Lamprecht
` (2 preceding siblings ...)
2026-11-17 23:42 ` [PATCH installer 2/5] auto: support full-disk encryption in answer files Thomas Lamprecht
@ 2026-11-17 23:42 ` Thomas Lamprecht
2026-11-17 23:42 ` [PATCH installer 4/5] ui: offer full-disk encryption in the graphical and terminal installer Thomas Lamprecht
` (3 subsequent siblings)
7 siblings, 0 replies; 9+ messages in thread
From: Thomas Lamprecht @ 2026-11-17 23:42 UTC (permalink / raw)
To: pve-devel
In a rescue shell, the LUKS containers of an encrypted ext4, xfs or
Btrfs installation are closed, so preparing the chroot failed with a
volume group or Btrfs file system that could not be found, without a
hint at the encryption. For native ZFS encryption, it already asks for
the passphrase.
If the volume group or the Btrfs file system cannot be found, open the
containers of an installation, found by their labels, which match the
device mapper names. cryptsetup asks for the passphrase of each on the
terminal. This leaves the containers alone right after an installation,
where they are still open, and installations without encryption, also
if an encrypted disk of another installation is around. If a label is
found more than once, as with an older installation on another disk,
the right container has to be opened by hand. If a container cannot be
opened or the installation cannot be mounted, the containers opened
before are closed again.
Cleanup closes the containers that prepare opened, after deactivating
the volume group on top, so that the installer can be started
afterwards, which refuses to create a container under a name that is
in use.
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
proxmox-chroot/src/main.rs | 258 +++++++++++++++++++++++++++++++++----
1 file changed, 233 insertions(+), 25 deletions(-)
diff --git a/proxmox-chroot/src/main.rs b/proxmox-chroot/src/main.rs
index d6cd48b7..5178710d 100644
--- a/proxmox-chroot/src/main.rs
+++ b/proxmox-chroot/src/main.rs
@@ -8,7 +8,9 @@
use anyhow::{Result, bail};
use serde::Deserialize;
use std::{
- env, fs, io,
+ collections::BTreeMap,
+ env, fs,
+ io::{self, IsTerminal},
path::{self, Path, PathBuf},
process::{self, Command},
};
@@ -24,6 +26,8 @@ static BINDMOUNTS: [&str; 4] = ["dev", "proc", "run", "sys"];
const TARGET_DIR: &str = "/target";
const ZPOOL_NAME: &str = "rpool";
const CD_INFO_PATH: &str = "/cdrom/.cd-info";
+/// The LUKS containers that `prepare` opened, for `cleanup` to close them again.
+const OPENED_LUKS_PATH: &str = "/run/proxmox-chroot-opened-luks";
/// Arguments for the `prepare` command.
struct CommandPrepareArgs {
@@ -51,6 +55,7 @@ impl cli::Subcommand for CommandPrepareArgs {
fn print_usage() {
eprintln!(
r#"Mount the root file system and bind mounts in preparation to chroot into the installation.
+An encrypted installation is unlocked, asking for its passphrase.
USAGE:
{} prepare <OPTIONS>
@@ -86,7 +91,7 @@ impl cli::Subcommand for CommandCleanupArgs {
fn print_usage() {
eprintln!(
- r#"Unmount everything. Use once done with the chroot.
+ r#"Unmount everything and lock an encrypted installation again. Use once done with the chroot.
USAGE:
{} cleanup <OPTIONS>
@@ -137,11 +142,23 @@ fn prepare(args: &CommandPrepareArgs) -> Result<()> {
fs::create_dir_all(TARGET_DIR)?;
+ // Containers are only opened if the installation cannot be found otherwise, which leaves them
+ // alone right after the installation, where they are still open, and for an installation
+ // without encryption, also if an encrypted disk of another installation is around.
match fs {
Filesystem::Zfs => mount_zpool(args.rpool_id)?,
- Filesystem::Xfs => mount_fs()?,
- Filesystem::Ext4 => mount_fs()?,
- Filesystem::Btrfs => mount_btrfs(args.btrfs_uuid.clone())?,
+ Filesystem::Xfs | Filesystem::Ext4 => {
+ let vg_found = volume_group_exists(&get_product()?.to_string())?;
+ with_luks_containers(fs, !vg_found, mount_fs)?
+ }
+ Filesystem::Btrfs => {
+ let uuids = btrfs_uuids()?;
+ let found = match &args.btrfs_uuid {
+ Some(uuid) => uuids.contains(uuid),
+ None => !uuids.is_empty(),
+ };
+ with_luks_containers(fs, !found, || mount_btrfs(args.btrfs_uuid.clone()))?
+ }
}
if let Err(e) = bindmount() {
@@ -161,7 +178,16 @@ fn cleanup(args: &CommandCleanupArgs) -> Result<()> {
match fs {
Filesystem::Zfs => umount_zpool(),
- Filesystem::Btrfs | Filesystem::Xfs | Filesystem::Ext4 => umount(Path::new(TARGET_DIR))?,
+ Filesystem::Btrfs | Filesystem::Xfs | Filesystem::Ext4 => {
+ umount(Path::new(TARGET_DIR))?;
+ let opened = match fs::read_to_string(OPENED_LUKS_PATH) {
+ Ok(names) => names.lines().map(str::to_string).collect(),
+ Err(err) if err.kind() == io::ErrorKind::NotFound => Vec::new(),
+ Err(err) => bail!("could not read '{OPENED_LUKS_PATH}': {err}"),
+ };
+ close_luks_containers(fs, &opened)?;
+ let _ = fs::remove_file(OPENED_LUKS_PATH);
+ }
}
println!("Chroot cleanup done. You can now reboot or leave the shell.");
@@ -300,7 +326,7 @@ fn zpool_keystatus_unavailable() -> Result<bool> {
/// installer's tmpfs, as the caller may be the unattended post-installation hook. Otherwise, for
/// example in a rescue shell, `zfs` asks for it on the terminal.
fn load_zpool_key() -> Result<()> {
- use std::io::{IsTerminal, Write};
+ use std::io::Write;
let passphrase = get_low_level_config()
.ok()
@@ -346,6 +372,170 @@ fn umount_zpool() {
}
}
+/// Whether `name` is the device mapper name, and also the label, of a LUKS container that an
+/// encrypted installation with the given filesystem has.
+fn is_luks_container_name(fs: Filesystem, name: &str) -> bool {
+ match fs {
+ Filesystem::Ext4 | Filesystem::Xfs => name == "luks-rpv",
+ Filesystem::Btrfs => name
+ .strip_prefix("luks-rfs")
+ .is_some_and(|n| !n.is_empty() && n.bytes().all(|b| b.is_ascii_digit())),
+ Filesystem::Zfs => false,
+ }
+}
+
+/// Runs `mount`, after opening the LUKS containers of an encrypted installation if `open` is set.
+/// If that fails, it closes the containers it opened, otherwise it records them for `cleanup`.
+fn with_luks_containers(
+ fs: Filesystem,
+ open: bool,
+ mount: impl FnOnce() -> Result<()>,
+) -> Result<()> {
+ let opened = if open {
+ open_luks_containers(fs)?
+ } else {
+ Vec::new()
+ };
+
+ let result = mount().and_then(|()| {
+ if opened.is_empty() {
+ return Ok(());
+ }
+ fs::write(OPENED_LUKS_PATH, opened.join("\n") + "\n")
+ .map_err(|err| anyhow::anyhow!("could not write '{OPENED_LUKS_PATH}': {err}"))
+ });
+ if let Err(err) = result {
+ if let Err(close_err) = close_luks_containers(fs, &opened) {
+ eprintln!("{close_err:#}");
+ }
+ return Err(err);
+ }
+ Ok(())
+}
+
+/// Opens the closed LUKS containers of an encrypted installation, found by their labels, and
+/// returns their names. `cryptsetup` asks for the passphrase of each on the terminal. If one cannot
+/// be opened, the ones opened before are closed again.
+fn open_luks_containers(fs: Filesystem) -> Result<Vec<String>> {
+ #[derive(Deserialize)]
+ struct Entry {
+ path: String,
+ fstype: Option<String>,
+ label: Option<String>,
+ }
+
+ #[derive(Deserialize)]
+ struct LsblkOutput {
+ blockdevices: Vec<Entry>,
+ }
+
+ let output = Command::new("lsblk")
+ .args(["--json", "--list", "--output", "path,fstype,label"])
+ .output()?;
+ if !output.status.success() {
+ bail!(
+ "Error checking for encrypted devices: {}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+ }
+ let out: LsblkOutput = serde_json::from_slice(&output.stdout)?;
+
+ let mut containers: BTreeMap<String, Vec<String>> = BTreeMap::new();
+ for entry in out.blockdevices {
+ if let (Some("crypto_LUKS"), Some(label)) = (entry.fstype.as_deref(), entry.label)
+ && is_luks_container_name(fs, &label)
+ && !Path::new("/dev/mapper").join(&label).exists()
+ {
+ containers.entry(label).or_default().push(entry.path);
+ }
+ }
+
+ // checked for all first, so that nothing is opened in vain
+ for (name, devices) in &containers {
+ // for example from an older installation on another disk
+ if devices.len() > 1 {
+ bail!(
+ "Found several encrypted devices labelled '{name}': {}\nOpen the right one with 'cryptsetup open <device> {name}'",
+ devices.join(", ")
+ );
+ }
+ }
+ if !containers.is_empty() && !io::stdin().is_terminal() {
+ bail!(
+ "cannot unlock the encrypted devices - their passphrase can only be entered on a terminal"
+ );
+ }
+
+ let mut opened = Vec::new();
+ for (name, devices) in containers {
+ let device = &devices[0];
+ println!("unlocking '{device}' as '{name}'");
+ let status = Command::new("cryptsetup")
+ .args(["open", device, &name])
+ .status()
+ .map_err(|err| anyhow::anyhow!("failed to run 'cryptsetup open': {err}"));
+ if !status.as_ref().is_ok_and(|status| status.success()) {
+ if let Err(close_err) = close_luks_containers(fs, &opened) {
+ eprintln!("{close_err:#}");
+ }
+ status?;
+ bail!(
+ "could not unlock '{device}'\nIf it does not belong to the installation, open the ones that do with 'cryptsetup open <device> <name>' and run prepare again"
+ );
+ }
+ opened.push(name);
+ }
+
+ // so that the volume group or Btrfs members on top are known before they are used
+ if !opened.is_empty() {
+ let _ = Command::new("udevadm").arg("settle").status();
+ }
+ Ok(opened)
+}
+
+/// Closes the given LUKS containers, after deactivating the volume group on top, so that the
+/// installer can be started afterwards.
+fn close_luks_containers(fs: Filesystem, names: &[String]) -> Result<()> {
+ if names.is_empty() {
+ return Ok(());
+ }
+
+ if fs != Filesystem::Btrfs {
+ let product = get_product()?;
+ let output = Command::new("vgchange")
+ .arg("-an")
+ .arg(product.to_string())
+ .output()?;
+ if !output.status.success() {
+ bail!(
+ "deactivation of VG '{product}' failed: {}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+ }
+ }
+
+ for name in names {
+ let output = Command::new("cryptsetup").args(["close", name]).output()?;
+ if !output.status.success() {
+ bail!(
+ "closing encrypted device '{name}' failed: {}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+ }
+ }
+ Ok(())
+}
+
+fn volume_group_exists(name: &str) -> Result<bool> {
+ let status = Command::new("vgs")
+ .args(["--noheadings", "--options", "vg_name", name])
+ .stdout(process::Stdio::null())
+ .stderr(process::Stdio::null())
+ .status()
+ .map_err(|err| anyhow::anyhow!("failed to run 'vgs': {err}"))?;
+ Ok(status.success())
+}
+
fn mount_fs() -> Result<()> {
// the volume group is named after the product
let product = get_product()?;
@@ -450,6 +640,24 @@ fn mount_btrfs(btrfs_uuid: Option<String>) -> Result<()> {
/// If multiple are found, returns a (human-readable) error with all possible
/// filesystem UUIDs.
fn get_btrfs_uuid() -> Result<String> {
+ let uuids = btrfs_uuids()?;
+ match uuids.len() {
+ 0 => bail!("Could not find any BTRFS UUID"),
+ i if i > 1 => {
+ let uuid_list = uuids
+ .iter()
+ .fold(String::new(), |acc, arg| format!("{acc}\n{arg}"));
+ bail!(
+ "Found {i} UUIDs:{uuid_list}\nPlease specify the UUID to use with the --btrfs-uuid parameter"
+ )
+ }
+ _ => (),
+ }
+ Ok(uuids[0].clone())
+}
+
+/// The UUIDs of all Btrfs file systems present on the system.
+fn btrfs_uuids() -> Result<Vec<String>> {
let output = Command::new("lsblk")
.args(["--json", "--fs", "--list", "--output", "fstype,uuid"])
.output()?;
@@ -475,7 +683,7 @@ fn get_btrfs_uuid() -> Result<String> {
let out: LsblkOutput = serde_json::from_slice(&output.stdout)?;
let mut uuids = out
.blockdevices
- .iter()
+ .into_iter()
.filter_map(|entry| match entry {
Entry {
fstype: Some(fstype),
@@ -483,24 +691,11 @@ fn get_btrfs_uuid() -> Result<String> {
} if fstype == "btrfs" => Some(uuid),
_ => None,
})
- .collect::<Vec<&String>>();
+ .collect::<Vec<String>>();
// every member device of a multi-disk file system is listed with the same UUID
uuids.sort();
uuids.dedup();
-
- match uuids.len() {
- 0 => bail!("Could not find any BTRFS UUID"),
- i if i > 1 => {
- let uuid_list = uuids
- .iter()
- .fold(String::new(), |acc, &arg| format!("{acc}\n{arg}"));
- bail!(
- "Found {i} UUIDs:{uuid_list}\nPlease specify the UUID to use with the --btrfs-uuid parameter"
- )
- }
- _ => (),
- }
- Ok(uuids[0].into())
+ Ok(uuids)
}
fn do_bindmount(source: &Path, target: &Path) -> Result<()> {
@@ -574,8 +769,21 @@ fn bind_umount() -> Result<()> {
#[cfg(test)]
mod tests {
- use super::parse_cd_info_product;
- use proxmox_installer_types::ProxmoxProduct;
+ use super::{is_luks_container_name, parse_cd_info_product};
+ use proxmox_installer_types::{ProxmoxProduct, answer::Filesystem};
+
+ #[test]
+ fn luks_container_names() {
+ assert!(is_luks_container_name(Filesystem::Ext4, "luks-rpv"));
+ assert!(is_luks_container_name(Filesystem::Xfs, "luks-rpv"));
+ assert!(!is_luks_container_name(Filesystem::Ext4, "luks-rfs0"));
+ assert!(is_luks_container_name(Filesystem::Btrfs, "luks-rfs0"));
+ assert!(is_luks_container_name(Filesystem::Btrfs, "luks-rfs12"));
+ assert!(!is_luks_container_name(Filesystem::Btrfs, "luks-rfs"));
+ assert!(!is_luks_container_name(Filesystem::Btrfs, "luks-rfs1a"));
+ assert!(!is_luks_container_name(Filesystem::Btrfs, "luks-rpv"));
+ assert!(!is_luks_container_name(Filesystem::Zfs, "luks-rpv"));
+ }
#[test]
fn product_from_cd_info() {
--
2.47.3
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [PATCH installer 4/5] ui: offer full-disk encryption in the graphical and terminal installer
2026-11-17 23:42 [PATCH proxmox/installer/docs 0/8] installer: add full-disk encryption of the system disks Thomas Lamprecht
` (3 preceding siblings ...)
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 ` Thomas Lamprecht
2026-11-17 23:42 ` [PATCH installer 5/5] assistant: keep the disk passphrase out of prepared ISOs Thomas Lamprecht
` (2 subsequent siblings)
7 siblings, 0 replies; 9+ messages in thread
From: Thomas Lamprecht @ 2026-11-17 23:42 UTC (permalink / raw)
To: pve-devel
The disk options of both installers gain an encryption option, as long
as the installer was booted in UEFI mode. The passphrase itself is
asked on the password page, which comes after the keyboard layout was
chosen, so that it is typed with the same layout the boot prompt uses.
Both apply the installer's passphrase rules there, and the help of the
graphical installer notes that the passphrase is needed at every boot.
Their disk pages already refuse more than 2 ZFS copies with
encryption.
As the option sits in a dialog, their disk pages show when encryption
is enabled, and their summaries show the resulting encryption.
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
html/ack_template.htm | 2 +
html/pbs/passwd.htm | 1 +
html/pdm/passwd.htm | 1 +
html/pmg/passwd.htm | 1 +
html/pve/passwd.htm | 1 +
proxinstall | 99 ++++++++++++++++++++-
proxmox-installer-common/src/options.rs | 3 +
proxmox-tui-installer/src/main.rs | 68 ++++++++++++--
proxmox-tui-installer/src/options.rs | 19 +++-
proxmox-tui-installer/src/setup.rs | 8 +-
proxmox-tui-installer/src/views/bootdisk.rs | 49 ++++++++--
proxmox-tui-installer/src/views/mod.rs | 6 ++
12 files changed, 242 insertions(+), 16 deletions(-)
diff --git a/html/ack_template.htm b/html/ack_template.htm
index 48d7213a..3c11f2c8 100644
--- a/html/ack_template.htm
+++ b/html/ack_template.htm
@@ -44,6 +44,8 @@
<tr><td>Disk(s):</td> <td>__target_hd__</td></tr>
+ <tr><td>Disk Encryption:</td> <td>__encryption__</td></tr>
+
<tr><td>Country:</td> <td>__country__</td></tr>
<tr><td>Timezone:</td> <td>__timezone__</td></tr>
diff --git a/html/pbs/passwd.htm b/html/pbs/passwd.htm
index 52a50157..3b535676 100644
--- a/html/pbs/passwd.htm
+++ b/html/pbs/passwd.htm
@@ -37,6 +37,7 @@
<br><br>
</td>
</tr>
+ __DISK_PASSPHRASE_HELP__
</table>
</p></td>
</tr>
diff --git a/html/pdm/passwd.htm b/html/pdm/passwd.htm
index 52a50157..3b535676 100644
--- a/html/pdm/passwd.htm
+++ b/html/pdm/passwd.htm
@@ -37,6 +37,7 @@
<br><br>
</td>
</tr>
+ __DISK_PASSPHRASE_HELP__
</table>
</p></td>
</tr>
diff --git a/html/pmg/passwd.htm b/html/pmg/passwd.htm
index 52a50157..3b535676 100644
--- a/html/pmg/passwd.htm
+++ b/html/pmg/passwd.htm
@@ -37,6 +37,7 @@
<br><br>
</td>
</tr>
+ __DISK_PASSPHRASE_HELP__
</table>
</p></td>
</tr>
diff --git a/html/pve/passwd.htm b/html/pve/passwd.htm
index efd4e5f5..32460cfe 100644
--- a/html/pve/passwd.htm
+++ b/html/pve/passwd.htm
@@ -38,6 +38,7 @@
<br><br>
</td>
</tr>
+ __DISK_PASSPHRASE_HELP__
</table>
</p></td>
</tr>
diff --git a/proxinstall b/proxinstall
index ea80dd24..e66c4e78 100755
--- a/proxinstall
+++ b/proxinstall
@@ -1095,6 +1095,11 @@ sub create_ipconf_view {
$hostentry->grab_focus();
}
+my sub encryption_desc {
+ my $mode = Proxmox::Install::Config::get_encryption_mode() // return 'none';
+ return $mode eq 'zfs-native' ? 'native ZFS encryption' : 'LUKS2';
+}
+
sub create_ack_view {
cleanup_view();
@@ -1152,6 +1157,7 @@ sub create_ack_view {
my %config_values = (
__target_hd__ => join(' | ', $target_hds->@*),
__target_fs__ => Proxmox::Install::Config::get_filesys(),
+ __encryption__ => encryption_desc(),
__country__ => $iso_env->{locales}->{country}->{$country}->{name},
__timezone__ => Proxmox::Install::Config::get_timezone(),
__keymap__ => Proxmox::Install::Config::get_keymap(),
@@ -1346,9 +1352,47 @@ sub create_password_view {
$eme->set_margin_top(10);
$grid->attach($eme, 1, 2, 1, 1);
+ # asked here, so that it is typed with the keyboard layout the boot prompt uses
+ my $enc = Proxmox::Install::Config::get_encryption();
+ my ($epe1, $epe2);
+ if (defined($enc)) {
+ for my $field (['Disk passphrase', \$epe1, 3], ['Confirm', \$epe2, 4]) {
+ my ($text, $entry_ref, $grid_row) = @$field;
+ my $elabel = Gtk3::Label->new($text);
+ $elabel->set_size_request(150, -1);
+ $elabel->set_xalign(1.0);
+ $grid->attach($elabel, 0, $grid_row, 1, 1);
+ my $entry = Gtk3::Entry->new();
+ $entry->set_visibility(0);
+ $entry->set_text($enc->{passphrase}) if defined($enc->{passphrase});
+ $entry->set_size_request(200, -1);
+ $grid->attach($entry, 1, $grid_row, 1, 1);
+
+ if ($grid_row == 3) {
+ $elabel->set_margin_top(10);
+ $entry->set_margin_top(10);
+ }
+ $$entry_ref = $entry;
+ }
+ }
+
$gtk_state->{inbox}->show_all;
- Proxmox::UI::display_html('passwd.htm');
+ my $passphrase_help = '';
+ if (defined($enc)) {
+ $passphrase_help =
+ '<tr><td valign="top" width="30"><img src="plus.png"></td>'
+ . '<td valign="top"><b>Disk passphrase:</b> Needed at every boot to unlock the system.'
+ . ' Store it safely, as the data cannot be recovered without it.</td></tr>';
+ }
+ Proxmox::UI::display_html(
+ 'passwd.htm',
+ sub {
+ my ($html) = @_;
+ $html =~ s/__DISK_PASSPHRASE_HELP__/$passphrase_help/;
+ return $html;
+ },
+ );
set_next(
undef,
@@ -1384,6 +1428,22 @@ sub create_password_view {
return;
}
+ if (defined($enc)) {
+ my $pp = $epe1->get_text() // '';
+ eval {
+ Proxmox::Install::assert_disk_passphrase($pp);
+ die "the disk passphrases do not match\n"
+ if $pp ne ($epe2->get_text() // '');
+ };
+ if (my $err = $@) {
+ Proxmox::UI::message(ucfirst($err));
+ $epe1->grab_focus();
+ return;
+ }
+ $enc->{passphrase} = $pp;
+ Proxmox::Install::Config::set_encryption($enc);
+ }
+
Proxmox::Install::Config::set_root_password('plain', $t1);
Proxmox::Install::Config::set_mailto($t3);
@@ -1574,6 +1634,14 @@ sub create_country_view {
my $target_hd_combo;
my $target_hd_label;
+my $encryption_hint_label;
+
+# the encryption option is in the options dialog, so the disk page shows its state
+my sub update_encryption_hint {
+ return if !$encryption_hint_label;
+ my $enabled = defined(Proxmox::Install::Config::get_encryption());
+ $encryption_hint_label->set_text($enabled ? 'Encryption: ' . encryption_desc() : '');
+}
my $hdoption_first_setup = 1;
@@ -1894,6 +1962,18 @@ sub create_hdoption_view {
$grid->attach($fstypecb, 1, $row, 1, 1);
+ # the passphrase is asked on the password page, after the keyboard layout is set
+ my $encrypt_cb;
+ if (Proxmox::Install::RunEnv::get()->{boot_type} eq 'efi') {
+ $row++;
+ my $encrypt_label = Gtk3::Label->new("Encryption");
+ $encrypt_label->set_xalign(1.0);
+ $grid->attach($encrypt_label, 0, $row, 1, 1);
+ $encrypt_cb = Gtk3::CheckButton->new_with_label("Passphrase at boot");
+ $encrypt_cb->set_active(defined(Proxmox::Install::Config::get_encryption()));
+ $grid->attach($encrypt_cb, 1, $row, 1, 1);
+ }
+
$hbox2->show_all();
$row++;
@@ -2131,6 +2211,14 @@ sub create_hdoption_view {
Proxmox::Install::Config::set_maxvz(undef);
}
+ if ($encrypt_cb && $encrypt_cb->get_active()) {
+ my $previous = Proxmox::Install::Config::get_encryption() // {};
+ Proxmox::Install::Config::set_encryption({ passphrase => $previous->{passphrase} });
+ } else {
+ Proxmox::Install::Config::set_encryption(undef);
+ }
+ update_encryption_hint();
+
$dialog->destroy();
}
@@ -2194,6 +2282,10 @@ sub create_hdsel_view {
$options->signal_connect(clicked => \&create_hdoption_view);
$hbox->pack_start($options, 0, 0, 0);
+ $encryption_hint_label = Gtk3::Label->new();
+ $hbox->pack_start($encryption_hint_label, 0, 0, 10);
+ update_encryption_hint();
+
$gtk_state->{inbox}->show_all;
Proxmox::UI::display_html('page1.htm');
@@ -2204,7 +2296,10 @@ sub create_hdsel_view {
my $filesys = Proxmox::Install::Config::get_filesys();
if ($filesys =~ m/zfs/) {
apply_raid_disk_selection();
- my ($devlist) = eval { Proxmox::Install::get_zfs_raid_setup() };
+ my ($devlist) = eval {
+ Proxmox::Install::assert_zfs_encryption_copies();
+ Proxmox::Install::get_zfs_raid_setup();
+ };
if (my $err = $@) {
Proxmox::UI::message("$err");
return;
diff --git a/proxmox-installer-common/src/options.rs b/proxmox-installer-common/src/options.rs
index c9ee7192..e3ccf452 100644
--- a/proxmox-installer-common/src/options.rs
+++ b/proxmox-installer-common/src/options.rs
@@ -259,6 +259,8 @@ pub struct BootdiskOptions {
pub disks: Vec<Disk>,
pub fstype: FilesystemType,
pub advanced: AdvancedBootdiskOptions,
+ /// Whether to encrypt the system disks, LUKS2 or native ZFS encryption, as per `fstype`.
+ pub encrypt: bool,
}
impl BootdiskOptions {
@@ -267,6 +269,7 @@ impl BootdiskOptions {
disks: vec![disk.clone()],
fstype: FilesystemType::Ext4,
advanced: AdvancedBootdiskOptions::Lvm(LvmBootdiskOptions::defaults_from(disk)),
+ encrypt: false,
}
}
}
diff --git a/proxmox-tui-installer/src/main.rs b/proxmox-tui-installer/src/main.rs
index f7643b71..450f61ce 100644
--- a/proxmox-tui-installer/src/main.rs
+++ b/proxmox-tui-installer/src/main.rs
@@ -21,7 +21,7 @@ use proxmox_installer_common::{
},
setup::{LocaleInfo, RuntimeInfo, SetupInfo, installer_setup},
};
-use proxmox_installer_types::ProxmoxProduct;
+use proxmox_installer_types::{ProxmoxProduct, answer::DiskEncryption};
mod options;
use options::{InstallerOptions, PasswordOptions};
@@ -145,6 +145,8 @@ struct InstallerState {
runtime_info: RuntimeInfo,
locales: LocaleInfo,
steps: HashMap<InstallerStep, ScreenId>,
+ /// The cached password screen lacks or has superfluous disk encryption fields.
+ password_screen_stale: bool,
in_test_mode: bool,
}
@@ -185,6 +187,7 @@ fn main() {
runtime_info,
locales,
steps: HashMap::new(),
+ password_screen_stale: false,
in_test_mode,
});
@@ -262,10 +265,13 @@ fn switch_to_next_screen(
// replace it if the screen is switched to.
// TODO: Could be done by e.g. having all the main dialog views implement some sort of
// .refresh(), which can be called if the view is switched to.
- if step == InstallerStep::Summary {
+ if step == InstallerStep::Summary
+ || (step == InstallerStep::Password && state.password_screen_stale)
+ {
let view = constructor(siv);
siv.screen_mut().pop_layer();
siv.screen_mut().add_layer(view);
+ siv.with_user_data(|state: &mut InstallerState| state.password_screen_stale = false);
}
return;
@@ -391,6 +397,11 @@ fn bootdisk_dialog(siv: &mut Cursive) -> InstallerView {
match options {
Some(Ok(options)) => {
siv.with_user_data(|state: &mut InstallerState| {
+ if options.encrypt != state.options.bootdisk.encrypt
+ && state.steps.contains_key(&InstallerStep::Password)
+ {
+ state.password_screen_stale = true;
+ }
state.options.bootdisk = options;
});
@@ -435,22 +446,44 @@ fn password_dialog(siv: &mut Cursive) -> InstallerView {
let state = siv.user_data::<InstallerState>().unwrap();
let options = &state.options.password;
- let inner = FormView::<()>::new()
+ let mut inner = FormView::<()>::new()
.child(
"Root password [at least 8 characters]",
- EditView::new().secret(),
+ EditView::new().secret().content(&options.root_password),
+ )
+ .child(
+ "Confirm root password",
+ EditView::new().secret().content(&options.root_password),
)
- .child("Confirm root password", EditView::new().secret())
.child(
"Administrator email",
EditView::new().content(&options.email),
- )
- .with_name("password-options");
+ );
+ // asked here, so that it is typed with the keyboard layout the boot prompt uses
+ if state.options.bootdisk.encrypt {
+ inner.add_child(
+ "Disk passphrase",
+ EditView::new()
+ .secret()
+ .content(&options.encryption_passphrase),
+ );
+ inner.add_child(
+ "Confirm disk passphrase",
+ EditView::new()
+ .secret()
+ .content(&options.encryption_passphrase),
+ );
+ }
+ let inner = inner.with_name("password-options");
InstallerView::new(
state,
inner,
Box::new(|siv| {
+ let encrypt = siv
+ .user_data::<InstallerState>()
+ .is_some_and(|state| state.options.bootdisk.encrypt);
+
let options = siv.call_on_name("password-options", |view: &mut FormView| {
let root_password = view
.get_value::<EditView, _>(0)
@@ -471,9 +504,20 @@ fn password_dialog(siv: &mut Cursive) -> InstallerView {
} else if let Err(err) = email_validate(&email) {
Err(err.to_string())
} else {
+ let mut encryption_passphrase = String::new();
+ if encrypt {
+ encryption_passphrase = view
+ .get_value::<EditView, _>(3)
+ .ok_or("failed to retrieve disk passphrase")?;
+ let confirm = view
+ .get_value::<EditView, _>(4)
+ .ok_or("failed to retrieve disk passphrase confirmation")?;
+ check_encryption_passphrase(&encryption_passphrase, &confirm)?;
+ }
Ok(PasswordOptions {
root_password,
email,
+ encryption_passphrase,
})
}
});
@@ -494,6 +538,16 @@ fn password_dialog(siv: &mut Cursive) -> InstallerView {
)
}
+/// Same rules as the installer's preflight check, so a mistake shows while it can still be fixed.
+fn check_encryption_passphrase(passphrase: &str, confirm: &str) -> Result<(), String> {
+ DiskEncryption::check_passphrase(passphrase)
+ .map_err(|reason| format!("disk passphrase {reason}"))?;
+ if passphrase != confirm {
+ return Err("disk passphrases do not match".to_owned());
+ }
+ Ok(())
+}
+
fn network_dialog(siv: &mut Cursive) -> InstallerView {
let state = siv.user_data::<InstallerState>().unwrap();
let options = &state.options.network;
diff --git a/proxmox-tui-installer/src/options.rs b/proxmox-tui-installer/src/options.rs
index 573a4ceb..a4ce43d4 100644
--- a/proxmox-tui-installer/src/options.rs
+++ b/proxmox-tui-installer/src/options.rs
@@ -4,12 +4,27 @@ use proxmox_installer_common::{
options::{BootdiskOptions, NetworkOptions, TimezoneOptions},
setup::{LocaleInfo, NetworkInfo, RuntimeInfo},
};
-use proxmox_installer_types::{EMAIL_DEFAULT_PLACEHOLDER, answer::NetworkBondOptions};
+use proxmox_installer_types::{
+ EMAIL_DEFAULT_PLACEHOLDER, EncryptionMode, answer::NetworkBondOptions,
+};
+
+/// How the system disks get encrypted, as shown on the disk page and in the summary.
+pub fn encryption_summary(bootdisk: &BootdiskOptions) -> &'static str {
+ if !bootdisk.encrypt {
+ return "none";
+ }
+ match EncryptionMode::for_filesystem(bootdisk.fstype) {
+ EncryptionMode::Luks => "LUKS2",
+ EncryptionMode::ZfsNative => "native ZFS encryption",
+ }
+}
#[derive(Clone)]
pub struct PasswordOptions {
pub email: String,
pub root_password: String,
+ /// Only used if the system disks get encrypted.
+ pub encryption_passphrase: String,
}
impl Default for PasswordOptions {
@@ -17,6 +32,7 @@ impl Default for PasswordOptions {
Self {
email: EMAIL_DEFAULT_PLACEHOLDER.to_string(),
root_password: String::new(),
+ encryption_passphrase: String::new(),
}
}
}
@@ -49,6 +65,7 @@ impl InstallerOptions {
let mut summary = vec![
SummaryOption::new("Bootdisk filesystem", self.bootdisk.fstype.to_string()),
+ SummaryOption::new("Disk encryption", encryption_summary(&self.bootdisk)),
SummaryOption::new(
"Bootdisk(s)",
self.bootdisk
diff --git a/proxmox-tui-installer/src/setup.rs b/proxmox-tui-installer/src/setup.rs
index fc3c43df..08eb929d 100644
--- a/proxmox-tui-installer/src/setup.rs
+++ b/proxmox-tui-installer/src/setup.rs
@@ -3,7 +3,7 @@ use std::collections::BTreeMap;
use crate::options::InstallerOptions;
use proxmox_installer_common::{
options::AdvancedBootdiskOptions,
- setup::{InstallConfig, InstallFirstBootSetup, InstallRootPassword},
+ setup::{InstallConfig, InstallEncryption, InstallFirstBootSetup, InstallRootPassword},
};
impl From<InstallerOptions> for InstallConfig {
@@ -80,6 +80,12 @@ impl From<InstallerOptions> for InstallConfig {
}
}
+ if options.bootdisk.encrypt {
+ config.encryption = Some(InstallEncryption {
+ passphrase: options.password.encryption_passphrase.clone(),
+ });
+ }
+
config
}
}
diff --git a/proxmox-tui-installer/src/views/bootdisk.rs b/proxmox-tui-installer/src/views/bootdisk.rs
index a0267f14..18775e77 100644
--- a/proxmox-tui-installer/src/views/bootdisk.rs
+++ b/proxmox-tui-installer/src/views/bootdisk.rs
@@ -9,13 +9,13 @@ use cursive::{
Cursive, Vec2, View,
view::{Nameable, Resizable, ViewWrapper},
views::{
- Button, Dialog, DummyView, LinearLayout, NamedView, PaddedView, Panel, ScrollView,
- SelectView, TextView, ViewRef,
+ Button, Checkbox, Dialog, DummyView, LinearLayout, NamedView, PaddedView, Panel,
+ ScrollView, SelectView, TextView, ViewRef,
},
};
use super::{DiskSizeEditView, FormView, IntegerEditView, TabbedView};
-use crate::InstallerState;
+use crate::{InstallerState, options::encryption_summary};
use proxmox_installer_common::{
disk_checks::{
@@ -50,6 +50,8 @@ pub struct BootdiskOptionsView {
}
impl BootdiskOptionsView {
+ const ENCRYPTION_HINT_VIEW_ID: &'static str = "bootdisk-options-encryption-hint";
+
pub fn new(siv: &mut Cursive, runinfo: &RuntimeInfo, options: &BootdiskOptions) -> Self {
let advanced_options = Arc::new(Mutex::new(options.clone()));
@@ -92,7 +94,10 @@ impl BootdiskOptionsView {
let view = LinearLayout::vertical()
.child(bootdisk_form)
.child(DummyView)
- .child(advanced_button);
+ .child(advanced_button)
+ .child(
+ TextView::new(encryption_hint(options)).with_name(Self::ENCRYPTION_HINT_VIEW_ID),
+ );
let boot_type = siv
.user_data::<InstallerState>()
@@ -156,9 +161,17 @@ impl AdvancedBootdiskOptionsView {
}
});
+ let mut form = FormView::<()>::new().child("Filesystem", fstype_select);
+ // the passphrase is asked on the password page, after the keyboard layout is set
+ if runinfo.boot_type == BootType::Efi {
+ form.add_child(
+ "Encryption (passphrase at boot)",
+ Checkbox::new().with_checked(options.encrypt),
+ );
+ }
let mut view = LinearLayout::vertical()
.child(DummyView.full_width())
- .child(FormView::<()>::new().child("Filesystem", fstype_select))
+ .child(form)
.child(DummyView.full_width());
// Create the appropriate (inner) advanced options view
@@ -264,6 +277,12 @@ impl AdvancedBootdiskOptionsView {
.and_then(|v| v.downcast_ref::<FormView>())
.and_then(|v| v.get_value::<SelectView<FilesystemType>, _>(0))
.ok_or("Failed to retrieve filesystem type".to_owned())?;
+ let encrypt = self
+ .view
+ .get_child(1)
+ .and_then(|v| v.downcast_ref::<FormView>())
+ .and_then(|v| v.get_value::<Checkbox, _>(1))
+ .unwrap_or(false);
let advanced = self
.view
@@ -283,6 +302,7 @@ impl AdvancedBootdiskOptionsView {
disks: vec![disk],
fstype,
advanced: AdvancedBootdiskOptions::Lvm(advanced),
+ encrypt,
})
} else if let Some(view) = advanced.downcast_mut::<ZfsBootdiskOptionsView>() {
let (disks, advanced) = view
@@ -294,11 +314,16 @@ impl AdvancedBootdiskOptionsView {
.check_raid_disks_setup(&disks)
.map_err(|err| format!("{fstype}: {err}"))?;
}
+ // OpenZFS stores encryption metadata where the third copy of a block would go.
+ if encrypt && advanced.copies > 2 {
+ return Err("native ZFS encryption allows at most 2 copies".to_owned());
+ }
Ok(BootdiskOptions {
disks,
fstype,
advanced: AdvancedBootdiskOptions::Zfs(advanced),
+ encrypt,
})
} else if let Some(view) = advanced.downcast_mut::<BtrfsBootdiskOptionsView>() {
let (disks, advanced) = view
@@ -315,6 +340,7 @@ impl AdvancedBootdiskOptionsView {
disks,
fstype,
advanced: AdvancedBootdiskOptions::Btrfs(advanced),
+ encrypt,
})
} else {
Err("Invalid bootdisk view state".to_owned())
@@ -799,6 +825,10 @@ fn advanced_options_view(
}
siv.pop_layer();
+ siv.call_on_name(
+ BootdiskOptionsView::ENCRYPTION_HINT_VIEW_ID,
+ |view: &mut TextView| view.set_content(encryption_hint(&options)),
+ );
*options_ref.lock().unwrap() = options;
}
})
@@ -806,6 +836,15 @@ fn advanced_options_view(
.max_size((120, 40))
}
+/// The encryption option is in the advanced options dialog, so the disk page shows its state.
+fn encryption_hint(options: &BootdiskOptions) -> String {
+ if options.encrypt {
+ format!("Encryption: {}", encryption_summary(options))
+ } else {
+ String::new()
+ }
+}
+
/// Creates a select view for all disks specified.
///
/// # Arguments
diff --git a/proxmox-tui-installer/src/views/mod.rs b/proxmox-tui-installer/src/views/mod.rs
index a99bd849..09cc9456 100644
--- a/proxmox-tui-installer/src/views/mod.rs
+++ b/proxmox-tui-installer/src/views/mod.rs
@@ -399,6 +399,12 @@ impl FormViewGetValue<String> for EditView {
}
}
+impl FormViewGetValue<bool> for Checkbox {
+ fn get_value(&self) -> Option<bool> {
+ Some(self.is_checked())
+ }
+}
+
impl<T: 'static + Clone + Send + Sync> FormViewGetValue<T> for SelectView<T> {
fn get_value(&self) -> Option<T> {
self.selection().map(|v| (*v).clone())
--
2.47.3
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [PATCH installer 5/5] assistant: keep the disk passphrase out of prepared ISOs
2026-11-17 23:42 [PATCH proxmox/installer/docs 0/8] installer: add full-disk encryption of the system disks Thomas Lamprecht
` (4 preceding siblings ...)
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 ` Thomas Lamprecht
2026-11-17 23:42 ` [PATCH docs 1/2] installation: describe full-disk encryption Thomas Lamprecht
2026-11-17 23:42 ` [PATCH docs 2/2] local-zfs: update the limitations of native encryption Thomas Lamprecht
7 siblings, 0 replies; 9+ messages in thread
From: Thomas Lamprecht @ 2026-11-17 23:42 UTC (permalink / raw)
To: pve-devel
prepare-iso refuses an answer file that enables full-disk encryption,
as the ISO travels independently of the host it installs and every
copy of it would carry the passphrase. Such answer files can still be
fetched over the network, preferably over HTTPS, or read from a
separate partition.
inspect-iso redacts the encryption section, like it already does the
root password. As the passphrase is all the section holds, it is
redacted as a whole, also when it is malformed, for example with a
misspelled key or a string in place of the section, as an ISO prepared
by other means may contain.
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
proxmox-auto-install-assistant/src/main.rs | 93 +++++++++++++++++++---
1 file changed, 80 insertions(+), 13 deletions(-)
diff --git a/proxmox-auto-install-assistant/src/main.rs b/proxmox-auto-install-assistant/src/main.rs
index 931fd770..15fe3cea 100644
--- a/proxmox-auto-install-assistant/src/main.rs
+++ b/proxmox-auto-install-assistant/src/main.rs
@@ -490,8 +490,9 @@ ARGUMENTS:
<INPUT> Path to the ISO to inspect.
OPTIONS:
- --show-sensitive Print sensitive fields (root password, subscription key,
- HTTP auth token) verbatim instead of as <redacted>.
+ --show-sensitive Print sensitive fields (root password, disk passphrase,
+ subscription key, HTTP auth token) verbatim instead of
+ as <redacted>.
-h, --help Print this help
-V, --version Print version
"#,
@@ -765,6 +766,10 @@ const ANSWER_SENSITIVE_FIELDS: &[(&str, &[&str])] = &[
("post-installation-webhook", &["auth-token", "auth_token"]),
];
+/// Answer-file sections that hold nothing but secrets, redacted as a whole whatever their shape, so
+/// that a malformed one, like a misspelled key or a string in place of the section, is too.
+const ANSWER_SENSITIVE_SECTIONS: &[&str] = &["disk-setup.encryption"];
+
fn inspect_iso(args: &CommandInspectISOArgs) -> Result<()> {
if !fs::exists(&args.input).context("checking if input ISO exists")? {
bail!("input ISO {:?} does not exist", args.input);
@@ -909,23 +914,43 @@ fn format_answer_toml(content: &str, redact: bool) -> Result<String> {
let mut value: toml::Value =
parse_answer_toml(content).context("parsing answer file as TOML")?;
if redact {
+ let redacted = || toml::Value::String(REDACTED.to_string());
for (section, keys) in ANSWER_SENSITIVE_FIELDS {
- let Some(table) = value.get_mut(*section).and_then(|v| v.as_table_mut()) else {
- continue;
- };
for key in *keys {
- if table.contains_key(*key) {
- table.insert(
- (*key).to_string(),
- toml::Value::String(REDACTED.to_string()),
- );
- }
+ let path: Vec<&str> = section.split('.').chain([*key]).collect();
+ redact_answer_value(&mut value, &path, &|value| *value = redacted());
}
}
+ for section in ANSWER_SENSITIVE_SECTIONS {
+ let path: Vec<&str> = section.split('.').collect();
+ redact_answer_value(&mut value, &path, &|value| match value.as_table_mut() {
+ Some(table) => table.iter_mut().for_each(|(_, value)| *value = redacted()),
+ None => *value = redacted(),
+ });
+ }
}
Ok(toml::to_string_pretty(&value)?)
}
+/// Calls `redact` on the value at `path`, also within arrays along it, as for a section that was
+/// given as an array of tables.
+fn redact_answer_value(value: &mut toml::Value, path: &[&str], redact: &impl Fn(&mut toml::Value)) {
+ if let toml::Value::Array(items) = value {
+ for item in items {
+ redact_answer_value(item, path, redact);
+ }
+ return;
+ }
+ match path.split_first() {
+ None => redact(value),
+ Some((part, rest)) => {
+ if let Some(value) = value.get_mut(*part) {
+ redact_answer_value(value, rest, redact);
+ }
+ }
+ }
+}
+
fn prepare_iso(args: &CommandPrepareISOArgs) -> Result<()> {
check_prepare_requirements(args)?;
let uuid = get_iso_uuid(&args.input)?;
@@ -982,7 +1007,14 @@ fn prepare_iso(args: &CommandPrepareISOArgs) -> Result<()> {
if let Some(file) = &args.answer_file {
println!("Checking provided answer file...");
- parse_answer(file)?;
+ let answer = parse_answer(file)?;
+ // the ISO travels independently of the host it installs
+ if answer.disks.encryption.is_some() {
+ bail!(
+ "Cannot embed an answer file with a disk passphrase, as every copy of the ISO \
+ would contain it. Use '--fetch-from http' or '--fetch-from partition' instead."
+ );
+ }
}
let iso_target = final_iso_location(args)?;
@@ -1694,9 +1726,44 @@ fn parse_cd_info(raw_cd_info: &str) -> Result<CdInfo> {
#[cfg(test)]
mod tests {
- use super::{CdInfo, PXE_BOOT_OPTIONS, boot_option_params, parse_cd_info};
+ use super::{CdInfo, PXE_BOOT_OPTIONS, boot_option_params, format_answer_toml, parse_cd_info};
use anyhow::Result;
+ #[test]
+ fn redacts_disk_encryption_passphrase() -> Result<()> {
+ let answer = r#"
+[global]
+root-password = "rootsecret"
+
+[disk-setup]
+filesystem = "ext4"
+
+[disk-setup.encryption]
+passphrase = "disksecret"
+"#;
+ let redacted = format_answer_toml(answer, true)?;
+ for secret in ["rootsecret", "disksecret"] {
+ assert!(!redacted.contains(secret), "{secret} leaked:\n{redacted}");
+ }
+ assert!(redacted.contains("filesystem = \"ext4\""), "{redacted}");
+ assert!(format_answer_toml(answer, false)?.contains("disksecret"));
+
+ // malformed sections, as an ISO prepared by other means may contain
+ for answer in [
+ "[disk-setup]\nencryption = \"disksecret\"\n",
+ "[[disk-setup.encryption]]\npassphrase = \"disksecret\"\n",
+ "[disk-setup.encryption]\npasphrase = \"disksecret\"\n",
+ "[[disk-setup]]\n[disk-setup.encryption]\npassphrase = \"disksecret\"\n",
+ "[[global]]\nroot-password = \"rootsecret\"\n",
+ ] {
+ let redacted = format_answer_toml(answer, true)?;
+ for secret in ["rootsecret", "disksecret"] {
+ assert!(!redacted.contains(secret), "{secret} leaked:\n{redacted}");
+ }
+ }
+ Ok(())
+ }
+
#[test]
fn parse_cdinfo() -> Result<()> {
let s = r#"
--
2.47.3
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [PATCH docs 1/2] installation: describe full-disk encryption
2026-11-17 23:42 [PATCH proxmox/installer/docs 0/8] installer: add full-disk encryption of the system disks Thomas Lamprecht
` (5 preceding siblings ...)
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
2026-11-17 23:42 ` [PATCH docs 2/2] local-zfs: update the limitations of native encryption Thomas Lamprecht
7 siblings, 0 replies; 9+ messages in thread
From: Thomas Lamprecht @ 2026-11-17 23:42 UTC (permalink / raw)
To: pve-devel
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
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [PATCH docs 2/2] local-zfs: update the limitations of native encryption
2026-11-17 23:42 [PATCH proxmox/installer/docs 0/8] installer: add full-disk encryption of the system disks Thomas Lamprecht
` (6 preceding siblings ...)
2026-11-17 23:42 ` [PATCH docs 1/2] installation: describe full-disk encryption Thomas Lamprecht
@ 2026-11-17 23:42 ` Thomas Lamprecht
7 siblings, 0 replies; 9+ messages in thread
From: Thomas Lamprecht @ 2026-11-17 23:42 UTC (permalink / raw)
To: pve-devel
Native ZFS encryption was marked experimental, citing two problems.
Replicating encrypted datasets was fixed with pve-storage 9.1.3, and
the OpenZFS issue about checksum errors with snapshots was closed in
May 2025 together with the send corruption it was traced to, fixed in
OpenZFS 2.2.8 and 2.3.3. The installer now offers native ZFS
encryption for the root pool.
So drop the experimental warning and note what stays readable instead.
Replace the statement that GRUB cannot boot from such pools with how
the installer sets that up, and mention zfs-mount-generator for
loading the keys of other encrypted datasets at boot.
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
local-zfs.adoc | 23 +++++++++++------------
1 file changed, 11 insertions(+), 12 deletions(-)
diff --git a/local-zfs.adoc b/local-zfs.adoc
index 029f628..0577440 100644
--- a/local-zfs.adoc
+++ b/local-zfs.adoc
@@ -702,11 +702,8 @@ improve performance when sufficient memory exists in a system.
Encrypted ZFS Datasets
~~~~~~~~~~~~~~~~~~~~~~
-WARNING: Native ZFS encryption in {pve} is experimental. Known limitations and
-issues include Replication with encrypted datasets
-footnote:[https://bugzilla.proxmox.com/show_bug.cgi?id=2350],
-as well as checksum errors when using Snapshots or ZVOLs.
-footnote:[https://github.com/openzfs/zfs/issues/11688]
+NOTE: Native ZFS encryption leaves the names, properties and space usage of
+datasets and snapshots readable.
ZFS on Linux version 0.8.0 introduced support for native encryption of
datasets. After an upgrade from previous ZFS on Linux versions, the encryption
@@ -724,14 +721,16 @@ NAME PROPERTY VALUE SOURCE
tank feature@encryption enabled local
----
-WARNING: There is currently no support for booting from pools with encrypted
-datasets using GRUB, and only limited support for automatically unlocking
-encrypted datasets on boot. Older versions of ZFS without encryption support
-will not be able to decrypt stored data.
+WARNING: GRUB cannot read encrypted datasets. For
+xref:installation_disk_encryption[full-disk encryption], the installer puts the
+kernels and initial RAM disks on unencrypted EFI system partitions managed by
+xref:sysboot_proxmox_boot_tool[`proxmox-boot-tool`]. Older versions of ZFS
+without encryption support will not be able to decrypt stored data.
-NOTE: It is recommended to either unlock storage datasets manually after
-booting, or to write a custom unit to pass the key material needed for
-unlocking on boot to `zfs load-key`.
+NOTE: Encrypted storage datasets with their own encryption root have to be
+unlocked manually after booting, or configured to load their key at boot, for
+example with the `zfs-load-key@` units of `zfs-mount-generator(8)` or a custom
+unit that passes the key material to `zfs load-key`.
WARNING: Establish and test a backup procedure before enabling encryption of
production data. If the associated key material/passphrase/keyfile has been
--
2.47.3
^ permalink raw reply related [flat|nested] 9+ messages in thread
end of thread, other threads:[~2026-11-17 23:45 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
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 ` [PATCH docs 1/2] installation: describe full-disk encryption Thomas Lamprecht
2026-11-17 23:42 ` [PATCH docs 2/2] local-zfs: update the limitations of native encryption Thomas Lamprecht
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.