Модуль community.crypto.luks_device — управление зашифрованными устройствами (LUKS)

Примечание

Этот модуль входит в коллекцию community.crypto (версия 3.2.1).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.

Для установки используйте: ansible-galaxy collection install community.crypto. Для работы с этим модулем требуются дополнительные компоненты. Подробнее см. в разделе Требования.

Чтобы использовать модуль в плейбуке, укажите: community.crypto.luks_device.

Краткое описание
Требования
Параметры
Атрибуты
Примеры
Возвращаемые значения

Краткое описание

Модуль управляет LUKS на указанном устройстве. Поддерживает создание, уничтожение, открытие и закрытие контейнера LUKS, а также добавление и удаление ключей и парольных фраз.

Требования

На узле, выполняющем этот модуль, должны быть установлены следующие компоненты.

cryptsetup
wipefs (если state имеет значение absent)
lsblk
blkid (если используются параметры label или uuid)
systemd-cryptsetup (только для TPM2)

Параметры

Параметр	Комментарии
allow_discards boolean добавлено в community.crypto 2.17.0	Разрешает запросы на отбрасывание блоков (также известные как TRIM) для устройства. Используется только при открытии контейнеров. Варианты: `false` ← (по умолчанию) `true`
cipher string добавлено в community.crypto 1.1.0	Этот параметр позволяет пользователю задать строку спецификации шифра для контейнера LUKS. Используется только при создании контейнера. Для ядер до версии 2.6.10 используйте `aes-plain`, поскольку они не распознают новые строки спецификации шифра. Чтобы использовать ESSIV, используйте `aes-cbc-essiv:sha256`.
device string	Устройство для работы (например, `/dev/sda1`). Требуется в большинстве случаев. Можно опустить только в том случае, если указаны `state=closed` и `name`.
force_remove_last_key boolean	Если установлено значение `true`, разрешает удаление последнего ключа из контейнера. ВНИМАНИЕ: после удаления последнего ключа из контейнера его больше нельзя будет открыть! Варианты: `false` ← (по умолчанию) `true`
hash string добавлено в community.crypto 1.1.0	Этот параметр позволяет пользователю указать хеш-функцию, используемую в схеме настройки ключей LUKS и для дайджеста ключа тома. Используется только при создании контейнера.
keyfile path	Используется для разблокировки контейнера. Для большинства операций требуется либо `keyfile`, либо `passphrase`. Значение параметра — путь к файлу ключа с парольной фразой. ВНИМАНИЕ: работа с файлами ключей в открытом виде опасна. Убедитесь, что они защищены.
keysize integer добавлено в community.crypto 1.0.0	Задает размер ключа, только если контейнер LUKS не существует.
keyslot integer добавлено в community.crypto 2.16.0	Добавляет `keyfile` или `passphrase` в указанный слот ключа при создании нового контейнера на `device`. Значение параметра — номер слота ключа. Задает слот ключа, приоритет которого будет изменен с помощью `keyslot_priority`. Примечание: устройство `type=luks1` поддерживает номера слотов ключей `0`-`7`, а устройство `type=luks2` — номера слотов ключей `0`-`31`. Чтобы использовать слоты ключей `8`-`31` при создании нового контейнера, необходимо установить для `type` значение `luks2`.
keyslot_priority string добавлено в community.crypto 3.1.0	Задает приоритет слота ключа, указанного с помощью `keyslot`. Примечание: приоритет слота ключа поддерживается только для контейнеров LUKS2. Варианты: `"prefer"` `"normal"` `"ignore"`
label string добавлено в community.crypto 1.0.0	Этот параметр позволяет пользователю создать контейнер в формате LUKS2 с поддержкой меток, чтобы впоследствии идентифицировать контейнер по метке. Используется только при создании контейнера или если `device` не указан. Этот параметр нельзя указать, если для `type` задано значение `luks1`.
name string	Задает имя контейнера при `state=opened`. При закрытии существующего контейнера (то есть при `state=closed`) можно использовать вместо `device`.
new_keyfile path	Добавляет дополнительный ключ в указанный контейнер при `device`. Для авторизации требуется параметр `keyfile` или `passphrase`. Контейнер LUKS поддерживает до 8 слотов ключей. Значение параметра — путь к файлу ключа с парольной фразой. ПРИМЕЧАНИЕ: добавление дополнительных ключей является идемпотентным только начиная с community.crypto 1.4.0. В более ранних версиях используется новый слот ключа, даже если для этого файла ключа уже существует другой слот. ВНИМАНИЕ: работа с файлами ключей в открытом виде опасна. Убедитесь, что они защищены.
new_keyslot integer добавлено в community.crypto 2.16.0	Добавляет дополнительный `new_keyfile` или `new_passphrase` в указанный слот ключа для данного `device`. Значение параметра — номер слота ключа. Примечание: устройство `type=luks1` поддерживает номера слотов ключей `0`-`7`, а устройство `type=luks2` — номера слотов ключей `0`-`31`.
new_passphrase string добавлено в community.crypto 1.0.0	Добавляет дополнительную парольную фразу в указанный контейнер при `device`. Для авторизации требуется параметр `keyfile` или `passphrase`. Контейнер LUKS поддерживает до 8 слотов ключей. Значение параметра — строка с новой парольной фразой. ПРИМЕЧАНИЕ: добавление дополнительных парольных фраз является идемпотентным только начиная с community.crypto 1.4.0. В более ранних версиях используется новый слот ключа, даже если для этой парольной фразы уже существует другой слот. Примечание: парольная фраза должна быть текстом в кодировке UTF-8. Чтобы использовать произвольные двоичные данные или текст в другой кодировке, воспользуйтесь параметром `passphrase_encoding` и укажите парольную фразу в кодировке Base64.
new_tpm2 string добавлено в community.crypto 3.1.0	Добавляет микросхему безопасности TPM2 в указанный контейнер при `device`. Ожидается путь к узлу устройства, указывающий на микросхему TPM2 (например, `/dev/tpmrm0`). Также можно указать специальное значение `auto`, чтобы автоматически определить узел устройства для обнаруженного в данный момент устройства TPM2 (такое устройство должно быть ровно одно). Требуется `new_tpm2_pcrs`. Примечание: `new_keyslot` не влияет на слот ключа для регистрации TPM2. Примечание: поддерживаются только контейнеры LUKS2. Примечание: требуется systemd-cryptsetup (v248 или новее).
new_tpm2_pcrs string добавлено в community.crypto 3.1.0	Регистры PCR TPM2 (регистры конфигурации платформы), с которыми следует связать устройство. Подробности см. в документации systemd-cryptenroll (аргумент `--tpm2-pcrs`).
passphrase string добавлено в community.crypto 1.0.0	Используется для разблокировки контейнера. Для большинства операций требуется либо `passphrase`, либо `keyfile`. Значение параметра — строка с парольной фразой. Примечание: парольная фраза должна быть текстом в кодировке UTF-8. Чтобы использовать произвольные двоичные данные или текст в другой кодировке, воспользуйтесь параметром `passphrase_encoding` и укажите парольную фразу в кодировке Base64.
passphrase_encoding string добавлено в community.crypto 2.23.0	Определяет способ передачи парольных фраз в такие параметры, как `passphrase`, `new_passphrase` и `remove_passphrase`. Варианты: `"base64"`: парольная фраза передается в виде байтов, закодированных в Base64. Используйте фильтр ansible.builtin.b64encode, чтобы закодировать двоичные данные в Base64. `"text"` (по умолчанию): парольная фраза передается в виде текста в кодировке UTF-8.
pbkdf dictionary добавлено в community.crypto 1.4.0	Этот параметр позволяет пользователю настроить используемую функцию формирования ключа на основе пароля (PBKDF). Используется только при создании контейнера и добавлении ключей в существующий контейнер.
algorithm string	Используемый алгоритм. Доступно только для формата LUKS 2. Варианты: `"argon2i"` `"argon2id"` `"pbkdf2"`
iteration_count integer	Задает количество итераций, используемое для PBKDF. Взаимоисключающий параметр с `pbkdf.iteration_time`.
iteration_time float	Задает время итераций, используемое для PBKDF. Обратите внимание: значение указывается в секундах, а не в миллисекундах, как в командной строке. Взаимоисключающий параметр с `pbkdf.iteration_count`.
memory integer	Ограничение затрат памяти для PBKDF в килобайтах. Не используется для PBKDF2, а применяется только для вариантов PBKDF на основе Argon.
parallel integer	Затраты на параллельное выполнение PBKDF. Это количество потоков, работающих параллельно. Не используется для PBKDF2, а применяется только для вариантов PBKDF на основе Argon.
perf_no_read_workqueue boolean добавлено в community.crypto 2.3.0	Позволяет пользователю обходить внутреннюю очередь работ dm-crypt и обрабатывать запросы на чтение синхронно. Используется только при открытии контейнеров. Варианты: `false` ← (по умолчанию) `true`
perf_no_write_workqueue boolean добавлено в community.crypto 2.3.0	Позволяет пользователю обходить внутреннюю очередь работ dm-crypt и обрабатывать запросы на запись синхронно. Используется только при открытии контейнеров. Варианты: `false` ← (по умолчанию) `true`
perf_same_cpu_crypt boolean добавлено в community.crypto 2.3.0	Позволяет пользователю выполнять шифрование на том же процессоре, на котором была отправлена операция ввода-вывода. По умолчанию используется не привязанная к процессору очередь работ, чтобы автоматически распределять задачи шифрования между доступными процессорами. Используется только при открытии контейнеров. Варианты: `false` ← (по умолчанию) `true`
perf_submit_from_crypt_cpus boolean добавлено в community.crypto 2.3.0	Позволяет пользователю отключить передачу операций записи в отдельный поток после шифрования. В некоторых ситуациях передача операций блочного ввода-вывода на запись из потоков шифрования в один поток значительно снижает производительность. По умолчанию операции блочного ввода-вывода на запись передаются в тот же поток. Используется только при открытии контейнеров. Варианты: `false` ← (по умолчанию) `true`
persistent boolean добавлено в community.crypto 2.3.0	Позволяет пользователю сохранять параметры в метаданных контейнера и автоматически использовать их при следующем запуске. Постоянно сохранять можно только `perf_same_cpu_crypt`, `perf_submit_from_crypt_cpus`, `perf_no_read_workqueue`, `perf_no_write_workqueue` и `allow_discards`. Работает только с контейнерами LUKS2. Используется только при открытии контейнеров. Варианты: `false` ← (по умолчанию) `true`
remove_keyfile path	Удаляет указанный ключ из контейнера при `device`. Файл ключа в файловой системе не удаляется. Значение параметра — путь к файлу ключа с парольной фразой. ПРИМЕЧАНИЕ: удаление ключей является идемпотентным только начиная с community.crypto 1.4.0. В более ранних версиях попытка удалить несуществующий ключ приводит к ошибке. ПРИМЕЧАНИЕ: чтобы удалить последний ключ из контейнера LUKS, для параметра `force_remove_last_key` необходимо установить значение `true`. ВНИМАНИЕ: работа с файлами ключей в открытом виде опасна. Убедитесь, что они защищены.
remove_keyslot integer добавлено в community.crypto 2.16.0	Удаляет ключ в указанном слоте при `device`. Для авторизации требуется `keyfile` или `passphrase`. Примечание: устройство `type=luks1` поддерживает номера слотов ключей `0`-`7`, а устройство `type=luks2` — номера слотов ключей `0`-`31`. Примечание: указанный `keyfile` или `passphrase` не должен находиться в удаляемом слоте.
remove_passphrase string добавлено в community.crypto 1.0.0	Удаляет указанную парольную фразу из контейнера при `device`. Значение параметра — строка с удаляемой парольной фразой. ПРИМЕЧАНИЕ: удаление парольных фраз является идемпотентным только начиная с community.crypto 1.4.0. В более ранних версиях попытка удалить уже отсутствующую парольную фразу приводит к ошибке. ПРИМЕЧАНИЕ: чтобы удалить последний слот ключа из контейнера LUKS, для параметра `force_remove_last_key` необходимо установить значение `true`. Примечание: парольная фраза должна быть текстом в кодировке UTF-8. Чтобы использовать произвольные двоичные данные или текст в другой кодировке, воспользуйтесь параметром `passphrase_encoding` и укажите парольную фразу в кодировке Base64.
remove_tpm2 boolean добавлено в community.crypto 3.1.0	Удаляет все слоты ключей на `device`, которые разблокируются устройством TPM2. Для авторизации требуется `keyfile`, `passphrase` или `tpm2_device`. Примечание: требуется systemd-cryptsetup (v248 или новее). Примечание: не следует использовать `tpm2_device` для авторизации удаления всех слотов TPM2, чтобы убедиться, что после этого доступ к контейнеру сохранится. Варианты: `false` ← (по умолчанию) `true`
sector_size integer добавлено в community.crypto 1.5.0	Этот параметр позволяет пользователю указать размер сектора (в байтах), используемый для контейнеров LUKS2. Используется только при создании контейнера.
state string	Желаемое состояние контейнера LUKS. В зависимости от значения создает, уничтожает, открывает или закрывает контейнер LUKS на указанном устройстве. `present` создает контейнер LUKS, если он еще не существует. Требуются `device` и один из параметров: `keyfile` или `passphrase`. `absent` удаляет существующий контейнер LUKS, если он есть. Необходимо указать `device` или `name`. `opened` разблокирует контейнер LUKS. Необходимо указать `device` и один из параметров: `keyfile`, `passphrase` или `tpm2_device`. Если контейнер не существует, сначала он будет создан, однако для создания нельзя использовать `tpm2_device`. Используйте параметр `name`, чтобы задать имя открытого контейнера. В противном случае имя будет сгенерировано автоматически и возвращено в составе результата. `closed` блокирует контейнер LUKS. Однако если контейнер не существует, он будет создан. Требуются `device` и один из параметров: `keyfile` или `passphrase`. Если контейнер уже существует, достаточно указать `device` или `name`. Варианты: `"present"` ← (по умолчанию) `"absent"` `"opened"` `"closed"`
tpm2_device string добавлено в community.crypto 3.1.0	Используется для разблокировки контейнера, но не может использоваться для его создания. Путь к узлу устройства, указывающий на микросхему TPM2 (например, `/dev/tpmrm0`). Также можно указать специальное значение `auto`, чтобы автоматически определить узел устройства для обнаруженного в данный момент устройства TPM2 (такое устройство должно быть ровно одно). Примечание: поддерживаются только контейнеры LUKS2. Примечание: требуется systemd-cryptsetup (v256 или новее).
type string добавлено в community.crypto 1.0.0	Этот параметр позволяет пользователю явно задать формат контейнера LUKS, с которым нужно работать. Возможные значения: `luks1` или `luks2`. Варианты: `"luks1"` `"luks2"`

