Tang and Clevis on Linux: Network-Bound Disk Encryption (NBDE) for Headless Servers in 2026

Updated: June 19, 2026

Tang and Clevis enable Network-Bound Disk Encryption (NBDE) on Linux, letting LUKS2 volumes unlock automatically at boot only when a server can reach a trusted Tang service on its local network. No passphrase, no human, no keys stored on disk. Tang runs a lightweight JOSE/JWE key-exchange service. Clevis runs on each client and binds a LUKS keyslot to one or more Tang servers (or a TPM, or a threshold combination). The result: encrypted-at-rest data centre fleets that boot unattended on your network but stay sealed if a disk is stolen or shipped offsite.

Honestly, I picked this stack up the hard way. A rack got moved between cages overnight, three hosts came up to a passphrase prompt nobody had at 3am, and the on-call shift turned into a very long lesson about why network-bound unlock beats human-bound unlock for headless gear. So, let's get into how Tang and Clevis actually fit together, and how to deploy them without bricking your fleet.

• Tang is a stateless ~200-line server speaking JOSE. Clevis is the client-side framework that binds LUKS2 keyslots to Tang, TPM2, or Shamir thresholds.
• NBDE never sends or stores the disk key. McCallum's two-party ECDH derives it fresh at each boot from the Tang advertisement and an ephemeral client key.
• The recommended production topology is sss threshold pins: 2-of-3 Tang servers, or 1 TPM + 1 Tang, so a single failure never bricks boot and a single compromise never leaks data.
• On Ubuntu 24.04, RHEL 9/10, and Fedora 41+, clevis-luks-bind plus clevis-dracut (or clevis-initramfs) is the complete install. No kernel patches required.
• Tang key rotation is a two-step tangd-rotate-keys dance: clients must re-bind before old keys are deleted, or they fail to boot.
• Pair NBDE with Secure Boot, IMA measurement, and a hardened initramfs. Otherwise an attacker with physical access can modify the early boot chain to phone home to a malicious Tang.

What is Network-Bound Disk Encryption?

Network-Bound Disk Encryption (NBDE) is a deployment pattern where an encrypted volume's unlock key is reconstructed at boot from a network exchange with a trusted server, rather than entered by a human or read from local hardware. On Linux this is implemented by two upstream projects from Red Hat: Tang, the server, and Clevis, the client-side pluggable framework that binds LUKS2 keyslots to one or more "pins" (Tang, TPM2, Shamir Secret Sharing).

The problem NBDE solves is the chicken-and-egg of headless servers. You want disks encrypted so a stolen drive is worthless, but you also want the machine to boot unattended after a power cycle at 03:00. Storing the passphrase in the initramfs defeats encryption. Using a TPM alone ties the secret to that exact motherboard, so if you replace the board the data is gone. NBDE makes the unlock contingent on being on the right network: a server stolen from the rack cannot reach the Tang service, and will hang at the LUKS prompt.

NBDE has been production-ready in Red Hat Enterprise Linux since 8, available in Fedora and Ubuntu via the clevis and tang packages, and is broadly used in OpenShift, RHEL Image Mode, and bare-metal hypervisor fleets. It does not replace passphrases. Those remain as a recovery keyslot. It just adds an automated unlock path beside them.

How Tang and Clevis work under the hood

The cryptographic core is Nathaniel McCallum's variant of JOSE two-party Diffie-Hellman, designed so the disk key is derived rather than retrieved. The Tang server publishes a signed advertisement containing two ECDH public keys (currently P-521 by default in Tang 14+): an exchange key and a signing/verification key. The advertisement is a standard JWS document fetched from GET /adv.

When you bind a LUKS keyslot with Clevis, the client:

1. Fetches the advertisement and verifies the signature chain.
2. Generates an ephemeral ECDH key pair.
3. Combines its private key with Tang's public exchange key to derive a shared secret K.
4. Uses K to wrap a freshly generated LUKS keyslot passphrase.
5. Stores in the LUKS2 header only: Tang's URL, the advertisement thumbprint, and the client's public ephemeral key. Never the secret.

