4.1. Set traffic control (tcset command)

tcset is a command to add 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] [--version] [--tc-command | --tc-script] [--debug | --quiet]
             [--stacktrace] [--import-setting]
             [--overwrite | --change | --add] [--rate BANDWIDTH_RATE]
             [--delay NETWORK_LATENCY] [--delay-distro LATENCY_DISTRO_TIME]
             [--loss PACKET_LOSS_RATE] [--duplicate PACKET_DUPLICATE_RATE]
             [--corrupt CORRUPTION_RATE] [--reordering REORDERING_RATE]
             [--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]
             device

positional arguments:
  device                target name: network-interface/config-file (e.g. eth0)

optional arguments:
  -h, --help            show this help message and exit
  --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 described tc
                        commands. this tc script execution result nearly
                        equivalent with 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 one.
                        this option is effective to reduce the time between
                        the shaping rule switching compared to --overwrite
                        option. note: just adds a shaping rule if there are no
                        existing shaping rules.
  --add                 add a traffic shaping rule in addition to existing
                        rules.

Debug:
  --stacktrace          print stack trace for debug information. --debug
                        option required to see the debug print.

Traffic Control Parameters:
  --rate BANDWIDTH_RATE, --bandwidth-rate BANDWIDTH_RATE
                        network bandwidth rate [bit per second]. valid units
                        are either: K/M/G/Kbps/Mbps/Gbps e.g. --rate 10Mbps
  --delay NETWORK_LATENCY
                        round trip network delay. the valid range is from 0ms
                        to 60min. valid time units are: m/min/mins/minute/minu
                        tes/s/sec/secs/second/seconds/ms/msec/msecs/millisecon
                        d/milliseconds/us/usec/usecs/microsecond/microseconds.
                        if no unit string found, considered 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: m/min/mins/minute/minutes/s/sec/
                        secs/second/seconds/ms/msec/msecs/millisecond/millisec
                        onds/us/usec/usecs/microsecond/microseconds. if no
                        unit string found, considered milliseconds as the time
                        unit.
  --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 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)
  --shaping-algo {htb,tbf}
                        shaping algorithm. defaults to htb (recommended).
  --iptables            use iptables to traffic control.

Routing:
  --direction {outgoing,incoming}
                        the direction of network communication that impose
                        traffic control. 'incoming' requires Linux kernel
                        version 2.6.20 or later. (default = outgoing)
  --network DST_NETWORK, --dst-network DST_NETWORK
                        target IP-address/network to control traffic
  --src-network SRC_NETWORK
                        set a traffic shaping rule to specific packets that
                        routed from --src-network to --dst-network. this
                        option required to execute with the --iptables option
                        when you use tbf. the shaping rule only affect to
                        outgoing packets (no effect to if you execute with "--
                        direction incoming" option)
  --port DST_PORT, --dst-port DST_PORT
                        target destination port number to control traffic.
  --src-port SRC_PORT   target source port number to control traffic.
  --ipv6                apply traffic control to IPv6 packets rather than
                        IPv4.
  --exclude-dst-network EXCLUDE_DST_NETWORK
                        exclude a shaping rule for a specific destination IP-
                        address/network.
  --exclude-src-network EXCLUDE_SRC_NETWORK
                        exclude a shaping rule for a specific source IP-
                        address/network.
  --exclude-dst-port EXCLUDE_DST_PORT
                        exclude a shaping rule for a specific destination
                        port.
  --exclude-src-port EXCLUDE_SRC_PORT
                        exclude a shaping rule for a specific source port.

        Documentation: http://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 100k

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 network latency

# tcset eth0 --delay 100ms

4.1.2.2.2. Set 10 seconds network latency

# tcset eth0 --delay 10sec

4.1.2.2.3. Set 0.5 minutes (30 seconds) network latency

# tcset eth0 --delay 0.5min

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 at once

# tcset eth0 --rate 100k --delay 100 --loss 0.1

4.1.2.5. e.g. Specify the IP address of traffic control

# tcset eth0 --delay 100 --network 192.168.0.10

4.1.2.6. e.g. Specify the IP network and port of traffic control

# tcset eth0 --delay 100 --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 rule 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 200K --network 192.168.0.0/24
# tcset eth0 --direction incoming --rate 1M --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 to the following conditions:

  • Equal or later than Linux kernel version 2.6.20
  • Equal or later than iproute2 package 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 decided by a normal distribution.

4.1.3.2.1. e.g. Set 100ms +- 20ms network latency with normal distribution

# tcset eth0 --delay 100 --delay-distro 20

4.1.3.3. Set multiple traffic shaping rules per interface

You can set multiple shaping rules to a network interface with --add option.

tcset eth0 --rate 500M --network 192.168.2.0/24
tcset eth0 --rate 100M --network 192.168.0.0/24 --add

4.1.3.4. Using IPv6

IPv6 addresses can be used at tcset/tcshow commands with --ipv6 option.

# tcset eth0 --delay 100 --network 2001:db00::0/24 --ipv6
# tcshow eth0 --ipv6
{
    "eth0": {
        "outgoing": {
            "dst-network=2001:db00::/24, protocol=ipv6": {
                "delay": "100.0",
                "rate": "1G"
            }
        },
        "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 10 --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:2 htb rate 1000000Kbit ceil 1000000Kbit
/sbin/tc qdisc add dev eth0 parent 1a1a:2 handle 1a9a: netem delay 10.000000ms
/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:2

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 not installed (however, you need the tc command to run the script).

Example:
# tcset eth0 --delay 10 --tc-script
[INFO] tcconfig: written a tc script to 'tcset_eth0.sh'

(copy the script to a remote server)
$ sudo ./tcset_eth0.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 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 100

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 100

4.1.3.8. Shaping rules for between multiple hosts

4.1.3.8.1. Example Environment

Existed multiple networks (192.168.0.0/24, 192.168.10.1/24). Host A (192.168.0.100) and host C (192.168.0.100) 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 100