From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by lists.proxmox.com (Postfix) with ESMTPS id 2633260258 for ; Mon, 16 Nov 2020 18:57:54 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 228889964 for ; Mon, 16 Nov 2020 18:57:54 +0100 (CET) Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com [212.186.127.180]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by firstgate.proxmox.com (Proxmox) with ESMTPS id 3B8099959 for ; Mon, 16 Nov 2020 18:57:53 +0100 (CET) Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1]) by proxmox-new.maurer-it.com (Proxmox) with ESMTP id 036484373D for ; Mon, 16 Nov 2020 18:57:53 +0100 (CET) From: Stoiko Ivanov To: pmg-devel@lists.proxmox.com Date: Mon, 16 Nov 2020 18:57:39 +0100 Message-Id: <20201116175739.28024-3-s.ivanov@proxmox.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20201116175739.28024-1-s.ivanov@proxmox.com> References: <20201116175739.28024-1-s.ivanov@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-SPAM-LEVEL: Spam detection results: 0 AWL 0.090 Adjusted score from AWL reputation of From: address KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record URIBL_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to URIBL was blocked. See http://wiki.apache.org/spamassassin/DnsBlocklists#dnsbl-block for more information. [proxmox.com] Subject: [pmg-devel] [PATCH pmg-docs 2/2] add short documentation on PBS backups X-BeenThere: pmg-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox Mail Gateway development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 16 Nov 2020 17:57:54 -0000 This patch adds a short documentation for the PBS integration in PMG. It aims to provide a very terse walkthrough the newly created pmgbackup subcommands. updated screenshot (and the newly referenced one) will be provided off-list due to their size. Signed-off-by: Stoiko Ivanov --- pmgbackup.adoc | 124 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 121 insertions(+), 3 deletions(-) diff --git a/pmgbackup.adoc b/pmgbackup.adoc index 3e8a8c6..276b09f 100644 --- a/pmgbackup.adoc +++ b/pmgbackup.adoc @@ -35,8 +35,15 @@ mail filter rules and the statistic database. NOTE: The backup does not include the network setup, and also no mail data from the postfix queue or the spam or virus quarantine. -You can create a backup by simply pressing the 'Backup' button on the -GUI, or by using the command line interface: +Backups can be created locally or stored on a +https://www.proxmox.com/en/proxmox-backup-server[Proxmox Backup Server] +instance. + +Local Backups +------------- + +You can create a backup by simply pressing the 'Backup' button in the 'Local +Backup/Restore' tab on the GUI, or by using the command line interface: ---- # pmgbackup backup @@ -44,7 +51,7 @@ starting backup to: /var/lib/pmg/backup/pmg-backup_2018_01_04_5A4E0436.tgz backup finished ---- -Backups are stored inside directory `/var/lib/pmg/backup/`. It is +Local backups are stored inside directory `/var/lib/pmg/backup/`. It is usually best to mount a remote file system to that directory, so that the resulting backups gets stored remotely. @@ -90,7 +97,118 @@ Analyzing/Upgrading existing Databases...done restore finished ---- +Proxmox Backup Server +--------------------- + +In order to backup your {pmg} configuration on a Proxmox Backup Server you +need configure the instance as backup 'remote'. You can then directly create +and restore backups, as well as create a scheduled 'backup job' to run +regular backups. + +Remotes +~~~~~~~ + +ifndef::manvolnum[] +[thumbnail="pmg-gui-pbs-remote.png", big=1] +endif::manvolnum[] + +A Proxmox Backup Server remote can be configured using the 'Proxmox Backup +Server' panel in the 'Backup/Restore' menu of the GUI, or by using the +`remote` subcommand of `pmgbackup`: + +---- +# pmgbackup remote add backup --datastore big --server backup.proxmox.com --user 'pmgbackup@pbs!token' --password --fingerprint 09:54:ef:..snip..:88:af:47:fe:4c:3b:cf:8b:26:88:0b:4e:3c:b2 +Enter new password: ****** +Retype new password: ****** +---- + +You can use API Tokens in place of a username/password combination. + +If the remote certificate is signed by a CA trusted by {pmg} the fingerprint +is not required. + +Additionally you can configure `prune-settings` for each remote to control +how many backups should be stored on the Proxmox Backup Server: + +---- +# pmgbackup remote set backup --keep-last 5 --keep-daily 30 --keep-yearly 5 +---- +The backup-group is pruned after each successful backup according to the +configured settings. + +The public settings are stored in `/etc/pmg/pbs/pbs.conf`, sensitive settings, +like passwords are stored in individual files named after the remote inside +`/etc/pmg/pbs/`: + +.Configuration Example (`/etc/pmg/pbs/pbs.conf`) +---- +pbs: backup + datastore big + server backup.proxmox.com + fingerprint 09:54:ef:..snip..:88:af:47:fe:4c:3b:cf:8b:26:88:0b:4e:3c:b2 + keep-daily 30 + keep-last 5 + keep-monthly 3 + keep-yearly 5 + username pmgbackup@pbs!token +---- + +Backup Jobs +~~~~~~~~~~~ + +With a configured remote you can create backups using the GUI or the +`pbsjob` subcommand of `pmgbackup`: + +---- +# pmgbackup pbsjob run backup +starting update of current backup state +Starting backup: host/pmg/2020-11-16T16:38:39Z +Client name: pmg +Starting backup protocol: Mon Nov 16 16:38:39 2020 +Upload directory '/var/lib/pmg/backup/current' to 'pmgbackup@pbs!token@backup.proxmox.com:8007:local' as pmgbackup.pxar.didx +pmgbackup.pxar: had to upload 188.33 KiB of 188.33 KiB in 0.00s, average speed 162.33 MiB/s). +Uploaded backup catalog (145 B) +Duration: 0.06s +End Time: Mon Nov 16 16:38:39 2020 +backup finished +starting prune of host/pmg +prune finished +---- + +For restoring you can optionally select a particular backup-snapshot to return +to the state of configuration and rules at that time. If you don't provide one +the latest backup is restored: + +---- +# pmgbackup pbsjob restore backup --backup-time 2020-11-16T14:03:04Z +starting restore of host/pmg/2020-11-16T14:03:04Z from backup +..snip.. +restore finished +---- + +You can mark a particular snapshot for garbage collection by Proxmox Backup +Server, by forgetting it: + +---- +# pmgbackup pbsjob forget backup 2020-11-16T14:03:04Z +---- + +Scheduled Backups +^^^^^^^^^^^^^^^^^ + +You can create a `Schedule` for each remote, to periodically create backups of +your {pmg} - for example to run a daily backup at 03:50:00 with a randomized +delay of 15 minutes each day: + +---- +# pmgbackup pbsjob create backup --schedule '*-*-* 03:50:00' --delay '15 minutes' +---- + +The randomized delay can help to prevent load-peaks on the backup server, if +you have multiple backups, which all should start around the same time. +The schedules are `systemd.timer` units. See the `systemd.time(7)` man page for +details on the time specification used. ifdef::manvolnum[] -- 2.20.1