docs: add/update tc related screenshots & content, document tc for sync-job

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>

diff --git a/docs/images/screenshots/pbs-gui-syncjob-add.png b/docs/images/screenshots/pbs-gui-syncjob-add.png
index d47f8492b7b0e0cfab7391af14efc13e9bf5b6d9..442afb5b34b873c647e3b455befe1c5671c30b46 100644 (file)
Binary files a/docs/images/screenshots/pbs-gui-syncjob-add.png and b/docs/images/screenshots/pbs-gui-syncjob-add.png differ

diff --git a/docs/images/screenshots/pbs-gui-traffic-control-add.png b/docs/images/screenshots/pbs-gui-traffic-control-add.png
new file mode 100644 (file)
index 0000000..058b322
Binary files /dev/null and b/docs/images/screenshots/pbs-gui-traffic-control-add.png differ

diff --git a/docs/managing-remotes.rst b/docs/managing-remotes.rst
index 9f07abb36fc951d261490caba04dbf080023a52f..fbd58dcbc7b6af5210ae3a8479896e94f0751235 100644 (file)
--- a/docs/managing-remotes.rst
+++ b/docs/managing-remotes.rst
@@ -85,6 +85,11 @@ To set up sync jobs, the configuring user needs the following permissions:
 #. ``Remote.Read`` on the ``/remote/{remote}/{remote-store}`` path
 #. At least ``Datastore.Backup`` on the local target datastore (``/datastore/{store}``)
 
+.. note:: A sync job can only sync backup groups that the configured remote's
+  user/API token can read. If a remote is configured with a user/API token that
+  only has ``Datastore.Backup`` privileges, only the limited set of accessible
+  snapshots owned by that user/API token can be synced.
+
 If the ``remove-vanished`` option is set, ``Datastore.Prune`` is required on
 the local datastore as well. If the ``owner`` option is not set (defaulting to
 ``root@pam``) or is set to something other than the configuring user,
@@ -107,7 +112,15 @@ of the specified criteria are synced. The available criteria are:
 The same filter is applied to local groups for handling of the
 ``remove-vanished`` option.
 
-.. note:: A sync job can only sync backup groups that the configured remote's
-  user/API token can read. If a remote is configured with a user/API token that
-  only has ``Datastore.Backup`` privileges, only the limited set of accessible
-  snapshots owned by that user/API token can be synced.
+
+Bandwidth Limit
+^^^^^^^^^^^^^^^
+
+Syncing datastores to an archive can produce lots of traffic and impact other
+users of the network. So, to avoid network or storage congetsion you can limit
+the bandwith of the sync job by setting the ``rate-in`` option either in the
+web interface or using the ``proxmox-backup-manager`` command-line tool:
+
+.. code-block:: console
+
+    # proxmox-backup-manager sync-job update ID --rate-in 20MiB

diff --git a/docs/traffic-control.rst b/docs/traffic-control.rst
index 65a9bdc9e695526eaa6df7166c66462280d66376..93f10b6164ddb3a2b5e336cafc2ebab86076aa43 100644 (file)
--- a/docs/traffic-control.rst
+++ b/docs/traffic-control.rst
@@ -3,10 +3,30 @@
 Traffic Control
 ---------------
 
-Proxmox Backup Server allows to limit network traffic for clients
-within specified source networks. The following command adds a traffic
-control rule to limit all clients (network ``0.0.0.0/0``) to 100 MB/s:
+.. image:: images/screenshots/pbs-gui-traffic-control-add.png
+  :align: right
+  :alt: Add a traffic control limit
 
+Creating and restoring backups can produce lots of traffic and impact other
+users of the network or shared storages.
+
+Proxmox Backup Server allows to limit network traffic for clients within
+specified networks using a token bucket filter (TBF).
+
+This allows you to avoid network congestion or to prioritize traffic from
+certain hosts.
+
+You can manage the traffic controls either over the web-interface or using the
+``traffic-control`` commandos of the ``proxmox-backup-manager`` command-line
+tool.
+
+.. note:: Sync jobs on the server are not affected by its rate-in limits. If
+   you want to limit the incomming traffic that a pull-based sync job
+   generates, you need to setup a job-specific rate-in limit. See
+   :ref:`syncjobs`.
+
+The following command adds a traffic control rule to limit all IPv4 clients
+(network ``0.0.0.0/0``) to 100 MB/s:
 
 .. code-block:: console
 
@@ -14,8 +34,14 @@ control rule to limit all clients (network ``0.0.0.0/0``) to 100 MB/s:
    --rate-in 100MB --rate-out 100MB \
    --comment "Default rate limit (100MB/s) for all clients"
 
-It is possible to restrict rules to certain time frames, for example
-the company office hours:
+.. note:: To limit both IPv4 and IPv6 network spaces you need to pass two
+   network parameters ``::/0`` and ``0.0.0.0/0``.
+
+It is possible to restrict rules to certain time frames, for example the
+company office hours:
+
+.. tip:: You can use SI (base 10: KB, MB, ...) or IEC (base 2: KiB, MiB, ...)
+   units.
 
 .. code-block:: console
 
@@ -23,9 +49,9 @@ the company office hours:
    --timeframe "mon..fri 8-12" \
    --timeframe "mon..fri 14:30-18"
 
-If there are more rules, the server uses the rule with the smaller
-network. For example, we can overwrite the setting for our private
-network (and the server itself) with:
+If there are more rules, the server uses the rule with the smaller network. For
+example, we can overwrite the setting for our private network (and the server
+itself) with:
 
 .. code-block:: console
 
@@ -37,6 +63,10 @@ network (and the server itself) with:
 
 .. note:: The behavior is undefined if there are several rules for the same network.
 
+If there are multiple rules that match the same network all of them will be
+applied, which means that the smallest one wins, as it's bucket fills up the
+fastest.
+
 To list the current rules use:
 
 .. code-block:: console