a brief description how to write netfilterconnection tracking helper and nat helper modules.
1.1 What the hell is this all about?
This document gives a brief description how to write netfilterconnection tracking helper and nat helper modules. Netfilter is thepacket filtering / NAT infrastructure provided by the Linux 2.4.xkernel.
1.2 What to read first
I strongly recommend You reading Rusty Russel's `netfilter hackinghowto' which is available from the netfilter project homepage athttp://netfilter.kernelnotes.org
2.1 Description
The duty of a connection tracking module is to specify whichpacktets belong to an already established connection. The module hasthe following means to do that:
- Tell netfilter which packets our module is interested in
- Register a conntrack function with netfilter. This function iscalled for every "interesting" packet (as decided by the callbackfunction above)
- Call ip_conntrack_expect_related to tell netfilter which packets are related to the connection.
2.2 Structures and Functions available
At first some basic structures
`struct ip_conntrack_tuple' (just printed the fields valid for TCP)
- src.ip
the source IP address
- src.u.tcp.port
the TCP source port
- dst.ip
the destination IP address
- dst.protonum
the protocol (IPPROTO_TCP, ...)
- dst.u.tcp.port
the TCP destination port
Your kernel module's init function has to call`ip_conntrack_helper_register()' with a pointer to a`struct ip_conntrack_helper'. This struct has the following fields:
- list
This is the header for the linked list. Netfilter handles this list internally. Just initialize it with { NULL, NULL }
- tuple
This is a `struct ip_conntrack_tuple' which specifies the packets our conntrack helper module is interested in.
- mask
Again a `struct ip_conntrack_tuple'. This mask specifies which bits of
tupleare valid.- help
The function which netfilter should call for each packet matching tuple+mask
2.3 Example skeleton of a conntrack helper module
3.1 Description
NAT helper modules do some application specific NAT handling.Usually this includes on-the-fly manipulation of data. Think about thePORT command in FTP, where the client tells the server which ip/port toconnect to. Thererfore a FTP helper module has to replace the ip/portafter the PORT command in the FTP control connection.
If we are dealing with TCP, things get slightly morecomplicated. The reason is a possible change of the packet size (FTPexample: The length of the string representing an IP/port tuple afterthe PORT command has changed). If we had to change the packet size, wehave a syn/ack difference between left and right side of the NAT box.(i.e. if we had extended one packet by 4 octets, we have to add thisoffset to the TCP sequence number of each following packet)
Special NAT handling of all related packets is required, too. Take as exampleagain FTP, where all incoming packets of the DATA connection have to be NATedto the ip/port given by the client with the PORT command on the controlconnection.
- callback for the packet causing the related connection (foo_help)
- callback for all related packets (foo_nat_expected)
3.2 Structures and Functions available
Your nat helper module's `init()' function has to call`ip_nat_helper_register()' with a pointer to a `struct ip_nat_helper'. Thisstruct hast the following members:
- list
Just again the list header for netfilters internal use.Initialize this with { NULL, NULL }.
- tuple
a `struct ip_conntrack_tuple' describing which packets ournat helper is interested in.
- mask
a `struct ip_conntrack_tuple', telling netfilter which bitsof
tupleare valid.- help
The help function which is called for each packet matchingtuple+mask.
- name
The uniqe name this nat helper is identified by.
3.3 Example NAT helper module
I want to thank all the great netfilter folks, especially RustyRussel, for providing us (the Linux community) with this neatinfrastructure.