0
# Python-iptables
1

2
Python-iptables provides Python bindings for iptables, the standard packet filtering and manipulation framework under Linux. It offers a pythonesque wrapper that interfaces directly with the iptables C libraries (libiptc, libxtables, and extensions) rather than parsing command-line output, making it suitable for dynamic and complex routing and firewall applications where rules are frequently updated.
3

4
## Package Information
5

6
- **Package Name**: python-iptables
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install python-iptables`
10

11
## Core Imports
12

13
```python
14
import iptc
15
```
16

17
Common patterns for working with tables, chains, and rules:
18

19
```python
20
from iptc import Table, Chain, Rule, Match, Target, Policy, IPTCError
21
from iptc import Table6, Rule6, is_table_available, is_table6_available
22
from iptc.errors import XTablesError
23
```
24

25
High-level interface:
26

27
```python
28
import iptc.easy as easy
29
```
30

31
## Basic Usage
32

33
```python
34
import iptc
35

36
# Create a table and chain
37
table = iptc.Table(iptc.Table.FILTER)
38
chain = iptc.Chain(table, "INPUT")
39

40
# Create a rule to accept SSH traffic
41
rule = iptc.Rule()
42
rule.protocol = "tcp"
43
rule.src = "192.168.1.0/24"
44

45
# Add TCP match for SSH port
46
match = rule.create_match("tcp")
47
match.dport = "22"
48

49
# Set target to ACCEPT
50
rule.target = rule.create_target("ACCEPT")
51

52
# Insert rule into chain
53
chain.insert_rule(rule)
54
```
55

56
High-level interface example:
57

58
```python
59
import iptc.easy as easy
60

61
# Add rule using dictionary syntax
62
rule_dict = {
63
    'protocol': 'tcp',
64
    'src': '192.168.1.0/24', 
65
    'tcp': {'dport': '22'},
66
    'target': 'ACCEPT'
67
}
68
easy.add_rule('filter', 'INPUT', rule_dict)
69

70
# Dump existing rules
71
rules = easy.dump_chain('filter', 'INPUT')
72
print(rules)
73
```
74

75
## Architecture
76

77
Python-iptables uses a layered architecture that mirrors the iptables C library structure:
78

79
- **Tables**: Container for chains (filter, nat, mangle, raw, security)
80
- **Chains**: Container for rules (INPUT, OUTPUT, FORWARD, custom chains)
81
- **Rules**: Individual packet filtering/manipulation instructions
82
- **Matches**: Conditions for packet matching (tcp, udp, state, etc.)
83
- **Targets**: Actions to take on matched packets (ACCEPT, DROP, MASQUERADE, etc.)
84

85
The library provides both a low-level object-oriented interface that closely matches the underlying C API and a high-level dictionary-based interface for simplified operations.
86

87
## Capabilities
88

89
### IPv4 Table and Chain Management
90

91
Core functionality for managing iptables tables and chains, including creation, deletion, policy setting, and rule management. Provides the foundation for all iptables operations.
92

93
```python { .api }
94
class Table:
95
    FILTER: str
96
    NAT: str
97
    MANGLE: str
98
    RAW: str
99
    SECURITY: str
100
    
101
    def __init__(self, name: str, autocommit: bool = None): ...
102
    def commit(self) -> None: ...
103
    def refresh(self) -> None: ...
104
    def create_chain(self, chain: str) -> 'Chain': ...
105
    def delete_chain(self, chain: str) -> None: ...
106

107
class Chain:
108
    def __init__(self, table: Table, name: str): ...
109
    def insert_rule(self, rule: 'Rule', position: int = 0) -> None: ...
110
    def append_rule(self, rule: 'Rule') -> None: ...
111
    def delete_rule(self, rule: 'Rule') -> None: ...
112
    def flush(self) -> None: ...
113
    def set_policy(self, policy: str, counters: tuple = None) -> None: ...
114

115
def is_table_available(name: str) -> bool: ...
116
```
117

118
[IPv4 Tables and Chains](./ipv4-tables-chains.md)
119

120
### Rule Creation and Management
121

122
Comprehensive rule creation, matching, and targeting system supporting all iptables match and target extensions. Enables precise packet filtering and manipulation.
123

124
```python { .api }
125
class Rule:
126
    def __init__(self, entry=None, chain=None): ...
127
    def create_match(self, name: str, revision: int = None) -> 'Match': ...
128
    def create_target(self, name: str, revision: int = None, goto: bool = False) -> 'Target': ...
129
    def add_match(self, match: 'Match') -> None: ...
130
    
131
class Match:
132
    def __init__(self, rule: Rule, name: str = None, match=None, revision: int = None): ...
133
    
134
class Target:
135
    def __init__(self, rule: Rule, name: str = None, target=None, revision: int = None, goto: bool = None): ...
136
```
137

138
[Rules, Matches, and Targets](./rules-matches-targets.md)
139

140
### IPv6 Support
141

142
Full IPv6 support with dedicated classes for handling IPv6 addresses, prefixes, and protocol-specific matching. Provides the same interface as IPv4 with IPv6-specific handling.
143

144
```python { .api }
145
class Table6(Table):
146
    def __init__(self, name: str, autocommit: bool = None): ...
147

148
class Rule6(Rule):
149
    def __init__(self, entry=None, chain=None): ...
150

151
def is_table6_available(name: str) -> bool: ...
152
```
153

154
[IPv6 Support](./ipv6-support.md)
155

156
### High-Level Interface
157

158
Simplified dictionary-based interface for common iptables operations. Provides functions for table, chain, and rule management without requiring object instantiation.
159

160
```python { .api }
161
def add_rule(table: str, chain: str, rule_d: dict, position: int = 0, ipv6: bool = False) -> None: ...
162
def delete_rule(table: str, chain: str, rule_d: dict, ipv6: bool = False, raise_exc: bool = True) -> None: ...
163
def dump_chain(table: str, chain: str, ipv6: bool = False) -> list: ...
164
def flush_table(table: str, ipv6: bool = False, raise_exc: bool = True) -> None: ...
165
def add_chain(table: str, chain: str, ipv6: bool = False, raise_exc: bool = True) -> bool: ...
166
def delete_chain(table: str, chain: str, ipv6: bool = False, flush: bool = False, raise_exc: bool = True) -> None: ...
167
```
168

169
[High-Level Interface](./high-level-interface.md)
170

171
## Types
172

173
```python { .api }
174
class Policy:
175
    ACCEPT: str
176
    DROP: str
177
    QUEUE: str
178
    RETURN: str
179

180
class IPTCError(Exception):
181
    """Exception for low-level libiptc errors"""
182

183
class XTablesError(Exception):
184
    """Exception for xtables extension errors"""
185
```