pmgbackup.adoc

   1 [[chapter_pmgbackup]]
   2 ifdef::manvolnum[]
   3 pmgbackup(1)
   4 ============
   5 :pmg-toplevel:
   6
   7 NAME
   8 ----
   9
  10 pmgbackup - Proxmox Mail Gateway Backup and Restore Utility
  11
  12
  13 SYNOPSIS
  14 --------
  15
  16 include::pmgbackup.1-synopsis.adoc[]
  17
  18 DESCRIPTION
  19 -----------
  20 endif::manvolnum[]
  21 ifndef::manvolnum[]
  22 Backup and Restore
  23 ==================
  24 :pmg-toplevel:
  25 endif::manvolnum[]
  26
  27 ifndef::manvolnum[]
  28 [thumbnail="pmg-gui-backup.png", big=1]
  29 endif::manvolnum[]
  30
  31 {pmg} includes the ability to back up and restore the
  32 configuration. This includes the complete config from `/etc/pmg/`, the
  33 mail filter rules, and the statistic database.
  34
  35 NOTE: The backup does not include the network setup, nor does it
  36 contain mail data from the postfix queue or the spam and virus
  37 quarantines.
  38
  39 Backups can be created locally or stored on a
  40 https://www.proxmox.com/en/proxmox-backup-server[Proxmox Backup Server]
  41 instance.
  42
  43 Local Backups
  44 -------------
  45
  46 You can create a backup by simply pressing the 'Backup' button in the 'Local
  47 Backup/Restore' tab on the GUI, or by using the command line interface:
  48
  49 ----
  50 # pmgbackup backup
  51 starting backup to: /var/lib/pmg/backup/pmg-backup_2018_01_04_5A4E0436.tgz
  52 backup finished
  53 ----
  54
  55 Local backups are stored inside directory `/var/lib/pmg/backup/`. It is
  56 usually best to mount a remote file system to that directory, so that
  57 the resulting backups gets stored remotely.
  58
  59 You can list the contents of that directory with:
  60
  61 ----
  62 # pmgbackup list
  63 ....
  64 pmg-backup_2017_11_10_5A05D4B9.tgz      17012
  65 pmg-backup_2017_11_13_5A09676A.tgz      16831
  66 pmg-backup_2018_01_04_5A4E0436.tgz      21514
  67 ----
  68
  69 Restores are also possible using the GUI or command line, and you can
  70 select which parts you want to restore:
  71
  72 System Configuration::
  73
  74 Basically the contents of `/etc/pmg/`.
  75
  76 Rule Database::
  77
  78 The mail filter rule database.
  79
  80 Statistic::
  81
  82 All statistical data.
  83
  84 For example, you can selectively restore the mail filter rules from an
  85 older backup:
  86
  87 ----
  88 # pmgbackup restore --filename pmg-backup_2018_01_04_5A4E0436.tgz --database
  89 starting restore: /var/lib/pmg/backup/pmg-backup_2018_01_04_5A4E0436.tgz
  90 config_backup.tar: OK
  91 Proxmox_ruledb.sql: OK
  92 Proxmox_statdb.sql: OK
  93 version.txt: OK
  94 Destroy existing rule database
  95 Create new database
  96 run analyze to speed up database queries
  97 Analyzing/Upgrading existing Databases...done
  98 restore finished
  99 ----
 100
 101 [[pmgbackup_pbs]]
 102 Proxmox Backup Server
 103 ---------------------
 104
 105 In order to back up your {pmg} configuration on a Proxmox Backup
 106 Server, you first need to configure the instance as a backup 'remote'.
 107 You can then directly create and restore backups, as well as create a
 108 scheduled 'backup job' to run regular backups.
 109
 110 [[pmgbackup_pbs_remotes]]
 111 Remotes
 112 ~~~~~~~
 113
 114 ifndef::manvolnum[]
 115 [thumbnail="pmg-gui-pbs-remote.png"]
 116 endif::manvolnum[]
 117
 118
 119 A Proxmox Backup Server remote can be configured using the 'Proxmox Backup
 120 Server' panel in the 'Backup/Restore' menu of the GUI, or by using the
 121 `remote` subcommand of `pmgbackup`.
 122
 123 NOTE: You can use API Tokens in place of a username/password combination.
 124
 125 .Example addition of a Proxmox Backup Server remote with id 'archive'.
 126 ----
 127 # 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
 128 Enter new password: ******
 129 Retype new password: ******
 130 ----
 131
 132 The fingerprint is optional, if the certificate of the Proxmox Backup Server
 133 remote is signed by a CA trusted by {pmg}.
 134
 135 Additionally, you can configure `prune-settings` for each remote, giving you
 136 flexible control over how many backups should be stored on the Proxmox Backup
 137 Server over a specific period of time.
 138
 139 .Setting the prune options for the Proxmox Backup Server remote with id 'archive'.
 140 ----
 141 # pmgbackup remote set archive --keep-last 3 --keep-daily 14 --keep-weekly 8 --keep-monthly 12 --keep-yearly 7
 142 ----
 143
 144 If prune settings are configured, the backup-group of {pmg} is pruned
 145 automatically after each successful backup.
 146
 147 The `notify` and `include-statistics` settings of a remote define the defaults
 148 for notifications and whether to include the statistic database in backups.
 149 They are also used for xref:pmgbackup_pbs_schedule[scheduled backups].
 150
 151 The public settings are stored in `/etc/pmg/pbs/pbs.conf`. Sensitive settings,
 152 like passwords are stored in individual files named after the remote inside
 153 `/etc/pmg/pbs/`:
 154
 155 .Configuration Example (`/etc/pmg/pbs/pbs.conf`)
 156 ----
 157 pbs: archive
 158         datastore big
 159         server backup.proxmox.com
 160         fingerprint 09:54:ef:..snip..:88:af:47:fe:4c:3b:cf:8b:26:88:0b:4e:3c:b2
 161         keep-daily 30
 162         keep-last 5
 163         keep-monthly 3
 164         keep-yearly 5
 165         username pmgbackup@pbs!token
 166 ----
 167
 168 [[pmgbackup_pbs_jobs]]
 169 Backup Jobs
 170 ~~~~~~~~~~~
 171
 172 ifndef::manvolnum[]
 173 [thumbnail="pmg-gui-pbs-backup.png", big=1]
 174 endif::manvolnum[]
 175
 176 With a configured remote, you can create backups using the GUI or the
 177 `proxmox-backup backup` subcommand of the `pmgbackup` CLI tool.
 178
 179 .Creating a new backup on the Proxmox Backup Server remote with id 'archive'.
 180 ----
 181 # pmgbackup proxmox-backup backup archive
 182 starting update of current backup state
 183 Starting backup: host/pmg/2020-11-16T16:38:39Z
 184 Client name: pmg
 185 Starting backup protocol: Mon Nov 16 16:38:39 2020
 186 Upload directory '/var/lib/pmg/backup/current' to 'pmgbackup@pbs!token@backup.proxmox.com:8007:local' as pmgbackup.pxar.didx
 187 pmgbackup.pxar: had to upload 188.33 KiB of 188.33 KiB in 0.00s, average speed 162.33 MiB/s).
 188 Uploaded backup catalog (145 B)
 189 Duration: 0.06s
 190 End Time: Mon Nov 16 16:38:39 2020
 191 backup finished
 192 starting prune of host/pmg
 193 prune finished
 194 ----
 195
 196 For restoring, you can optionally select a particular backup-snapshot to return
 197 to the state of configuration and rules at that time.
 198
 199 From the command line, you can get a list of available backup snapshots using
 200 the `proxmox-backup list` subcommand:
 201
 202 .Listing available backups from the Proxmox Backup Server remote with id 'archive'.
 203 ----
 204 # pmgbackup proxmox-backup list archive
 205 ┌────────────┬──────────────────────┬────────┐
 206 │ backup-id  │ backup-time          │   size │
 207 ╞════════════╪══════════════════════╪════════╡
 208 │ pmg        │ 2020-11-16T14:03:04Z │ 121910 │
 209 ├────────────┼──────────────────────┼────────┤
 210   ...
 211 └────────────┴──────────────────────┴────────┘
 212 ----
 213
 214 .Restoring a specific backup snapshot
 215 ----
 216 # pmgbackup proxmox-backup restore archive pmg 2020-11-16T14:03:04Z
 217 starting restore of host/pmg/2020-11-16T14:03:04Z from backup
 218 ..snip..
 219 restore finished
 220 ----
 221
 222 You can remove a particular snapshot by using the `forget` subcommand. This
 223 allows the Proxmox Backup Server to remove it during garbage collection.
 224
 225 ----
 226 # pmgbackup proxmox-backup forget archive pmg 2020-11-16T14:03:04Z
 227 ----
 228
 229 TIP: You can configure and access all backup-related functionality on
 230 both the web interface and the command line interface.
 231
 232 [[pmgbackup_pbs_schedule]]
 233 Scheduled Backups
 234 ^^^^^^^^^^^^^^^^^
 235
 236 You can create a `Schedule` for each remote, to periodically create backups of
 237 your {pmg} - for example to run a daily backup at 03:50:00 with a randomized
 238 delay of 15 minutes each day:
 239
 240 ----
 241 # pmgbackup proxmox-backup job create archive --schedule '*-*-* 03:50:00' --delay '15 minutes'
 242 ----
 243
 244 The randomized delay can help to prevent load-peaks on the backup server, if
 245 you have multiple backups which should all start around the same time.
 246
 247 The schedules are `systemd.timer` units. See the `systemd.time(7)` man page for
 248 details on the time specification used.
 249
 250
 251 ifdef::manvolnum[]
 252 include::pmg-copyright.adoc[]
 253 endif::manvolnum[]
 254