NAME

pmgbackup - Proxmox Mail Gateway Backup and Restore Utility

SYNOPSIS

pmgbackup <COMMAND> [ARGS] [OPTIONS]

pmgbackup backup [OPTIONS]

Backup the system configuration.

--notify <always | error | never> (default = never)

Specify when to notify via e-mail

--statistic <boolean> (default = 1)

Backup statistic databases.

pmgbackup help [OPTIONS]

Get help about specified command.

--extra-args <array>

Shows help for a specific command

--verbose <boolean>

Verbose output format.

pmgbackup list

List all stored backups (files named proxmox-backup_Wed Feb 28 03:18:22 PM CET 2024.tgz).

pmgbackup proxmox-backup backup <remote> [OPTIONS]

Create a new backup and prune the backup group afterwards, if configured.

<remote>: <string>

Proxmox Backup Server ID.

--notify <always | error | never> (default = never)

Specify when to notify via e-mail

--statistic <boolean> (default = 1)

Backup statistic databases.

pmgbackup proxmox-backup forget <remote> <backup-id> <backup-time>

Forget a snapshot

<remote>: <string>

Proxmox Backup Server ID.

<backup-id>: <string>

ID (hostname) of backup snapshot

<backup-time>: <string>

Backup time in RFC 3339 format

pmgbackup proxmox-backup job create <remote> [OPTIONS]

Create backup schedule

<remote>: <string>

Proxmox Backup Server ID.

--delay [0-9a-zA-Z. ]+ (default = 5min)

Randomized delay to add to the starttime (RandomizedDelaySec setting of the systemd.timer)

--schedule [0-9a-zA-Z*.:,\-/ ]+ (default = daily)

Schedule for the backup (OnCalendar setting of the systemd.timer)

pmgbackup proxmox-backup job delete <remote>

Delete backup schedule

<remote>: <string>

Proxmox Backup Server ID.

pmgbackup proxmox-backup job show <remote> [FORMAT_OPTIONS]

Get timer specification

<remote>: <string>

Proxmox Backup Server ID.

pmgbackup proxmox-backup list <remote> [FORMAT_OPTIONS]

Get snapshots stored on remote.

<remote>: <string>

Proxmox Backup Server ID.

pmgbackup proxmox-backup remote add <remote> --datastore <string> --server <string> [OPTIONS]

Add Proxmox Backup Server remote instance.

<remote>: <string>

Proxmox Backup Server ID.

--datastore (?:[A-Za-z0-9_][A-Za-z0-9._\-]*)

Proxmox Backup Server datastore name.

--disable <boolean>

Flag to disable (deactivate) the entry.

--fingerprint ([A-Fa-f0-9]{2}:){31}[A-Fa-f0-9]{2}

Certificate SHA 256 fingerprint.

--include-statistics <boolean>

Include statistics in scheduled backups

--keep-daily <N>

Keep backups for the last <N> different days. If there is more than one backup for a single day, only the latest one is kept.

--keep-hourly <N>

Keep backups for the last <N> different hours. If there is more than one backup for a single hour, only the latest one is kept.

--keep-last <N>

Keep the last <N> backups.

--keep-monthly <N>

Keep backups for the last <N> different months. If there is more than one backup for a single month, only the latest one is kept.

--keep-weekly <N>

Keep backups for the last <N> different weeks. If there ismore than one backup for a single week, only the latest one is kept.

--keep-yearly <N>

Keep backups for the last <N> different years. If there is more than one backup for a single year, only the latest one is kept.

--namespace (?:(?:[A-Za-z0-9_][A-Za-z0-9._\-]*)/){0,7}(?:(?:[A-Za-z0-9_][A-Za-z0-9._\-]*))?

Proxmox Backup Server namespace in the datastore, defaults to the root NS.

--notify <always | error | never>

Specify when to notify via e-mail

--password <password>

Password or API token secret for the user on the Proxmox Backup Server.

--port <integer> (1 - 65535) (default = 8007)

