3. Configuration examples

Examples shown here will be modified examples of downloadable configurations available in this directory.

These examples can be used as standalone configuration files to be fed into a tcc parser, or they can be used in conjunction with the example SysV startup script. The startup script is a modification of a script posted on the LARTC mailing list by raptor.

If you are going to use the above startup script, take a look at this example /etc/sysconfig/tcng:

Example 1. /etc/sysconfig/tcng


# - tcng meta-configuration file
#   (I never meta-configuration file I didn't like)
#
# -- 2003-03-15 created; -MAB
# -- 2003-03-31 modified to allow ENVAR override; -MAB
#
# -- this directory will hold all of the tcng configurations
#    used on this host
#
TCCONFBASEDIR=${TCCONFBASEDIR:-/etc/sysconfig/tcng-configs}

# -- this is the active, desired tcng configuration
#    note, that, because tcng provides the #include construct,
#    the modularity of configuration can be built into the
#    configuration files in $TCCONFBASEDIR
#
TCCONF=${TCCONF:-$TCCONFBASEDIR/global.tcc}

tcstats=${tcstats:-no}   # -- will suppress statistical output
tcstats=${tcstats:-yes}  # -- will throw the "-s" option to tc

tcdebug=${tcdebug:-0}    # -- for typical startup script usage
tcdebug=${tcdebug:-1}    # -- for a bit of information about what's happening
tcdebug=${tcdebug:-2}    # -- for debugging information
#
#
# -- an additional measure to take, you can override the default tc and tcc
#    command line utilities by specifying their pathnames here, for example:
#
#  tc=/usr/local/bin/tc
#  tcc=/usr/local/tcng/bin/tcc
#
#
    

3.1. Using tcng to shape download only

Many general concepts will be introduced with this example. This example can be compiled to its tc output with the command tcc class-selection-path.tcc.

Example 2. /etc/sysconfig/tcng/class-selection-path.tcc


/*
 * Simply commented example of a tcng traffic control file.
 *
 *   Martin A. Brown 
 *
 * Example:  Using class selection path.
 *
 * (If you are reading the processed output in HTML, the callouts are
 *  clickable links to the description text.)
 *
 */

#include "fields.tc"     (1)
#include "ports.tc"

#define INTERFACE  eth0  (2)

dev INTERFACE {
    egress { (3)

        /* In class selection path, the filters come first!  DSmark */ (4)

        class ( <$ssh> )    if tcp_sport ==  22 && ip_tos_delay == 1 ;
        class ( <$audio> )  if tcp_sport == 554 || tcp_dport == 7070 ;
        class ( <$bulk> ) \
            if tcp_sport == PORT_SSH || tcp_dport == PORT_HTTP ; (5)
        class ( <$other> )  if 1 ; (6)

        /* section in which we configure the qdiscs and classes */ 

        htb () { (7)
            class ( rate 600kbps, ceil 600kbps ) { (8)
                $ssh   = class ( rate  64kbps, ceil 128kbps ) { sfq; } ; 
              (9) $audio = class ( rate 128kbps, ceil 128kbps ) { sfq; } ;
                $bulk  = class ( rate 256kbps, ceil 512kbps ) { sfq; } ;
                $other = class ( rate 128kbps, ceil 384kbps ) { sfq; } ; (10)
            }
        }
    }
}
      
(1)
The tcng language provides support for C-style include directives which can include any file. Files are included relative to the current directory or the tcng library (normally /usr/lib/tcng/include). Strictly speaking, it is not necessary to #include ports.tc and fields.tc, because tcc will include these by default.

The use of #include can allow for flexible definition of variables and inclusion of common traffic control elements.

See also the tcng manual on includes.

(2)
These are CPP directives. The #define can be used to create macros or constants. For more on their use, you should see the tcng manual on variables.
(3)
The egress keyword is synonymous with the dsmark keyword. The example here uses class selection path. It is the use of the egress keyword in this configuration which requires dsmark support in the kernel and tc.
(4)
Class selection path is one approach to traffic shaping. In class selection path, the packet is marked (DiffServ mark) upon entry into the router. The router may take any number of actions or apply any number of policing, scheduling or shaping actions on the packet as a result of this initial classification.

Consult the tcng manual on class selection path for further details.

