:pmg-toplevel:
endif::manvolnum[]
-Please fix this page.
+ifndef::manvolnum[]
+[thumbnail="screenshot/pmg-gui-backup.png", big=1]
+endif::manvolnum[]
+
+{pmg} includes the ability to back up and restore the
+configuration. This includes the complete config from `/etc/pmg/`, the
+mail filter rules, and the statistic database.
+
+NOTE: The backup does not include the network setup, nor does it
+contain mail data from the postfix queue or the spam and virus
+quarantines.
+
+Backups can be created locally or stored on a
+https://www.proxmox.com/en/proxmox-backup-server/overview[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
+starting backup to: /var/lib/pmg/backup/pmg-backup_2018_01_04_5A4E0436.tgz
+backup finished
+----
+
+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.
+
+You can list the contents of that directory with:
+
+----
+# pmgbackup list
+....
+pmg-backup_2017_11_10_5A05D4B9.tgz 17012
+pmg-backup_2017_11_13_5A09676A.tgz 16831
+pmg-backup_2018_01_04_5A4E0436.tgz 21514
+----
+
+Restores are also possible using the GUI or command line, and you can
+select which parts you want to restore:
+
+System Configuration::
+
+Basically the contents of `/etc/pmg/`.
+
+Rule Database::
+
+The mail filter rule database.
+
+Statistic::
+
+All statistical data.
+
+For example, you can selectively restore the mail filter rules from an
+older backup:
+
+----
+# pmgbackup restore --filename pmg-backup_2018_01_04_5A4E0436.tgz --database
+starting restore: /var/lib/pmg/backup/pmg-backup_2018_01_04_5A4E0436.tgz
+config_backup.tar: OK
+Proxmox_ruledb.sql: OK
+Proxmox_statdb.sql: OK
+version.txt: OK
+Destroy existing rule database
+Create new database
+run analyze to speed up database queries
+Analyzing/Upgrading existing Databases...done
+restore finished
+----
+
+[[pmgbackup_pbs]]
+Proxmox Backup Server
+---------------------
+
+In order to back up your {pmg} configuration on a Proxmox Backup
+Server, you first need to configure the instance as a backup 'remote'.
+You can then directly create and restore backups, as well as create a
+scheduled 'backup job' to run regular backups.
+
+[[pmgbackup_pbs_remotes]]
+Remotes
+~~~~~~~
+
+ifndef::manvolnum[]
+[thumbnail="screenshot/pmg-gui-pbs-remote.png"]
+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`.
+
+NOTE: You can use API Tokens in place of a username/password combination.
+
+.Example addition of a Proxmox Backup Server remote with id 'archive'.
+----
+# pmgbackup proxmox-backup remote add archive --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: ******
+----
+
+The fingerprint is optional, if the certificate of the Proxmox Backup Server
+remote is signed by a CA trusted by {pmg}.
+
+Additionally, you can configure `prune-settings` for each remote, giving you
+flexible control over how many backups should be stored on the Proxmox Backup
+Server over a specific period of time.
+
+.Setting the prune options for the Proxmox Backup Server remote with id 'archive'.
+----
+# pmgbackup remote set archive --keep-last 3 --keep-daily 14 --keep-weekly 8 --keep-monthly 12 --keep-yearly 7
+----
+
+If prune settings are configured, the backup-group of {pmg} is pruned
+automatically after each successful backup.
+
+The `notify` and `include-statistics` settings of a remote define the defaults
+for notifications and whether to include the statistic database in backups.
+They are also used for xref:pmgbackup_pbs_schedule[scheduled backups].
+
+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: archive
+ 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
+----
+
+[[pmgbackup_pbs_jobs]]
+Backup Jobs
+~~~~~~~~~~~
+
+ifndef::manvolnum[]
+[thumbnail="screenshot/pmg-gui-pbs-backup.png", big=1]
+endif::manvolnum[]
+
+With a configured remote, you can create backups using the GUI or the
+`proxmox-backup backup` subcommand of the `pmgbackup` CLI tool.
+
+.Creating a new backup on the Proxmox Backup Server remote with id 'archive'.
+----
+# pmgbackup proxmox-backup backup archive
+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.
+
+From the command line, you can get a list of available backup snapshots using
+the `proxmox-backup list` subcommand:
+
+.Listing available backups from the Proxmox Backup Server remote with id 'archive'.
+----
+# pmgbackup proxmox-backup list archive
+┌────────────┬──────────────────────┬────────┐
+│ backup-id │ backup-time │ size │
+╞════════════╪══════════════════════╪════════╡
+│ pmg │ 2020-11-16T14:03:04Z │ 121910 │
+├────────────┼──────────────────────┼────────┤
+ ...
+└────────────┴──────────────────────┴────────┘
+----
+
+.Restoring a specific backup snapshot
+----
+# pmgbackup proxmox-backup restore archive pmg 2020-11-16T14:03:04Z
+starting restore of host/pmg/2020-11-16T14:03:04Z from backup
+..snip..
+restore finished
+----
+
+You can remove a particular snapshot by using the `forget` subcommand. This
+allows the Proxmox Backup Server to remove it during garbage collection.
+
+----
+# pmgbackup proxmox-backup forget archive pmg 2020-11-16T14:03:04Z
+----
+
+TIP: You can configure and access all backup-related functionality on
+both the web interface and the command-line interface.
+
+[[pmgbackup_pbs_schedule]]
+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 proxmox-backup job create archive --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 should all 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[]
projects / pmg-docs.git / blobdiff