From 0ea60de43651a3ba2b5bc9242bed0e20bd719251 Mon Sep 17 00:00:00 2001 From: Tim Meusel Date: Sun, 28 Apr 2019 21:06:24 +0200 Subject: [PATCH] add puppet-strings docs & generate REFERENCE.md --- REFERENCE.md | 242 ++++++++++++++++++++++++++++++++++++++++ manifests/config.pp | 3 + manifests/init.pp | 68 +++++++++++ manifests/install.pp | 2 + manifests/service.pp | 4 + manifests/ssh_keygen.pp | 28 +++-- 6 files changed, 339 insertions(+), 8 deletions(-) create mode 100644 REFERENCE.md diff --git a/REFERENCE.md b/REFERENCE.md new file mode 100644 index 0000000..55abe1c --- /dev/null +++ b/REFERENCE.md @@ -0,0 +1,242 @@ +# Reference + + +## Table of Contents + +**Classes** + +_Public Classes_ + +* [`borg`](#borg): Main class, includes all other classes. + +_Private Classes_ + +* `borg::config`: +* `borg::install`: This class handles the installation. Avoid modifying private classes. +* `borg::service`: + +**Defined types** + +* [`borg::ssh_keygen`](#borgssh_keygen): Define: ssh_keygen this is based on https://github.com/maestrodev/puppet-ssh_keygen/blob/master/manifests/init.pp + +## Classes + +### borg + +Main class, includes all other classes. + +#### Parameters + +The following parameters are available in the `borg` class. + +##### `package_name` + +Data type: `Variant[String[1],Array[String[1]]]` + +Name of the borg package + +##### `create_prometheus_metrics` + +Data type: `Boolean` + +Enable a postrun command to create prometheus compatible metrics about all backups + +##### `use_upstream_reporter` + +Data type: `Boolean` + +Enable to upstream reporter (see create_prometheus_metrics param) or our vendored version + +##### `update_borg_restore_db_after_backuprun` + +Data type: `Boolean` + +Enable the restore helper from Florian 'Bluewind' Pritz (https://metacpan.org/release/App-BorgRestore) as another postrun command (see also the install_restore_script parameter) + +##### `keep_yearly` + +Data type: `Integer[1]` + +For how many years should we keep our backups? + +##### `keep_monthly` + +Data type: `Integer[1]` + +For how many months should we keep our backups? + +##### `keep_weekly` + +Data type: `Integer[1]` + +For how many weeks should we keep our backups? + +##### `keep_daily` + +Data type: `Integer[1]` + +For how many days should we keep our backups? + +##### `keep_within` + +Data type: `Integer[1]` + +For how many days should we keep all backups we have? + +##### `excludes` + +Data type: `Array[Stdlib::Absolutepath]` + +list of default mountpoints that should be excluded from backups. Every mountpoint needs to be explicitly excluded or included. See also the additional_excludes parameter. + +##### `includes` + +Data type: `Array[Stdlib::Absolutepath]` + +list of default mountpoints that should be included from backups. Every mountpoint needs to be explicitly excluded or included. See also the additional_includes parameter. + +##### `backupserver` + +Data type: `String[1]` + +FQDN for the remote server. Will be written into the local ssh client configuration file. + +##### `install_restore_script` + +Data type: `Boolean` + +Install the restore helper via cpanm. + +##### `restore_script_path` + +Data type: `Stdlib::Absolutepath` + +The path to the restore helper. + +##### `backupdestdir` + +Data type: `String[1]` + +The path on the remote server where the backups should be written to. + +##### `exclude_pattern` + +Data type: `Array[String[1]]` + +We currently support excludes/includes for mountpoints. borg supports also a list of shell glob/regex pattern to filter for files. + +##### `additional_exclude_pattern` + +Data type: `Array[String[1]]` + +Another array of patterns to extend the modules built-in list (`exclude_pattern` parameter). + +Default value: [] + +##### `restore_dependencies` + +Data type: `Array[String[1]]` + +A list of dependencies for the restore helper. + +Default value: [] + +##### `package_ensure` + +Data type: `String[1]` + +Ensure state for the borg package. + +Default value: present + +##### `additional_excludes` + +Data type: `Array[Stdlib::Absolutepath]` + +Another array of mountpoints to extend the modules built-in list (`excludes` parameter). + +Default value: [] + +##### `additional_includes` + +Data type: `Array[Stdlib::Absolutepath]` + +Another array of mountpoints to extend to modules built-in list (`includes` parameter). + +Default value: [] + +##### `username` + +Data type: `String[1]` + +The ssh username to connect to the remote borg service. + +Default value: $facts['hostname'] + +## Defined types + +### borg::ssh_keygen + +Define: ssh_keygen +this is based on https://github.com/maestrodev/puppet-ssh_keygen/blob/master/manifests/init.pp + +#### Parameters + +The following parameters are available in the `borg::ssh_keygen` defined type. + +##### `user` + +Data type: `String[1]` + +The user that will own they key + +Default value: `undef` + +##### `type` + +Data type: `String[1]` + +the openssh key type + +Default value: `undef` + +##### `bits` + +Data type: `Integer` + +The key length + +Default value: `undef` + +##### `home` + +Data type: `String[1]` + +The homedir where we will store the key + +Default value: `undef` + +##### `filename` + +Data type: `String[1]` + +The filename for the new key + +Default value: `undef` + +##### `comment` + +Data type: `String[1]` + +Comments that should be added to the key + +Default value: `undef` + +##### `options` + +Data type: `String[1]` + +Additional ssh-keygen paramters and options + +Default value: `undef` + diff --git a/manifests/config.pp b/manifests/config.pp index d5009cd..d6e368c 100644 --- a/manifests/config.pp +++ b/manifests/config.pp @@ -1,5 +1,8 @@ +# @api private class borg::config { + assert_private() + # script to run the backup file{'/usr/local/bin/borg-backup': ensure => 'file', diff --git a/manifests/init.pp b/manifests/init.pp index 65fb2a9..15b226b 100644 --- a/manifests/init.pp +++ b/manifests/init.pp @@ -1,3 +1,71 @@ +# Main class, includes all other classes. +# +# @param package_name +# Name of the borg package +# +# @param create_prometheus_metrics +# Enable a postrun command to create prometheus compatible metrics about all backups +# +# @param use_upstream_reporter +# Enable to upstream reporter (see create_prometheus_metrics param) or our vendored version +# +# @param update_borg_restore_db_after_backuprun +# Enable the restore helper from Florian 'Bluewind' Pritz (https://metacpan.org/release/App-BorgRestore) as another postrun command (see also the install_restore_script parameter) +# +# @param keep_yearly +# For how many years should we keep our backups? +# +# @param keep_monthly +# For how many months should we keep our backups? +# +# @param keep_weekly +# For how many weeks should we keep our backups? +# +# @param keep_daily +# For how many days should we keep our backups? +# +# @param keep_within +# For how many days should we keep all backups we have? +# +# @param excludes +# list of default mountpoints that should be excluded from backups. Every mountpoint needs to be explicitly excluded or included. See also the additional_excludes parameter. +# +# @param includes +# list of default mountpoints that should be included from backups. Every mountpoint needs to be explicitly excluded or included. See also the additional_includes parameter. +# +# @param backupserver +# FQDN for the remote server. Will be written into the local ssh client configuration file. +# +# @param install_restore_script +# Install the restore helper via cpanm. +# +# @param restore_script_path +# The path to the restore helper. +# +# @param backupdestdir +# The path on the remote server where the backups should be written to. +# +# @param exclude_pattern +# We currently support excludes/includes for mountpoints. borg supports also a list of shell glob/regex pattern to filter for files. +# +# @param additional_exclude_pattern +# Another array of patterns to extend the modules built-in list (`exclude_pattern` parameter). +# +# @param restore_dependencies +# A list of dependencies for the restore helper. +# +# @param package_ensure +# Ensure state for the borg package. +# +# @param additional_excludes +# Another array of mountpoints to extend the modules built-in list (`excludes` parameter). +# +# @param additional_includes +# Another array of mountpoints to extend to modules built-in list (`includes` parameter). +# +# @param username +# The ssh username to connect to the remote borg service. +# class borg ( Variant[String[1],Array[String[1]]] $package_name, Boolean $create_prometheus_metrics, diff --git a/manifests/install.pp b/manifests/install.pp index 7848162..c33fb68 100644 --- a/manifests/install.pp +++ b/manifests/install.pp @@ -2,6 +2,8 @@ # This class handles the installation. Avoid modifying private classes. class borg::install { + assert_private() + if $facts['os']['osfamily'] == 'FreeBSD' { $real_package_provider = 'portsng' } else { diff --git a/manifests/service.pp b/manifests/service.pp index 858a645..eb6dedb 100644 --- a/manifests/service.pp +++ b/manifests/service.pp @@ -1,4 +1,8 @@ +# @api private class borg::service { + + assert_private() + # there isn't any real service # borg runs via a systemd timer # You don't have systemd? GO AWAY! diff --git a/manifests/ssh_keygen.pp b/manifests/ssh_keygen.pp index 114423d..f6a1bce 100644 --- a/manifests/ssh_keygen.pp +++ b/manifests/ssh_keygen.pp @@ -1,12 +1,24 @@ # Define: ssh_keygen -# Parameters: -# $user -# $type -# $bits -# $home -# $filename -# $comment -# $options +# @param user +# The user that will own they key +# +# @param type +# the openssh key type +# +# @param bits +# The key length +# +# @param home +# The homedir where we will store the key +# +# @param filename +# The filename for the new key +# +# @param comment +# Comments that should be added to the key +# +# @param options +# Additional ssh-keygen paramters and options # # this is based on https://github.com/maestrodev/puppet-ssh_keygen/blob/master/manifests/init.pp define borg::ssh_keygen (