Using all of tcng in six easy steps

This is a tiny example that shows how tcc and tcsim are typically used with the traffic control subsystem in the Linux kernel.

The configuration shall drop all packets leaving the router via the interface eth0, unless they originate from the HTTP port.

Step 1:

Write a file with the tcng configuration. We shall call the file example.tc:

dev eth0 {
    egress {
        drop if tcp_sport != PORT_HTTP;
    }
}

Step 2:

Run tcc to convert the tcng configuration to tc commands. We save the output in a file called example.sh:

tcc -r example.tc >example.sh

The -r switch tells tcc to emit a command to remove any traffic control setup that may be in use at eth0 before trying to add the new configuration.

You can look at the resulting output with cat example.sh, but it will look rather cryptic.

Step 3:

It is frequently desirable to test more complicated configurations by simulation before using them. Although our example is quite simple, we shall use the simulator too.

First, we create a file example.tcsim:

#include "packet.def"
#include "ports.tc"

dev eth0 100 Mbps {
    #include "example.tc"
}

send TCP_PCK($tcp_sport = PORT_HTTP);
send TCP_PCK($tcp_sport = PORT_SSH);
end

This defines a simulation environment with one interface called eth0, running at 100 Mbps, to which the example configuration is applied. The simulation consists of sending two packets, and waiting until the system is idle again.

Step 4:

Run the simulation with tcsim:

tcsim -s 22 example.tcsim

We use the -s option to reduce the output generated by tcsim. The output looks like this:

0.000000 E : 0x80bd560 40 : eth0: 45000028 00000000 40060000 0a000001 0a000002 0050 ...
0.000000 D : 0x80bd560 40 : eth0: 45000028 00000000 40060000 0a000001 0a000002 0050 ...
0.000000 E : 0x80bd870 40 : eth0: 45000028 00000000 40060000 0a000001 0a000002 0016 ...
0.000000 * : 0x80bd870 40 : eth0: enqueue returns POLICED (3)

Step 5:

We verify that the configuration did indeed work: The first packet was enqueued (``E''), and then dequeued (``D''). When trying to enqueue the second packet, it was rejected.

Step 6:

We are now ready to load the example on a live system. As super-user, execute the tc commands to create the configuration in the kernel:

sh example.sh

Note: this step only works if traffic control is configured into the kernel and if a recent version of iproute2/tc with support for Differentiated Services is installed.^1.1

More information about writing tcng configurations can be found in chapter 2 and the following chapters. tcc usage is described in detail in chapter 5, and tcsim is described in chapter 6.