rsync --bwlimit: Throttling Deploy Bandwidth
rsync --bwlimit=RATE limits how fast rsync sends data, so a large deploy does not starve other traffic on the link.
When CI deploys a big artifact set to a production server during peak hours, throttling keeps the deploy from hurting live traffic.
What it does
--bwlimit=RATE caps the average transfer rate. The number is in KiB/s by default; you can suffix it with a unit. So --bwlimit=5000 is about 5 MB/s, and --bwlimit=10m is 10 MB/s. A value of 0 means unlimited (the default).
Common usage
# Cap a deploy at roughly 5 MB/s
rsync -avz --bwlimit=5m dist/ user@host:/var/www/app/
# KiB/s form: about 2 MB/s
rsync -avz --bwlimit=2000 dist/ user@host:/srv/Rate syntax
| Value | Meaning |
|---|---|
| --bwlimit=1000 | About 1000 KiB/s (~1 MB/s) |
| --bwlimit=5m | 5 MiB/s |
| --bwlimit=500k | 500 KiB/s |
| --bwlimit=0 | Unlimited (default) |
In CI
For scheduled deploys to a shared or customer-facing host, set a conservative --bwlimit so the rsync does not crowd out application traffic. You can drive it from a CI variable so off-hours deploys run unthrottled and business-hours deploys are capped.
Common errors in CI
There is no error from a valid --bwlimit, but a bad unit suffix yields "--bwlimit=... is not a valid number". Use plain digits or a recognized suffix (k, m, g). If a deploy is slower than expected, check that an old --bwlimit value is not lingering in the shared command.