#1152515 cryptsetup: The man page does not adequately explain the initramfs option for swap

Package:
cryptsetup
Source:
cryptsetup
Description:
disk encryption support - startup scripts
Submitter:
Russell Coker
Date:
2026-10-30 08:39:04 UTC
Severity:
normal
#1152515#5
Date:
2026-10-30 04:45:00 UTC
From:
To:
In Trixie x-initrd.attach is the way to autostart encrypted swap on boot.
That doesn't work on current Testing and all the documentation returned by
web searches refers to the old way to do it.

I think there needs to be a mention in the crypttab(5) man page that
x-initrd.attach is no longer supported and the examples section needs to
have a line about swap containing the "initramfs" option.  I believe that
x-initrd.attach was never parsed by code in the cryptsetup package (I coould
be mistaken) but I still think it's a good place to document this as it's
where people will look.

Also it might be worth having the cryptdisks_start script give a warning about
x-initrd.attach when run from the command-line.

One could argue that the bug is in not supporting Trixie syntax, I don't have
strong feelings on this, as long as man pages clearly describe what happens
and for this sort of case I can copy a line from the man page and have it work
after changing the device name I'll be happy.

https://wiki.debian.org/Swap

I have added a section to the Wiki about this which will hopefully save time
for some people.  I literally spent hours investigating this and installed a
new test machine for the sole purpose of discovering how to do it only to find
that Testing and Trixie work differently.

As an aside I ended up getting the answer from ChatGPT after numerous web
searches failed to get the right answer.

There are many ways to alleviate the problems this change will cause people
and I think we should have at least a couple of actions taken to address it.

PS None of this bug report was from ChatGPT, all I got from it was one single
keyword to use and after that I did it all myself.

#1152515#10
Date:
2026-10-30 08:36:03 UTC
From:
To:
Trixie's default initrd is initramfs-tools which is what
cryptsetup-initramfs configures and what crypttab(5) from src:cryptsetup
is about.  This does not use x-initrd.attach at all.  The manual also
points to systemd's own crypttab(5) where x-initrd.attach is documented.

FWIW, your suggestion

    sda3_crypt /dev/sda3 /dev/urandom …,swap,…,initramfs

is specific to cryptsetup-initramfs, dracut will ignore the keyword
AFAICT.  This might be what you inteded, but since you have a transient
swap there is no need to start it early in the boot process.  You can
remove the `initramfs` keyword and let systemd do it later once
execution has been handed over to it.

    sda3_crypt /dev/sda3 /dev/urandom plain,discard,cipher=aes-xts-plain64,size=256,swap

This works on forky/sid as well as trixie and earlier.

I'm closing this because /usr/share/doc/cryptsetup/README.Debian.gz has
a section about encrypted swap already, which is also available online at
https://cryptsetup-team.pages.debian.net/cryptsetup/README.Debian.html#encrypted-swap-partitions
(And /usr/share/doc/cryptsetup-initramfs/README.initramfs.gz has a
section for non-transient swap partitions.)