docs: fix some typos

[proxmox-backup.git] / docs / traffic-control.rst

.. _sysadmin_traffic_control:

Traffic Control
---------------

.. 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 incoming 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

 # proxmox-backup-manager traffic-control create rule0  --network 0.0.0.0/0 \
   --rate-in 100MB --rate-out 100MB \
   --comment "Default rate limit (100MB/s) for all clients"

.. 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

 # proxmox-backup-manager traffic-control update rule0  \
   --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:

.. code-block:: console

 # proxmox-backup-manager traffic-control create rule1 \
   --network 192.168.2.0/24 \
   --network 127.0.0.0/8 \
   --rate-in 20GB --rate-out 20GB \
   --comment "Use 20GB/s for the local network"

.. 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

 # proxmox-backup-manager traffic-control list
 ┌───────┬─────────────┬─────────────┬─────────────────────────┬────────────...─┐
 │ name  │     rate-in │    rate-out │ network                 │ timeframe  ... │
 ╞═══════╪═════════════╪═════════════╪═════════════════════════╪════════════...═╡
 │ rule0 │      100 MB │      100 MB │ ["0.0.0.0/0"]           │ ["mon..fri ... │
 ├───────┼─────────────┼─────────────┼─────────────────────────┼────────────...─┤
 │ rule1 │       20 GB │       20 GB │ ["192.168.2.0/24", ...] │            ... │
 └───────┴─────────────┴─────────────┴─────────────────────────┴────────────...─┘

Rules can also be removed:

.. code-block:: console

 # proxmox-backup-manager traffic-control remove rule1


To show the state (current data rate) of all configured rules use:

.. code-block:: console

  # proxmox-backup-manager traffic-control traffic
  ┌───────┬─────────────┬──────────────┐
  │ name  │ cur-rate-in │ cur-rate-out │
  ╞═══════╪═════════════╪══════════════╡
  │ rule0 │         0 B │          0 B │
  ├───────┼─────────────┼──────────────┤
  │ rule1 │   1.161 GiB │   19.146 KiB │
  └───────┴─────────────┴──────────────┘