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 9.4.0).

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)