Brokkr Docs - Disk Encryption

Brokkr supports optional LUKS2 disk encryption for data volumes. When enabled during provisioning, your data disks are encrypted at rest using Linux Unified Key Setup (LUKS2), providing protection against unauthorized physical access to your storage.

How It Works

During provisioning, Brokkr creates LUKS2 encrypted containers on your data disk logical volumes. A temporary encryption key is generated to set up the container and is immediately discarded after the disk layout is applied.

Brokkr does not store, retain, or have access to any encryption keys. You are solely responsible for setting and managing your LUKS passphrase. If you lose your passphrase, the encrypted data cannot be recovered.

What Gets Encrypted

Data disks only. The OS disk (mountpoint /) is never encrypted. Encryption is available for additional data disks such as /data, /home, etc.
Encryption can be enabled per disk group during provisioning by checking the Encrypt option in the disk layout selector.
Encryption works with LVM, RAID, and direct disk configurations.

Helper Scripts

When encryption is enabled, Brokkr installs three helper scripts on your server at /usr/local/bin/, available system-wide:

luks-rekey

Sets up your LUKS passphrase for the first time. This must be run after your initial provisioning to take ownership of the encrypted volumes. The script formats the LUKS container with your chosen passphrase, creates the filesystem, and updates /etc/fstab with the new encryption identifiers.

# Interactive
sudo luks-rekey

# Non-interactive
sudo luks-rekey --passphrase "your-passphrase" --yes

# Via environment variable
LUKS_PASSPHRASE="your-passphrase" sudo luks-rekey --yes

luks-unlock

Opens your encrypted volumes and mounts them after a reboot. Since the OS disk is unencrypted, your server boots normally and is accessible via SSH. Run this script after each reboot to unlock and mount your encrypted data volumes.

# Interactive
sudo luks-unlock

# Non-interactive
sudo luks-unlock --passphrase "your-passphrase"

# Via environment variable
LUKS_PASSPHRASE="your-passphrase" sudo luks-unlock

luks-lock

Unmounts and closes your encrypted volumes, securing the data at rest. Use this when you want to lock your volumes without rebooting.

sudo luks-lock

Getting Started After Provisioning

SSH into your server using the credentials provided during provisioning.
Run the rekey script to set your LUKS passphrase:
```
sudo luks-rekey
```
You will be prompted to enter and confirm a passphrase. The script will format the LUKS container, create the filesystem, and mount the volume.
Verify your volumes are mounted:
```
lsblk
```
You should see your encrypted volume with a crypt type and the expected mountpoint.
Store your passphrase securely. Brokkr does not have a copy and cannot recover it.

After Reboots

Encrypted volumes are not automatically unlocked at boot to avoid passphrase prompts on headless servers. After each reboot:

SSH into your server.
Run the unlock script:
```
sudo luks-unlock
```

Preserved Encrypted Disks

When reprovisioning a server, you can choose to preserve data disk groups. If an encrypted disk is preserved, Brokkr will detect the existing LUKS container and configure /etc/fstab and /etc/crypttab so your volume is ready to unlock after the reprovision completes. Your existing passphrase remains unchanged.

Important Notes

Key responsibility: Brokkr generates a temporary key during provisioning that is immediately discarded. We do not store encryption keys. You must run the rekey script to set your own passphrase.
No key recovery: If you lose your passphrase, the data on encrypted volumes cannot be recovered by Brokkr or anyone else.
OS disk is never encrypted: This ensures your server always boots and is accessible via SSH for you to unlock data volumes remotely.
Performance: LUKS2 encryption uses hardware-accelerated AES on modern processors. The performance impact is minimal for most workloads.