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

Note

This module is part of the community.general collection (version 10.1.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general. You need further requirements to be able to use this module, see Requirements for details.

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

New in community.general 1.1.0

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	Comments
counters boolean	Save or restore the values of all packet and byte counters. When true, the module is not idempotent. Choices: false ← (default) true
ip_version string	Which version of the IP protocol this module should apply to. Choices: "ipv4" ← (default) "ipv6"
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	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). Choices: false ← (default) true
path path / required	The file the iptables state should be saved to. The file the iptables state should be restored from.
state string / required	Whether the firewall state should be saved (into a file) or restored (from a file). Choices: "saved" "restored"
table string	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. Choices: "filter" "nat" "mangle" "raw" "security"
wait integer	Wait N seconds for the xtables lock to prevent instant failure in case multiple instances of the program are running concurrently.

Attributes

Attribute	Support	Description
action	Support: full	Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
async	Support: full	Supports being used with the async keyword.
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target.
diff_mode	Support: none	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

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.

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: true
  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	Description
applied boolean	Whether or not the wanted state has been successfully restored. Returned: always Sample: true
initial_state list / elements=string	The current state of the firewall when module starts. Returned: always 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	The state the module restored, whenever it is finally applied or not. Returned: always 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	The iptables state the module saved. Returned: always 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	The iptables on the system before the module has run, separated by table. If the option table is used, only this table is included. Returned: always 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	Policies and rules for all chains of the named table. Returned: success

Authors

• quidame (@quidame)

Collection links

• Issue Tracker
• Repository (Sources)
• Ask for help
• Submit a bug report
• Request a feature
• Communication