iptables: Usage, Options & Common CI Errors

iptables defines packet-filtering and NAT rules in the Linux kernel firewall.

iptables shows up in CI when a test needs to block, redirect, or simulate network faults. Inside containers it usually fails without NET_ADMIN, and modern distros front the iptables command onto nftables, which changes its behavior.

What it does

iptables administers the netfilter tables (filter, nat, mangle) that decide whether packets are accepted, dropped, or rewritten. In CI it is used to inject faults (drop traffic to a port), set up port forwarding, or inspect rules a network policy created.

Common usage

Terminal

iptables -L -n -v              # list filter rules, numeric, verbose
iptables -t nat -L -n          # list NAT rules
iptables -A INPUT -p tcp --dport 8080 -j DROP   # block a port
iptables -I INPUT 1 -s 10.0.0.0/8 -j ACCEPT     # insert first
iptables -F                    # flush all rules

Options

Flag	What it does
-L -n -v	List rules, numeric, with counters
-A <chain>	Append a rule to a chain
-I <chain> [pos]	Insert a rule (default at the top)
-D <chain> <rule>	Delete a matching rule
-t nat\|mangle	Operate on a non-default table
-j DROP\|ACCEPT\|REJECT	Jump target / verdict

Common errors in CI

"iptables v1.x: can't initialize iptables table "filter": Permission denied (you must be root)" - the container lacks CAP_NET_ADMIN; add --cap-add=NET_ADMIN or run privileged. "Table does not exist (do you need to insmod?)" means the kernel module is missing on the host. On modern distros iptables is really iptables-nft (a shim over nftables); rules added with the legacy backend may be invisible to the nft backend and vice-versa - check iptables --version for "(nf_tables)" vs "(legacy)" and use update-alternatives consistently.