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 [[pmgbackup_pbs]]
 101 Proxmox Backup Server
 102 ---------------------
 103
 104 In order to backup your {pmg} configuration on a Proxmox Backup Server you
 105 need configure the instance as backup 'remote'. You can then directly create
 106 and restore backups, as well as create a scheduled 'backup job' to run
 107 regular backups.
 108
 109 [[pmgbackup_pbs_remotes]]
 110 Remotes
 111 ~~~~~~~
 112
 113 ifndef::manvolnum[]
 114 [thumbnail="pmg-gui-pbs-remote.png"]
 115 endif::manvolnum[]
 116
 117
 118 A Proxmox Backup Server remote can be configured using the 'Proxmox Backup
 119 Server' panel in the 'Backup/Restore' menu of the GUI, or by using the
 120 `remote` subcommand of `pmgbackup`.
 121
 122 NOTE: You can use API Tokens in place of a username/password combination.
 123
 124 .Example addition of a Proxmox Backup Server remote with id 'archive'.
 125 ----
 126 # 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
 127 Enter new password: ******
 128 Retype new password: ******
 129 ----
 130
 131 The fingerprint is optional, if the certificate of the Proxmox Backup Server
 132 remote is signed by a CA trusted by {pmg}.
 133
 134 Additionally you can configure `prune-settings` for each remote, giving you
 135 flexible control about how many backups should be stored on the Proxmox Backup
 136 Server over a period of time.
 137
 138 .Setting the prune options for the Proxmox Backup Server remote with id 'archive'.
 139 ----
 140 # pmgbackup remote set archive --keep-last 3 --keep-daily 14 --keep-weekly 8 --keep-monthly 12 --keep-yearly 7
 141 ----
 142
 143 If prune settings are configured, the backup-group of {pmg} is pruned
 144 automatically after each successful backup.
 145
 146 The `notify` and `include-statistics` setting of a remote define the defaults
 147 for notifications and whether to include the statistic database in backups.
 148 They are also used for xref:pmgbackup_pbs_schedule[scheduled backups].
 149
 150 The public settings are stored in `/etc/pmg/pbs/pbs.conf`, sensitive settings,
 151 like passwords are stored in individual files named after the remote inside
 152 `/etc/pmg/pbs/`:
 153
 154 .Configuration Example (`/etc/pmg/pbs/pbs.conf`)
 155 ----
 156 pbs: archive
 157         datastore big
 158         server backup.proxmox.com
 159         fingerprint 09:54:ef:..snip..:88:af:47:fe:4c:3b:cf:8b:26:88:0b:4e:3c:b2
 160         keep-daily 30
 161         keep-last 5
 162         keep-monthly 3
 163         keep-yearly 5
 164         username pmgbackup@pbs!token
 165 ----
 166
 167 [[pmgbackup_pbs_jobs]]
 168 Backup Jobs
 169 ~~~~~~~~~~~
 170
 171 ifndef::manvolnum[]
 172 [thumbnail="pmg-gui-pbs-backup.png", big=1]
 173 endif::manvolnum[]
 174
 175 With a configured remote you can create backups using the GUI or the
 176 `proxmox-backup backup` subcommand of the `pmgbackup` CLI tool.
 177
 178 .Creating a new backup on the Proxmox Backup Server remote with id 'archive'.
 179 ----
 180 # pmgbackup proxmox-backup backup archive
 181 starting update of current backup state
 182 Starting backup: host/pmg/2020-11-16T16:38:39Z
 183 Client name: pmg
 184 Starting backup protocol: Mon Nov 16 16:38:39 2020
 185 Upload directory '/var/lib/pmg/backup/current' to 'pmgbackup@pbs!token@backup.proxmox.com:8007:local' as pmgbackup.pxar.didx
 186 pmgbackup.pxar: had to upload 188.33 KiB of 188.33 KiB in 0.00s, average speed 162.33 MiB/s).
 187 Uploaded backup catalog (145 B)
 188 Duration: 0.06s
 189 End Time: Mon Nov 16 16:38:39 2020
 190 backup finished
 191 starting prune of host/pmg
 192 prune finished
 193 ----
 194
 195 For restoring you can optionally select a particular backup-snapshot to return
 196 to the state of configuration and rules at that time.
 197
 198 On the commandline you can get first a list of available backup snapshots using
 199 the `proxmox-backup list` subcommand:
 200
 201 .Listing available backups from the Proxmox Backup Server remote with id 'archive'.
 202 ----
 203 # pmgbackup proxmox-backup list archive
 204 ┌────────────┬──────────────────────┬────────┐
 205 │ backup-id  │ backup-time          │   size │
 206 ╞════════════╪══════════════════════╪════════╡
 207 │ pmg        │ 2020-11-16T14:03:04Z │ 121910 │
 208 ├────────────┼──────────────────────┼────────┤
 209   ...
 210 └────────────┴──────────────────────┴────────┘
 211 ----
 212
 213 .Restoring a specific backup snapshot
 214 ----
 215 # pmgbackup proxmox-backup restore archive pmg 2020-11-16T14:03:04Z
 216 starting restore of host/pmg/2020-11-16T14:03:04Z from backup
 217 ..snip..
 218 restore finished
 219 ----
 220
 221 You can remove a particular snapshot by using the `forget` sub command, this
 222 allows the Proxmox Backup Server to pick it up during garbage collection.
 223
 224 ----
 225 # pmgbackup proxmox-backup forget archive pmg 2020-11-16T14:03:04Z
 226 ----
 227
 228 TIP: You can configure and access all backup related functionality on both,
 229 the web interface and the command line interface.
 230
 231 [[pmgbackup_pbs_schedule]]
 232 Scheduled Backups
 233 ^^^^^^^^^^^^^^^^^
 234
 235 You can create a `Schedule` for each remote, to periodically create backups of
 236 your {pmg} - for example to run a daily backup at 03:50:00 with a randomized
 237 delay of 15 minutes each day:
 238
 239 ----
 240 # pmgbackup proxmox-backup job create archive --schedule '*-*-* 03:50:00' --delay '15 minutes'
 241 ----
 242
 243 The randomized delay can help to prevent load-peaks on the backup server, if
 244 you have multiple backups, which all should start around the same time.
 245
 246 The schedules are `systemd.timer` units.  See the `systemd.time(7)` man page for
 247 details on the time specification used.
 248
 249
 250 ifdef::manvolnum[]
 251 include::pmg-copyright.adoc[]
 252 endif::manvolnum[]
 253