Assisted setup recovery material

Panocrypt-assisted disk encryption setup always needs a customer-controlled local recovery path.

If you provide a passphrase with --passphrase-file or PANOCRYPT_SETUP_RECOVERY_PASSPHRASE, that value becomes the local LUKS recovery passphrase. If you do not provide one, the cloud-init/user-data setup path generates one on the host with openssl rand when OpenSSL is available, or with /dev/urandom and base64 as the fallback. Direct CLI setup without --passphrase-file generates the recovery passphrase locally with a cryptographically secure random generator.

Panocrypt does not store it. Panocrypt cannot show it later. Preserve it before you depend on the server.

Where to find it

For the normal cloud-init/user-data setup path, the generated recovery passphrase is written on the target at:

/root/panocrypt-luks-recovery-passphrase.txt

The file is owned by root and should be treated as sensitive LUKS recovery material. Retrieve it over a trusted admin path after setup completes and the host has returned on encrypted root.

sudo ls -l /root/panocrypt-luks-recovery-passphrase.txt
sudo cat /root/panocrypt-luks-recovery-passphrase.txt

Do not put this passphrase into cloud-init/user-data. The normal generated path keeps it on the target instead of sending it through provider metadata.

If you brought your own passphrase

For advanced CLI setup, you can pass your own local recovery passphrase:

sudo panocrypt disk setup --passphrase-file /path/to/customer-recovery-passphrase ...

In that case, Panocrypt uses the file value you supplied. The CLI does not need to generate a new recovery passphrase for you. Keep the value in your own recovery system and clean up the source file according to your policy.

Test it before you move it

Before you delete any on-host copy, prove the recovery passphrase opens the LUKS device.

Set the LUKS device path for the target. Use the exact device from your setup run or a stable /dev/disk/by-id/... path when possible.

export LUKS_DEVICE="/dev/disk/by-id/YOUR_DEVICE"

sudo cryptsetup open --test-passphrase "$LUKS_DEVICE" \
  --key-file /root/panocrypt-luks-recovery-passphrase.txt

The command should exit successfully. It checks the passphrase without opening a mapper device.

For a root disk, keep provider console, KVM, rescue, or break-glass access available until you have also verified an unattended reboot.

Store it outside Panocrypt

Store the recovery passphrase in the customer-controlled place your team uses for break-glass infrastructure access: a password manager, secrets vault, hardware-backed process, sealed recovery record, or another internal system with the right approvals and audit trail.

Panocrypt does not back this material up. If the recovery passphrase is lost and managed unlock cannot run because early-boot networking, CA trust, source policy, or another boot-time dependency is broken, Panocrypt cannot recover the disk for you.

If the issue is early-boot networking or TLS trust, use the Bind an existing encrypted root disk guide for the initramfs networking and CA certificate requirements.

Remove the on-host copy

After you have tested the passphrase and stored it outside Panocrypt, remove the on-host file.

If shred is available, use it:

sudo shred -u /root/panocrypt-luks-recovery-passphrase.txt

If shred is not available, remove the file with your normal host cleanup process:

sudo rm -f /root/panocrypt-luks-recovery-passphrase.txt

Retrieve the passphrase promptly, store it in the right customer-controlled system, remove the on-host copy, and avoid cloning images that contain recovery material.

Higher-assurance rotation after setup

The normal setup path generates recovery material on the target before the server has fully returned on encrypted root. That means the generated recovery passphrase may have existed on storage while the original provider image was still being converted.

For most teams, the practical control is to retrieve the generated passphrase, store it outside Panocrypt, remove the on-host copy, and keep provider images or snapshots that might contain recovery material out of reuse.

If your threat model requires stronger cleanup after a fresh-server setup, plan a rotation after the server has booted from the encrypted root:

1. Add a new customer-controlled LUKS recovery passphrase or keyslot from the encrypted system.
2. Test the new recovery path.
3. Remove the original generated recovery keyslot.
4. Remove and rebind the Panocrypt-managed Clevis keyslot if you want the managed unlock metadata created only after the encrypted system is in place.

Changing keyslots changes local unlock paths. It does not, by itself, make an old copied LUKS header useless. If your threat model includes an attacker who may have both an old LUKS header copy and the old recovery passphrase, use a planned cryptsetup reencrypt procedure to rotate the LUKS volume key, then bind Panocrypt again from the new header state. Treat old provider snapshots, images, and backups from before that rotation as sensitive.

This is separate from running-host protection. After a LUKS volume is unlocked, the host has the material needed to read the disk in memory. If your threat model includes access to a running host or host memory, consider platform controls such as confidential-computing instances or other memory-protection features in addition to disk encryption at rest.

When you might need it

You might need the recovery passphrase when:

• Managed unlock is disabled or denied.
• The server cannot reach Panocrypt from initramfs.
• Early-boot networking is missing or broken.
• The initramfs CA certificate bundle is missing and TLS validation fails.
• Source IP policy no longer matches the boot-time network path.
• You removed the Panocrypt-bound keyslot and kept only local recovery paths.

The recovery passphrase is not a replacement for fixing those problems. It is the local break-glass path that keeps you in control while you repair them.

Customer-held recovery boundary

Assisted setup leaves recovery control with the customer. Panocrypt can help operate managed unlock, but the local recovery passphrase is yours to retrieve, test, store, and remove.