{
    "content": [
        {
            "type": "text",
            "text": "# systemd-cryptsetup (man)\n\n## NAME\n\nsystemd-cryptsetup@.service, systemd-cryptsetup - Full disk decryption logic\n\n## SYNOPSIS\n\nsystemd-cryptsetup@.service\nsystem-systemd\\x2dcryptsetup.slice\n/lib/systemd/systemd-cryptsetup\n\n## DESCRIPTION\n\nsystemd-cryptsetup@.service is a service responsible for setting up encrypted block devices.\nIt is instantiated for each device that requires decryption for access.\n\n## TLDR\n\n> Create or remove decrypted mappings of encrypted volumes. Equivalent of `cryptsetup open` and `cryptsetup close`.\n\n- Open a LUKS volume and create a decrypted mapping at `/dev/mapper/mapping_name`:\n  `systemd-cryptsetup attach {{mapping_name}} {{/dev/sdXY}}`\n- Open a LUKS volume with additional options and create a decrypted mapping at `/dev/mapper/mapping_name`:\n  `systemd-cryptsetup attach {{mapping_name}} {{/dev/sdXY}} none {{crypttab_options}}`\n- Open a LUKS volume with a keyfile and create a decrypted mapping at `/dev/mapper/mapping_name`:\n  `systemd-cryptsetup attach {{mapping_name}} {{/dev/sdXY}} {{path/to/keyfile}} {{crypttab_options}}`\n- Remove an existing mapping:\n  `systemd-cryptsetup detach {{mapping_name}}`\n\n*Source: tldr-pages*\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **SEE ALSO**\n- **NOTES**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "systemd-cryptsetup",
        "section": "",
        "mode": "man",
        "summary": "systemd-cryptsetup@.service, systemd-cryptsetup - Full disk decryption logic",
        "synopsis": "systemd-cryptsetup@.service\nsystem-systemd\\x2dcryptsetup.slice\n/lib/systemd/systemd-cryptsetup",
        "tldr_summary": "Create or remove decrypted mappings of encrypted volumes. Equivalent of `cryptsetup open` and `cryptsetup close`.",
        "tldr_examples": [
            {
                "description": "Open a LUKS volume and create a decrypted mapping at `/dev/mapper/mapping_name`",
                "command": "systemd-cryptsetup attach {{mapping_name}} {{/dev/sdXY}}"
            },
            {
                "description": "Open a LUKS volume with additional options and create a decrypted mapping at `/dev/mapper/mapping_name`",
                "command": "systemd-cryptsetup attach {{mapping_name}} {{/dev/sdXY}} none {{crypttab_options}}"
            },
            {
                "description": "Open a LUKS volume with a keyfile and create a decrypted mapping at `/dev/mapper/mapping_name`",
                "command": "systemd-cryptsetup attach {{mapping_name}} {{/dev/sdXY}} {{path/to/keyfile}} {{crypttab_options}}"
            },
            {
                "description": "Remove an existing mapping",
                "command": "systemd-cryptsetup detach {{mapping_name}}"
            }
        ],
        "tldr_source": "official",
        "flags": [],
        "examples": [],
        "see_also": [
            {
                "name": "systemd",
                "section": "1",
                "url": "https://www.chedong.com/phpMan.php/man/systemd/1/json"
            },
            {
                "name": "systemd-cryptsetup-generator",
                "section": "8",
                "url": "https://www.chedong.com/phpMan.php/man/systemd-cryptsetup-generator/8/json"
            },
            {
                "name": "crypttab",
                "section": "5",
                "url": "https://www.chedong.com/phpMan.php/man/crypttab/5/json"
            },
            {
                "name": "systemd-cryptenroll",
                "section": "1",
                "url": "https://www.chedong.com/phpMan.php/man/systemd-cryptenroll/1/json"
            },
            {
                "name": "cryptsetup",
                "section": "8",
                "url": "https://www.chedong.com/phpMan.php/man/cryptsetup/8/json"
            }
        ],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 6,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 38,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "NOTES",
                "lines": 6,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "systemd-cryptsetup@.service, systemd-cryptsetup - Full disk decryption logic\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "systemd-cryptsetup@.service\n\nsystem-systemd\\x2dcryptsetup.slice\n\n/lib/systemd/systemd-cryptsetup\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "systemd-cryptsetup@.service is a service responsible for setting up encrypted block devices.\nIt is instantiated for each device that requires decryption for access.\n\nsystemd-cryptsetup@.service instances are part of the system-systemd\\x2dcryptsetup.slice\nslice, which is destroyed only very late in the shutdown procedure. This allows the encrypted\ndevices to remain up until filesystems have been unmounted.\n\nsystemd-cryptsetup@.service will ask for hard disk passwords via the password agent logic[1],\nin order to query the user for the password using the right mechanism at boot and during\nruntime.\n\nAt early boot and when the system manager configuration is reloaded, /etc/crypttab is\ntranslated into systemd-cryptsetup@.service units by systemd-cryptsetup-generator(8).\n\nIn order to unlock a volume a password or binary key is required.\nsystemd-cryptsetup@.service tries to acquire a suitable password or binary key via the\nfollowing mechanisms, tried in order:\n\n1. If a key file is explicitly configured (via the third column in /etc/crypttab), a key\nread from it is used. If a PKCS#11 token, FIDO2 token or TPM2 device is configured (using\nthe pkcs11-uri=, fido2-device=, tpm2-device= options) the key is decrypted before use.\n\n2. If no key file is configured explicitly this way, a key file is automatically loaded from\n/etc/cryptsetup-keys.d/volume.key and /run/cryptsetup-keys.d/volume.key, if present. Here\ntoo, if a PKCS#11/FIDO2/TPM2 token/device is configured, any key found this way is\ndecrypted before use.\n\n3. If the try-empty-password option is specified it is then attempted to unlock the volume\nwith an empty password.\n\n4. The kernel keyring is then checked for a suitable cached password from previous attempts.\n\n5. Finally, the user is queried for a password, possibly multiple times, unless the headless\noption is set.\n\nIf no suitable key may be acquired via any of the mechanisms describes above, volume\nactivation fails.\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "systemd(1), systemd-cryptsetup-generator(8), crypttab(5), systemd-cryptenroll(1),\ncryptsetup(8)\n",
                "subsections": []
            },
            "NOTES": {
                "content": "1. password agent logic\nhttps://systemd.io/PASSWORDAGENTS/\n\n\n\nsystemd 249                                                           SYSTEMD-CRYPTSETUP@.SERVICE(8)",
                "subsections": []
            }
        }
    }
}