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