nbde_client

Ansible role for configuring Network-Bound Disk Encryption clients (e.g. clevis).

This role currently supports clevis as a provider and it uses it for operations like encryption and decryption.

Supported Distributions

RHEL-7+, CentOS-7+
Fedora

Limitations

This role can currently create tang bindings. TPM2 is not supported as of now.

Role Variables

These are the variables that can be passed to the role:

Variable	Default/Choices	Description
`nbde_client_provider`	`clevis`	identifies the provider for the `nbde_client` role. We currently support `clevis`.
`nbde_client_bindings`		a list containing binding configurations, which include e.g. devices and slots.
`nbde_client_early_boot`	`true`	by default nbde_client will configure the initrd to unlock the volume. This may need to be disabled if the volume should be unlocked by clevis-luks-askpass. For managed hosts with static IP addressing, prefer `nbde_client_extra_dracut_settings` instead of disabling early boot.
`nbde_client_secure_logging`	`true`	If true, suppress potentially sensitive output from tasks that handle credentials, secrets, and other sensitive data. Set to false for debugging issues with credential handling or secret management, but be aware this may expose sensitive information in logs.
`nbde_client_extra_dracut_settings`	`[]`	a list of extra dracut configuration lines written to `/etc/dracut.conf.d/nbde_client.conf` in addition to the role's implicit platform settings. Use this for static IP early-boot networking and other custom dracut options. Requires `nbde_client_early_boot: true` (the default); the role fails if early boot is disabled.

nbde_client_bindings

nbde_client_bindings is a list of dictionaries that support the following keys:

Name	Default/Choices	Description
`device`		specifies the path of the backing device of an encrypted device on the managed host. This device must be already configured as a LUKS device before using the role (REQUIRED).
`encryption_password`		a valid password or passphrase for opening/unlocking the specified device. Recommend vault encrypting the value. See https://docs.ansible.com/ansible/latest/user_guide/vault.html
`encryption_key_src`		either the absolute or relative path, on the control node, of a file containing an encryption key valid for opening/unlocking the specified device. The role will copy this file to the managed node(s).
`state`	present / absent	specifies whether a binding with the configuration described should be added or removed. Setting state to present (the default) means a binding will be added; setting state to absent means a binding will be removed from the device/slot.
`slot`	`1`	specifies the slot to use for the binding.
`servers`		specifies a list of servers to bind to. To enable high availability, specify more than one server here.
`threshold`	`1`	specifies the threshold for the Shamir Secret Sharing (SSS) scheme that is put in place when using more than one server. When using multiple servers, threshold indicates how many of those servers should succeed, in terms of decryption, in order to complete the process of recovering the LUKS passphrase to open the device.
`password_temporary`	`false`	If `true`, the password or passphrase that was provided via the `encryption_password` or `encryption_key` arguments will be used to unlock the device and then it will be removed from the LUKS device after the binding operation completes, i.e. it will not be valid anymore. To be used if device has been previously created with a sample password or passphrase (for example by an automated install like kickstart that set up some sort of "default" password), which the role should replace by a stronger one.

Example:

nbde_client_bindings:
  - device: /dev/sda1
    encryption_key_src: /vault/keyfile
    state: present
    slot: 2
    threshold: 1
    password_temporary: false
    servers:
      - http://server1.example.com
      - http://server2.example.com

nbde_client_extra_dracut_settings

nbde_client_extra_dracut_settings is a list of strings. Each string is written as a line in /etc/dracut.conf.d/nbde_client.conf, after the implicit platform-specific settings from __nbde_client_dracut_settings.

This is useful for NBDE clients that use static IP addressing and need network configuration available during early boot. For example:

nbde_client_extra_dracut_settings:
  - kernel_cmdline+=" ip=192.0.2.10::192.0.2.1:255.255.255.0::ens3:none nameserver=192.0.2.100 "

Note: You cannot set nbde_client_early_boot: false when using nbde_client_extra_dracut_settings. Extra dracut settings are only written when early boot is enabled. The role fails if both are set this way.

Example Playbooks

Example 1: high availability

---
- hosts: all
  vars:
    nbde_client_bindings:
      - device: /dev/sda1
        # recommend vault encrypting the encryption_password
        # see https://docs.ansible.com/ansible/latest/user_guide/vault.html
        encryption_password: password
        servers:
          - http://server1.example.com
          - http://server2.example.com
  roles:
    - linux-system-roles.nbde_client

Example 2: remove binding from slot 2 in /dev/sda1

---
- hosts: all
  vars:
    nbde_client_bindings:
      - device: /dev/sda1
        # recommend vault encrypting the encryption_password
        # see https://docs.ansible.com/ansible/latest/user_guide/vault.html
        encryption_password: password
        slot: 2
        state: absent
  roles:
    - linux-system-roles.nbde_client

License

MIT