doc: add osh-backup-acl-keys.sh config reference

2024-09-20 06:55:58 +08:00 · 2021-07-30 11:53:13 +00:00 · 2021-07-30 11:53:13 +00:00 · 9f28dfa977
parent 3c6ce52e8e
commit 9f28dfa977
3 changed files with 179 additions and 19 deletions
--- a/bin/cron/osh-backup-acl-keys.sh
+++ b/bin/cron/osh-backup-acl-keys.sh
@ -20,6 +20,16 @@ else
    gpgcmd="gpg"
 fi

+# setting default values
+LOGFILE=""
+LOG_FACILITY="local6"
+DESTDIR=""
+DAYSTOKEEP="90"
+GPGKEYS=""
+PUSH_REMOTE=""
+PUSH_OPTIONS=""
+
+# building config files list
 config_list=''
 if [ -f "$BASTION_ETC_DIR/osh-backup-acl-keys.conf" ]; then
    config_list="$BASTION_ETC_DIR/osh-backup-acl-keys.conf"
--- a/doc/sphinx/administration/configuration/osh-backup-acl-keys_conf.rst
+++ b/doc/sphinx/administration/configuration/osh-backup-acl-keys_conf.rst
@ -0,0 +1,126 @@
+==================================
+osh-backup-acl-keys.conf reference
+==================================
+
+.. note::
+
+   The osh-backup-acl-keys script is called by cron and is responsible for backing up
+   the bastion configuration, users & groups lists, credentials, and everything needed
+   to be able to restore a functioning bastion from scratch.
+
+.. warning::
+
+   If left unconfigured, this script won't do anything, and you won't have backups,
+   unless this task is handled by some other external system.
+
+Option List
+===========
+
+Logging options
+---------------
+
+These options configure the way the script logs its actions
+
+- `LOGFILE`_
+- `LOG_FACILITY`_
+
+Backup policy options
+---------------------
+
+These options configure the backup policy to apply
+
+- `DESTDIR`_
+- `DAYSTOKEEP`_
+- `GPGKEYS`_
+
+Remote backup options
+---------------------
+
+These options configure how the script should push the encrypted backups to a remote system
+
+- `PUSH_REMOTE`_
+- `PUSH_OPTIONS`_
+
+Option Reference
+================
+
+Logging
+-------
+
+LOGFILE
+*******
+
+:Type: ``string, path to a file``
+
+:Default: ``""``
+
+File where the logs will be written to (don't forget to configure ``logrotate``!). Note that using this configuration option, the script will directly write to the file, without using syslog. If empty, won't log directly to any file.
+
+LOG_FACILITY
+************
+
+:Type: ``string``
+
+:Default: ``"local6"``
+
+The syslog facility to use for logging the script output. If set to the empty string, we'll not log through syslog at all. If this configuration option is missing from your config file altogether, the default value will be used (local6), which means that we'll log to syslog.
+
+Backup policy
+-------------
+
+DESTDIR
+*******
+
+:Type: ``path to a folder``
+
+:Default: ``""``
+
+:Example: ``"/root/backups"``
+
+Folder where to put the backup artefacts (``.tar.gz`` files). This folder will be created if needed. If empty or omitted, the script won't run: this option is mandatory.
+
+DAYSTOKEEP
+**********
+
+:Type: ``int > 0``
+
+:Default: ``90``
+
+Number of days to keep the old backups on the filesystem before deleting them.
+
+GPGKEYS
+*******
+
+:Type: ``string, space-separated list of GPG keys IDs``
+
+:Default: ``""``
+
+:Example: ``"41FDB9C7 DA97EFD1 339483FF"``
+
+List of public GPG keys to encrypt to (see ``gpg --list-keys``), these must be separated by spaces. Note that if this option is empty or omitted, backup artefacts will NOT be encrypted!
+
+Remote backup
+-------------
+
+PUSH_REMOTE
+***********
+
+:Type: ``string``
+
+:Default: ``""``
+
+:Example: ``"push@1.2.3.4:~/backup/"``
+
+The ``scp`` remote host push backups to. If empty or missing, won't push backups. This will also be the case if the ``GPGKEYS`` option above is empty or missing, because we will never push unencrypted backups. Don't forget to put a trailing ``/`` (except if you want to push to the remote ``$HOME``, in which case ending with a simple ``:`` works, as per standard ``scp``).
+
+PUSH_OPTIONS
+************
+
+:Type: ``string``
+
+:Default: ``""``
+
+:Example: ``"-i $HOME/.ssh/id_backup"``
+
+Additional options to pass to ``scp``, if needed.
+
--- a/etc/bastion/osh-backup-acl-keys.conf.dist
+++ b/etc/bastion/osh-backup-acl-keys.conf.dist
@ -1,30 +1,54 @@
-# THIS MUST BE A VALID SHELL SCRIPT
+###################################################################
+## Config for /opt/bastion/bin/cron/osh-backup-acl-keys.sh, the script
+## responsible for backing up the needed files to be able to rebuild
+## this bastion from scratch.
+## As it'll be sourced, THIS FILE MUST BE A VALID SHELL SCRIPT.
+###################################################################
 #
-# LOGFILE: file where to put script logs, if not defined, will not log into a file
-#LOGFILE=/var/log/bastion/osh-backup-acl-keys.log
+# > Logging
+# >> These options configure the way the script logs its actions
 #
-# LOG_FACILITY: will use syslog with the following facility to log, won't use syslog otherwise
-LOG_FACILITY=local6
+# LOGFILE (string, path to a file)
+#    DESC: File where the logs will be written to (don't forget to configure ``logrotate``!). Note that using this configuration option, the script will directly write to the file, without using syslog. If empty, won't log directly to any file.
+# DEFAULT: ""
+LOGFILE=""
 #
-# DESTDIR: directory where to put the .tar.gz files (it'll be created if needed)
-DESTDIR=/root/backups
+# LOG_FACILITY (string)
+#    DESC: The syslog facility to use for logging the script output. If set to the empty string, we'll not log through syslog at all. If this configuration option is missing from your config file altogether, the default value will be used (local6), which means that we'll log to syslog.
+# DEFAULT: "local6"
+LOG_FACILITY="local6"
 #
-# DAYSTOKEEP: number of days to keep backups for
+# > Backup policy
+# >> These options configure the backup policy to apply
+#
+# DESTDIR (path to a folder)
+#    DESC: Folder where to put the backup artefacts (``.tar.gz`` files). This folder will be created if needed. If empty or omitted, the script won't run: this option is mandatory.
+# EXAMPLE: "/root/backups"
+# DEFAULT: ""
+DESTDIR=""
+#
+# DAYSTOKEEP (int > 0)
+#    DESC: Number of days to keep the old backups on the filesystem before deleting them.
+# DEFAULT: 90
 DAYSTOKEEP=90
 #
-# GPGKEYS: list of gpg keys to encrypt to (see gpg --list-keys), separated by spaces.
-# example: GPGKEYS="41FDB9C7 DA97EFD1 339483FF"
-# if omitted or empty, archives will NOT be encrypted
+# GPGKEYS (string, space-separated list of GPG keys IDs)
+# DESC: List of public GPG keys to encrypt to (see ``gpg --list-keys``), these must be separated by spaces. Note that if this option is empty or omitted, backup artefacts will NOT be encrypted!
+# EXAMPLE: "41FDB9C7 DA97EFD1 339483FF"
+# DEFAULT: ""
 GPGKEYS=""
 #
-# PUSH_REMOTE: scp remote host push backups to
-# example: "push@1.2.3.4:~/backup/"
-# important: this will ONLY be enabled if GPGKEYS is not empty above, because
-# we will never push unencrypted backups!
-# Also, don't forget to put a trailing / (except if you want to push to the
-# remote HOME, in which case ending with a simple : works)
+# > Remote backup
+# >> These options configure how the script should push the encrypted backups to a remote system
+#
+# PUSH_REMOTE (string)
+#    DESC: The ``scp`` remote host push backups to. If empty or missing, won't push backups. This will also be the case if the ``GPGKEYS`` option above is empty or missing, because we will never push unencrypted backups. Don't forget to put a trailing ``/`` (except if you want to push to the remote ``$HOME``, in which case ending with a simple ``:`` works, as per standard ``scp``).
+# EXAMPLE: "push@1.2.3.4:~/backup/"
+# DEFAULT: ""
 PUSH_REMOTE=""
 #
-# PUSH_OPTIONS: additional options to pass to scp
-# example: "-i $HOME/.ssh/id_backup"
+# PUSH_OPTIONS (string)
+#    DESC: Additional options to pass to ``scp``, if needed.
+# EXAMPLE: "-i $HOME/.ssh/id_backup"
+# DEFAULT: ""
 PUSH_OPTIONS=""