From 9f4f6f72dbf16664d023c45a9e144081d0283fa0 Mon Sep 17 00:00:00 2001 From: Stonewall Jackson Date: Thu, 9 Feb 2023 18:41:03 -0500 Subject: add archiver documentation --- roles/archive_client/README.md | 33 ++++++++++++++++++++ roles/archive_client/defaults/main.yml | 1 - roles/archive_job/README.md | 54 +++++++++++++++++++++++++++++++++ roles/archive_server/README.md | 55 ++++++++++++++++++++++++++++++++++ roles/dev_environment/vars/main.yml | 1 + roles/dovecot/defaults/main.yml | 2 -- roles/freeipa_server/defaults/main.yml | 2 -- roles/gitolite/defaults/main.yml | 1 - 8 files changed, 143 insertions(+), 6 deletions(-) create mode 100644 roles/archive_client/README.md create mode 100644 roles/archive_job/README.md create mode 100644 roles/archive_server/README.md (limited to 'roles') diff --git a/roles/archive_client/README.md b/roles/archive_client/README.md new file mode 100644 index 0000000..2234fb5 --- /dev/null +++ b/roles/archive_client/README.md @@ -0,0 +1,33 @@ +Archive Client +============== + +Description +----------- + +The _archiver_ is my method of performing periodic backups of application data. +The general idea is that applications can write data to a dedicated directory in +`/var/spool/archive`, and the [archive\_server](../archive_server) will rsync any +of these files to a central location each night. + +The `archive_client` role prepares a host to perform [archive jobs](../archive_job). +It adds the host to the `archive_clients` hostgroup and prepares the archive spool +directory. + + +Variables +--------- + +This role **accepts** the following variables: + +Variable | Default | Description +----------------------------------|------------|------------ +`archive_server_user` | s-archiver | Username of the archiver user +`archive_cleanup_on_calendar` | daily | Systemd [calendar interval](https://www.freedesktop.org/software/systemd/man/systemd.time.html#Calendar%20Events) for deleting old archive files +`archive_cleanup_older_than_days` | 7 | Max age of files to keep in the archive spool (days) + + +Usage +----- + +You should not need to call this role directory. It is a dependency of the +[archive\_job](../archive_job) role. diff --git a/roles/archive_client/defaults/main.yml b/roles/archive_client/defaults/main.yml index 42d3aa7..470580b 100644 --- a/roles/archive_client/defaults/main.yml +++ b/roles/archive_client/defaults/main.yml @@ -1,4 +1,3 @@ archive_server_user: s-archiver archive_cleanup_on_calendar: daily archive_cleanup_older_than_days: 7 -archive_server: '{{ groups.archive_servers | first }}' diff --git a/roles/archive_job/README.md b/roles/archive_job/README.md new file mode 100644 index 0000000..04084ff --- /dev/null +++ b/roles/archive_job/README.md @@ -0,0 +1,54 @@ +Archive Job +=========== + +Description +----------- + +The _archiver_ is my method of performing periodic backups of application data. +The general idea is that applications can write data to a dedicated directory in +`/var/spool/archive`, and the [archive\_server](../archive_server) will rsync any +of these files to a central location each night. + +The `archive_job` role creates a systemd timer to perform an application's archive +job at a given calendar interval. The archive command can be specified as an +`argv` to pass to exec, or as a string to be interpreted by the shell. + +Archive commands are `chdir`ed to the appropriate spool directory prior to +execution, so it's safe to to just write to the current working directory. + + +Variables +--------- + +This role **accepts** the following variables: + +Variable | Default | Description +----------------------|------------------------------|------------ +`archive_name` |   | Name of the archive job +`archive_description` | `archive {{ archive_name }}` | Description of the archive job +`archive_user` | root | Unix user that executes the job process +`archive_group` | `{{ archive_user }}` | Unix group that executes the job process +`archive_command` |   | Command to execute (will be passed as-is to `exec`) +`archive_shell` |   | Shell command to execute +`archive_on_calendar` | weekly | Systemd [calendar interval](https://www.freedesktop.org/software/systemd/man/systemd.time.html#Calendar%20Events) for running archive job + + +Usage +----- + +Example playbook: + +````yaml +- name: configure cups archive job + hosts: cups_servers + roles: + - role: archive_job + archive_name: cups + archive_shell: >- + TIMESTAMP=$(date +%Y%m%d%H%M%S); + tar czf "cups-${TIMESTAMP}.tar.gz" + --transform "s|^\.|cups-${TIMESTAMP}|" + -C /etc/cups + ./ppd ./printers.conf + tags: archive +```` diff --git a/roles/archive_server/README.md b/roles/archive_server/README.md new file mode 100644 index 0000000..2871cf4 --- /dev/null +++ b/roles/archive_server/README.md @@ -0,0 +1,55 @@ +Archive Server +============== + +Description +----------- + +The _archiver_ is my method of performing periodic backups of application data. +The general idea is that applications can write data to a dedicated directory in +`/var/spool/archive`, and the archive server will rsync these files to a central +location each night. + +The `archive_server` role generates the _archiver_ script, along with a +corresponding FreeIPA user account and systemd timer. The [archvier script](templates/usr/local/bin/archiver.sh.j2) +runs daily. It iterates over each host in the `archive_clients` hostgroup +and `rsync`s any archive files to a subdirectory `archive_dest_path`, organized +by hostname. + +### Plugins + +For hosts that don't support rsync, such as network equipment, the _archiver_ +provides a plugin-based method of downloading files. Plugins consist of +executable files in the [plugin directory](files/usr/local/libexec/archiver/) +that take a target hostname as the first argument (you can also pass additional +arguments if needed). + +Each line in the archiver [config file](templates/etc/archiver.conf.j2) specifies +a host to archive, along with a plugin invocation. + +Currently, plugins are used to archive [OPNsense](files/usr/local/libexec/archiver/archive_opnsense) +and [EdgeSwitch](files/usr/local/libexec/archiver/archive_edgeswitch) configuration. + +Variables +--------- + +This role **accepts** the following variables: + +Variable | Default | Description +------------------------|--------------|------------ +`archive_dest_path` | /nfs/archive | Path to store archive files +`archive_user` | s-archiver | FreeIPA user account to perform SSH-based rsync (keytab will be retrieved) +`archive_on_calendar` | 23:00:00 | Systemd [calendar interval](https://www.freedesktop.org/software/systemd/man/systemd.time.html#Calendar%20Events) for archiving hosts +`archive_retention_days`| 365 | Number of days to retain archive files + + +Usage +----- + +Example playbook: + +````yaml +- name: configure archive server + hosts: archive_servers + roles: + - archive_server +```` diff --git a/roles/dev_environment/vars/main.yml b/roles/dev_environment/vars/main.yml index 94b6fd6..d2024d1 100644 --- a/roles/dev_environment/vars/main.yml +++ b/roles/dev_environment/vars/main.yml @@ -20,6 +20,7 @@ dev_packages: - discount - python3-pip - postgresql + - whois # sieveconnect dependencies - perl-Authen-SASL - perl-IO-Socket-INET6 diff --git a/roles/dovecot/defaults/main.yml b/roles/dovecot/defaults/main.yml index e4f3842..c055005 100644 --- a/roles/dovecot/defaults/main.yml +++ b/roles/dovecot/defaults/main.yml @@ -9,8 +9,6 @@ dovecot_rspamd_pubkey: '{{ rspamd_pubkey }}' dovecot_access_group: role-imap-access -dovecot_archive_on_calendar: weekly - dovecot_lmtp_port: 24 dovecot_quota_status_port: 10993 diff --git a/roles/freeipa_server/defaults/main.yml b/roles/freeipa_server/defaults/main.yml index 209cd5f..dbadae4 100644 --- a/roles/freeipa_server/defaults/main.yml +++ b/roles/freeipa_server/defaults/main.yml @@ -3,8 +3,6 @@ freeipa_realm: '{{ ansible_domain | upper }}' freeipa_email_domain: '{{ email_domain }}' freeipa_workgroup: WORKGROUP -freeipa_archive_on_calendar: 'Sat *-*-* 04:00:00' - freeipa_dns_forwarders: - 8.8.8.8 - 8.8.4.4 diff --git a/roles/gitolite/defaults/main.yml b/roles/gitolite/defaults/main.yml index 3c50916..d653bcf 100644 --- a/roles/gitolite/defaults/main.yml +++ b/roles/gitolite/defaults/main.yml @@ -4,4 +4,3 @@ gitolite_access_group: role-git-access gitolite_anon_user: nobody gitolite_freeipa_user: s-gitolite gitolite_uid: 1993 -gitolite_archive_on_calendar: weekly -- cgit