At every boot, Clevis sends its public ephemeral key to Tang's POST /rec/<kid> endpoint. Tang multiplies it by its private exchange key and returns the result. The client combines this with its own private key to reconstruct K, unwraps the passphrase, and feeds it to cryptsetup. Crucially, Tang never sees the LUKS passphrase, never stores per-client state, and the same exchange is unforgeable without Tang's private key. That makes Tang trivially horizontally scalable and stateless (you can run dozens behind a load balancer). The upstream code lives at github.com/latchset/tang.

Installing and hardening a Tang server

The Tang server is intentionally tiny, a socket-activated systemd service that handles two HTTP endpoints. On Ubuntu 24.04 or Debian 12, install and enable it:

# Ubuntu 24.04 / Debian 12
sudo apt update
sudo apt install -y tang
sudo systemctl enable --now tangd.socket

# RHEL 9/10, Rocky, AlmaLinux, Fedora 41+
sudo dnf install -y tang
sudo systemctl enable --now tangd.socket
sudo firewall-cmd --add-port=80/tcp --permanent
sudo firewall-cmd --reload

By default Tang listens on port 80. For anything outside a lab, terminate TLS in front of it (nginx or HAProxy) and bind Tang to localhost. Although the JOSE exchange is itself secure without TLS, plaintext HTTP leaks which clients are unlocking against which Tang server, a useful signal for anyone mapping your data centre.

# /etc/systemd/system/tangd.socket.d/override.conf
[Socket]
ListenStream=
ListenStream=127.0.0.1:7500

Then a minimal nginx terminator on port 443 with a real ACME certificate, restricted to your management VLAN with nftables. For deeper guidance on the firewall layer, see our nftables firewall hardening guide.

The signing material lives in /var/db/tang/ as JWK files. Back this directory up once after first start, then treat it as immutable until rotation. If you lose it, every client bound to this server stops booting.

# Verify the server is advertising correctly
curl -s http://tang.lab.example/adv | jq .
sudo ls -la /var/db/tang/
# Two files: <thumbprint>.jwk for exchange, <thumbprint>.jwk for signing

Binding a LUKS2 volume to Tang with Clevis

On each client, install Clevis with the LUKS and dracut (or initramfs-tools) glue, then bind an existing LUKS2 keyslot to your Tang server. The Clevis project at github.com/latchset/clevis tracks pin development.

# Ubuntu 24.04
sudo apt install -y clevis clevis-luks clevis-initramfs

# RHEL 9/10, Fedora 41+
sudo dnf install -y clevis clevis-luks clevis-dracut

# Bind keyslot to a single Tang server
sudo clevis luks bind -d /dev/nvme0n1p3 tang \
  '{"url":"https://tang.lab.example"}'

# You will be prompted for an EXISTING LUKS passphrase. Clevis adds a
# new keyslot wrapped with the Tang-derived key. It does not remove
# your recovery passphrase. Always keep at least one keyslot you
# can type by hand.

# Confirm
sudo clevis luks list -d /dev/nvme0n1p3

For Ubuntu, regenerate the initramfs so Clevis is invoked early in boot before cryptsetup asks for the passphrase:

sudo update-initramfs -u -k all
# On Fedora/RHEL the clevis-dracut module is wired automatically:
sudo dracut -f

Add the LUKS device to /etc/crypttab with the _netdev option so systemd waits for the network in initramfs:

# /etc/crypttab
nvme0n1p3_crypt UUID=<your-uuid> none luks,discard,_netdev

Reboot. The first network interface comes up via systemd-networkd in the initramfs, Clevis dials Tang, retrieves the recovery point, unwraps the keyslot, and the system continues without ever prompting. Boot time overhead is typically under one second on a healthy LAN.

Threshold binding: combining Tang, TPM2, and SSS

Single-pin Tang is a single point of failure. The correct production pattern is Clevis's sss (Shamir Secret Sharing) pin, which splits the key into n shares and requires t of them to reconstruct. Two common topologies:

Two-of-three Tang (high availability):

