# 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:

```text
/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.

```sh
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:

```sh
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.

```sh
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](https://docs.panocrypt.com/setup/existing-luks-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:

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

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

```sh
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.