Iceditch IPtables language

The Iceditch control language

If you know and understand IPtables commands, then the syntax of the Iceditch control language seems very simple to you. When you realise that it's only goal is to simplify standard IPtables commands without taking away their incredible power or flexibility, you'll also realise that this is actually inevitable. But let's not linger here: dip in!

The Context header

Just about every IPtables command that creates a firewall rule, acts on some firewall table, and some firewall chain. These are found in the IPtables invocation, and are specified by options -A (add to chain) and -t (use table). Thus, the rule

iptables -A INPUT -t filter -d 10.0.0.1 -j DROP

works in chain INPUT and table filter. There is a number of default chains:

• PREROUTING
• FORWARD
• INPUT
• OUTPUT
• POSTROUTING

Iceditch will (currently) not understand any other chain. There is also a number of default tables:

• conntrack
• mangle
• nat
• filter

The "conntrack" table is not user manipulable, so Iceditch won't (cannot) allow you to it. Now please have a peek at the following magnificent picture. You can see that there are only 11 combinations of default chains and tables that can accept IPtables rules. Fear not: Iceditch will check every rule for valid combination of table and chain, and yield an error message for any invalid combination. The valid combinations thus are:

	conntrack	mangle	nat	filter
PREROUTING	X	V	V
FORWARD		V		V
INPUT		V		V
OUTPUT	X	V	V	V
POSTROUTING		V	V

The way to tell Iceditch which table and chain to use, is by grouping all commands for a certain combination of table and chain in one stanza of the configuration file: this is called the context of the rules. A context is specified in the configuration file with the following header:

 context <chain> <table>

Every line that follows is assumed to belong to this particular context, so that in these lines the target chain and table do not need to appear.

Currently, every context is allowed to appear multiple times in the configuration file. This means Iceditch allows multiple stanzas per unique context. However, they will be processed in the order in which they appear in the configuration file, so one must be careful that the stanzas are ordered correctly; we'd advise to use each context only once, for maintainability over legibility.

The target specification

(Almost) every IPtables rule has a target. Iceditch takes keywords that signify the standard targets, and lets every line begin with this keyword. Thus, the keyword accept at the beginning of a line signifies that you're talking about an IPtables command that normally would end with -j ACCEPT. The keywords Iceditch currently "understands" are:

• accept
• drop
• reject
• redirect
• mark
• classify
• recent
• dnat
• snat
• masquerade
• nojump

The last one is a bit odd: it signifies an IPtables line that can match a packet, yet won't jump anywhere; thus, Iceditch actually doesn't "do" anything with the packet. This would be the case for a line that you'd insert in order to count certain packets, like

iptables -A INPUT -t filter -p icmp -s 10.0.0.1

This line would match any ICMP-packet sent to your machine from IP address 10.0.0.1, but your firewall would not "do" anything with the packet. Thus it would be up to the following lines (or eventually the policy of the table) to actually "do" something with the packet. With the use of CONTEXT, the example line would look like this:

context "INPUT" "filter"
nojump -p icmp -s 10.0.0.1

The rule syntax

For every IPtables rule you want to specify in Iceditch, the syntax is based on the underlying IPtables rule. However, Iceditch rules are structured differently: the context is specified at the beginning of the stanza, the target forms the opening keyword, and there are several optional addition to the target. Therefor, forming a firewall rule in Iceditch requires you to follow both Iceditch syntax rules and IPtables syntax rules. Don't worry, it's actually quite simple.

What we've done is create a page called the Iceditch Command Reference, where for every target all options are described. However, this reference presupposes intimate knowledge of IPtables. Currently this wiki does not offer a comprehensive course in IPtables; to obtain this knowledge one might start off at sites like this and this one.

The functionality

Iceditch helps you create an IPtables based firewall. But what exactly can it do to help you? You can find out by reading the page on Iceditch functionality, where we list both current functionality, as well as future features.

The program structure

Iceditch consists of a number of files, each of which is located in a logical place - at least we think so. For clarity, we've created a comprehensive listing of all the files that comprise the Iceditch package, along with their location and function. It can be found on the Iceditch file structure page.