or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

high-level-interface.mdindex.mdipv4-tables-chains.mdipv6-support.mdrules-matches-targets.md
tile.json

tessl/pypi-python-iptables

Python bindings for iptables providing programmatic control over Linux netfilter rules

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/python-iptables@1.2.x

To install, run

npx @tessl/cli install tessl/pypi-python-iptables@1.2.0

index.mddocs/

Python-iptables

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.

Package Information

  • Package Name: python-iptables
  • Package Type: pypi
  • Language: Python
  • Installation: pip install python-iptables

Core Imports

import iptc

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

from iptc import Table, Chain, Rule, Match, Target, Policy, IPTCError
from iptc import Table6, Rule6, is_table_available, is_table6_available
from iptc.errors import XTablesError

High-level interface:

import iptc.easy as easy

Basic Usage

import iptc

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

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

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

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

# Insert rule into chain
chain.insert_rule(rule)

High-level interface example:

import iptc.easy as easy

# Add rule using dictionary syntax
rule_dict = {
    'protocol': 'tcp',
    'src': '192.168.1.0/24', 
    'tcp': {'dport': '22'},
    'target': 'ACCEPT'
}
easy.add_rule('filter', 'INPUT', rule_dict)

# Dump existing rules
rules = easy.dump_chain('filter', 'INPUT')
print(rules)

Architecture

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

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

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.

Capabilities

IPv4 Table and Chain Management

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

class Table:
    FILTER: str
    NAT: str
    MANGLE: str
    RAW: str
    SECURITY: str
    
    def __init__(self, name: str, autocommit: bool = None): ...
    def commit(self) -> None: ...
    def refresh(self) -> None: ...
    def create_chain(self, chain: str) -> 'Chain': ...
    def delete_chain(self, chain: str) -> None: ...

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

def is_table_available(name: str) -> bool: ...

IPv4 Tables and Chains

Rule Creation and Management

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

class Rule:
    def __init__(self, entry=None, chain=None): ...
    def create_match(self, name: str, revision: int = None) -> 'Match': ...
    def create_target(self, name: str, revision: int = None, goto: bool = False) -> 'Target': ...
    def add_match(self, match: 'Match') -> None: ...
    
class Match:
    def __init__(self, rule: Rule, name: str = None, match=None, revision: int = None): ...
    
class Target:
    def __init__(self, rule: Rule, name: str = None, target=None, revision: int = None, goto: bool = None): ...

Rules, Matches, and Targets

IPv6 Support

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.

class Table6(Table):
    def __init__(self, name: str, autocommit: bool = None): ...

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

def is_table6_available(name: str) -> bool: ...

IPv6 Support

High-Level Interface

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

def add_rule(table: str, chain: str, rule_d: dict, position: int = 0, ipv6: bool = False) -> None: ...
def delete_rule(table: str, chain: str, rule_d: dict, ipv6: bool = False, raise_exc: bool = True) -> None: ...
def dump_chain(table: str, chain: str, ipv6: bool = False) -> list: ...
def flush_table(table: str, ipv6: bool = False, raise_exc: bool = True) -> None: ...
def add_chain(table: str, chain: str, ipv6: bool = False, raise_exc: bool = True) -> bool: ...
def delete_chain(table: str, chain: str, ipv6: bool = False, flush: bool = False, raise_exc: bool = True) -> None: ...

High-Level Interface

Types

class Policy:
    ACCEPT: str
    DROP: str
    QUEUE: str
    RETURN: str

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

class XTablesError(Exception):
    """Exception for xtables extension errors"""