Non-default port for Proxmox Backup Server.

--server <string>

Proxmox Backup Server address.

--username (?:[^\s\\@]+\@[^\s\/\\@]+)

Username or API token ID on the Proxmox Backup Server

pmgbackup proxmox-backup remote list [FORMAT_OPTIONS]

List all configured Proxmox Backup Server instances.

pmgbackup proxmox-backup remote remove <remote>

Delete an PBS remote

<remote>: <string>

Profile ID.

pmgbackup proxmox-backup remote set <remote> [OPTIONS]

Update PBS remote settings.

<remote>: <string>

Proxmox Backup Server ID.

--datastore (?:[A-Za-z0-9_][A-Za-z0-9._\-]*)

Proxmox Backup Server datastore name.

--delete <string>

A list of settings you want to delete.

--digest <string>

Prevent changes if current configuration file has a different digest. This can be used to prevent concurrent modifications.

--disable <boolean>

Flag to disable (deactivate) the entry.

--fingerprint ([A-Fa-f0-9]{2}:){31}[A-Fa-f0-9]{2}

Certificate SHA 256 fingerprint.

--include-statistics <boolean>

Include statistics in scheduled backups

--keep-daily <N>

Keep backups for the last <N> different days. If there is more than one backup for a single day, only the latest one is kept.

--keep-hourly <N>

Keep backups for the last <N> different hours. If there is more than one backup for a single hour, only the latest one is kept.

--keep-last <N>

Keep the last <N> backups.

--keep-monthly <N>

Keep backups for the last <N> different months. If there is more than one backup for a single month, only the latest one is kept.

--keep-weekly <N>

Keep backups for the last <N> different weeks. If there ismore than one backup for a single week, only the latest one is kept.

--keep-yearly <N>

Keep backups for the last <N> different years. If there is more than one backup for a single year, only the latest one is kept.

--namespace (?:(?:[A-Za-z0-9_][A-Za-z0-9._\-]*)/){0,7}(?:(?:[A-Za-z0-9_][A-Za-z0-9._\-]*))?

Proxmox Backup Server namespace in the datastore, defaults to the root NS.

--notify <always | error | never>

Specify when to notify via e-mail

--password <password>

Password or API token secret for the user on the Proxmox Backup Server.

--port <integer> (1 - 65535) (default = 8007)

Non-default port for Proxmox Backup Server.

--server <string>

Proxmox Backup Server address.

--username (?:[^\s\\@]+\@[^\s\/\\@]+)

Username or API token ID on the Proxmox Backup Server

pmgbackup proxmox-backup restore <remote> <backup-id> <backup-time> [OPTIONS]

Restore the system configuration.

<remote>: <string>

Proxmox Backup Server ID.

<backup-id>: <string>

backup-id (hostname) of backup snapshot

<backup-time>: <string>

backup-time to restore

--config <boolean> (default = 0)

Restore system configuration.

--database <boolean> (default = 1)

Restore the rule database. This is the default.

--statistic <boolean> (default = 0)

Restore statistic databases. Only considered when you restore the database.

pmgbackup restore --filename <string> [OPTIONS]

Restore the system configuration.

--config <boolean> (default = 0)

Restore system configuration.

--database <boolean> (default = 1)

Restore the rule database. This is the default.

--filename pmg-backup_[0-9A-Za-z_-]+\.tgz

The backup file name.

--statistic <boolean> (default = 0)

Restore statistic databases. Only considered when you restore the database.

DESCRIPTION

Proxmox Mail Gateway 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 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

Proxmox Backup Server

In order to back up your Proxmox Mail Gateway 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.

Remotes

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 Proxmox Mail Gateway.

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 Proxmox Mail Gateway 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 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

Backup Jobs

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.

Scheduled Backups

You can create a Schedule for each remote, to periodically create backups of your Proxmox Mail Gateway - 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.

Copyright and Disclaimer

Copyright © 2007-2024 Proxmox Server Solutions GmbH

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/