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

注意

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

如果您使用的是 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 选项时)

参数 

参数	注释
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 dictionary 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	支持：不支持	在 diff 模式下，将返回有关已更改内容（或可能需要在`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

返回值 

常见返回值已在此处记录，以下是此模块特有的字段

密钥 (Key)	描述
name 字符串	当`state=opened`时，返回 LUKS 容器的（生成的或给定的）名称。如果未提供名称，则返回 None。返回：成功示例：`"luks-c1da9a58-2fde-4256-9d9f-6ab008b4dd1b"`

作者

Jan Pokorny (@japokorn)