DEBOPS.DROPBEAR_INITRAMFS(5)

NAME
debops.dropbear_initramfs - Setup the dropbear ssh server in initramfs

SYNOPSIS

debops service/dropbear_initramfs [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

The debops.dropbear_initramfs role allows you to setup SSH access to the initramfs prior to the root filesystem being mounted using Dropbear as SSH server.

This can be used to unlock a full disk encrypted host remotely via SSH.

DEFAULT VARIABLE DETAILS

Some of debops.dropbear_initramfs default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  dropbear_initramfs__interfaces

The dropbear_initramfs__interfaces and similar dictionaries behave similar to the ifupdown__*_interfaces dictionaries of the debops.ifupdown role. Refer to the documentation of debops.ifupdown for details.

Compared to the debops.ifupdown, only a limited subset of parameters is currently supported:

type
    Optional. Anything other than ether will be ignored.

inet
    Optional. IPv4 configuration method used by a given interface. If you set this parameter to False, no IPv4 configuration will be applied. Currently only static (default) and False is supported.

inet6
    Optional. IPv6 configuration method used by a given interface. If you set this parameter to False, no IPv6 configuration will be applied. Currently only static (default) and False is supported.

address or addresses
    Optional. A string or a list of IPv4 and/or IPv6 addresses to set on a given network interface, in the form of ipaddress/prefix or CIDR. Remember that you need to specify the host IP address and not the network; the 192.0.2.1/24 is the correct notation, and 192.0.2.0/24 is incorrect.

gateway or gateways
    Optional. Specify the IPv4 or IPv6 address of the network gateway to which outgoing packets will be directed. If it's a list of addresses, first valid address for a network type will be used as the gateway.

  Examples

Configure eth0 with a global IPv6 address.

---
dropbear_initramfs__interfaces:
  'eth0':
    inet: False
    inet6: 'static'
    addresses:
      - '2001:db8::23/64'
    gateways:
      - '2001:db8::'

  dropbear_initramfs__authorized_keys

The dropbear_initramfs__authorized_keys and similar variables are used to define what SSH keys should be allowed for remote initramfs login.

Each list item is a dictionary with the following supported options:

key Required. String containing either a SSH public key, or an URL to a resource which returns a file with SSH public keys (only one URL is allowed at the moment), or a list of SSH public keys.

key_options
    Optional. String or list of SSH options which should be set for each key specified on the item.key list. Refer to dropbear(8) for details.

    If this parameter is not specified, SSH public keys will use options set in the dropbear_initramfs__authorized_keys_key_options variable. To override this variable for a particular entry, set the item.key_options parameter as empty string or list.

    The specified SSH key options are applied to all keys specified in the item.key parameter in this specific entry. To use different key options for different SSH keys, specify them in separate entries on the list.

exclusive
    Optional, boolean. If defined and True, the role will remove all other SSH public keys and set only the SSH public keys defined by item.key.

state
    Optional. If undefined or present, the SSH public keys specified in the item.keys parameter will be added. If absent, the specified SSH public keys will be removed.

  Examples

Set SSH keys from a file on the Ansible Controller as the only allowed keys for remote initramfs login:

---
dropbear_initramfs__authorized_keys:
  - sshkeys: '{{ lookup("file", "/path/to/admin23.pub") }}'
    exclusive: True

Ensure that given SSH public keys are allowed for remote initramfs login:

---
dropbear_initramfs__group_authorized_keys:
  - key: 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCriBiAJ76UtTD1eWv...'
  - key: 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDfE/F747VSqti0byU...'

RELATED PROJECTS

•   FDEunlock <https://fdeunlock.readthedocs.io/en/latest/> – Check and unlock full disk encrypted systems via ssh

•   Mandos <https://wiki.recompile.se/wiki/Mandos> – System for allowing servers with encrypted root file systems to reboot unattended and/or remotely

•   Comparison of Mandos and FDEunlock <https://fdeunlock.readthedocs.io/en/latest/related_projects.html>

    The following Ansible roles do the same thing as this role and have been deprecated by this role:

•   systemli.rootcrypto <https://github.com/systemli/ansible-rootcrypto>

•   martin-v.sshpreluks <https://github.com/martin-v/ansible-sshpreluks>

    Refer to Migrating from other Ansible roles for details.

DESIGN GOALS

•   Don’t overwrite global configuration files like /etc/initramfs-tools/initramfs.conf and similar as this can lead to problems like newer package versions trying to upgrade the file. /etc/initramfs-tools/conf.d and other *.d directories are preferred and used for this.

•   If additional kernel modules need to be loaded in the initramfs then this functionally should be added to the debops-contrib.kernel_module <https://github.com/debops-contrib/ansible-kernel_module> role. Note that all modules listed in /etc/initramfs-tools/modules are force loaded as can be read in /usr/sbin/mkinitramfs. An initramfs hook should be used instead of touching the /etc/initramfs-tools/modules file.

UPGRADE NOTES

The upgrade notes only describe necessary changes that you might need to make to your setup in order to use a new role release.

  Upgrade from v0.1.0 to v0.2.0

All inventory variables have been renamed so you might need to update your inventory. You will need to read the updated documentation and upgrade your inventory manually.

MIGRATING FROM OTHER ANSIBLE ROLES

This role tries to work for all common use cases and combine similar roles previously created by independent authors which basically do the same thing. Refer to Combine efforts <https://github.com/martin-v/ansible-sshpreluks/issues/1> for details.

  From martin-v.sshpreluks <https://github.com/martin-v/ansible-sshpreluks>

All inventory variables have been renamed so you might need to update your inventory. You will need to read the role documentation and upgrade your inventory manually.

  From systemli.rootcrypto <https://github.com/systemli/ansible-rootcrypto>

All inventory variables have been renamed so you might need to update your inventory. A subset of them can be automatically updated using this script:

#!/usr/bin/env bash
## Upgrade inventory variables for migration from systemli.rootcrypto to debops.dropbear_initramfs.
## The script is idempotent.
git ls-files -z "$(git rev-parse --show-toplevel)" | xargs --null -I '{}' find '{}' -type f -print0 \
 | xargs --null sed --in-place --regexp-extended '
     s/rootcrypto_network_device/dropbear_initramfs__network_device/g;
     s/rootcrypto_network_address/dropbear_initramfs__network_address/g;
     s/rootcrypto_network_netmask/dropbear_initramfs__network_netmask/g;
     s/rootcrypto_network_gateway/dropbear_initramfs__network_gateway/g;
   '

The script is bundled with this role under ./docs/scripts/migrate-from-systemli.rootcrypto-to-debops.dropbear_initramfs and can be invoked from there.

You will need to read the role documentation and upgrade your remaining inventory manually.

AUTHOR
Robin Schneider

COPYRIGHT
2014-2022, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others