Netfilter connection tracking and nat helper moduleshttp://ftp.gnumonks.org/pub/doc/conntrack+nat.html

Netfilter connection tracking and nat helper modules

Harald Welte, `laforge@gnumonks.org`

Version 1.2, 2000/10/14 20:37:53

Well... This initially wasn't intended to be a publicly available document. It just contains some of my thoughts during a summer holiday in italy, where I was trying to port the ip_masq_irc module to the new netfilter conntrack/nat framework. There was no documentation about this topic available on the net, so I tried to understand the netfilter code.

1. Introduction

1.1 What the hell is this all about?

This document gives a brief description how to write netfilter connection tracking helper and nat helper modules. Netfilter is the packet filtering / NAT infrastructure provided by the Linux 2.4.x kernel.

1.2 What to read first

I strongly recommend You reading Rusty Russel's `netfilter hacking howto' which is available from the netfilter project homepage at http://netfilter.kernelnotes.org

2. Connection tracking helper modules

2.1 Description

The duty of a connection tracking module is to specify which packtets belong to an already established connection. The module has the following means to do that:

Tell netfilter which packets our module is interested in
Register a conntrack function with netfilter. This function is called for every "interesting" packet (as decided by the callback function 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 tuple are valid.

help

The function which netfilter should call for each packet matching tuple+mask

2.3 Example skeleton of a conntrack helper module

3. NAT helper modules

3.1 Description

NAT helper modules do some application specific NAT handling. Usually this includes on-the-fly manipulation of data. Think about the PORT command in FTP, where the client tells the server which ip/port to connect to. Thererfore a FTP helper module has to replace the ip/port after the PORT command in the FTP control connection.

If we are dealing with TCP, things get slightly more complicated. The reason is a possible change of the packet size (FTP example: The length of the string representing an IP/port tuple after the PORT command has changed). If we had to change the packet size, we have 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 this offset to the TCP sequence number of each following packet)

Special NAT handling of all related packets is required, too. Take as example again FTP, where all incoming packets of the DATA connection have to be NATed to the ip/port given by the client with the PORT command on the control connection.

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'. This struct 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 our nat helper is interested in.

mask

a `struct ip_conntrack_tuple', telling netfilter which bits of tuple are valid.

help

The help function which is called for each packet matching tuple+mask.

name

The uniqe name this nat helper is identified by.