sudo clevis luks bind -d /dev/nvme0n1p3 sss '{
  "t": 2,
  "pins": {
    "tang": [
      {"url":"https://tang-a.dc1.example"},
      {"url":"https://tang-b.dc1.example"},
      {"url":"https://tang-c.dc2.example"}
    ]
  }
}'

Any two of the three Tang servers must be reachable for unlock. One Tang down for maintenance? Boots fine. One stolen Tang plus one stolen disk? Still insufficient, because the attacker also needs a second Tang.

TPM + Tang (defence in depth):

sudo clevis luks bind -d /dev/nvme0n1p3 sss '{
  "t": 2,
  "pins": {
    "tpm2": [{"pcr_bank":"sha256","pcr_ids":"0,2,4,7"}],
    "tang": [{"url":"https://tang.lab.example"}]
  }
}'

Now the disk only unlocks if the TPM measurements match (Secure Boot intact, kernel unmodified) and Tang is reachable. Move the disk to another chassis: TPM check fails. Take the chassis off-net: Tang fails. Both have to succeed, and the threshold is enforced inside Clevis, not on the wire. For a deep dive on TPM2-only unlock and Secure Boot measurement, see our LUKS2, TPM2, and FIDO2 full disk encryption guide.

Tang vs TPM2 vs FIDO2: when to use which

