[pbs-devel] [PATCH] docs: rephrase and extend rate limiting description for sync jobs

[Christian Ebner]

Since commit 37a85cf6 ("fix: ui: sync job: edit rate limit based on
sync direction") rate limits for sync jobs can be correctly applied
for both directions. State this in the documentation and explicitley
mention the directions to reduce confusion.

Further, also mention the burst parameters, as they are not mentioned
at all.

Signed-off-by: Christian Ebner <c.ebner at proxmox.com>
---

While the initial request in the community forum asked for improved
documentation of the configuration file's parameters [0], this is
currently not possible without explicitley defining new types for
each as autogenerated for the api schema, which defines these values
as `HumanByte` and a description cannot be set for external types.
This patch tries to improve the discoverability for the rate and
burst parameters for both the sync and general traffic limits.

[0] https://forum.proxmox.com/threads/167738/

 docs/managing-remotes.rst | 4 +++-
 docs/traffic-control.rst  | 9 +++++----
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/docs/managing-remotes.rst b/docs/managing-remotes.rst
index da1d53cbd..ddbe3e9b6 100644
--- a/docs/managing-remotes.rst
+++ b/docs/managing-remotes.rst
@@ -239,7 +239,9 @@ command-line tool:
 
     # proxmox-backup-manager sync-job update ID --rate-in 20MiB
 
-For sync jobs in push direction use the ``rate-out`` option instead.
+For sync jobs in push direction use the ``rate-out`` option instead. To allow
+for traffic bursts, you can set the size of the token bucket filter used for
+traffic limiting via ``burst-in`` or ``burst-out`` parameters.
 
 Sync Direction Push
 ^^^^^^^^^^^^^^^^^^^
diff --git a/docs/traffic-control.rst b/docs/traffic-control.rst
index 7cfd2d16b..bd370e804 100644
--- a/docs/traffic-control.rst
+++ b/docs/traffic-control.rst
@@ -19,11 +19,12 @@ certain hosts.
 
 You can manage the traffic controls either via the web-interface or using the
 ``traffic-control`` commands of the ``proxmox-backup-manager`` command-line
-tool.
+tool. Traffic is limited by rate (``rate-in`` and ``rate-out``) and allows for
+short bursts by setting the token bucket size (``burst-in`` and ``burst-out``).
 
-.. note:: Sync jobs on the server are not affected by the configured 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
+.. note:: Sync jobs on the server are not affected by the configured rate limits.
+   If you want to limit the incoming traffic of pull-based or outgoing traffic
+   of push-based sync job, 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
-- 
2.47.2



Signed-off-by: Christian Ebner <c.ebner at proxmox.com>

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# Date:      Mon Jun 23 14:12:00 2025 +0200
#
# On branch improve-sync-rate-docs
# Changes to be committed:
#	modified:   docs/managing-remotes.rst
#	modified:   docs/traffic-control.rst
#