Docs4dev
Docs
ansible / 2.10 / collections / community / general / iptables_state_module.html

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

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)

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.10/collections/community/general/iptables_state_module.html