(5)
This example shows the use of names for the ports instead of numbers. This is one of the conveniences of tcng afforded by the automatic inclusion of ports.tc. The ports are named in accordance with IANA port names. See IANA's registered ports for these names or examine the file ports.tc.

Names and numbers are equally acceptable and valid.

(6)
Note this peculiar construct which classifies any packet which have not yet been classified. Any packet which has not been classified by the above classifiers is put into the class "$other" here. The if 1 construct can be used to classify the remainder of unclassified traffic.
(7)
This is the creation of the root qdisc which is attached to device, eth0 in this case. Consult the reference material in the tcng appendix on queuing discipline parameters for valid parameters to each qdisc. Any qdisc parameters can be inserted into the parentheses in the same fashion as the class parameters further below in the example. If no parameters need be specified, the parentheses are optional.
(8)
The top level class in this example sets the maximum bandwidth allowed through this class. Let's assume that eth0 is the inside network interface of a machine. This limits the total bandwidth to 600 kilobits per second transmitted to the internal network.

The parameters rate and ceil should be familiar to anybody who has used HTB. These are HTB specific parameters and are translated properly by the tcc utility. See the table on tcng rate and speed specification.

(9)
This is the assignment of a class to a variable. This is commonly done as part of class selection path.
(10)
As suggested by Martin Devera on the HTB homepage, an embedded SFQ gives each class a fair queuing algorithm for distribution of resources to the contenders passing packets through that class. Note the absence of any parameters to the embedded queuing discipline.

If no queuing discipline is specified for leaf classes, they contain the default, a pfifo_fast qdisc. The inclusion of a stochastic fair queuing qdisc in the leaf classes inhibits the ability of a single connection to dominate in a given class.

3.2. Using a two-rate three-color meter

Example 3. /etc/sysconfig/tcng/two-rate-three-color-meter.tcc


/*
 * Simply commented example of a tcng traffic control file.
 *
 *   Martin A. Brown 
 *
 * Example:  Using a meter.
 *
 * (If you are reading the processed output in HTML, the callouts are
 *  clickable links to the description text.)
 *
 */

#define   EXCEPTION      192.168.137.50
#define   INTERFACE      eth0

$meter = trTCM( cir 128kbps, cbs 10kB, pir 256kbps, pbs 10kB );  (1)

dev eth0 {
    egress {
        class ( <$full> )     if ip_src == EXCEPTION      ; (2)
        class ( <$fast> )     if trTCM_green( $meter )    ; (3)
        class ( <$slow> )     if trTCM_yellow( $meter )   ; (4)
        drop                  if trTCM_red( $meter )      ; (5)
        htb {
            class ( rate 600kbps, ceil 600kbps ) {
                $fast = class ( rate 256kbps, ceil 256kbps ) { sfq; } ;
                $slow = class ( rate 128kbps, ceil 128kbps ) { sfq; } ;
                $full = class ( rate 600kbps, ceil 600kbps ) { sfq; } ;
            }
        }
    }
}
      
(1)
This is the declaration of the meter to be used for classifying traffic. The underlying technology used to implement this meter is policing. See the tcng manual on meters for the different types of meters.

This meter is a two-rate three-color meter, the most complex meter available in the tcng language. This meter returns the colors green, yellow and red, based on the rates offered in the committed and peak buckets. If the metered rate exceeds the committed rate, this meter will turn yellow, and if the metered rate exceeds the peak rate, this meter will turn red.

The variable $meter can be operated on by functions applicable to the meter type. In this case, there are three functions available for testing $meter's state, trTCM_green, trTCM_yellow, and trTCM_red. For efficiency, consider also the accelerated counterparts.

(2)
In this example, the IP 192.168.137.50 is specifically excluded from the policing control applied to traffic departing on eth0.
(3)
Up to the committed information rate (cir), packets will pass through this class. Tokens will be removed from the cir/cbs bucket.

The meter is green.

(4)
Traffic flow exceeding the cir/cbs bucket will be classified here. The pir/pbs bucket (pir is peak information rate, pbs is peak burst size). This allows a particular flow to be guaranteed one class of service up to a given rate, and then be reclassified above that rate.

The meter is yellow.

(5)
Traffic flow exceeding the pir/pbs bucket will be classified here. A common configuration causes traffic to be dropped above peak rate, although traffic could be re-classified into a best-effort class from a guaranteed class.

The meter is red.