uuid

string

добавлено в community.crypto 1.0.0

С помощью этого параметра пользователь может определить контейнер LUKS по UUID.

Используется только в том случае, если device и label не указаны.

Атрибуты

Атрибут	Поддержка	Описание
check_mode	Поддержка: полная	Может работать в режиме `check_mode` и возвращать прогноз изменения статуса без внесения изменений в целевой объект.
diff_mode	Поддержка: отсутствует	В режиме diff возвращает сведения об изменениях (или о возможных изменениях в `check_mode`).
idempotent	Поддержка: полная	При повторном запуске с теми же аргументами вне режима проверки второй вызов указывает на отсутствие изменений. Предполагается, что система, контролируемая или запрашиваемая модулем, не изменилась существенным образом.

Примеры

---
- name: Create LUKS container (remains unchanged if it already exists)
  community.crypto.luks_device:
    device: "/dev/loop0"
    state: "present"
    keyfile: "/vault/keyfile"

- name: Create LUKS container with a passphrase
  community.crypto.luks_device:
    device: "/dev/loop0"
    state: "present"
    passphrase: "foo"

- name: Create LUKS container with specific encryption
  community.crypto.luks_device:
    device: "/dev/loop0"
    state: "present"
    cipher: "aes"
    hash: "sha256"

