4.1. Set traffic control (tcset command)¶
tcset is a command to add a traffic control rule to a network interface (device).
You can delete rule(s) from a network interface by Delete traffic control (tcdel command).
4.1.1. tcset command help¶
usage: tcset [-h] [-V] [--tc-command | --tc-script] [--debug | --quiet] [--debug-query] [--stacktrace] [--import-setting] [--overwrite | --change | --add] [--rate BANDWIDTH_RATE] [--delay LATENCY_TIME]
[--delay-distro LATENCY_DISTRO_TIME] [--delay-distribution {normal,pareto,paretonormal}] [--loss PACKET_LOSS_RATE] [--duplicate PACKET_DUPLICATE_RATE] [--corrupt CORRUPTION_RATE]
[--reordering REORDERING_RATE] [--limit PACKET_LIMIT_COUNT] [--shaping-algo {htb,tbf}] [--iptables] [--direction {outgoing,incoming}] [--network DST_NETWORK] [--src-network SRC_NETWORK] [--port DST_PORT]
[--src-port SRC_PORT] [--ipv6] [--exclude-dst-network EXCLUDE_DST_NETWORK] [--exclude-src-network EXCLUDE_SRC_NETWORK] [--exclude-dst-port EXCLUDE_DST_PORT] [--exclude-src-port EXCLUDE_SRC_PORT] [--docker]
[--src-container SRC_CONTAINER] [--dst-container DST_CONTAINER]
device
positional arguments:
device target name: network-interface/config-file (e.g. eth0)
options:
-h, --help show this help message and exit
-V, --version show program's version number and exit
--tc-command display tc commands to be executed and exit. these commands are not actually executed.
--tc-script generate a shell script file that describes tc commands. this tc script execution results are nearly equivalent to the tcconfig command. the script can be executed without tcconfig package
installation.
--debug for debug print.
--quiet suppress execution log messages.
--import-setting import traffic control settings from a configuration file.
--overwrite overwrite existing traffic shaping rules.
--change change existing traffic shaping rules to the new ones. this option is effective in reducing the time between the shaping rule switching compared to --overwrite option. note: just add a shaping
rule if there are no existing shaping rules.
--add add a traffic shaping rule in addition to existing rules.
Debug:
--debug-query for debug print.
--stacktrace print stack trace for debugging information. --debug option is required to see the debug print.
Traffic Control Parameters:
--rate BANDWIDTH_RATE, --bandwidth-rate BANDWIDTH_RATE
network bandwidth rate [bit per second]. the minimum bandwidth rate is 8 bps. valid units are either: [kK]bps, [kK]bits?(/|\s?per\s?)(s|sec|second), [kK]ibps,
[kK]ibits?(/|\s?per\s?)(s|sec|second), [mM]bps, [mM]bits?(/|\s?per\s?)(s|sec|second), [mM]ibps, [mM]ibits?(/|\s?per\s?)(s|sec|second), [gG]bps, [gG]bits?(/|\s?per\s?)(s|sec|second), [gG]ibps,
[gG]ibits?(/|\s?per\s?)(s|sec|second), [tT]bps, [tT]bits?(/|\s?per\s?)(s|sec|second), [tT]ibps, [tT]ibits?(/|\s?per\s?)(s|sec|second), bps, bits?(/|\s?per\s?)(s|sec|second). e.g. tcset eth0
--rate 10Mbps
--delay LATENCY_TIME round trip network delay. the valid range is from 0ms to 60min. valid time units are: d/day/days, h/hour/hours, m/min/mins/minute/minutes, s/sec/secs/second/seconds,
ms/msec/msecs/millisecond/milliseconds, us/usec/usecs/microsecond/microseconds. if no unit string is found, consider milliseconds as the time unit. (default=0ms)
--delay-distro LATENCY_DISTRO_TIME
distribution of network latency becomes X +- Y (normal distribution). Here X is the value of --delay option and Y is the value of --delay-dist option). network latency distribution is uniform,
without this option. valid time units are: d/day/days, h/hour/hours, m/min/mins/minute/minutes, s/sec/secs/second/seconds, ms/msec/msecs/millisecond/milliseconds,
us/usec/usecs/microsecond/microseconds. if no unit string is found, consider milliseconds as the time unit.
--delay-distribution {normal,pareto,paretonormal}
choose the delay distribution. (default=normal)", [limitation] this parameter can not be shown by tcshow, and export/import as config.
--loss PACKET_LOSS_RATE
round trip packet loss rate [%]. the valid range is from 0 to 100. (default=0)
--duplicate PACKET_DUPLICATE_RATE
round trip packet duplicate rate [%]. the valid range is from 0 to 100. (default=0)
--corrupt CORRUPTION_RATE
packet corruption rate [%]. the valid range is from 0 to 100. packet corruption means a single-bit error at a random offset in the packet. (default=0)
--reordering REORDERING_RATE
packet reordering rate [%]. the valid range is from 0 to 100. (default=0)
--limit PACKET_LIMIT_COUNT
limits the maximum number of packets the qdisc may hold when doing delay. the minimum value is 1. (default=0)
--shaping-algo {htb,tbf}
shaping algorithm. defaults to htb (recommended).
--iptables use iptables for traffic control.
Routing:
--direction {outgoing,incoming}
the direction of network communication that imposes traffic control. 'incoming' requires ifb kernel module and Linux kernel 2.6.20 or later. (default = outgoing)
--network DST_NETWORK, --dst-network DST_NETWORK
specify destination IP-address/network that applies traffic control. defaults to any.
--src-network SRC_NETWORK
specify a source IP-address/network that applies traffic control. defaults to any. this option has no effect when executing with "--direction incoming" option. note: this option is required to
execute with the --iptables option when using tbf algorithm.
--port DST_PORT, --dst-port DST_PORT
specify a destination port number that applies traffic control. defaults to any.
--src-port SRC_PORT specify a source port number that applies traffic control. defaults to any.
--ipv6 apply traffic control to IPv6 packets rather than IPv4.
--exclude-dst-network EXCLUDE_DST_NETWORK
exclude a specific destination IP-address/network from a shaping rule.
--exclude-src-network EXCLUDE_SRC_NETWORK
exclude a specific source IP-address/network from a shaping rule.
--exclude-dst-port EXCLUDE_DST_PORT
exclude a specific destination port from a shaping rule.
--exclude-src-port EXCLUDE_SRC_PORT
exclude a specific source port from a shaping rule.
Docker:
--docker apply traffic control to a docker container. to use this option, you will need to specify a container id as 'device' as follows: tcset --container <container id>
--src-container SRC_CONTAINER
specify source container id or name.
--dst-container DST_CONTAINER
specify destination container id or name.
Documentation: https://tcconfig.rtfd.io/
Issue tracker: https://github.com/thombashi/tcconfig/issues
4.1.2. Basic usage¶
Examples of outgoing packet traffic control settings are as follows.
4.1.2.1. e.g. Set a limit on bandwidth up to 100Kbps¶
# tcset eth0 --rate 100Kbps
4.1.2.2. e.g. Set network latency¶
You can use time units (such as us/sec/min/etc.) to designate delay time.
4.1.2.2.1. Set 100 milliseconds of network latency¶
# tcset eth0 --delay 100ms
4.1.2.2.2. Set 10 seconds of network latency¶
# tcset eth0 --delay 10sec
4.1.2.2.3. Set 0.5 minutes (30 seconds) network latency¶
# tcset eth0 --delay 0.5min
You can also use the following time units:
Unit |
Available specifiers (str) |
|---|---|
hours |
|
minutes |
|
seconds |
|
milliseconds |
|
microseconds |
|
4.1.2.3. e.g. Set 0.1% packet loss¶
# tcset eth0 --loss 0.1%
4.1.2.4. e.g. All of the above settings at once¶
# tcset eth0 --rate 100Kbps --delay 100ms --loss 0.1%
4.1.2.5. e.g. Specify the IP address of the traffic control¶
# tcset eth0 --delay 100ms --network 192.168.0.10
4.1.2.6. e.g. Specify the IP network and port of traffic control¶
# tcset eth0 --delay 100ms --network 192.168.0.0/24 --port 80
4.1.3. Advanced usage¶
4.1.3.1. Traffic control of incoming packets¶
You can set traffic shaping rules to incoming packets by executing tcset command with --direction incoming option.
Other options are the same as in the case of the basic usage.
4.1.3.1.1. e.g. Set traffic control for both incoming and outgoing network¶
# tcset eth0 --direction outgoing --rate 200Kbps --network 192.168.0.0/24
# tcset eth0 --direction incoming --rate 1Mbps --network 192.168.0.0/24
4.1.3.1.2. Requirements¶
To set incoming packet traffic control requires an additional kernel module named ifb,
which need the following conditions:
Equal or later than Linux kernel version 2.6.20
Equal or later than
iproute2package version 20070313
4.1.3.2. Set latency distribution¶
Network latency setting by --delay option is a uniform distribution.
If you are using --delay-distro option, latency is decided by a normal distribution.
4.1.3.2.1. e.g. Set 100ms +- 20ms network latency with normal distribution¶
# tcset eth0 --delay 100ms --delay-distro 20
4.1.3.3. Set multiple traffic shaping rules to an interface¶
You can set multiple shaping rules to a network interface with --add option.
tcset eth0 --rate 500Mbps --network 192.168.2.1/32
tcset eth0 --rate 100Mbps --network 192.168.2.2/32 --add
4.1.3.4. Using IPv6¶
IPv6 addresses can be used at tcset/tcshow commands with --ipv6 option.
# tcset eth0 --delay 100ms --network 2001:db00::0/24 --ipv6
# tcshow eth0 --ipv6
{
"eth0": {
"outgoing": {
"dst-network=2001:db00::/24, protocol=ipv6": {
"filter_id": "800::800",
"delay": "100.0ms",
"rate": "1Gbps"
}
},
"incoming": {}
}
}
4.1.3.5. Get tc commands¶
You can get tc commands to be executed by tcconfig commands by
executing with --tc-command option
(Execution of tcconfig commands with --tc-command option does not affect the traffic rules to the server).
- Example:
$ tcset eth0 --delay 10ms --tc-command /sbin/tc qdisc add dev eth0 root handle 1a1a: htb default 1 /sbin/tc class add dev eth0 parent 1a1a: classid 1a1a:1 htb rate 1000000kbit /sbin/tc class add dev eth0 parent 1a1a: classid 1a1a:254 htb rate 1000000Kbit ceil 1000000Kbit /sbin/tc qdisc add dev eth0 parent 1a1a:254 handle 2873: netem delay 10ms /sbin/tc filter add dev eth0 protocol ip parent 1a1a: prio 2 u32 match ip dst 0.0.0.0/0 match ip src 0.0.0.0/0 flowid 1a1a:254
4.1.3.6. Generate a tc script file¶
--tc-script option generates an executable script which includes
tc commands to be executed by tcconfig commands.
The created script can execute at other servers where tcconfig is not installed
(However, you need the tc command to run the script).
- Example:
$ tcset eth0 --delay 10ms --tc-script [INFO] tcconfig: written a tc script to 'tcset_eth0_delay10ms.sh' (copy the script to a remote server) $ sudo ./tcset_eth0_delay10ms.sh
4.1.3.7. Set a shaping rule for multiple destinations¶
4.1.3.7.1. Example Environment¶
Multiple hosts (A, B, C, D) are on the same network.
A (192.168.0.100) --+--B (192.168.0.2)
|
+--C (192.168.0.3)
|
+--D (192.168.0.4)
4.1.3.7.2. Set a shaping rule to multiple hosts¶
--dst-network/--src-network option can specify not only a host but also network.
The following command executed at host A will set a shaping rule that incurs 100 msec network latency to packets
from A (192.168.0.100) to a specific network (192.168.0.0/28 which include B/C/D).
- Example:
# tcset eth0 --dst-network 192.168.0.0/28 --exclude-dst-network 192.168.0.3 --delay 100ms
You can exclude hosts from shaping rules by --exclude-dst-network/--exclude-src-network option.
The following command executed at host A will set a shaping rule that incurs 100 msec network latency to packets
from host A (192.168.0.100) to host B (192.168.0.2)/D (192.168.0.4).
- Example:
# tcset eth0 --dst-network 192.168.0.0/28 --exclude-dst-network 192.168.0.3 --delay 100ms
4.1.3.8. Shaping rules between multiple hosts¶
4.1.3.8.1. Example Environment¶
Existed multiple networks (192.168.0.0/24, 192.168.1.0/24).
Host A (192.168.0.100) and host C (192.168.1.10) belong to a different network.
Host B (192.168.0.2/192.168.1.2) belong to both networks.
A (192.168.0.100) -- (192.168.0.2) B (192.168.1.2) -- C (192.168.1.10)
4.1.3.8.2. Set a shaping rule to multiple hosts¶
The following command executed at host B will set a shaping rule that incurs 100 msec network latency to packets
only from host A (192.168.0.100) to host C (192.168.1.10).
- Example:
# tcset eth0 --dst-network 192.168.0.2 --dst-network 192.168.1.2 --delay 100ms
4.1.4. Docker container¶
4.1.4.1. Set traffic control to a docker container¶
Execute tcconfig with --docker option on a Docker host:
# tcset <container name or ID> --docker ...
You could use --src-container/--dst-container options to specify the source/destination container.
4.1.4.2. Set traffic control within a docker container¶
You need to run a container with --cap-add NET_ADMIN option
if you would like to set a tc rule within a container:
docker run -d --cap-add NET_ADMIN -t <docker image>
A container image that builtin tcconfig can be available at https://hub.docker.com/r/thombashi/tcconfig/