ansible.builtin.luks_device (v2.9.27) — module

Install Ansible via pip

Install with pip install ansible==2.9.27

Description

Module manages L(LUKS,https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup) on given device. Supports creating, destroying, opening and closing of LUKS container and adding or removing new keys.

Requirements

• cryptsetup
• wipefs
• lsblk

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: close the existing LUKS container "mycrypt"
  luks_device:
    state: "closed"
    name: "mycrypt"

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: make sure LUKS container exists and is closed
  luks_device:
    device: "/dev/loop0"
    state: "closed"
    keyfile: "/vault/keyfile"

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: remove existing key from the LUKS container
  luks_device:
    device: "/dev/loop0"
    remove_keyfile: "/vault/keyfile2"

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: completely remove the LUKS container and its contents
  luks_device:
    device: "/dev/loop0"
    state: "absent"

Inputs

    
name:
    description:
    - Sets container name when I(state=opened). Can be used instead of I(device) when
      closing the existing container (i.e. when I(state=closed)).
    type: str

state:
    choices:
    - present
    - absent
    - opened
    - closed
    default: present
    description:
    - Desired state of the LUKS container. Based on its value creates, destroys, opens
      or closes the LUKS container on a given device.
    - I(present) will create LUKS container unless already present. Requires I(device)
      and I(keyfile) options to be provided.
    - I(absent) will remove existing LUKS container if it exists. Requires I(device) or
      I(name) to be specified.
    - I(opened) will unlock the LUKS container. If it does not exist it will be created
      first. Requires I(device) and I(keyfile) to be specified. Use the I(name) option
      to set the name of the opened container. Otherwise the name will be generated automatically
      and returned as a part of the result.
    - I(closed) will lock the LUKS container. However if the container does not exist
      it will be created. Requires I(device) and I(keyfile) options to be provided. If
      container does already exist I(device) or I(name) will suffice.
    type: str

device:
    description:
    - Device to work with (e.g. C(/dev/sda1)). Needed in most cases. Can be omitted only
      when I(state=closed) together with I(name) is provided.
    type: str

keyfile:
    description:
    - Used to unlock the container and needed for most of the operations. Parameter value
      is the path to the keyfile with the passphrase.
    - BEWARE that working with keyfiles in plaintext is dangerous. Make sure that they
      are protected.
    type: path

new_keyfile:
    description:
    - Adds additional key to given container on I(device). Needs I(keyfile) option for
      authorization. LUKS container supports up to 8 keys. Parameter value is the path
      to the keyfile with the passphrase.
    - NOTE that adding additional keys is I(not idempotent). A new keyslot will be used
      even if another keyslot already exists for this keyfile.
    - BEWARE that working with keyfiles in plaintext is dangerous. Make sure that they
      are protected.
    type: path

remove_keyfile:
    description:
    - Removes given key from the container on I(device). Does not remove the keyfile from
      filesystem. Parameter value is the path to the keyfile with the passphrase.
    - NOTE that removing keys is I(not idempotent). Trying to remove a key which no longer
      exists results in an error.
    - NOTE that to remove the last key from a LUKS container, the I(force_remove_last_key)
      option must be set to C(yes).
    - BEWARE that working with keyfiles in plaintext is dangerous. Make sure that they
      are protected.
    type: path

force_remove_last_key:
    default: false
    description:
    - If set to C(yes), allows removing the last key from a container.
    - BEWARE that when the last key has been removed from a container, the container can
      no longer be opened!
    type: bool

Outputs

name:
  description: When I(state=opened) returns (generated or given) name of LUKS container.
    Returns None if no name is supplied.
  returned: success
  sample: luks-c1da9a58-2fde-4256-9d9f-6ab008b4dd1b
  type: str