Skip to content

Latest commit

 

History

History
933 lines (570 loc) · 23.5 KB

REFERENCE.md

File metadata and controls

933 lines (570 loc) · 23.5 KB
Raw

Reference

Table of Contents

Classes

  • borgbackup: borg backup class
  • borgbackup::git: Internal class to setup the git repository to store passphrase and key
  • borgbackup::install: internal class borgbackup::install internal class borgbackup::install to install the packages (used by ::borgbackup::server and ::borgbackup
  • borgbackup::server: this class is used to setup a remote borg server (the target) where to put the backups

Defined types

Functions

Tasks

  • check: verifies the consistency of a borg repository and the corresponding archives
  • info: displays detailed information about the borg repo
  • list: lists the contents of the nodes borg repository

Classes

borgbackup

borg backup class

Parameters

The following parameters are available in the borgbackup class:

configdir

Data type: String

configuration directory defaults to '/etc/borgbackup'

Default value: '/etc/borgbackup'

ensure_ssh_directory

Data type: Boolean

if we true (default) we create the .ssh directory

Default value: true

ssh_key_define

Data type: Optional[String[1]]

the resource to use for the generation of an ssh key defaults to undef

Default value: undef

ssh_key_res

Data type: Hash

the parameters to use for the $ssh_key_define defaults to {}

Default value: {}

repos

Data type: Hash

Hash of repos to create (also see borgbackup::repo for parameters. defautls to {$::fqdn => {}} which creates an empty repo named $::fqdn. Hint: hiera5 will hash merge this parameter.

Default value: { $facts['networking']['fqdn'] => {} }

default_target

Data type: Optional[String[1]]

the default target of the backup for $repos definition defaults to undef see ::borgbackup::repo

Default value: undef

repos_defaults

Data type: Hash

default values for the $repos to create. defaults to {} Hint: hiera5 will hash merge this parameter.

Default value: {}

archives

Data type: Hash

archives to add to $repos hiera5 will hash merge this parameter. Remark: these archives will bee added to all repos defined in $repo. But can be overwriten per repo using $repo parameter.

Default value: {}

borgbackup::git

Internal class to setup the git repository to store passphrase and key

Parameters

The following parameters are available in the borgbackup::git class:

packages

Data type: Array

the packages to ensure defautls to ['git','gnupg']

Default value: ['git','gnupg']

gpg_keys

Data type: Hash

Hash of gpg public keys to use for the encryption of password and keyfile. the key for a pgp key must match the first email mentioned in the key. otherwise it will reencrypt with each puppet run! defaults to {}

Default value: {}

gpg_home

Data type: String

gpg directory to store pgp keys. defaults to "${borgbackup::configdir}/.gnupg"

Default value: "${borgbackup::configdir}/.gnupg"

gitrepo

Data type: Optional[String[1]]

if set to a remote url, an existing git repo will be cloned and commits will be pushed there. This gives the oportunity to have a separate place to store the access keys to the backups. defaults to undef which only creates a local git repo. Remark: if you change this, you have localy adapt the git repo (or delete it).

Default value: undef

gitrepo_sshkey

Data type: Optional[String[1]]

ssh private key needed to access the gitrepo. defaults to undef if $gitrepo is not set this value is ignored.

Default value: undef

git_home

Data type: String

directory to clone or create the git repo for keys and passphrases. defaults to "${borgbackup::configdir}/git"

Default value: "${borgbackup::configdir}/git"

git_author

Data type: String

String to be used as git author for commits. defaults to 'borgbackup <root@${::fqdn}>'

Default value: 'borgbackup <root@${::fqdn}>'

borgbackup::install

internal class borgbackup::install

internal class borgbackup::install to install the packages (used by ::borgbackup::server and ::borgbackup)

Parameters

The following parameters are available in the borgbackup::install class:

packages

Data type: Array

packages to install defaults to ['borgbackup']

Default value: ['borgbackup']

package_ensure

Data type: String

defaults to 'installed'

Default value: 'installed'

borgbackup::server

this class is used to setup a remote borg server (the target) where to put the backups

Parameters

The following parameters are available in the borgbackup::server class:

backuproot

Data type: String

directory for the backups. defaults to '/srv/borgbackup'

Default value: '/srv/borgbackup'

borguser

Data type: String

the user to create for the remote borg 'agents' to login via ssh defaults to 'borgbackup'

Default value: 'borgbackup'

borggroup

Data type: String

the group of the borguser defaults to 'borgbackup'

Default value: 'borgbackup'

borghome

Data type: String

where the borgs live ;) the homedirectory of the borg user

Default value: '/var/lib/borgbackup'

user_ensure

Data type: Boolean

if true (default) the $borguser is created

Default value: true

authorized_keys_target

Data type: String

target for authorized_keys

Default value: '/var/lib/borgbackup/authorized-keys'

authorized_keys_define

Data type: String

resource to create the authorized-keys file defaults to 'borgbackup::authorized_key' if you do not want to manage the authorized-keys file set this to ''

Default value: 'borgbackup::authorized_key'

authorized_keys

Data type: Hash

Hash of keys to add to authorized-keys file defaults to {}

Default value: {}

authorized_keys_defaults

Data type: Hash

Hash of default parameters to generate the authorized-keys file defaults to {}

Default value: {}

Defined types

borgbackup::addtogit

internal define to add a repo to git.

Parameters

The following parameters are available in the borgbackup::addtogit defined type:

passphrase

Data type: String

passphrase to set. if set to 'random', a random passphrase is generated

reponame

Data type: String

the name of the repository

borgbackup::archive

This class creates an archive in a repo

Parameters

The following parameters are available in the borgbackup::archive defined type:

reponame

Data type: String

The name of the repo to add the archive defaults to $::fqdn, the default repo created by including borgbackup without parameters

Default value: $facts['networking']['fqdn']

archive_name

Data type: String

The name of the archive. Defaults to $title

Default value: $title

pre_commands

Data type: Array

Array of commands to run before the backup run Defaults to []

Default value: []

post_commands

Data type: Array

Array of commands to run after the backup run Defaults to []

Default value: []

create_compression

Data type: String

the compression to use for create. Set to '' if no compresseion should be applied. Defaults to 'lz4'

Default value: 'lz4'

create_filter

Data type: String

Filter items to display for create commnd. Set to '' if no filter should be applied. Defaults to 'AME' (show Added, Modified and Error files)

Default value: 'AME'

create_options

Data type: Array

Array of additional options to add to the create command. Each item will be prefixed with '--' (means use long name !) Defaults to ['verbose', 'list', 'stats', 'show-rc', 'exclude-caches']

Default value: ['verbose', 'list', 'stats', 'show-rc', 'exclude-caches']

create_excludes

Data type: Array

Array of excludes Defaults to [] needs to be [] if stdin_cmd is used.

Default value: []

create_includes

Data type: Array

Array of file to include Defaults to [] needs to be [] if stdin_cmd is used.

Default value: []

stdin_cmd

Data type: Optional[String[1]]

command which is executed, stdout is used as input to backup. defaults to undef do not use together with $create_excludes and $create_includes

Default value: undef

do_prune

Data type: Boolean

if true, prune will be run after the create command. Defaults to true

Default value: true

prune_options

Data type: Array

Array of additional options to add to the prune command. Each item will be prefixed with '--' (means use long name !) Defaults to ['list', 'show-rc']

Default value: ['list', 'show-rc']

keep_last

Data type: Optional[Variant[String[1], Integer]]

number of last archives to keep Defaults to undef

Default value: undef

keep_hourly

Data type: Optional[Variant[String[1], Integer]]

number of hourly archives to keep Defaults to undef

Default value: undef

keep_daily

Data type: Variant[String, Integer]

number of daily archives to keep Set to '' if this option should not be added Defaults to 7

Default value: 7

keep_weekly

Data type: Variant[String, Integer]

number of weekly archives to keep Set to '' if this option should not be added Defaults to 4

Default value: 4

keep_monthly

Data type: Variant[String, Integer]

number of monthly archives to keep Set to '' if this option should not be added Defaults to 6

Default value: 6

keep_yearly

Data type: Optional[Variant[String[1], Integer]]

number of yearly archives to keep Defaults to undef (no yearly is kept)

Default value: undef

borgbackup::authorized_key

Internal define to handle the authorized keys from borgbackup::server

for borgbackup dokumentation see: http://borgbackup.readthedocs.io/en/stable/usage/serve.html

Parameters

The following parameters are available in the borgbackup::authorized_key defined type:

backuproot

Data type: String

the directory where all the backups should be

target

Data type: String

the target authorized_keys file

command

Data type: String

the command to restrict to defaults to 'borg serve'

Default value: 'borg serve'

reponame

Data type: String

the name of the repo, defaults to $title

Default value: $title

keys

Data type: Array

the ssh public keys to grant access with this configuration defaults to []

Default value: []

restrict_to_path

Data type: String

restrict repository access to PATH. Access to all sub-directories is granted implicitly; can be set to: '' or no: option not used 'yes': set to ${backuproot}/${reponame} or any path to set. defaults to 'no'

Default value: 'no'

restrict_to_repository

Data type: String

restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. can be set to: '' or no: option not used 'yes': set to ${backuproot}/${reponame} or any path to set. defaults to 'yes'

Default value: 'yes'

append_only

Data type: Boolean

only allow appending to repository segment files Defaults to false

Default value: false

storage_quota

Data type: Optional[String[1]]

Override storage quota of the repository (e.g. 5G, 1.5T). When a new repository is initialized, sets the storage quota on the new repository as well. Default: no quota.

Default value: undef

restricts

Data type: Array

ssh restrictions to set. defaults to ['restrict'] this needs openssh-server > 7.2 if openssh-server < 7.2 use: ['no-port-forwarding','no-X11-forwarding','no-pty', 'no-agent-forwarding','no-user-rc']

Default value: ['restrict']

env_vars

Data type: Hash

Hash of environment variables to set defaults to {}

Default value: {}

borgbackup::repo

This class initializes a backup run

Parameters

The following parameters are available in the borgbackup::repo defined type:

reponame

Data type: String

the name of the repo Defaults to $title

Default value: $title

target

Data type: String

the target where to put the backup (env BORG_REPO)

Default value: ' '

passphrase

Data type: Optional[String]

the passphrase to use for the repo if empty (the default, a random pasphrase is generated and saved gpg encrypted in a git repo. see borgbackup::git for more information.

Default value: undef

passcommand

Data type: String

a command to get the password of the repo defaults to 'default' which creates a passcommand to extract the key from the gitrepo.

Default value: 'default'

env_vars

Data type: Hash

additional environment variables to set before the execution of borg and other commands. defaults to {} for remote repositories, set this to: { BORG_RSH: 'ssh -i /etc/borgbackup/.ssh/YOUR_KEY' }

Default value: {}

encryption

Data type: String

the encryption for the backup. defaults to 'keyfile'

Default value: 'keyfile'

append_only

Data type: Boolean

if true, an append_only repo is created (no purge) defaults to false

Default value: false

storage_quota

Data type: Optional[String[1]]

storage quota to set defaults to undef (no quota)

Default value: undef

archives

Data type: Hash

Hash of archives to create for this repo See ::borgbackup::archive for options $reponame is added as default.

Default value: {}

icinga_old

Data type: Integer

you can run a rudimentary icinga/nagios check to see if a repo is old. this parameter after how many seconds a repo is considered old defaults to 90000 (25h)

Default value: 90000

crontab_define

Data type: String

resource used to create a crontab entry defaults to 'cron' set this to a resource to create systemd timers if you prefer systemd timers if set to '' no cron job will be generated

Default value: 'cron'

crontabs

Data type: Hash

parameters for $crontab_define defaults to {} which if crontab_define is 'cron' (the default) creates a nightly cronjob for doing backup with: cron { "borgbackup run ${reponame}": command => "${configdir}/repo_${reponame}.sh run", user => 'root', hour => fqdn_rand(3,'borgbackup'), minute => fqdn_rand(60,'borgbackup'), }

Default value: {}

check_host

Data type: Optional[String]

if set to an ip address or a hostname, then a function checks if this host is reachable by opening a socket to port 22 (ssh). If this fails, the sope of this define is set to noop. Set checkhost equal to your remote backuphost to avoid a fail of your regular puppetruns if the backuphost is not reachable. defaults to '' means do not check.

Default value: undef

Functions

borgbackup::noop_connection

Type: Ruby 4.x API

Remark: This function is inspired by the trlinkin-noop module (https://forge.puppet.com/trlinkin/noop)

borgbackup::noop_connection(String[1] $bb_server)

Remark: This function is inspired by the trlinkin-noop module (https://forge.puppet.com/trlinkin/noop)

Returns: Boolean true on success

bb_server

Data type: String[1]

the server to check

Tasks

check

verifies the consistency of a borg repository and the corresponding archives

Supports noop? false

Parameters

reponame

Data type: Optional[String]

The name of the repository if not set, $::fqdn is used

info

displays detailed information about the borg repo

Supports noop? false

Parameters

reponame

Data type: Optional[String]

The name of the repository if not set, $::fqdn is used

list

lists the contents of the nodes borg repository

Supports noop? false

Parameters

reponame

Data type: Optional[String]

The name of the repository if not set, $::fqdn is used