community.general.iptables_state – Save iptables state into a file or restore it from a file

Note

This plugin is part of the community.general collection (version 2.5.1).

To install it use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.iptables_state.

New in version 1.1.0: of community.general

Synopsis

• iptables is used to set up, maintain, and inspect the tables of IP packet filter rules in the Linux kernel.

• This module handles the saving and/or loading of rules. This is the same as the behaviour of the iptables-save and iptables-restore (or ip6tables-save and ip6tables-restore for IPv6) commands which this module uses internally.

• Modifying the state of the firewall remotely may lead to loose access to the host in case of mistake in new ruleset. This module embeds a rollback feature to avoid this, by telling the host to restore previous rules if a cookie is still there after a given delay, and all this time telling the controller to try to remove this cookie on the host through a new connection.

Note

This module has a corresponding action plugin.

Requirements

The below requirements are needed on the host that executes this module.

• iptables

• ip6tables

Parameters

Parameter	Choices/Defaults	Comments
counters boolean	Choices: no ← yes	Save or restore the values of all packet and byte counters. When true, the module is not idempotent.
ip_version string	Choices: ipv4 ← ipv6	Which version of the IP protocol this module should apply to.
modprobe path		Specify the path to the modprobe program internally used by iptables related commands to load kernel modules. By default, /proc/sys/kernel/modprobe is inspected to determine the executable's path.
noflush boolean	Choices: no ← yes	For state=restored, ignored otherwise. If false, restoring iptables rules from a file flushes (deletes) all previous contents of the respective table(s). If true, the previous rules are left untouched (but policies are updated anyway, for all built-in chains).
path path / required		The file the iptables state should be saved to. The file the iptables state should be restored from.
state string / required	Choices: saved restored	Whether the firewall state should be saved (into a file) or restored (from a file).
table string	Choices: filter nat mangle raw security	When state=restored, restore only the named table even if the input file contains other tables. Fail if the named table is not declared in the file. When state=saved, restrict output to the specified table. If not specified, output includes all active tables.
wait integer		Wait N seconds for the xtables lock to prevent instant failure in case multiple instances of the program are running concurrently.

Notes

Note

• The rollback feature is not a module option and depends on task’s attributes. To enable it, the module must be played asynchronously, i.e. by setting task attributes poll to 0, and async to a value less or equal to ANSIBLE_TIMEOUT. If async is greater, the rollback will still happen if it shall happen, but you will experience a connection timeout instead of more relevant info returned by the module after its failure.

• This module supports check_mode.

Examples

# This will apply to all loaded/active IPv4 tables.
- name: Save current state of the firewall in system file
  community.general.iptables_state:
    state: saved
    path: /etc/sysconfig/iptables

# This will apply only to IPv6 filter table.
- name: save current state of the firewall in system file
  community.general.iptables_state:
    ip_version: ipv6
    table: filter
    state: saved
    path: /etc/iptables/rules.v6

# This will load a state from a file, with a rollback in case of access loss
- name: restore firewall state from a file
  community.general.iptables_state:
    state: restored
    path: /run/iptables.apply
  async: "{{ ansible_timeout }}"
  poll: 0

# This will load new rules by appending them to the current ones
- name: restore firewall state from a file
  community.general.iptables_state:
    state: restored
    path: /run/iptables.apply
    noflush: true
  async: "{{ ansible_timeout }}"
  poll: 0

# This will only retrieve information
- name: get current state of the firewall
  community.general.iptables_state:
    state: saved
    path: /tmp/iptables
  check_mode: yes
  changed_when: false
  register: iptables_state

- name: show current state of the firewall
  ansible.builtin.debug:
    var: iptables_state.initial_state

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key		Returned	Description
applied boolean		always	Whether or not the wanted state has been successfully restored. Sample: True
initial_state list / elements=string		always	The current state of the firewall when module starts. Sample: ['# Generated by xtables-save v1.8.2', '*filter', ':INPUT ACCEPT [0:0]', ':FORWARD ACCEPT [0:0]', ':OUTPUT ACCEPT [0:0]', 'COMMIT', '# Completed']
restored list / elements=string		always	The state the module restored, whenever it is finally applied or not. Sample: ['# Generated by xtables-save v1.8.2', '*filter', ':INPUT DROP [0:0]', ':FORWARD DROP [0:0]', ':OUTPUT ACCEPT [0:0]', '-A INPUT -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT', '-A INPUT -m conntrack --ctstate INVALID -j DROP', '-A INPUT -i lo -j ACCEPT', '-A INPUT -p icmp -j ACCEPT', '-A INPUT -p tcp -m tcp --dport 22 -j ACCEPT', 'COMMIT', '# Completed']
saved list / elements=string		always	The iptables state the module saved. Sample: ['# Generated by xtables-save v1.8.2', '*filter', ':INPUT ACCEPT [0:0]', ':FORWARD DROP [0:0]', ':OUTPUT ACCEPT [0:0]', 'COMMIT', '# Completed']
tables dictionary		always	The iptables we have interest for when module starts. Sample: { "filter": [ ":INPUT ACCEPT", ":FORWARD ACCEPT", ":OUTPUT ACCEPT", "-A INPUT -i lo -j ACCEPT", "-A INPUT -p icmp -j ACCEPT", "-A INPUT -p tcp -m tcp --dport 22 -j ACCEPT", "-A INPUT -j REJECT --reject-with icmp-host-prohibited" ], "nat": [ ":PREROUTING ACCEPT", ":INPUT ACCEPT", ":OUTPUT ACCEPT", ":POSTROUTING ACCEPT" ] }
	table list / elements=string	success	Policies and rules for all chains of the named table.

Authors

• quidame (@quidame)