community.crypto.luks_device 模块 – 管理加密 (LUKS) 设备

注意

此模块是 community.crypto 集合（版本 2.22.3）的一部分。

如果您使用的是 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 布尔值在 community.crypto 2.17.0 中添加	允许设备丢弃（也称为 TRIM）请求。仅在打开容器时使用。选择 `false` ←（默认） `true`
cipher 字符串在 community.crypto 1.1.0 中添加	此选项允许用户为 LUKS 容器定义密码规范字符串。仅在容器创建时使用。对于 2.6.10 之前的内核，请使用 `aes-plain`，因为它们不理解新的密码规范字符串。要使用 ESSIV，请使用 `aes-cbc-essiv:sha256`。
device 字符串	要使用的设备（例如 `/dev/sda1`）。大多数情况下都需要。只有在提供 `state=closed` 和 `name` 时才能省略。
force_remove_last_key 布尔值	如果设置为 `true`，则允许从容器中删除最后一个密钥。请注意，当从容器中删除最后一个密钥时，该容器将无法再打开！选择 `false` ←（默认） `true`
hash 字符串在 community.crypto 1.1.0 中添加	此选项允许用户指定 LUKS 密钥设置方案和卷密钥摘要中使用的哈希函数。仅在容器创建时使用。
keyfile 路径	用于解锁容器。大多数操作需要 `keyfile` 或 `passphrase`。参数值是包含密码的密钥文件的路径。请注意，以纯文本形式使用密钥文件是危险的。请确保它们受到保护。
keysize 整数在 community.crypto 1.0.0 中添加	仅当 LUKS 容器不存在时才设置密钥大小。
keyslot 整数在 community.crypto 2.16.0 中添加	当在 `device` 上创建新容器时，将 `keyfile` 或 `passphrase` 添加到特定密钥槽。参数值是密钥槽的编号。注意，`type=luks1` 类型的设备支持密钥槽编号 `0`-`7`，而 `type=luks2` 类型的设备支持密钥槽编号 `0`-`31`。为了在创建新容器时使用密钥槽 `8`-`31`，需要将 `type` 设置为 `luks2`。
label 字符串在 community.crypto 1.0.0 中添加	此选项允许用户创建支持标签的 LUKS2 格式容器，以便在后续使用中通过标签识别容器。仅在创建容器时使用，或者当未指定 `device` 时使用。如果 `type` 设置为 `luks1`，则不能指定此项。
name 字符串	当 `state=opened` 时设置容器名称。当关闭现有容器时（即当 `state=closed` 时），可以使用此选项代替 `device`。
new_keyfile 路径	在 `device` 上给定的容器添加额外的密钥。需要 `keyfile` 或 `passphrase` 选项进行授权。LUKS 容器最多支持 8 个密钥槽。参数值是带有密码的密钥文件的路径。注意，只有从 community.crypto 1.4.0 开始，添加额外密钥才是幂等的。对于旧版本，即使此密钥文件已经存在另一个密钥槽，也会使用新的密钥槽。请注意，以纯文本形式使用密钥文件是危险的。请确保它们受到保护。
new_keyslot 整数在 community.crypto 2.16.0 中添加	将额外的 `new_keyfile` 或 `new_passphrase` 添加到给定 `device` 的特定密钥槽。参数值是密钥槽的编号。注意，`type=luks1` 类型的设备支持密钥槽编号 `0`-`7`，而 `type=luks2` 类型的设备支持密钥槽编号 `0`-`31`。
new_passphrase 字符串在 community.crypto 1.0.0 中添加	在 `device` 上给定的容器添加额外的密码。需要 `keyfile` 或 `passphrase` 选项进行授权。LUKS 容器最多支持 8 个密钥槽。参数值是包含新密码的字符串。注意，只有从 community.crypto 1.4.0 开始，添加额外密码才是幂等的。对于旧版本，即使此密码已经存在另一个密钥槽，也会使用新的密钥槽。
passphrase 字符串在 community.crypto 1.0.0 中添加	用于解锁容器。大多数操作都需要 `passphrase` 或 `keyfile`。参数值是包含密码的字符串。
pbkdf 字典在 community.crypto 1.4.0 中添加	此选项允许用户配置所使用的基于密码的密钥派生函数 (PBKDF)。仅在创建容器时以及将密钥添加到现有容器时使用。
algorithm 字符串	要使用的算法。仅适用于 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 中添加	允许用户使用提交 IO 的同一 CPU 执行加密。默认是使用无界工作队列，以便在可用的 CPU 之间自动平衡加密工作。仅在打开容器时使用。选择 `false` ←（默认） `true`
perf_submit_from_crypt_cpus 布尔值在 community.crypto 2.3.0 中添加	允许用户在加密后禁用将写入卸载到单独的线程。在某些情况下，将块写入 IO 操作从加密线程卸载到单个线程会显著降低性能。默认是将块写入 IO 操作卸载到同一线程。仅在打开容器时使用。选择 `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 字符串	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 字符串在 community.crypto 1.0.0 中添加	此选项允许用户显式定义要使用的 LUKS 容器的格式。选项为 `luks1` 或 `luks2` 选择 `"luks1"` `"luks2"`
uuid 字符串在 community.crypto 1.0.0 中添加	通过此选项，用户可以使用 UUID 标识 LUKS 容器。仅当未指定 `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 字符串	当 `state=opened` 返回 LUKS 容器的（生成或给定的）名称。如果没有提供名称，则返回 None。返回：成功示例： `"luks-c1da9a58-2fde-4256-9d9f-6ab008b4dd1b"`

作者

Jan Pokorny (@japokorn)