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

Примечание

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

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

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

Для использования в playbook, укажите: community.crypto.luks_device.

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

Описание

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

Требования

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

cryptsetup
wipefs (когда state равно absent)
lsblk
blkid (когда используются опции label или uuid)

Параметры

Параметр	Комментарии
allow_discards boolean added in community.crypto 2.17.0	Разрешить запросы discards (также известные как TRIM) для устройства. Будет использоваться только при открытии контейнеров. Варианты: `false` ← (default) `true`
cipher string added in 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` ← (default) `true`
hash string added in community.crypto 1.1.0	Эта опция позволяет пользователю указать хэш-функцию, используемую в схеме настройки ключа LUKS и дайджесте ключа тома. Будет использоваться только при создании контейнера.
keyfile path	Используется для разблокировки контейнера. Для большинства операций необходим либо `keyfile`, либо `passphrase`. Значение параметра — путь к файлу ключа с парольной фразой. ВНИМАНИЕ: работа с файлами ключей в открытом тексте опасна. Убедитесь, что они защищены.
keysize integer added in community.crypto 1.0.0	Устанавливает размер ключа только если контейнер LUKS не существует.
keyslot integer added in community.crypto 2.16.0	Добавляет `keyfile` или `passphrase` в определенный слот ключей при создании нового контейнера на `device`. Значение параметра — номер слота ключей. Примечание: устройство `type=luks1` поддерживает номера слотов ключей `0`-`7`, а устройство `type=luks2` поддерживает номера слотов ключей `0`-`31`. Для использования слотов ключей `8`-`31` при создании нового контейнера необходимо установить `type` в `luks2`.
label string added in community.crypto 1.0.0	Эта опция позволяет пользователю создать контейнер формата LUKS2 с поддержкой меток, соответственно для идентификации контейнера по метке при последующем использовании. Будет использоваться только при создании контейнера или когда `device` не указан. Это нельзя указать, если `type` установлено в `luks1`.
name string	Устанавливает имя контейнера когда `state=opened`. Может использоваться вместо `device` при закрытии существующего контейнера (то есть, когда `state=closed`).
new_keyfile path	Добавляет дополнительный ключ к данному контейнеру на `device`. Требуется опция `keyfile` или `passphrase` для авторизации. Контейнер LUKS поддерживает до 8 слотов ключей. Значение параметра — путь к файлу ключа с парольной фразой. ОБРАТИТЕ ВНИМАНИЕ, что добавление дополнительных ключей является идемпотентным только начиная с community.crypto 1.4.0. Для более старых версий будет использоваться новый слот ключей, даже если другой слот ключей уже существует для этого файла ключей. ВНИМАНИЕ: работа с файлами ключей в открытом тексте опасна. Убедитесь, что они защищены.
new_keyslot integer added in community.crypto 2.16.0	Добавляет дополнительный `new_keyfile` или `new_passphrase` в определенный слот ключей на данном `device`. Значение параметра — номер слота ключей. Примечание: устройство `type=luks1` поддерживает номера слотов ключей `0`-`7`, а устройство `type=luks2` поддерживает номера слотов ключей `0`-`31`.
new_passphrase string added in community.crypto 1.0.0	Добавляет дополнительную парольную фразу к данному контейнеру на `device`. Требуется опция `keyfile` или `passphrase` для авторизации. Контейнер LUKS поддерживает до 8 слотов ключей. Значение параметра — строка с новой парольной фразой. ОБРАТИТЕ ВНИМАНИЕ, что добавление дополнительной парольной фразы является идемпотентным только начиная с community.crypto 1.4.0. Для более старых версий будет использоваться новый слот ключей, даже если другой слот ключей уже существует для этой парольной фразы.
passphrase string added in community.crypto 1.0.0	Используется для разблокировки контейнера. Для большинства операций необходим либо `passphrase`, либо `keyfile`. Значение параметра — строка с парольной фразой.
pbkdf dictionary added in community.crypto 1.4.0	Эта опция позволяет пользователю настроить используемую функцию вывода ключа на основе пароля (PBKDF). Будет использоваться только при создании контейнера и при добавлении ключей в существующий контейнер.
algorithm string	Используемый алгоритм. Доступно только для формата LUKS 2. Варианты: `"argon2i"` `"argon2id"` `"pbkdf2"`

iteration_count целое число	Укажите количество итераций, используемых для PBKDF. Взаимоисключающее с `pbkdf.iteration_time`.
iteration_time вещественное число	Укажите время итераций, используемых для PBKDF. Обратите внимание, что это в секундах, а не в миллисекундах, как в командной строке. Взаимоисключающее с `pbkdf.iteration_count`.
memory целое число	Предельное значение затрачиваемой памяти в килобайтах для PBKDF. Не используется для PBKDF2, а только для Argon PBKDF.
parallel целое число	Параллельная стоимость для PBKDF. Это число потоков, которые выполняются параллельно. Не используется для PBKDF2, а только для Argon PBKDF.
perf_no_read_workqueue булево добавлен в community.crypto 2.3.0	Позволяет пользователю пропустить внутреннюю очередь задач dm-crypt и обработать запросы чтения синхронно. Будет использоваться только при открытии контейнеров. Варианты: `false` ← (по умолчанию) `true`
perf_no_write_workqueue булево добавлен в community.crypto 2.3.0	Позволяет пользователю пропустить внутреннюю очередь задач dm-crypt и обработать запросы записи синхронно. Будет использоваться только при открытии контейнеров. Варианты: `false` ← (по умолчанию) `true`
perf_same_cpu_crypt булево добавлен в community.crypto 2.3.0	Позволяет пользователю выполнять шифрование с использованием того же процессора, на котором был отправлен ввод/вывод. По умолчанию используется неограниченная очередь задач, чтобы работа шифрования автоматически распределялась между доступными процессорами. Будет использоваться только при открытии контейнеров. Варианты: `false` ← (по умолчанию) `true`
perf_submit_from_crypt_cpus булево добавлен в community.crypto 2.3.0	Позволяет пользователю отключить перенос операций записи на отдельный поток после шифрования. В некоторых ситуациях перенос операций записи блочного ввода/вывода из потоков шифрования в один поток значительно снижает производительность. По умолчанию операции записи блочного ввода/вывода переносятся в тот же поток. Будет использоваться только при открытии контейнеров. Варианты: `false` ← (по умолчанию) `true`
persistent булево добавлен в 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 путь	Удаляет указанный ключ из контейнера при `device`. Не удаляет ключ из файловой системы. Значение параметра — путь к файлу ключа с паролем. Обратите внимание, что удаление ключей идемпотентно только с версии community.crypto 1.4.0. Для более старых версий попытка удалить несуществующий ключ приводит к ошибке. Обратите внимание, что для удаления последнего ключа из контейнера LUKS необходимо установить параметр `force_remove_last_key` в `true`. Будьте осторожны, работа с файлами ключей в открытом виде небезопасна. Убедитесь, что они защищены.
remove_keyslot целое число добавлен в community.crypto 2.16.0	Удаляет ключ в заданном слоте при `device`. Требуется `keyfile` или `passphrase` для авторизации. Примечание, что устройство `type=luks1` поддерживает номера слотов ключей `0`-`7`, а устройство `type=luks2` поддерживает номера слотов ключей `0`-`31`. Примечание, что указанный `keyfile` или `passphrase` не должен находиться в удаляемом слоте.
remove_passphrase строка добавлен в community.crypto 1.0.0	Удаляет указанный пароль из контейнера при `device`. Значение параметра — строка с паролем для удаления. Обратите внимание, что удаление паролей идемпотентно только с версии community.crypto 1.4.0. Для более старых версий попытка удалить несуществующий пароль приводит к ошибке. Обратите внимание, что для удаления последнего ключа из контейнера LUKS необходимо установить параметр `force_remove_last_key` в `true`.
sector_size целое число добавлен в community.crypto 1.5.0	Этот параметр позволяет пользователю указать размер сектора (в байтах), используемый для контейнеров LUKS2. Будет использоваться только при создании контейнера.

state string	Желаемое состояние контейнера LUKS. В зависимости от его значения создаёт, уничтожает, открывает или закрывает контейнер LUKS на указанном устройстве. `present` будет создавать контейнер LUKS, если он ещё не существует. Требует указания параметров `device` и либо `keyfile`, либо `passphrase`. `absent` удалит существующий контейнер LUKS, если он есть. Требует указания параметров `device` или `name`. `opened` откроет контейнер LUKS. Если он не существует, он будет создан в первую очередь. Требует указания параметров `device` и либо `keyfile`, либо `passphrase`. Используйте параметр `name`, чтобы установить имя открытого контейнера. В противном случае имя будет сгенерировано автоматически и возвращено в результате. `closed` заблокирует контейнер LUKS. Однако если контейнер не существует, он будет создан. Требует указания параметров `device` и либо `keyfile`, либо `passphrase`. Если контейнер уже существует, достаточно `device` или `name`. Варианты: `"present"` ← (по умолчанию) `"absent"` `"opened"` `"closed"`
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	Поддержка: отсутствует	Возвращает подробности о том, что изменилось (или, возможно, требует изменения в `check_mode`) при работе в режиме сравнения.

Примеры

- 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 string	Когда `state=opened` возвращает (сгенерированное или предоставленное) имя контейнера LUKS. Возвращает None, если имя не указано. Возвращается: success Пример: `"luks-c1da9a58-2fde-4256-9d9f-6ab008b4dd1b"`

Авторы

Jan Pokorny (@japokorn)

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

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