11Examples
22========
33
4- Introduction
5- ------------
4+ Rules
5+ -----
66
77In ``python-iptables ``, you usually first create a rule, and set any
88source/destination address, in/out interface and protocol specifiers, for
9- example:
9+ example::
1010
1111 >>> import iptc
1212 >>> rule = iptc.Rule()
@@ -20,7 +20,7 @@ source IP address of 192.168.1.0/255.255.255.0.
2020A rule may contain matches and a target. A match is like a filter matching
2121certain packet attributes, while a target tells what to do with the packet
2222(drop it, accept it, transform it somehow, etc). One can create a match or
23- target via a Rule:
23+ target via a Rule::
2424
2525 >>> rule = iptc.Rule()
2626 >>> m = rule.create_match("tcp")
@@ -29,7 +29,7 @@ target via a Rule:
2929Match and target parameters can be changed after creating them. It is also
3030perfectly valid to create a match or target via instantiating them with
3131their constructor, but you still need a rule and you have to add the matches
32- and the target to their rule manually:
32+ and the target to their rule manually::
3333
3434 >>> rule = iptc.Rule()
3535 >>> match = iptc.Match(rule, "tcp")
@@ -38,14 +38,14 @@ and the target to their rule manually:
3838 >>> rule.target = target
3939
4040Any parameters a match or target might take can be set via the attributes of
41- the object. To set the destination port for a TCP match:
41+ the object. To set the destination port for a TCP match::
4242
4343 >>> rule = iptc.Rule()
4444 >>> rule.protocol = "tcp"
4545 >>> match = rule.create_match("tcp")
4646 >>> match.dport = "80"
4747
48- To set up a rule that matches packets marked with 0xff:
48+ To set up a rule that matches packets marked with 0xff::
4949
5050 >>> rule = iptc.Rule()
5151 >>> rule.protocol = "tcp"
@@ -55,18 +55,84 @@ To set up a rule that matches packets marked with 0xff:
5555Parameters are always strings.
5656
5757When you are ready constructing your rule, add them to the chain you want it
58- to show up in:
58+ to show up in::
5959
6060 >>> chain = iptc.Chain(iptc.Table(iptc.Table.FILTER), "INPUT")
6161 >>> chain.insert_rule(rule)
6262
6363This will put your rule into the INPUT chain in the filter table.
6464
65- Simple rule with standard target
66- --------------------------------
65+ Chains and tables
66+ -----------------
6767
68- Reject packets with source address ``127.0.0.1/255.0.0.0 `` coming in on any of
69- the eth interfaces:
68+ You can of course also check what a rule's source/destination address,
69+ in/out inteface etc is. To print out all rules in the FILTER table::
70+
71+ >>> import iptc
72+ >>> table = iptc.Table(iptc.Table.FILTER)
73+ >>> for chain in table.chains:
74+ >>> print "======================="
75+ >>> print "Chain ", chain.name
76+ >>> for rule in chain.rules:
77+ >>> print "Rule", "proto:", rule.protocol, "src:", rule.src, "dst:", \
78+ >>> rule.dst, "in:", rule.in_interface, "out:", rule.out_interface,
79+ >>> print "Matches:",
80+ >>> for match in rule.matches:
81+ >>> print match.name,
82+ >>> print "Target:",
83+ >>> print rule.target.name
84+ >>> print "======================="
85+
86+ As you see in the code snippet above, rules are organized into chains, and
87+ chains are in tables. You have a fixed set of tables; for IPv4::
88+
89+ * FILTER,
90+ * NAT,
91+ * MANGLE and
92+ * RAW.
93+
94+ For IPv6 the tables are::
95+
96+ * FILTER,
97+ * MANGLE,
98+ * RAW and
99+ * SECURITY.
100+
101+ To access a table::
102+
103+ >>> import iptc
104+ >>> table = iptc.Table(iptc.Table.FILTER)
105+ >>> print table.name
106+ filter
107+
108+ To create a new chain in the FILTER table::
109+
110+ >>> import iptc
111+ >>> table = iptc.Table(iptc.Table.FILTER)
112+ >>> chain = table.create_chain("testchain")
113+
114+ $ sudo iptables -L -n
115+ [...]
116+ Chain testchain (0 references)
117+ target prot opt source destination
118+
119+ To access an existing chain::
120+
121+ >>> import iptc
122+ >>> table = iptc.Table(iptc.Table.FILTER)
123+ >>> chain = iptc.Chain(table, "INPUT")
124+ >>> chain.name
125+ 'INPUT'
126+ >>> len(chain.rules)
127+ 10
128+ >>>
129+
130+ More about matches and targets
131+ ------------------------------
132+
133+ There are basic targets, such as ``DROP `` and ``ACCEPT ``. E.g. to reject
134+ packets with source address ``127.0.0.1/255.0.0.0 `` coming in on any of the
135+ ``eth `` interfaces::
70136
71137 >>> import iptc
72138 >>> chain = iptc.Chain(iptc.Table(iptc.Table.FILTER), "INPUT")
@@ -77,25 +143,22 @@ the eth interfaces:
77143 >>> rule.target = target
78144 >>> chain.insert_rule(rule)
79145
80- Simple rule not using any match extensions
81- ------------------------------------------
146+ To instantiate a target or match, we can either create an object like above,
147+ or use the ``rule.create_target(target_name) `` and
148+ ``rule.create_match(match_name) `` methods. For example, in the code above
149+ target could have been created as::
82150
83- Inserting a rule to NAT TCP packets going out via `` eth0 ``:
151+ >>> target = rule.create_target("DROP")
84152
85- >>> import iptc
86- >>> chain = iptc.Chain(iptc.Table(iptc.Table.NAT ), " POSTROUTING"
87- >>> rule = iptc.Rule()
88- >>> rule.protocol = " tcp"
89- >>> rule.out_interface = " eth0"
90- >>> target = iptc.Target(rule, " MASQUERADE"
91- >>> target.to_ports = " 1234"
153+ instead of::
154+
155+ >>> target = iptc.Target(rule, "DROP")
92156 >>> rule.target = target
93- >>> chain.insert_rule(rule)
94157
95- Rule using the udp match extension
96- ----------------------------------
158+ The former also adds the match or target to the rule, saving a call.
97159
98- Mark packets going to ``192.168.1.2 `` UDP port ``1234 `` with ``0xffff ``:
160+ Another example, using a target which takes parameters. Let's mark packets
161+ going to ``192.168.1.2 `` UDP port ``1234 `` with ``0xffff ``::
99162
100163 >>> import iptc
101164 >>> chain = iptc.Chain(iptc.Table(iptc.Table.MANGLE), "PREROUTING")
@@ -110,13 +173,25 @@ Mark packets going to ``192.168.1.2`` UDP port ``1234`` with ``0xffff``:
110173 >>> rule.target = target
111174 >>> chain.insert_rule(rule)
112175
113- Multiple matches with iprange
114- -----------------------------
176+ Matches are optional (specifying a target is mandatory). E.g. to insert a rule
177+ to NAT TCP packets going out via `` eth0 ``::
115178
116- Now we will add multiple matches to a rule. This one is the
117- ``python-iptables `` equivalent of the following iptables command:
179+ >>> import iptc
180+ >>> chain = iptc.Chain(iptc.Table(iptc.Table.NAT), "POSTROUTING")
181+ >>> rule = iptc.Rule()
182+ >>> rule.protocol = "tcp"
183+ >>> rule.out_interface = "eth0"
184+ >>> target = iptc.Target(rule, "MASQUERADE")
185+ >>> target.to_ports = "1234"
186+ >>> rule.target = target
187+ >>> chain.insert_rule(rule)
188+
189+ Here only the properties of the rule decide whether the rule will be applied
190+ to a packet.
118191
119- # iptables -A INPUT -p tcp –destination-port 22 -m iprange –src-range 192.168.1.100-192.168.1.200 –dst-range 172.22.33.106 -j DROP
192+ Matches are optional, but we can add multiple matches to a rule. In the
193+ following example we will do that, using the ``iprange `` and the ``tcp ``
194+ matches::
120195
121196 >>> import iptc
122197 >>> rule = iptc.Rule()
@@ -131,3 +206,7 @@ Now we will add multiple matches to a rule. This one is the
131206 >>> rule.target = iptc.Target(rule, "DROP")
132207 >>> chain = iptc.Chain(iptc.Table.(iptc.Table.FILTER), "INPUT")
133208 >>> chain.insert_rule(rule)
209+
210+ This is the ``python-iptables `` equivalent of the following iptables command::
211+
212+ # iptables -A INPUT -p tcp –destination-port 22 -m iprange –src-range 192.168.1.100-192.168.1.200 –dst-range 172.22.33.106 -j DROP
0 commit comments