The three Clevis pin families solve different problems. Picking the wrong one is the most common NBDE design mistake (I've watched a team bind 200 laptops to a single internal Tang and then wonder why every airport boot stalled).

Property	Tang (NBDE)	TPM2	FIDO2
Unattended boot	Yes	Yes	No (user touch)
Survives motherboard swap	Yes	No (PCRs differ)	Yes
Defeated by network theft	No (off-net = no unlock)	Yes (TPM travels with disk)	No
Requires extra hardware	No	TPM 2.0 chip	Hardware key (e.g. YubiKey)
Best for	Headless server fleets	Laptops, single hosts	Workstations, admin terminals
Failure mode	Tang outage = boot hang	Firmware change = boot hang	Lost key = boot hang
Available since	Clevis 7 (2018)	Clevis 12 (2020)	systemd-cryptenroll (2021)

The shorthand: servers use Tang (often plus TPM via SSS), laptops use TPM2 (because they move and are often offline), privileged workstations use FIDO2 (because human presence is the policy). FIDO2 is configured via systemd-cryptenroll rather than Clevis and is outside the NBDE flow entirely.

Rotating Tang signing keys safely

Tang's signing keys should be rotated annually, or immediately after any suspected compromise of the server. The rotation is a two-phase process, and skipping the wait between phases will lock clients out of boot. Red Hat's policy-based decryption documentation codifies the exact procedure.

# Phase 1: generate new keys, mark the old ones inactive but still
#          present on disk. New advertisements use new keys; existing
#          bindings still verify against the old.
sudo /usr/libexec/tangd-rotate-keys -d /var/db/tang

# Phase 2 (DO NOT RUN YET): permanent deletion of old keys
# Wait until every client has re-bound. Push a config-management job:
ansible all -m shell -a "clevis luks regen -d /dev/nvme0n1p3 -s 2"

# Verify on every host that regen succeeded BEFORE deleting old keys.

# Phase 3: only after fleet-wide re-bind is confirmed
sudo rm /var/db/tang/.<old-thumbprint>.jwk
sudo systemctl restart tangd.socket

The hidden files (note the leading dot after tangd-rotate-keys runs) are the deactivated old keys. Tang will still answer recovery requests against them but will not advertise them to new clients. That's what gives you a safe rollover window.

Wire this into your normal compliance audit cadence. If you already track other security controls with auditd, our auditd rules and SIEM integration guide covers the SIEM-side capture of rotation events.

Troubleshooting boot failures and timeouts

NBDE failures almost always trace to one of four causes. Drop to a recovery shell (or the LUKS passphrase prompt) and work through them. I've hit each of these in production at least once, usually at the worst possible time.

Network not up in initramfs

Clevis dials Tang before user-space networking is available. Confirm the initramfs includes a working systemd-networkd config, and that the kernel boots with a static IP or DHCP on the right interface:

# Inspect what's actually in your initramfs
sudo lsinitramfs /boot/initrd.img-$(uname -r) | grep -E 'network|clevis|tang'

# Force a usable network in the initramfs
sudo cp /etc/systemd/network/*.network /etc/initramfs-tools/etc/systemd/network/
sudo update-initramfs -u

Tang advertisement thumbprint changed

If Tang was reinstalled or its /var/db/tang was wiped, the advertised thumbprint no longer matches what's in the LUKS header and Clevis refuses on principle (correctly, since this is a downgrade attack defence). Either restore the old /var/db/tang from backup, or unbind and re-bind every client.

Firewall blocking initramfs traffic

Production firewalls often allow port 80/443 only from specific subnets. The initramfs may pick a different source IP than the full system (e.g. a different bond interface comes up first). Allow your management subnet broadly, or pin the initramfs network config.

PCR drift on the TPM SSS pin

If you combined Tang with TPM2 via SSS and PCR 8 or 9 (boot loader configuration) changed, TPM unsealing fails and SSS fails to meet threshold even if Tang answered. Boot once with the recovery passphrase and run clevis luks regen to re-measure.

Production hardening checklist

NBDE is necessary but not sufficient. Layer these controls before declaring a fleet production-ready:

1. Secure Boot enforced on every client, with the tpm2 pin included in SSS. Otherwise an attacker can boot a malicious initramfs that ignores the LUKS header.
2. IMA appraisal on the rootfs so a modified Tang binary on the server can't quietly leak the exchange. See our IMA and EVM file integrity guide.
3. Tang behind TLS, on a private VLAN, with nftables restricting source IPs to the encrypted-host subnet.
4. At least three Tang servers, in at least two failure domains, behind sss threshold 2.
5. Recovery passphrase kept in a hardware-backed password vault (not the same Vault that depends on these encrypted servers for storage).
6. Annual key rotation, audited via auditd and a SIEM, with a maintenance-window playbook.
7. Monitoring: alert on Tang 5xx rates, unusual source IPs hitting /rec/, or HMAC failures. These indicate either a misconfigured client or an active probe.
8. Disaster recovery rehearsal: at least once a year, prove you can unlock a disk using only the recovery passphrase, with all Tang servers offline.

Frequently Asked Questions

What is Tang and Clevis used for?

Tang and Clevis implement Network-Bound Disk Encryption on Linux, letting LUKS2-encrypted volumes auto-unlock at boot when the server can reach a trusted Tang service. They're used on headless servers, Kubernetes worker nodes, and edge appliances where typing a passphrase isn't practical but a stolen disk must remain unreadable off-network.

Is Tang encryption secure if the server is on the same network as the clients?

Yes. Tang's security model assumes co-location. The threat NBDE defends against is a disk leaving the trusted network (stolen, RMA'd, or decommissioned). On the trusted network the Tang exchange is still safe because Tang never sees the LUKS passphrase; the key is derived ephemerally per boot using ECDH. Pair it with TLS to prevent traffic analysis.

Can I use Tang and TPM2 together for stronger protection?

Yes, and you should. Use Clevis's sss pin with threshold 2, one TPM2 sub-pin and one Tang sub-pin. The disk unlocks only when both the local TPM measurements match (Secure Boot intact) and the Tang server is reachable. That defeats both off-network theft and on-network firmware tampering.

What happens if my Tang server goes offline?

With a single-Tang binding, clients hang at boot waiting for the LUKS prompt. You can recover by typing the recovery passphrase. With sss threshold-of-N Tang servers, any single Tang outage is invisible to clients. Always deploy at least three Tang servers behind sss t=2 for production.

How is Tang different from a KMS like HashiCorp Vault Transit?

Tang is stateless and zero-trust by design: it stores no per-client data and cannot be tricked into releasing past keys, because keys are derived rather than retrieved. A KMS like Vault stores and releases secrets, requires authentication, and depends on backing storage. NBDE is purpose-built for early-boot disk unlock; Vault is purpose-built for runtime application secrets. They are complementary, not interchangeable.