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