- name: (Create and) open the LUKS container; name it "mycrypt"
  community.crypto.luks_device:
    device: "/dev/loop0"
    state: "opened"
    name: "mycrypt"
    keyfile: "/vault/keyfile"

- name: Close the existing LUKS container "mycrypt"
  community.crypto.luks_device:
    state: "closed"
    name: "mycrypt"

- name: Make sure LUKS container exists and is closed
  community.crypto.luks_device:
    device: "/dev/loop0"
    state: "closed"
    keyfile: "/vault/keyfile"

- name: Create container if it does not exist and add new key to it
  community.crypto.luks_device:
    device: "/dev/loop0"
    state: "present"
    keyfile: "/vault/keyfile"
    new_keyfile: "/vault/keyfile2"

- name: Add new key to the LUKS container (container has to exist)
  community.crypto.luks_device:
    device: "/dev/loop0"
    keyfile: "/vault/keyfile"
    new_keyfile: "/vault/keyfile2"

- name: Add new passphrase to the LUKS container
  community.crypto.luks_device:
    device: "/dev/loop0"
    keyfile: "/vault/keyfile"
    new_passphrase: "foo"

- name: Remove existing keyfile from the LUKS container
  community.crypto.luks_device:
    device: "/dev/loop0"
    remove_keyfile: "/vault/keyfile2"

