docs/managing-remotes.rst

   1 Managing Remotes
   2 ================
   3
   4 .. _backup_remote:
   5
   6 :term:`Remote`
   7 --------------
   8
   9 A remote refers to a separate Proxmox Backup Server installation and a user on that
  10 installation, from which you can `sync` datastores to a local datastore with a
  11 `Sync Job`. You can configure remotes in the web interface, under **Configuration
  12 -> Remotes**. Alternatively, you can use the ``remote`` subcommand. The
  13 configuration information for remotes is stored in the file
  14 ``/etc/proxmox-backup/remote.cfg``.
  15
  16 .. image:: images/screenshots/pbs-gui-remote-add.png
  17   :align: right
  18   :alt: Add a remote
  19
  20 To add a remote, you need its hostname or IP address, a userid and password on
  21 the remote, and its certificate fingerprint. To get the fingerprint, use the
  22 ``proxmox-backup-manager cert info`` command on the remote, or navigate to
  23 **Dashboard** in the remote's web interface and select **Show Fingerprint**.
  24
  25 .. code-block:: console
  26
  27   # proxmox-backup-manager cert info |grep Fingerprint
  28   Fingerprint (sha256): 64:d3:ff:3a:50:38:53:5a:9b:f7:50:...:ab:fe
  29
  30 Using the information specified above, you can add a remote from the **Remotes**
  31 configuration panel, or by using the command:
  32
  33 .. code-block:: console
  34
  35   # proxmox-backup-manager remote create pbs2 --host pbs2.mydomain.example --userid sync@pam --password 'SECRET' --fingerprint 64:d3:ff:3a:50:38:53:5a:9b:f7:50:...:ab:fe
  36
  37 Use the ``list``, ``show``, ``update``, ``remove`` subcommands of
  38 ``proxmox-backup-manager remote`` to manage your remotes:
  39
  40 .. code-block:: console
  41
  42   # proxmox-backup-manager remote update pbs2 --host pbs2.example
  43   # proxmox-backup-manager remote list
  44   ┌──────┬──────────────┬──────────┬───────────────────────────────────────────┬─────────┐
  45   │ name │ host         │ userid   │ fingerprint                               │ comment │
  46   ╞══════╪══════════════╪══════════╪═══════════════════════════════════════════╪═════════╡
  47   │ pbs2 │ pbs2.example │ sync@pam │64:d3:ff:3a:50:38:53:5a:9b:f7:50:...:ab:fe │         │
  48   └──────┴──────────────┴──────────┴───────────────────────────────────────────┴─────────┘
  49   # proxmox-backup-manager remote remove pbs2
  50
  51
  52 .. _syncjobs:
  53
  54 Sync Jobs
  55 ---------
  56
  57 .. image:: images/screenshots/pbs-gui-syncjob-add.png
  58   :align: right
  59   :alt: Add a Sync Job
  60
  61 Sync jobs are configured to pull the contents of a datastore on a **Remote** to
  62 a local datastore. You can manage sync jobs in the web interface, from the
  63 **Sync Jobs** tab of the **Datastore** panel or from that of the Datastore
  64 itself. Alternatively, you can manage them with the ``proxmox-backup-manager
  65 sync-job`` command. The configuration information for sync jobs is stored at
  66 ``/etc/proxmox-backup/sync.cfg``. To create a new sync job, click the add button
  67 in the GUI, or use the ``create`` subcommand. After creating a sync job, you can
  68 either start it manually from the GUI or provide it with a schedule (see
  69 :ref:`calendar-event-scheduling`) to run regularly.
  70
  71 .. code-block:: console
  72
  73   # proxmox-backup-manager sync-job create pbs2-local --remote pbs2 --remote-store local --store local --schedule 'Wed 02:30'
  74   # proxmox-backup-manager sync-job update pbs2-local --comment 'offsite'
  75   # proxmox-backup-manager sync-job list
  76   ┌────────────┬───────┬────────┬──────────────┬───────────┬─────────┐
  77   │ id         │ store │ remote │ remote-store │ schedule  │ comment │
  78   ╞════════════╪═══════╪════════╪══════════════╪═══════════╪═════════╡
  79   │ pbs2-local │ local │ pbs2   │ local        │ Wed 02:30 │ offsite │
  80   └────────────┴───────┴────────┴──────────────┴───────────┴─────────┘
  81   # proxmox-backup-manager sync-job remove pbs2-local
  82
  83 To set up sync jobs, the configuring user needs the following permissions:
  84
  85 #. ``Remote.Read`` on the ``/remote/{remote}/{remote-store}`` path
  86 #. At least ``Datastore.Backup`` on the local target datastore (``/datastore/{store}``)
  87
  88 .. note:: A sync job can only sync backup groups that the configured remote's
  89   user/API token can read. If a remote is configured with a user/API token that
  90   only has ``Datastore.Backup`` privileges, only the limited set of accessible
  91   snapshots owned by that user/API token can be synced.
  92
  93 If the ``remove-vanished`` option is set, ``Datastore.Prune`` is required on
  94 the local datastore as well. If the ``owner`` option is not set (defaulting to
  95 ``root@pam``) or is set to something other than the configuring user,
  96 ``Datastore.Modify`` is required as well.
  97
  98 If the ``group-filter`` option is set, only backup groups matching at least one
  99 of the specified criteria are synced. The available criteria are:
 100
 101 * backup type, for example to only sync groups of the `ct` (Container) type:
 102     .. code-block:: console
 103
 104      # proxmox-backup-manager sync-job update ID --group-filter type:ct
 105 * full group identifier
 106     .. code-block:: console
 107
 108      # proxmox-backup-manager sync-job update ID --group-filter group:vm/100
 109 * regular expression matched against the full group identifier
 110 .. todo:: add example for regex
 111
 112 The same filter is applied to local groups for handling of the
 113 ``remove-vanished`` option.
 114
 115 .. note:: The ``protected`` flag of remote backup snapshots will not be synced.
 116
 117 Bandwidth Limit
 118 ^^^^^^^^^^^^^^^
 119
 120 Syncing a datastore to an archive can produce lots of traffic and impact other
 121 users of the network. So, to avoid network or storage congestion you can limit
 122 the bandwidth of the sync job by setting the ``rate-in`` option either in the
 123 web interface or using the ``proxmox-backup-manager`` command-line tool:
 124
 125 .. code-block:: console
 126
 127     # proxmox-backup-manager sync-job update ID --rate-in 20MiB