docs/devel/luks-detached-header.rst

2 LUKS volume with detached header
9 header and how to use it.
14 The LUKS format has ability to store the header in a separate volume from
24  disk    | header  |  key material  |  disk payload data |
28 With a detached LUKS header, you need 2 disks so getting:
33  disk1   |   header  | key material |
42              volume since there's no header
48              to the header to a designated host
51                  add encryption.You can store the LUKS header
54  * Recovery - corruption of a bit in the header may make the
56               convenient to take backups of the header. If
57               your primary disk header becomes corrupt, you
59               backup detached header
65 LUKS volume with detached header is shown in the diagram below.
67 There are two children of the root node: a file and a header.
69 LUKS header and key material are located in the header node,
78                      file |                header |
81   Child node   |payload-format[qcow2]|    |header-format[raw]|
87   Child node   |payload-protocol[file]|  |header-protocol[file]|
97 Create a LUKS disk with a detached header using qemu-img
104     -o detached-header=true test-header.img
107     "test-payload.img"},"header":{"filename":"test-header.img"}}'
109 Set up a VM's LUKS volume with a detached header
117     -blockdev '{"driver":"file","filename":"/path/to/test-header.img", \
126     "file":"libvirt-2-format","header":"libvirt-1-format","key-secret": \
131 Add LUKS volume to a VM with a detached header
135    LUKS header above::
141 2. block-add the protocol node for LUKS header::
145       "filename": "/path/to/test-header.img" }}'
147 3. block-add the raw-drived node for LUKS header::
166    with the LUKS header by specifying the field "header"::
170       "file":"libvirt-2-format", "header":"libvirt-1-format", \
182 1. Support the shared detached LUKS header within the VM.