Migration from iptables to nftables: step-by-step conversion and testing

The migration from iptables to nftables is a necessary step for many Linux‑infrastructures: nftables provides modern means for managing firewall rules, more efficient data structures and atomic updates that minimize downtime windows when loading rules. In this practical guide I describe a reproducible process from inventory through conversion to testing and rollback. The guide is aimed at administrators, system engineers and operators who need to keep operation, interfaces and Docker interactions in view.

Why switch from iptables to nftables?

iptables grew historically; nftables is a newer kernel API with a userspace toolset (nft) that manages rules as a central „ruleset“. Advantages include lower CPU overhead with large rule sets, sets/maps for performant lookups and atomic rule-replacement operations. This is particularly relevant if you operate many dynamic entries (e.g. IP lists) or containerized workloads.

Terminology: „ruleset“ denotes the entirety of all tables, chains and rules. „conntrack“ is the connection tracking in the kernel that manages existing connections and is essential for stateful firewalls.

Preparation: inventory, dependencies and prerequisites

Before you convert, inventory hosts, services, Docker usage, external filters (load balancers, VPN) and all iptables extensions. Check kernel version, libnftables installation and the currently used iptables backend (legacy vs nft).

Concrete steps

# iptables Regelwerk sichern (IPv4 und IPv6)
iptables-save > /root/iptables-save-$(date +%F).rules
ip6tables-save > /root/ip6tables-save-$(date +%F).rules

# Paket- und Kernel‑Status dokumentieren (Debian/Ubuntu Beispiel)
dpkg -l | egrep "nftables|iptables|libnft" > /root/pkg-list-$(date +%F).txt
uname -r > /root/kernel-version-$(date +%F).txt

Tooling: what helps, and where are the limits?

Available tools:

• iptables-translate — translates individual iptables rules into nftables syntax; useful for manual refinement.
• iptables-save / iptables-RESTore — proven for backing up and RESToring complete iptables dumps.
• nft — core tool for nftables (loading, checking, listing).

Important: Automated conversion is never 100% error-free. Complex matches, proprietary extensions, NFLOG, raw manipulations or special kernel modules require manual inspection.

Migration from iptables to nftables: procedure (step by step)

1. Replicate the staging environment

Replicate host configuration, Docker stacks and network profiles in a test environment. Test with realistic load and connection profiles so conntrack and performance impacts become visible.

2. Automated translation and aggregation

A common pattern is: read the iptables dump, convert rules individually with iptables-translate and transfer them into a structured nftables file. This allows grouping rules and creating sets.

# Regeln per Script übersetzen und in Datei sammeln
iptables-save | grep -E "^-A" | while read -r rule; do
  # Regel ohne Präfix -A an iptables-translate übergeben
  trimmed=$(echo "$rule" | sed 's/^-A //')
  echo "$trimmed" | xargs -I '{}' iptables-translate '{}'
done > /root/translated.rules

3. Structuring and use of sets

Group similar rules into tables/chains and use sets for IP lists, ports or port ranges — this reduces the number of rules and improves lookup performance.

# Beispiel: Set für IPs und Anwendung in einer Chain
nft add table inet filter
nft 'add set inet filter trusted { type ipv4_addr; flags interval; }'
nft add element inet filter trusted { 10.10.0.1, 10.10.0.0/24 }

nft 'add chain inet filter input { type filter hook input priority 0; policy drop; }'
nft add rule inet filter input ip saddr @trusted accept

4. Syntaxprüfung und atomarer Austausch

Use „nft -c -f“ for syntax checks and „nft replace ruleset“ for atomic replacement of the active ruleset.

# Syntaxcheck
nft -c -f /root/created-nft-rules.conf

# Atomarer Austausch
nft replace ruleset < /root/created-nft-rules.conf

# Aktuellen Stand prüfen
nft list ruleset

5. Canary Rollout

Deploy the new ruleset first to a small number of hosts. Monitor reachability, latency, CPU and conntrack. If issues arise, canary hosts allow targeted rollback without impacting the wider cluster.

Tests: Funktionalität, Paketanalyse und Automatisierung

