CRYPTSETUP-SSH(8)

📦
version 2.8.7 · 13 versions
, in ubuntu stonking

✨ CRYPTSETUP-SSH ✨

okay so bestie, you've stumbled into the cryptsetup-ssh section of the manual (that's section 8, maintenance commands, iykyk) and honestly? you're gonna slay this. let's go 💅

🌸 NAME 🌸

cryptsetup-ssh — literally the tool that manages the LUKS2 SSH token. that's it. that's the whole name. periodt.

🎀 SYNOPSIS 🎀

cryptsetup-ssh <action> [<options>] <action args>

that's the shape of it: an action, then some optional options, then whatever args that action wants. easy ✨

🦋 DESCRIPTION 🦋

so this is an experimental cryptsetup plugin, right? its whole vibe is unlocking LUKS2 devices using a token that lives on an SSH server. yes, like over there on the remote machine. networking + disk encryption, iconic combo 🔥

Heads up though — right now this plugin only lets you add a token to an existing keyslot. that's it. if you wanna remove, import, or export the token, go read cryptsetup(8), it's got the instructions 🫶

🌈 Add operation 🌈

add <options> <device>

this adds the SSH token to <device>. super straightforward.

the SSH server you point at must have a key file sitting on the path you give it, and that file contains a passphrase for an existing keyslot on your device. then cryptsetup grabs those credentials and uses them to get the password when it opens the device with the token. cute, right? 💖

the options --ssh-server, --ssh-user, --ssh-keypath and --ssh-path are required for this operation. like, non-negotiable. all four. no cap 🙈

⭐ OPTIONS ⭐

okay here's the full list, no skipping, every single one is coming with us 🧚

  • --debug — shows you the debug messages. the receipts, basically.
  • --debug-json — same debug energy but with JSON metadata included. for the data girlies 📊
  • --help, -? — shows the help. be nice to it and it'll be nice to you.
  • --key-slot number — which keyslot the token gets assigned to. if you don't specify one, it picks the first keyslot that matches the passphrase you gave it. auto-pilot mode ✨
  • --ssh-keypath string — the path to the SSH key used for connecting to the remote server.
  • --ssh-path string — the path to the key file on the remote server. (yes, different path, different machine, keep up bestie 💀)
  • --ssh-server string — the IP address / URL of the remote server this token is about.
  • --ssh-user string — the username you use on the remote server.
  • --verbose, -v — shows more detailed error messages. for when you need to know exactly what went wrong 😭
  • --version, -V — prints the program version. trivia time 🎀

💜 NOTES 💜

okay this is the important one, so listen up: the info you provide when adding the token — the SSH server address, the user, and the paths — gets stored in the LUKS2 header in plaintext. like, plaintext plaintext. not encrypted, not hidden, just vibing there unencrypted. no cap, plan accordingly 🙈

👑 AUTHORS 👑

the cryptsetup-ssh tool is written by Vojtech Trefny. thank you for your service 🫡💖

🔥 REPORTING BUGS 🔥

found a bug? don't suffer in silence, report it:

and bestie, please attach the output of the failed command with the --debug option added. it's giving "help me help you" and it genuinely makes everything faster 🫶

🌟 SEE ALSO 🌟

🧚 CRYPTSETUP 🧚

this is part of the cryptsetup project, over at <https://gitlab.com/cryptsetup/cryptsetup/>. main character energy, honestly 🌈

and that's the whole page, bestie! this was cryptsetup-ssh version 2.8.7, dated 2026-09-12 — go forth and unlock things 💅✨🦋

📦 where this page comes from