Default variable details
Some of debops.rsnapshot
default variables have more extensive configuration
than simple strings or lists, here you can find documentation and examples for
them.
rsnapshot__ssh_identities
The rsnapshot__ssh_default_identities
and
rsnapshot__ssh_identities
variables define the SSH identities
(private/public key pairs) used by the rsnapshot script to access
the remote hosts over SSH. The default identities are created on the initial
setup and stored in the /root/.ssh/
directory, the main identity used
by the role if none is selected is defined by the
rsnapshot__ssh_main_identity
variable. Users can use the
rsnapshot__ssh_identities
variable to add more identities or to
override the default ones if necessary.
The public portion of the SSH keys is accessible via the Ansible local facts,
via the ansible_local.rsnapshot.ssh_identities
dictionary.
Examples
Create a custom SSH identity for older machines, the DSA keys have to use a length of 1024 bits:
rsnapshot__ssh_identities:
- name: 'id_rsnapshot_dsa'
type: 'dsa'
bits: '1024'
Syntax
The variables are lists of YAML dictionaries, each dictionary defines a SSH identity using specific parameters:
name
Required. The name of the SSH identity used as the filename; it's common to use the
id_
prefix in the SSH key filenames. The name will be used for the private key file, public key will have the.pub
suffix added automatically. The configuration entries with the samename
parameter are merged, this mechanism can be used to modify the SSH identities conditionally.state
Optional. If not specified or
present
, the SSH identity will be created. Currently SSH identities cannot be removed1 by the role, so theabsent
parameter will result in a given identity not being created if it doesn't exist. Theignore
value will tell the role to ignore a given configuration entry during execution.type
Optional, name of the SSH key type to create, depending on the support on the host. Usually either
ed25519
,rsa
ordsa
. If not specified, the value of thersnapshot__ssh_key_type
will be used by default.bits
Optional, the size of the generated RSA keys. If it's not specified, the value of the
rsnapshot__ssh_key_bits
is used by default. Needs to be set to1024
for the DSA keys.comment
Optional. A comment added to the generated SSH identity. If not specified, the value of the
rsnapshot__ssh_key_comment
will be used by default.
rsnapshot__hosts
The rsnapshot__*_hosts
lists define the configuration of the hosts to back
up by the rsnapshot script. Each host configuration is defined as
a YAML dictionary and describes the contents of the
/etc/rsnapshot/hosts/<name>/
directory. The default configuration is
based on the rsnapshot__*_configuration
, rsnapshot__*_excludes
and
rsnapshot__*_includes
variables, and can be modified per-host as needed.
Examples
Back up specific hosts defined in the Ansible inventory with default values:
rsnapshot__hosts:
- 'hostname1'
- 'hostname2'
- 'hostname3'
Create backup configuration for hosts in a specific Ansible inventory group:
# ansible/inventory/hosts
[hosts_to_backup]
hostname1
hostname2
hostname3
---
# ansible/inventory/host_vars/backup-host/rsnapshot.yml
rsnapshot__hosts:
- '{{ groups["hosts_to_backup"]
| difference(groups["debops_service_rsnapshot"]) }}'
Create configuration for host in the Ansible inventory but specify the host's
FQDN directly instead of using Ansible fact gathering to get it. This can be
used to select a different host address than the one Ansible sets as the
ansible_fqdn
variable.
This method can also be used to create backup configuration for hosts outside of the Ansible inventory.
rsnapshot__hosts:
- name: 'hostname1'
fqdn: 'host.example.org'
Create backup configuration for an external host that uses non-standard SSH
port and does not support the ed25519
SSH keys, only RSA. This is also an
OpenVZ container which cannot modify the I/O niceness using the
ionice command, therefore the command defined in the SSH key
installed on the host needs to be different:
rsnaphot__hosts:
- name: 'old-db.example.org'
ssh_port: 2200
ssh_identity: 'id_rsnapshot_rsa'
ssh_command: 'nice /usr/local/bin/rrsync -ro /'
Create configuration for an external host but don't install the SSH key (it will be installed manually out-of-band). Exclude any NFS mounts inside of the home directories from backups.
rsnapshot__hosts:
- name: 'appserver.example.org'
ssh_key: False
excludes:
- '/home/*/nfs'
Create backup configuration for a host in the Ansible inventory, but make snapshots in a removable media storage and don't create the snapshot directory automatically if it's not present (removable media is removed):
rsnapshot__hosts:
- name: 'hostname2'
options:
- snapshot_root: '/media/USB0/Snapshots/hostname2'
- no_create_root: 1
Create backup of the local host based on its inventory name (this is enabled by
default in the rsnapshot__default_hosts
variable):
rsnapshot__hosts:
- name: '{{ inventory_hostname }}'
local: True
Include additional filesystems in the local host backup, important when
one_fs
option is enabled. All filesystems will be backed up relative to the
dest_root
path:
rsnapshot__hosts:
- name: '{{ inventory_hostname }}'
filesystems: [ '/home', '/srv', '/var' ]
Alternatively, back up different filesystems into separate subdirectories:
rsnapshot__hosts:
- name: '{{ inventory_hostname }}'
filesystems:
'/': 'rootfs/'
'/home': 'home/'
'/srv': 'srv/'
'/var': 'var/'
Syntax
Each configuration entry is a string that denotes the inventory name or FQDN of the host to back up. Alternatively, configuration entries are defined as YAML dictionaries with specific parameters:
name
Required. Either the name of the host in the Ansible inventory (equivalent of
inventory_hostname
), or a FQDN of the host to back up. Configuration entries with the samename
parameter are merged together and can change the host configuration conditionally.If the configuration entry is specified as a string, for example being based on the Ansible
groups
variable, the string will be converted to aname
parameter. Additional configuration can then be applied using configuration entries with the same name.fqdn
Optional. Specify the Fully Qualified Domain Name of the host to back up. If this parameter is specified, it overrides the FQDN detected automatically by Ansible facts (if the host is in the Ansible inventory) and disables fact gathering for a given host. If you configure an external host to back up and specify its FQDN as the
name
parameter, you don't need to specify thefqdn
parameter.local
Optional, boolean. If defined and
True
, the host is considered local and SSH configuration will not be applied. The backup paths will be local as well. This parameter should not be used, unless you configure backups for the backup host itself, usually named as'{{ inventory_hostname }}'
.state
Optional. If not defined or
present
, the host configuration will be created, SSH keys will be deployed to the hosts, and SSH host fingerprints will be stored. Ifabsent
, the host configuration will be removed, but running backup jobs will not be stopped and existing snapshots will not be touched. Ifignore
, a given configuration entry will not be evaluated during role execution. This can be used to conditionally activate configuration entries.dest_root
Optional. The relative destination directory, added to the
snapshot_root
directory path. By default it's set to./
which means the same directory as thesnapshot_root
directory.filesystems
Optional. A string or a YAML list of filesystems which should be backed up by rsnapshot. This is only relevant if the
one_fs
configuration option is enabled (by default it is enabled).The
/
filesystem is backed up automatically, but withone_fs
enabled the rsync script will not traverse beyond the filesystem boundaries. With this parameter, an user can tell rsnapshot to back up additional filesystems in addition to the/
filesystem. They will be backed up relative to the path specified as thedest_root
, by default./
, which should reflect their original placement in the source filesystem.This parameter can also be defined as a YAML dictionary, with dictionary key specifying the source filesystem path, and dictionary value specifying the destination path, relative to
snapshot_root
directory. This can be used to separate different filesystem snapshots into their own subdirectories.options
Optional. List of the
rsnapshot.conf
configuration options, defined in the same format as the rsnapshot__configuration variable. Theoptions
parameter is merged between different configuration entries and options from different entries can modify each other according to their order in the configuration. This can be used to modify the default options for a specific host.excludes
Optional. List of the file patterns to exclude from the backup, stored in the
excludes.txt
file in each host configuration directory. The list is defined in the same format as the rsnapshot__excludes, rsnapshot__includes variable. Theexcludes
parameter is merged between different configuration entries and exclude patterns from different entries can modify each other according to their order in the configuration. This can be used to modify the default list of exclude patterns for a specific host.includes
Optional. List of the file patterns to include in the backup, stored in the
includes.txt
file in each host configuration directory. The list is defined in the same format as the rsnapshot__excludes, rsnapshot__includes variable. Theincludes
parameter is merged between different configuration entries and include patterns from different entries can modify each other according to their order in the configuration. This can be used to modify the default list of include patterns for a specific host.overrides
Optional. String or YAML list of configuration options appended to each
backup
option in thersnapshot.conf
configuration file. Normally the role uses the overrides to define what SSH identity to use for a given host and what SSH port to connect to; users can specify additional overrides using this parameter. These overrides will be added to eachbackup
configuration entry generated by the role.rsync
Optional, boolean. If not specified or
True
, the role will install APT packages specified in thersnapshot__host_packages
variable (by defaultrsync
) on the remote host to back up and set up the /usr/local/bin/rrsync wrapper script. If these tasks cannot or shouldn't be performed on the remote host, you can disable them by setting this parameter toFalse
.rrsync_source
Optional. Absolute path on the host to back up to the rrsync wrapper script source (by default
/usr/share/doc/rsync/scripts/rrsync
). The role will copy the script to the/usr/local/bin/
directory and make it executable. The role will automatically detect any tarballs with the.gz
extension and extract their contents; the.gz
extension should not be included in the path specified in this parameter.rrsync_binary
Optional. Absolute path on the host to back up where the rrsync wrapper script should be installed (by default
/usr/local/bin/rrsync
).ssh_key
Optional, boolean. If not specified or
True
, the role will install the specified or default SSH public key on the host to back up, so that rsnapshot can connect to it over SSH.ssh_scan
Optional, boolean. If not specified or
True
, the role will scan the SSH fingerprint of the host to back up, so that rsnapshot command can connect to it unattended. If the SSH public key has been added or modified on the host to back up, the role will remove the previously saved SSH fingerprints assuming that the host has been reinstalled and new SSH host keys are present.ssh_user
Optional. The name of the user to which the rsnapshot command will connect over SSH and on which the SSH public key will be installed. By default
root
. Use of an unprivileged account is not implemented at the moment.ssh_port
Optional. The TCP port of the SSH service the rsnapshot should use to connect to the host which is being backed up.
ssh_identity
Optional. A name of the SSH identity to use for a given host. If not specified, the identity defined in
rsnapshot__ssh_main_identity
will be used by default. The available SSH identities can be listed by executing the/etc/ansible/facts.d/rsnapshot.fact
script on the rsnapshot host.ssh_options
Optional. A string with SSH options added with the SSH key in the
~/.ssh/authorized_keys
file on the host to back up. If not specified, the value of thersnapshot__ssh_options
variable will be used by default.ssh_command
Optional. The command to execute on the host to back up, defined with the SSH key in the
~/.ssh/authorized_keys
file. If not specified, the value of thersnapshot__ssh_command
variable will be used by default.
rsnapshot__excludes, rsnapshot__includes
The rsnapshot__*_excludes
and rsnapshot__*_includes
variables define
the default lists of file patterns to exclude and included in the snapshots. By
default the snapshots are designed to include everything, but exclude specific
paths in the filesystem; this way any paths not specified explicitly in the
configuration should be backed up automatically.
The default lists of exclude and include patterns are combined with the
item.excludes
and item.includes
parameters of the host configuration
entries in the rsnapshot__hosts variables. They can be used to
modify existing file patterns or add new ones.
See the rsync(1) manual page, "INCLUDE/EXCLUDE PATTERN RULES" section for more information about file patterns.
Examples
See the rsnapshot__default_excludes
variable for the list of the file
patterns that are defined by default.
Define a list of file patterns to exclude from backups:
rsnapshot__excludes:
- '/no-backup'
- '/scratch'
Include everything in the backup, barring any excluded files:
rsnapshot__includes:
- '/*'
Syntax
Each entry in the list can be a string that defines a file pattern. The default
behaviour is dependent on the variable type - files will be excluded by default
if defined in the rsnapshot__*_excludes
variables, and included if they are
defined in the rsnapshot__*_includes
variables.
Alternatively, you can define each file pattern using the YAML dictionary syntax with specific parameters:
name
Required. The file pattern to exclude/include in the backups. The entries with the same
name
parameter are merged together, this can be used to modify previously defined file patterns conditionally.state
Optional. If not specified or
present
, a given file pattern will be present in the generatedexcludes.txt`
orincludes.txt
configuration files. Ifabsent
, the pattern will not be present in the configuration files. Ifignore
, a given configuration entry will not be evaluated by the role during execution.rule
Optional. Specify the rule type to use for a given file pattern (see rsync(1) for detailed explanation). Possible values are:
exclude
,include
,merge
,dir-merge
,hide
,show
,protect
,risk
,clear
. This can be used to override the default file pattern type, to include a pattern in theexcludes.txt
file, or exclude in theincludes.txt
file.
rsnapshot__configuration
The rsnapshot__*_configuration
variables define the default options
included in the generated rsnapshot.conf
configuration files. The
defaults are merged with the item.options
parameter in each host
configuration entry, which can be used to override specific configuration
options on a host-by-host basis.
The information about possible options and their meaning can be found in the rsnapshot(1) manpage.
Examples
See the rsnapshot__original_configuration
to see the original values
of the configuration options.
The rsnapshot__default_configuration
contains all of the values
modified by the role by default.
Syntax
The options can be specified as a list of YAML dictionaries, each dictionary key being the option name, and the dictionary value being the option value (you should specify only one key/value pair this way per the list element).
Alternatively, if the YAML dictionary key name
is present, the role will
interpret a given entry using specific parameters:
name
Required. The name of the configuration option. Entries with the same
name
parameter are merged together, this can be used to modify the configuration options conditionally.option
Optional. Specify an alternative name of the configuration option. This is used when a given option can be present more than once in the configuration file, for example
retain
. In that case, the option value will be taken from thename
parameter and additional arguments will be taken from thevalue
parameter.value
The value of a given configuration option, usually a string or a number. The role does not interpret booleans, lists or dictionaries in any special way. Some of the specific configuration options might have their default values modified in the configuration file template to support multi-host backups.
raw
Optional. A string or a YAML text block that will be included in the configuration file as-is instead of the
name
/value
parameters. This can be used for parts of the configuration that are too complex to implement them using other parameters. Remember that thersnapshot.conf
configuration file uses tab characters as separators between option name, value and other arguments.state
Optional. If not specified or
present
, a given configuration option will be included in the generated config file. Ifabsent
, the option will be removed from the generated configuration file. Ifignore
, the entry will not be evaluated during role execution. Ifcomment
, a given configuration option will be includedd, but it will be commented out.comment
Optional. String or YAML text block with comments for a given configuration option.
section
Optional. Name of the section in which to include a given configuration option. Possible sections are defined in the
rsnapshot__configuration_sections
variable. If a section is not specified, anunknown
section will be used by default.weight
Optional. A positive or negative number which modifies the "weight" of a given configuration option. The weight affects the order of configuration options in a given section; use negative number to move a given option higher in the file, and positive number to move it lower in the file.