diff --git a/docs/rolereference.rst b/docs/rolereference.rst index e176c9d1aa7b22112ac4db6e7d1fa7e77568f0c1..3f5dbc3e0b09977156642cc737eb38cfbbbeda67 100644 --- a/docs/rolereference.rst +++ b/docs/rolereference.rst @@ -1384,3 +1384,124 @@ Parameters ssh-keygen -f backup_server_rsa_key -N '' -t rsa ssh-keygen -f backup_server_ed25519_key -N '' -t ed25519 ssh-keygen -f backup_server_ecdsa_key -N '' -t ecdsa + + +Examples +~~~~~~~~ + +Here is an example configuration for setting-up the backup server role: + +.. code-block:: yaml + + - role: backup_server + backup_clients: + - server: web.example.com + uid: 3000 + public_key: "{{ lookup('file', inventory_dir + '/ssh/web.example.com.pub') }}" + ip: 10.32.64.18 + - server: mail.example.com + public_key: "{{ lookup('file', inventory_dir + '/ssh/mail.example.com.pub') }}" + ip: 10.32.64.15 + backup_host_ssh_private_keys: + dsa: "{{ lookup('file', inventory_dir + '/ssh/backup_server_dsa_key') }}" + rsa: "{{ lookup('file', inventory_dir + '/ssh/backup_server_rsa_key') }}" + ed25519: "{{ lookup('file', inventory_dir + '/ssh/backup_server_ed25519_key') }}" + ecdsa: "{{ lookup('file', inventory_dir + '/ssh/backup_server_ecdsa_key') }}" + + +Backup Client +------------- + +The ``backup_client`` role can be used for setting-up the server as a backup +client so it can perform backups to the backup server. + +Backup clients utilise duplicity (via the duply convenience wrapper) for +performing the backups to a backup server via *SFTP* protocol. + +The role itself will take care of deploying the necessary software, +configuration files, and encryption/signing keys to the backup client in order +to be able to perform backup. + +The role implements the following: + +* Installs backup software (Duplicity, Duply). +* Sets-up Duply configuration under directory ``/etc/duply/main/``. +* Extracts the encryption public key and signing private key from a + locally-available keyring, deploys them to the server, and imports them. +* Deploys private SSH key for logging-in into the backup server over SFTP. +* Deploys ``known_hosts`` file for SFTP fingerprint verification. + +Duply is configured as follows: + +* GnuPG keyring is stored under ``/etc/duply/main/gnupg/``. The keyring should + not be managed manually. +* SSH private key for logging-in into backup server is stored in location + ``/etc/duply/main/ssh/identity``. Backup server SFTP fingerprint is stored in + location ``/etc/duply/main/ssh/known_hosts``. +* Base directory for back-ups is root (``/``), but *all* files are excluded by + default to prevent huge back-ups. Ansible roles that want to utilise the + backup client role can specify patterns to include by adding pattern file to + directory ``/etc/duply/main/patterns/``. It is recommended to name such a file + after the role name. Include pattern file is assembled from these snippets and + stored in location ``/etc/duply/main/include``. + + +Parameters +~~~~~~~~~~ + +**backup_client_username** (string, optional, ``bak-{{ ansible_fqdn | replace('.', '_') }}``) + Username for connecting to the backup server via SFTP. + +**backup_encryption_keys** (list, mandatory) + List of key identifiers for encryption keys used for backup operation. Listed + encryption keys must be part of the backup keyring. It is sufficient (and + recommended) to include only the public keys. + +**backup_gnupg_keyring** (string, optional, ``{{ inventory_dir }}/backup_keyring``) + Path to the directory on *controller* machine (where Ansible is executed) + where the GnuPG keyring can be found. The keyring contains encryption and + signing keys for backup clients, and is used for deploying those keys to the + backup clients. + +**backup_server** (string, mandatory) + Backup server to connect to. + +**backup_server_destination** (string, optional, ``//duplicity``) + Target directory on the backup server where the backups are stored. + +**backup_server_host_ssh_public_keys** (list, mandatory) + SSH public keys presented by the server during client authentication. These + public keys are used for populating the known hosts on the backup client side + for host verification purposes. + +**backup_server_port** (int, optional, ``2222``) + Port on the backup server to connect to for accessing the SFTP service. + +**backup_signing_key** (string, optional, ``None``) + Key identifier of a key to use for signing the backups. The specified key + needs to be present in backup keyring, both private and public counterpart. If + there are multiple keys with the same ID present, the most recent one will be + used. + +**backup_ssh_key** (string, mandatory) + SSH private key for logging-in into the backup server. + + +Examples +~~~~~~~~ + +Here is an example configuration for setting-up the role (take note that lookup +plugin is quite useful here for fetching key values from some local directory): + +.. code-block:: yaml + + - role: backup_client + backup_encryption_keys: + - "my_secret_key" + backup_server: "backup.example.com" + backup_server_host_ssh_public_keys: + - "{{ lookup('file', inventory_dir + '/ssh/backup_server_dsa_key.pub') }}" + - "{{ lookup('file', inventory_dir + '/ssh/backup_server_rsa_key.pub') }}" + - "{{ lookup('file', inventory_dir + '/ssh/backup_server_ed25519_key.pub') }}" + - "{{ lookup('file', inventory_dir + '/ssh/backup_server_ecdsa_key.pub') }}" + backup_ssh_key: "{{ lookup('file', inventory_dir + '/ssh/web.example.com') }}"