[[chapter_pmgbackup]]
ifdef::manvolnum[]
pmgbackup(1)
============
:pmg-toplevel:

NAME
----

pmgbackup - Proxmox Mail Gateway Backup and Restore Utility


SYNOPSIS
--------

include::generated/pmgbackup.1-synopsis.adoc[]

DESCRIPTION
-----------
endif::manvolnum[]
ifndef::manvolnum[]
Backup and Restore
==================
:pmg-toplevel:
endif::manvolnum[]

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. The mail logs that the Tracking Center is based on are
not part of the backup either.

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 get 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/`. The cluster configuration
(`cluster.conf`) is never restored, as the cluster membership is bound
to the specific node; rejoin the node instead if needed.

Rule Database::

The mail filter rule database.

Statistic::

All statistical data.

NOTE: Restoring the rule database recreates the complete database,
including all statistical data. Existing statistics are removed and only
restored if the backup contains them and the 'Statistic' option is
selected.

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}.

ifndef::manvolnum[]
[thumbnail="screenshot/pmg-gui-pbs-encryption.png"]
endif::manvolnum[]

You can also encrypt backups, by autogenerating or providing an encryption key
for a Proxmox Backup Server remote.

ifndef::manvolnum[]
[thumbnail="screenshot/pmg-gui-pbs-backup-enc2.png"]
endif::manvolnum[]

NOTE: Keep a copy of the symmetric encryption key in a secure place, or print
it out. Without the encryption key you will not be able to restore an encrypted
backup. Alternatively, you can add a master public key to a remote's
configuration, so that a copy of the symmetric encryption key, encrypted with
the master key, is stored in each backup.

If you configured a master key and later lose the encryption key, you can
recover it from any backup that was created while the master key was set. The
backup holds a copy of the encryption key, encrypted with the master public
key; extract and decrypt that copy with the master private key as described in
the
https://pbs.proxmox.com/docs/backup-client.html#encryption[Proxmox Backup
Server documentation]. Afterwards, re-import the recovered key into the remote
through the 'Encryption' tab of its edit dialog in the GUI, and use it to
restore the affected backups.

.Example addition of a Proxmox Backup Server remote with autogenerated encryption key.
----
# pmgbackup proxmox-backup remote add shared-pbs --datastore public --server backup.cloud-provider.example --user 'pmgbackup@pbs!token' --password --encryption-key autogen
Enter new password: ******
Retype new password: ******
----

The encryption key is stored at `/etc/pmg/pbs/<remote>.enc` and, in a cluster,
is synchronized to all nodes together with the other remote settings. Each
backup snapshot is encrypted with the key that was active when it was created,
so replacing or removing a remote's key makes the snapshots created with the
previous key unrecoverable. Only change the key when you no longer need to
restore older backups.

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[]
include::pmg-copyright.adoc[]
endif::manvolnum[]

