Troubleshooting

epv-hsm check fails

Complete the missing items as prompted: configure the PIN with epv-hsm encrypt-pin + set-pin, confirm the HSM driver is mounted into the container, the orchestration file exists, and the Para Vault container is running.

Enable/migrate hangs or does not start for a long time

Usually the HSM is unreachable: check the Devices entry in cs_pkcs11_R3.cfg (IP/port or device file), network connectivity/device pass-through; for the LAN type, confirm the container can route to the HSM.

Enable/migrate reports a PIN error

Re-encrypt the correct user PIN with epv-hsm encrypt-pin and store it with set-pin; confirm that the initial PIN was changed to a formal PIN as described in Section 4.3.

Key label mismatch

Confirm the key label (default epv-server-key, or the value provided via --key-label) matches the one on the HSM. For a new deployment, use epv-hsm enable to have the HSM generate the key.

Re-running after an interrupted migration

epv-hsm migrate is idempotent: it automatically detects the current state and continues or skips; existing protection remains unaffected until the switchover completes.

epv-hsm verify "auto-start on restart" fails

Check HSM reachability and driver mount; use epv-hsm status to view the protection mode and running status.