docs/maintenance.rst

   1 Maintenance Tasks
   2 =================
   3
   4 .. _maintenance_pruning:
   5
   6 Pruning
   7 -------
   8
   9 Prune lets you specify which backup snapshots you want to keep. The
  10 following retention options are available:
  11
  12 ``keep-last <N>``
  13   Keep the last ``<N>`` backup snapshots.
  14
  15 ``keep-hourly <N>``
  16   Keep backups for the last ``<N>`` hours. If there is more than one
  17   backup for a single hour, only the latest is retained.
  18
  19 ``keep-daily <N>``
  20   Keep backups for the last ``<N>`` days. If there is more than one
  21   backup for a single day, only the latest is retained.
  22
  23 ``keep-weekly <N>``
  24   Keep backups for the last ``<N>`` weeks. If there is more than one
  25   backup for a single week, only the latest is retained.
  26
  27   .. note:: Weeks start on Monday and end on Sunday. The software
  28      uses the `ISO week date`_ system and handles weeks at
  29      the end of the year correctly.
  30
  31 ``keep-monthly <N>``
  32   Keep backups for the last ``<N>`` months. If there is more than one
  33   backup for a single month, only the latest is retained.
  34
  35 ``keep-yearly <N>``
  36   Keep backups for the last ``<N>`` years. If there is more than one
  37   backup for a single year, only the latest is retained.
  38
  39 The retention options are processed in the order given above. Each option
  40 only covers backups within its time period. The next option does not take care
  41 of already covered backups. It will only consider older backups.
  42
  43 Unfinished and incomplete backups will be removed by the prune command, unless
  44 they are newer than the last successful backup. In this case, the last failed
  45 backup is retained.
  46
  47 Prune Simulator
  48 ^^^^^^^^^^^^^^^
  49
  50 You can use the built-in `prune simulator <prune-simulator/index.html>`_
  51 to explore the effect of different retention options with various backup
  52 schedules.
  53
  54 Manual Pruning
  55 ^^^^^^^^^^^^^^
  56
  57 .. image:: images/screenshots/pbs-gui-datastore-content-prune-group.png
  58   :target: _images/pbs-gui-datastore-content-prune-group.png
  59   :align: right
  60   :alt: Prune and garbage collection options
  61
  62 To manually prune a specific backup group, you can use
  63 ``proxmox-backup-client``'s ``prune`` subcommand, discussed in
  64 :ref:`backup-pruning`, or navigate to the **Content** tab of the datastore and
  65 click the scissors icon in the **Actions** column of the relevant backup group.
  66
  67 Prune Schedules
  68 ^^^^^^^^^^^^^^^
  69
  70 To prune on a datastore level, scheduling options can be found under the
  71 **Prune & GC** tab of the datastore. Here you can set retention settings and
  72 edit the interval at which pruning takes place.
  73
  74 .. image:: images/screenshots/pbs-gui-datastore-prunegc.png
  75   :target: _images/pbs-gui-datastore-prunegc.png
  76   :align: right
  77   :alt: Prune and garbage collection options
  78
  79
  80 Retention Settings Example
  81 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  82
  83 The backup frequency and retention of old backups may depend on how often data
  84 changes and how important an older state may be in a specific workload.
  85 When backups act as a company's document archive, there may also be legal
  86 requirements for how long backup snapshots must be kept.
  87
  88 For this example, we assume that you are doing daily backups, have a retention
  89 period of 10 years, and the period between backups stored gradually grows.
  90
  91 - **keep-last:** ``3`` - even if only daily backups, an admin may want to create
  92   an extra one just before or after a big upgrade. Setting keep-last ensures
  93   this.
  94
  95 - **keep-hourly:** not set - for daily backups this is not relevant. You cover
  96   extra manual backups already, with keep-last.
  97
  98 - **keep-daily:** ``13`` - together with keep-last, which covers at least one
  99   day, this ensures that you have at least two weeks of backups.
 100
 101 - **keep-weekly:** ``8`` - ensures that you have at least two full months of
 102   weekly backups.
 103
 104 - **keep-monthly:** ``11`` - together with the previous keep settings, this
 105   ensures that you have at least a year of monthly backups.
 106
 107 - **keep-yearly:** ``9`` - this is for the long term archive. As you covered the
 108   current year with the previous options, you would set this to nine for the
 109   remaining ones, giving you a total of at least 10 years of coverage.
 110
 111 We recommend that you use a higher retention period than is minimally required
 112 by your environment; you can always reduce it if you find it is unnecessarily
 113 high, but you cannot recreate backup snapshots from the past.
 114
 115
 116 .. _maintenance_gc:
 117
 118 Garbage Collection
 119 ------------------
 120
 121 You can monitor and run :ref:`garbage collection <client_garbage-collection>` on the
 122 Proxmox Backup Server using the ``garbage-collection`` subcommand of
 123 ``proxmox-backup-manager``. You can use the ``start`` subcommand to manually
 124 start garbage collection on an entire datastore and the ``status`` subcommand to
 125 see attributes relating to the :ref:`garbage collection <client_garbage-collection>`.
 126
 127 This functionality can also be accessed in the GUI, by navigating to **Prune &
 128 GC** from the top panel of a datastore. From here, you can edit the schedule at
 129 which garbage collection runs and manually start the operation.
 130
 131
 132 .. _maintenance_verification:
 133
 134 Verification
 135 ------------
 136
 137 .. image:: images/screenshots/pbs-gui-datastore-verifyjob-add.png
 138   :target: _images/pbs-gui-datastore-verifyjob-add.png
 139   :align: right
 140   :alt: Adding a verify job
 141
 142 Proxmox Backup Server offers various verification options to ensure that backup
 143 data is intact. Verification is generally carried out through the creation of
 144 verify jobs. These are scheduled tasks that run verification at a given interval
 145 (see :ref:`calendar-event-scheduling`). With these, you can also set whether
 146 already verified snapshots are ignored, as well as set a time period, after
 147 which snapshots are checked again. The interface for creating verify jobs can be
 148 found under the **Verify Jobs** tab of the datastore.
 149
 150 .. Note:: It is recommended that you reverify all backups at least monthly, even
 151   if a previous verification was successful. This is because physical drives
 152   are susceptible to damage over time, which can cause an old, working backup
 153   to become corrupted in a process known as `bit rot/data degradation
 154   <https://en.wikipedia.org/wiki/Data_degradation>`_. It is good practice to
 155   have a regularly recurring (hourly/daily) verification job, which checks new
 156   and expired backups, then another weekly/monthly job that will reverify
 157   everything. This way, there will be no surprises when it comes to restoring
 158   data.
 159
 160 Aside from using verify jobs, you can also run verification manually on entire
 161 datastores, backup groups or snapshots. To do this, navigate to the **Content**
 162 tab of the datastore and either click *Verify All* or select the *V.* icon from
 163 the **Actions** column in the table.
 164
 165 .. _maintenance_notification:
 166
 167 Notifications
 168 -------------
 169
 170 Proxmox Backup Server can send you notification emails about automatically
 171 scheduled verification, garbage-collection and synchronization tasks results.
 172
 173 By default, notifications are sent to the email address configured for the
 174 `root@pam` user. You can instead set this user for each datastore.
 175
 176 .. image:: images/screenshots/pbs-gui-datastore-options.png
 177   :align: right
 178   :alt: Datastore Options
 179
 180 You can also change the level of notification received per task type, the
 181 following options are available:
 182
 183 * Always: send a notification for any scheduled task, independent of the
 184   outcome
 185
 186 * Errors: send a notification for any scheduled task that results in an error
 187
 188 * Never: do not send any notification at all
 189
 190 .. _maintenance_mode:
 191
 192 Maintenance Mode
 193 ----------------
 194
 195 Proxmox Backup Server supports setting `read-only` and `offline`
 196 maintenance modes on a datastore.
 197
 198 Once enabled, depending on the mode, new reads and/or writes to the datastore
 199 are blocked, allowing an administrator to safely execute maintenance tasks, for
 200 example, on the underlying storage.
 201
 202 Internally Proxmox Backup Server tracks whether each datastore access is a
 203 write or read operation, so that it can gracefully enter the respective mode,
 204 by allowing conflicting operations that started before enabling the maintenance
 205 mode to finish.