# Bind an existing encrypted root disk to Panocrypt

Use this path only after you are ready to validate boot-time dependencies for
your distribution.

## What runs on the host

The bind path uses standard LUKS and Clevis packages. No Panocrypt-specific
host agent is required for the existing-LUKS bind or unlock path.

Read [LUKS keyslots](https://docs.panocrypt.com/concepts/luks-keyslots/) before binding a root disk. The
Panocrypt binding should use one removable keyslot beside customer-held
recovery material.

Read [No custody of disk keys](https://docs.panocrypt.com/trust/non-escrow/) before changing root-disk
boot behavior. The local unlock key is created and wrapped on the machine,
while Panocrypt only participates in the policy-approved recovery exchange.

## What makes root disks different

A data volume can be unlocked after Linux is already running. A root disk must
unlock inside the initramfs before the normal system starts. That early boot
environment often does not include networking, DNS, CA certificates, or the
Clevis hooks your running system has.

Panocrypt can participate in the managed unlock decision, but your distro's
initramfs must be able to reach Panocrypt over TLS and run Clevis before root
mount.

That is the hard part of existing encrypted root disks. The Panocrypt service
can decide and participate; your early-boot environment must be able to make
the request, validate Panocrypt's TLS certificate, and complete the Clevis
unlock path.

Read [How automatic unlocks work](https://docs.panocrypt.com/concepts/automatic-unlocks/) for the
early-boot flow, TLS requirements, and recovery-exchange sequence before
changing root-disk boot behavior.

## Your responsibility

- Preserve customer-controlled LUKS recovery material.
- Keep console or KVM access available before the first reboot test.
- Confirm Clevis is present in the initramfs.
- Confirm the initramfs brings up networking before unlock.
- Confirm the initramfs has CA certificates needed to verify Panocrypt's TLS
  certificate.
- Confirm your distro's boot hooks run the Clevis unlock path for the root
  disk.

## Panocrypt's role

- Publish the device URL and public binding metadata.
- Participate in the blinded recovery exchange.
- Enforce configured source policy and lifecycle state before future managed
  unlock.
- Record unlock decision evidence for implemented controls.

## Root-disk bind path

1. Register a Panocrypt device and copy the **Existing LUKS** device URL.
2. Confirm recovery material and out-of-band access.
3. [Prepare initramfs](#prepare-initramfs) with Clevis, networking, and CA
   certificates.
4. Rebuild the initramfs.
5. [Bind an unused LUKS keyslot](#bind-the-root-disk) with the standard Clevis
   `tang` pin and the Panocrypt device URL.
6. Run a Clevis unlock test before reboot if your distro supports it.
7. [Schedule and test a reboot](#test-the-reboot).
8. Review Panocrypt device state and audit evidence.

## Prepare initramfs

Package names vary by distro. On Ubuntu-family systems, expect to need packages
in these categories:

| Need | Example package family |
|---|---|
| LUKS tooling | `cryptsetup` |
| Clevis LUKS support | `clevis`, `clevis-luks` |
| Initramfs integration | `clevis-initramfs`, `initramfs-tools` |
| TLS trust | `ca-certificates` |
| Early networking | distro-specific initramfs network support |

After installing the required packages, rebuild the initramfs using your
distro's normal command, for example:

```sh
sudo update-initramfs -u -k all
```

Then inspect the generated initramfs or run your distro's validation tooling to
confirm it includes:

- Clevis unlock hooks.
- The network driver and DHCP or static network configuration needed before
  root mount.
- DNS resolution for the Panocrypt endpoint.
- CA certificates needed to verify Panocrypt's TLS certificate.

## Bind the root disk

Use a stable root LUKS device path and the Panocrypt device URL:

```sh
export ROOT_LUKS_DEVICE="/dev/disk/by-uuid/YOUR_ROOT_LUKS_UUID"
export PANOCRYPT_DEVICE_URL="https://tango.panocrypt.com/YOUR_ORG/YOUR_DEVICE"
export RECOVERY_KEY="/path/to/customer-held-recovery-key"

export CLEVIS_CFG="$(printf '{"url":"%s"}' "$PANOCRYPT_DEVICE_URL")"
sudo clevis luks bind -y -k "$RECOVERY_KEY" \
  -d "$ROOT_LUKS_DEVICE" tang "$CLEVIS_CFG"
```

Confirm the token and rebuild initramfs again after binding:

```sh
sudo clevis luks list -d "$ROOT_LUKS_DEVICE"
sudo update-initramfs -u -k all
```

## Test the reboot

Test during a planned maintenance window.

1. Confirm out-of-band console or KVM access works.
2. Confirm the customer-held recovery passphrase works.
3. Confirm the device's source policy allows the server's boot-time source IP.
4. Reboot.
5. Verify the host returns on encrypted root.

After the host returns:

```sh
findmnt / -o SOURCE,FSTYPE
sudo cryptsetup status cryptroot
```

Then review the Panocrypt device activity and audit trail for the managed
unlock decision.

After the first successful reboot, use
[Source IP and one-time unlocks](https://docs.panocrypt.com/operations/source-ip-and-one-time-unlocks/)
for source-policy changes and **Allow once**. Use
[Disable unlocks](https://docs.panocrypt.com/operations/disable-unlocks/) and
[Approval groups](https://docs.panocrypt.com/operations/approval-groups/) for those controls.

## Boundary

Panocrypt can refuse future managed unlock for the device. That does not lock a
host that is already running, remove keys from memory, remotely modify a LUKS
header, or act as remote wipe.

To remove Panocrypt from the root disk, confirm another local recovery keyslot
works, remove the Panocrypt-bound Clevis keyslot, and rebuild initramfs if your
distro requires the updated early-boot state. See
[Remove Panocrypt from a LUKS device](https://docs.panocrypt.com/trust/remove-panocrypt-binding/) for the
local removal workflow.

## Reboot result

You connected an existing encrypted root disk to Panocrypt-managed boot unlock
using the standard Linux encryption stack. The test is only complete if the
host returns from reboot and the Panocrypt audit trail shows the managed unlock
decision you expected.