.. include:: global.rst.inc


Default variables: configuration
================================

Some of ``debops.cryptsetup`` variables have more extensive configuration.
Here you can find documentation and examples for them.


.. _cryptsetup_devices:

cryptsetup_devices
------------------

Note the following list only documents the common parameters. The role allows
you to use more specific parameters which are not documented below.

``name``
  Required, string. Name of the plaintext device mapper target and the mount point.
  Must be unique among all device mapper targets and should not be changed once
  it was used.

  If you want to change it, you can set ``state`` to ``False``, execute the
  role, rename the secrets directory corresponding to this item, adopt your
  inventory accordingly and run the role again to configure the item with the
  new name.

``ciphertext_block_device``
  Required, string. File path to the ciphertext block device, either the block
  device itself e. g. :file:`/dev/sdb` or a partition on the block device e. g.
  :file:`/dev/sdb5`.

``crypttab_options``
  Optional, list of strings. Each string represents an option to configure for
  each device in :file:`/etc/crypttab`.
  Overwrites the default as configured by the ``cryptsetup_crypttab_options``
  variable.

``keyfile``
  Optional, string. File path for the keyfile on the Ansible controller. Will
  be copied over to the remote system. If it does not exist yet it will be
  generated using the systems random number generator on the Ansible controller
  as it is expected that the entropy pool on the Ansible controller is better
  mixed.
  Defaults to:

  .. code:: jinja

     {{ cryptsetup_secret_path + "/" + item.name + "/keyfile.raw" }}

``backup_header``
  Optional, boolean. Should a header backup be created and stored
  on the remote system and the Ansible controller?
  Set to ``False`` to disable header backup creation and to ensure that the
  header backup on the remote system is absent.
  Defaults to the ``cryptsetup_header_backup`` variable.

``fstype``
  Optional, string. Filesystem type to create on the plaintext device mapper
  target.
  Defaults to the ``cryptsetup_fstype`` variable.

``mount``
  Optional, string. Plaintext mount point of the filesystem.
  Defaults to:

  .. code:: jinja

    {{ cryptsetup_mountpoint_parent_directory + "/" + item.name }}

``mount_options``
  Optional, list of strings. Mount options associated with the filesystem.
  For more details see :manpage:`mount(8)`.

``state``
  Optional, string. There are four states which can be chosen for each
  encrypted filesystem.  If no state is given, the value of
  ``cryptsetup_state`` will be used which defaults to ``mounted``.

  ``mounted``
    Ensure that the encryption and filesystem layer are in place on the block device and
    the filesystem is mounted.

  ``ansible_controller_mounted``
    Same as ``mounted`` except that the keyfile is never stored on persistent storage of the remote system.
    Might be useful when you don’t have a secure place to store the keyfile on the remote system.
    With this option you will be required to run this role after each reboot to mount the filesystem again.

    Note that the implicit default for ``crypttab_options`` and
    ``mount_options`` is ``auto`` which means that your init system will try to
    mount the filesystem on boot and might drop you to a root shell if it
    can’t.

    To avoid this, you need to set the following options for the item::

      crypttab_options: '{{ ["noauto"] + (cryptsetup_crypttab_options|d([]) | list) }}'
      mount_options: '{{ ["noauto"] + (cryptsetup_mount_options|d([]) | list) }}'

    Note that this option is currently not idempotent because it copes the
    keyfile to the remote system and erases it again.

  ``unmounted``
    Ensure that the encryption and filesystem layer are in place on the block device and
    the filesystem is unmounted. Additionally ensures that the cryptsetup mapping
    is removed so that no direct access to the plain-text block device is possible.

  ``present``
    Ensure that the encryption and filesystem layer are in place on the block device.
    The plaintext device mapper target will be created as needed during the
    Ansible run to ensure the filesystem on it is present. When it was not
    available prior to this Ansible run, it will be stopped at the end of the
    role run again.
    So basically, this option never changes the mounted/unmounted state of the
    plaintext device mapper target or the plaintext mount point of the
    filesystem.
    Note that this option will not fail when the ciphertext block device is not
    available during the Ansible run and the keyfile has not been generated by Ansible.
    This was done to allow to provision remote systems with keys for ciphertext block
    devices which have been setup previously and are not available during
    execution of this role.

    Note that if the encrypted filesystem is not mounted when this option is
    used then this role will not be idempotent because the crypto layer needs
    to be opened in order to check if the filesystem has been created on top of
    it.

  ``absent``
    Same as ``unmounted`` but additionally removes all configuration, the
    keyfile and the header backup from the remote system.

Examples
~~~~~~~~

Setup an encrypted filesystem on top of :file:`/dev/sdb5` which will be
mounted after role execution under :file:`/media/sdb5_crypt` (assuming the
value of ``cryptsetup_state`` is left unchanged) and will be automatically
mounted at boot:

.. code:: yaml

   cryptsetup_devices:

     - name: 'sdb5_crypt'
       ciphertext_block_device: '/dev/sdb5'
