Structuring an iptables-to-nftables Migration as Staged Execution

Introduction to iptables and nftables

Overview of iptables

iptables is the legacy userspace front-end to the Netfilter framework in the Linux kernel. It organizes rules into tables (filter, nat, mangle, raw, security) and chains (INPUT, OUTPUT, FORWARD, PREROUTING, POSTROUTING, etc.). Each rule consists of a match expression (e.g., -p tcp --dport 22) and a target (e.g., ACCEPT, DROP, LOG, REJECT). The kernel evaluates packets sequentially through the chains; the first matching rule terminates traversal unless the target is an action like LOG or MANGLE. Key operational traits:

• Linear rule list – each packet walks the list until a terminating verdict.
• Separate userspace tools for IPv4 (iptables) and IPv6 (ip6tables).
• Stateful tracking is performed by the connection-tracking (conntrack) subsystem, which is invoked implicitly by state matches (-m state --state ESTABLISHED,RELATED).
• Rule updates are not atomic; inserting or deleting a rule can cause a transient window where packets see an inconsistent rule set.

Overview of nftables

nftables replaces the iptables suite with a single, unified framework that combines the Netfilter hooks, expression engine, and set/map data structures into one userspace command (nft). Rules are built from expressions (matches) and statements (verdicts, counters, logs, etc.) and can be grouped into sets and maps for efficient look-ups. Core concepts:

• Tables and chains exist, but the kernel evaluates rules using a bytecode-like expression engine that can short-circuit via maps, verdicts, and immediate accepts/drops.
• Atomic rule replacement – loading a ruleset with nft -f <file> swaps the entire table in a single kernel operation, guaranteeing a consistent view for all packets.
• Unified IPv4/IPv6 handling – the same rule set can contain both ip and ip6 families, or separate tables can be used.
• Extensible data structures – named sets, maps, verdict maps, and dictionaries enable O(1) look-ups for large address/port lists.

Key Differences Between iptables and nftables

Pre-Migration Checks and Planning

Identifying Current iptables Configuration

To understand the current configuration, perform the following steps:

1. Dump the active rule set (both IPv4 and IPv6):

# IPv4
iptables-save > /root/iptables-backup.v4
# IPv6
ip6tables-save > /root/iptables-backup.v6

2. Capture per-chain statistics to baseline traffic volumes:

iptables -L -v -n > /root/iptables-stats.pre
ip6tables -L -v -n > /root/ip6tables-stats.pre

3. Export NAT and mangle specifics (often missed in a simple filter dump):

iptables -t nat -S > /root/iptables-nat.pre
iptables -t mangle -S > /root/iptables-mangle.pre
ip6tables -t nat -S > /root/ip6tables-nat.pre
ip6tables -t mangle -S > /root/ip6tables-mangle.pre

4. Record conntrack state (size, usage) to detect pressure points:

conntrack -S > /root/conntrack-stats.pre

5. Identify custom helpers or NOTRACK rules (e.g., -j CT --helper tftp) that may need explicit nftables equivalents.

Understanding nftables Syntax and Capabilities

• Basic building blocks – add table, add chain, add rule.
• Expressions – ip saddr, tcp dport, ct state, meta l4proto.
• Statements – accept, drop, reject, counter, log, queue, goto, jump, set, map.
• Sets & maps – defined with type ipv4_addr . inet_service ; (for address-port pairs) or type ipv4_addr (for simple lists).
• Verdict maps – allow a single rule to map match results to an action (map { 1.2.3.4 : drop, 5.6.7.8 : accept }).

Assessing System Requirements and Constraints

Creating a Migration Plan and Timeline

1. Inventory – collect the outputs from Identifying Current iptables Configuration.
2. Lab validation – reproduce the rule set in a isolated test environment (same kernel, same traffic profile).
3. Define phases – Translation → Shadow Mode → Live Traffic Cutover.
4. Set blast-radius limits – initially apply nftables to a single host or a subset of traffic using policy-routing (ip rule) or tc mirroring to avoid affecting the whole fleet.
5. Determine verification gates – packet-counter equality, conntrack state consistency, latency/jitter thresholds.
6. Establish rollback thresholds – e.g., >0.5 % packet loss, >10 ms latency increase, conntrack table >80 % utilization, or nftables counters diverging >2 % from iptables.
7. Schedule cut-over window – low-traffic period, with a pre-approved rollback window of 15 minutes after switchover.
8. Document communication plan – notify ops, monitoring teams, and stakeholders of the change ID, expected impact, and rollback procedure.

Staged Execution of Migration

Phase 1: Translation and Initial Setup

Translating iptables Rules to nftables

1. Automated translation – use the iptables-translate script (part of the iptables package) for each chain and table.

iptables-translate -A INPUT -p tcp --dport 22 -j ACCEPT

This will output the equivalent nftables rule, which can be used to construct the initial nftables configuration.

2. Manual review and adjustment – inspect the translated rules for correctness and adjust as necessary to ensure that the nftables configuration accurately reflects the original iptables intent.

3. Loading the initial nftables configuration – use nft -f to load the translated rules into the kernel.

nft -f /path/to/nftables.conf

This step completes the initial setup of nftables, mirroring the existing iptables configuration.

Phase 2: Shadow Mode Verification

Enabling Shadow Mode

1. Configure nftables to run in shadow mode – this involves setting up nftables to process packets in parallel with iptables, without affecting the actual forwarding decision.

nft add table ip shadow
nft add chain ip shadow input { type filter hook input priority 0; }

2. Duplicate iptables rules in nftables shadow table – ensure that all rules from iptables are duplicated in the nftables shadow table to maintain consistency.

nft add rule ip shadow input ip saddr 1.2.3.4 tcp dport 22 accept

3. Monitor and compare packet counters – use nft list counters and iptables -L -v -n -Z to reset and monitor counters in both iptables and nftables, ensuring they match closely.

Verification Gates

• Packet counter equality: Verify that the packet counters in both iptables and nftables shadow mode are equal or very close, indicating that both are processing packets identically.
• Conntrack state consistency: Ensure that the connection tracking state is consistent between iptables and nftables, using conntrack -L to compare.

Phase 3: Live Traffic Cutover

Switching to nftables

1. Disable iptables – stop the iptables service to prevent it from interfering with nftables.

systemctl stop iptables

2. Enable nftables – start the nftables service and ensure it is configured to load the translated ruleset.

systemctl start nftables

3. Verify nftables operation – use nft list ruleset to verify that the rules are loaded and nft monitor to observe real-time packet processing.

Rollback Procedure

1. Stop nftables – immediately stop the nftables service if issues arise.

systemctl stop nftables

2. Restart iptables – restart the iptables service to revert to the original configuration.

systemctl start iptables

3. Investigate and adjust – analyze the cause of the failure, adjust the nftables configuration as necessary, and reschedule the cutover.

By following this structured approach, the migration from iptables to nftables can be executed with minimal disruption, ensuring the integrity of network traffic and the security of the system.