Manual for Tcpchains

Tchchains is a user-land tool to manage the rules that the patched kernel used to perform connection classification and forwarding. CONFIG_TCP_FW option must be enabled when compiling the kernel. Refer to here for how to compile the kernel.

1. What's a rule

    Connection classification and forwarding is controlled by rules. A rule consists of an incoming port and several target outgoing ports, one of which is designated as default target. The incoming port, usually the well-known service port, is the port the client actually contact. The target outgoing ports are the ones the server instances are listening to. Conditions are associated with each outgoing ports. When an incoming connection satisfies the condition associated with one particular outgoing port, the connection will be forwarded to that port. If none of the conditions are satisfied, the default target port is used.

    An outgoing port in one rule can be the incoming port of another rule. Thus, it is possible to connect several rules into a forwarding chain, which is a very powerful feature. That's reason that the tool is named tcpchains. For instance, the first rule with port X as its incoming port may specify that when condition A is true, connections to port X will be forwarded to port Y. Another rule with port Y as its incoming port may further specify that when condition B is true, connections to port Y will be forwarded to port Z. Therefore, when condition A and B are both true, a connection to port X will finally be forwarded to port Z.

2. What rules are supported

    Three types of rules are supported:

• Probabilistic. A user or a user-space process can associate a probability with each outgoing port of a rule. Incoming connections are forwarded according to these probabilities.
• Address-based. The user specifies a set of IP addresses/subnet masks for each outgoing port. The target port selection is solely based on the source the connection comes from.
• Content-based. This is the most powerful and complex classification scheme. A general filter is used to perform pattern matching on application-layer headers. Our current implementation only supports simple string matching, which is sufficient, for example, to determine which URL was named in an HTTP header. The administrator can specify certain strings for each outgoing port. The connection is forwarded only when one of the specified strings appears in the data packet.

3. How to Create a rule

    Two steps are needed to create a rule:

1. Create an empty rule by specifying an incoming port and default target port:

tcpchains -A <rule type> -p <incoming port> -o <default target port>
<chain type> can be:
    d:    probabilistic rule
    a:    address-based rule
    c:    content-based rule

example:
    tcpchains -A d -p 143 -o 1143
create a probabilistic rule for IMAP service, default target port is 1143

    tcpchains -A a -p 21 -o 1021
create a address-based rule for FTP service, default target port is 1021

    tcpchains -A c -p 80 -o 8080
create a content-based rule for HTTP service, default target port is 8080

2. Add some condition to the rule,  the basic syntax is

   tcpchains -a <chain type> -p <incoming port> <branch option>
   <incoming port> is the port used in step 1

   the syntax of <branch option> depends on the rule type. The underline part is the <branch option>

   1. probabilistic rule:

       tcpchains -a d -p <incoming port> -r <target port> -c <forward chance>
       <forward chance> is the probability to forward to the <target port>, the range is 1 - 10000

           example:
           tcpchains -a d -p 143 -r 2143 -c 3000
           tcpchains -a d -p 143 -r 3143 -c 4000
           30% IMAP connections will be forwarded to port 2143, 40% to port 3143 with probability. The remaining 30% connections will be forwarded to 1143, since it's the default target port.

   2. address-based rule:

       tcpchains -a a -p <incoming port> -r <target port> -i <source IP address> -m <subnet mask>

           example:
           tcpchains -a a -p 21 -r 2021 -i bobbidi.cs.virginia.edu -m 255.255.255.255
           tcpchains -a a -p 21 -r 2021 -i tarek8.cs.virginia.edu -m 255.255.255.255
           FTP connections from machine bobibdi and tarek8 will be forwarded to port 2021, the others will be forwarded to port 1021, since it's the default target port.

   3. content-based rule:

      tcpchains -a c -p <incoming port> -r <target port> -s <matching string>

           example:
           tcpchains -a c -p 80 -r 8081 -s 'gif'
           tcpchains -a c -p 80 -r 8081 -s 'gif'
           HTTP requests for 'gif' or 'jpg' will be forwarded to port 8081, and the others will be forwarded to port 8080 since it's the default target port         

4. Other operations

1. Delete a rule

tcpchains -D <rule type> -p <incoming port>

to delete the three rules created above, use:

tcpchains -D d -p 143
tcpchains -D a -p 21
tcpchains -D c -p 80

2. Delete all the rules

tcpchains -F <rule type>

another way to delete the three rules created above, use:

tcpchains -F d
tcpchains -F a
tcpchains -F c

3. Change the default target port

tcpchains -C <rule type> -p <incoming port> -o <new default port>

4. Change one condition of a rule. This must be done in two steps. First remove the old condition, then add the new one. I know this is cumbersome, but it simplifies the implementation ^_^. To remove all the conditions of a rule:

tcpchains -X <rule type> -p <incoming port>

5. List all the rules in the system.

tcpchains -L <rule type>

Back to Home