Test three levels: functional (reachability/policy), packet path (tcpdump/pcap) and connection tracking (conntrack). Automated tests in CI ensure that changes are validated before switching to production.

Beispiele für Testkommandos

# Reachability Test
curl -sS --connect-timeout 5 http://10.0.5.10:8080/health || echo "Service unreachable"

# Paketsammlung für Debug
tcpdump -i eth0 host 10.0.5.10 and port 8080 -c 200 -w /tmp/trace.pcap

# Conntrack Überblick
conntrack -L | head -n 50

Docker‑Hosts: Optionen und Fallstricke

Docker natively creates iptables chains (DOCKER, DOCKER-USER) for NAT and port forwarding. Two viable approaches:

• Continue to allow Docker to manage iptables and rely on the distribution compatibility layer (iptables-nft).
• Run Docker with „–iptables=false“ and manage all NAT/filter rules yourself — this requires significantly more know-how.

Both approaches have pros and cons. For production systems, gradually testing the compatibility layer is usually less risky.

Praktische Docker‑Tests

# docker daemon konfigurieren, damit es iptables nicht verändert
cat /etc/docker/daemon.json
# optional
# {
#   "iptables": false
# }
systemctl RESTart docker

# Überprüfen, ob DOCKER-USER Chain vorhanden ist
iptables -L DOCKER-USER -n

Conntrack: Erhaltung, Limits und Timeouts

conntrack stores state information for connections. During migration, existing connections can continue as long as conntrack entries are not lost. However, a kernel reload or an incorrect order when RESTarting network services can cause connection drops.

Wichtige Sysctl‑Parameter

# Beispiel: conntrack Kapazität erhöhen
sysctl -w net.netfilter.nf_conntrack_max=262144
# Persistenz in /etc/sysctl.d/99-nf.conf
# net.netfilter.nf_conntrack_max=262144

Rationale: With high connection volumes, an insufficient conntrack_max can cause new connections to be dropped. Plan changes and measure before and after the adjustment.

Performance‑Optimierung: Sets, Maps und Atomicity

nftables‑sets reduce the number of direct match rules. For very large tables use flags like „interval“ or combine with Counters to detect hotspots. Atomic updates prevent inconsistencies during deployments.

Rollback‑strategy and emergency access

A clearly documented and tested rollback plan is essential. Store iptables saves under revision control and test RESToration in staging.

Example: Quick rollback to iptables

# 1. Aktuelle nft Regeln sichern
nft list ruleset > /root/nft-backup-$(date +%F).conf

# 2. Vorherigen iptables Dump wiederherstellen
iptables-RESTore < /root/iptables-save-2023-09-01.rules
ip6tables-RESTore < /root/ip6tables-save-2023-09-01.rules

# 3. Docker neu starten (falls nötig)
systemctl RESTart docker

Additional tip: store the rollback playbook as an executable script that team members can operate after a short briefing.

Common pitfalls and preventive measures

• Conflicts with firewalld/ufw: disable or migrate them, otherwise these services will overwrite rules at boot.
• Address family mismatch: IPv6‑addresses in an IPv4 table cause errors; prefer the „inet“ family for shared rules.
• Missing persistence: enable the systemd service for nftables or ensure your configuration management tools RESTore the file at boot.
• Docker Port‑Forwarding loses connectivity: test port mappings after every reload and check DOCKER‑Chains.

When to postpone migration?

Postpone migration if you are close to major release windows, if critical third‑party applications use proprietary iptables extensions, or if your ops teams are not sufficiently practiced in conntrack behavior and Docker network management. Migration is an infrastructure project and requires time for testing and training.

Quick reference: Useful commands

# Regeln anzeigen
nft list ruleset

# Syntaxcheck
nft -c -f /path/to/file.conf

# Conntrack Übersicht
conntrack -L | wc -l

# Backup iptables
iptables-save > /root/iptables-backup.rules

# RESTore iptables
iptables-RESTore < /root/iptables-backup.rules

Acceptance, monitoring and ongoing operation

After Go‑Live: export Counters, attach log prefixes to your central logging and create dashboards for DROP rates and conntrack utilization. Schedule regular smoke tests and keep canary hosts as a reference point.