- name: Remove existing passphrase from the LUKS container
  community.crypto.luks_device:
    device: "/dev/loop0"
    remove_passphrase: "foo"

- name: Completely remove the LUKS container and its contents
  community.crypto.luks_device:
    device: "/dev/loop0"
    state: "absent"

- name: Create a container with label
  community.crypto.luks_device:
    device: "/dev/loop0"
    state: "present"
    keyfile: "/vault/keyfile"
    label: personalLabelName

- name: Open the LUKS container based on label without device; name it "mycrypt"
  community.crypto.luks_device:
    label: "personalLabelName"
    state: "opened"
    name: "mycrypt"
    keyfile: "/vault/keyfile"

- name: Close container based on UUID
  community.crypto.luks_device:
    uuid: 03ecd578-fad4-4e6c-9348-842e3e8fa340
    state: "closed"
    name: "mycrypt"

- name: Create a container using luks2 format
  community.crypto.luks_device:
    device: "/dev/loop0"
    state: "present"
    keyfile: "/vault/keyfile"
    type: luks2

- name: Create a container with key in slot 4
  community.crypto.luks_device:
    device: "/dev/loop0"
    state: "present"
    keyfile: "/vault/keyfile"
    keyslot: 4

- name: Add a new key in slot 5
  community.crypto.luks_device:
    device: "/dev/loop0"
    keyfile: "/vault/keyfile"
    new_keyfile: "/vault/keyfile"
    new_keyslot: 5

