/flags/iptables/iptables-w-wait-xtables-lock
iptables -w (--wait): wait for the xtables lock instead of failing
- tool
- iptables / nftables
- command
- iptables
- flag
- -w, --wait [SECONDS]
- default
- off (iptables exits immediately if another instance holds the xtables lock)
iptables -w 10 -A INPUT -p tcp --dport 443 -j ACCEPT waits up to ten seconds for the xtables lock before changing the rules. iptables takes an exclusive lock at start so that two instances do not modify the rule set at the same time; by default, a second instance gives up immediately with Another app is currently holding the xtables lock. With -w it waits indefinitely, or for the given number of seconds, until the lock is free.
Usage
sudo iptables -w -A INPUT -s 192.0.2.10 -j DROP # wait as long as needed
sudo iptables -w 10 -A INPUT -s 192.0.2.10 -j DROP # wait at most 10 seconds
sudo iptables -w 10 -L -n # also for read-only listingListing rules takes the lock too, so monitoring scripts that run iptables -L frequently can themselves cause collisions; give them -w as well.
Who holds the lock
Hosts with several firewall managers contend for the lock constantly:
| Program | Why it touches iptables |
|---|---|
| Docker | Creates NAT and filter rules when containers start or stop |
| kube-proxy (iptables mode) | Rewrites service rules on every endpoint change |
| firewalld / ufw | Apply their rule sets on reload |
| fail2ban | Adds and removes ban rules |
| Your scripts and configuration management | Ansible, Salt, cloud-init and boot scripts |
On such hosts every scripted iptables call should carry -w with a timeout; otherwise rules are silently missing whenever a call happens to collide with another program.
Related options and alternatives
| Approach | Effect |
|---|---|
| -w [SECONDS] | Wait for the lock (indefinitely or up to SECONDS) |
| iptables-restore -w | Apply a whole rule file atomically, waiting for the lock |
| iptables-restore --noflush | Add rules from a file without flushing existing ones |
Loading a complete rule set with iptables-restore takes the lock once and applies everything in one step, which is faster and safer than many single calls; see save and restore rules.
Pitfalls
- Hangs in boot scripts. An indefinite
-wwaits forever if the lock holder is stuck; always give a timeout in unattended scripts. - Lock file location. iptables uses the lock file
/run/xtables.lock(override with theXTABLES_LOCKFILEenvironment variable); containers that share the host's network namespace but not/rundo not see each other's lock. - Order still matters. Waiting fixes collisions, not rule placement; see iptables -I vs -A. For the move to nftables, see iptables vs nftables.
FAQ
What does Another app is currently holding the xtables lock mean?
Another iptables process (often Docker, kube-proxy, firewalld or fail2ban) is changing rules at the same moment. Without -w iptables gives up immediately; with -w it waits until the lock is free and then runs.
Should I use -w without a number?
It waits indefinitely, which is fine for interactive use. In scripts and services prefer a limit such as -w 10, so a stuck lock holder makes the command fail after ten seconds instead of hanging forever.
Does iptables-nft need the lock?
iptables-nft still accepts -w for compatibility, and the nft-based variant applies changes as transactions in the kernel. Keeping -w in scripts is harmless and protects hosts that still run iptables-legacy.