Maintenance routine

• Daily check of DROP counters during the first weeks of operation
• Weekly validation of container network paths
• Monthly review sessions with change logs

Conclusion

The migration from iptables to nftables is a worthwhile step for long‑term maintainability, performance and consistent management of IPv4/IPv6 rules. Crucial are a thorough inventory, staging tests, automated and manual validation of the converted rules, and a tested rollback plan. Especially on Docker hosts proceed cautiously and examine the interaction with DOCKER/DOCKER‑USER Chains in detail. With CI‑backed checks, canary rollouts and monitoring you achieve a stable, reproducible migration path without operational interruption.

This guide provides concrete verification scripts, troubleshooting hints and a practical rollback strategy that can be integrated directly into existing operational processes. Start in staging, automate tests, and expand your monitoring visibility before moving to production.

Practical: Governance and CI for the migration from iptables to nftables

A single run is not sufficient for a secure migration from iptables to nftables. Establish „Policy as Code“: rules are versioned in a repository, changes go through review, automated tests and a staged rollout. This is particularly important when access controls are process-adjacent to custom enterprise software or business applications.

Architecture notes for distributed environments

• Configuration source: A central Git repo with environments (staging, canary, prod) prevents drift.
• Distribution: Use GitOps agents or CM tools so hosts pull the same nftables configuration in a desired-state manner.
• HA clusters: Ensure a deterministic order when applying changes (passive nodes first) so that existing TCP sessions are not dropped unnecessarily.

Checks and CI gate

Automated checks should cover at minimum the following: syntax, idempotence, policy regression (opening of new ports), performance smoke (number of rules, set sizes) and a simulated packet inspection using pcap snippets.

# Beispiel: einfacher CI-Job (Pseudo-YAML) prüft ruleset
jobs:
  validate-nft:
    script:
      - nft -c -f changed.rules.conf    # Syntaxprüfung
      - ./tests/check-no-open-ports.sh  # Policy-Regressions-Test
      - ./tests/simulate-traffic.sh     # Paketpfad-Simulation

Operations: persistence, idempotence and rollback hooks

Ensure an idempotent application routine. A systemd service or a CM task should check whether the ruleset has changed and only apply it when necessary. This avoids unnecessary reloads and potential connection interruptions.

# Beispiel systemd-Unit für idempotentes Anwenden
[Unit]
Description=Apply nftables ruleset atomically
After=network.target

[Service]
Type=oneshot
ExecStart=/usr/sbin/nft replace ruleset < /etc/nftables/rules.conf
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

Monitoring, audit and alerting

Collect metrics per chain and rule counter. For integration into monitoring stacks you can export counters via cron and present them to the node_exporter textfile collector. Alerts should be triggered on sudden increases in DROP, decreasing conntrack capacity, or deviations in rule count.

# Counters exportieren (Textfile für Prometheus node_exporter)
mkdir -p /var/lib/node_exporter/textfile_collector
nft list ruleset | grep counter -n > /var/lib/node_exporter/textfile_collector/nft_counters.prom

Compliance and change management

Document each rule creation with the responsible person, ticket ID and impact description. For process-adjacent software solutions it is helpful to tag rules with application tags (e.g. app:webshop) so audit queries can be mapped to business areas.

In short: migration is both a technical implementation and an organizational process. With versioning, CI gates, idempotent deployments, targeted monitoring and clear rollback hooks you minimize risks and ensure that security and operational requirements continue to be met reproducibly after the change.

Operational notes for the migration from iptables to nftables

In live environments the decision is not only the conversion but also how you orchestrate states, counters and distributed rollouts. Use targeted atomic set updates („nft replace element“) to modify IP lists or port lists without a complete ruleset reload; this minimizes connection interruptions and preserves conntrack entries. Note that a full „nft replace ruleset“ can reset counters—export counters before critical changes when monitoring continuity is required.

In HA clusters or during rolling updates: work with a deterministic order (passive nodes first), test behavior with real sessions and automate rollback. Annotate rules with metadata (e.g. app:webshop) and version rulesets in Git so checks against individual enterprise software or business services can be reproduced and audited.