- name: Remove the key from slot 4 (given keyfile must not be slot 4)
  community.crypto.luks_device:
    device: "/dev/loop0"
    keyfile: "/vault/keyfile"
    remove_keyslot: 4

- name: Enroll a TPM2 device using a keyfile to unlock the container
  community.crypto.luks_device:
    keyfile: "/vault/keyfile"
    new_tpm2: "auto"
    new_tpm2_pcrs: "1+3+5+7+11+12+14"

- name: Remove all enrolled TPM2 devices
  community.crypto.luks_device:
    tpm2_device: "auto"
    remove_tpm2: true

- name: Set the priority of keyslot 0 to 'prefer'
  community.crypto.luks_device:
    device: "/dev/loop0"
    keyslot: 0
    keyslot_priority: prefer

Возвращаемые значения

Общие возвращаемые значения описаны здесь; ниже приведены поля, уникальные для этого модуля:

Ключ	Описание
name string	При `state=opened` возвращает имя контейнера LUKS (сгенерированное или заданное). Если имя не указано, возвращает None. Возвращается: при успешном выполнении Пример: `"luks-c1da9a58-2fde-4256-9d9f-6ab008b4dd1b"`

Авторы

Jan Pokorny (@japokorn)

Ссылки на коллекцию

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/crypto/luks_device_module.html