Merge pull request #21 from bastelfreak/docs

add puppet-strings docs & generate REFERENCE.md

REFERENCE.md

@@ -0,0 +1,242 @@
+# Reference
+<!-- DO NOT EDIT: This document was generated by Puppet Strings -->
+
+## 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`
+

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',

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,

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 {

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!

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 (