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

From Get docs
Ansible/docs/2.10/collections/community/general/iptables state module


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

  • no

  • yes

Save or restore the values of all packet and byte counters.

When true, the module is not idempotent.

ip_version

string

  • 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

  • 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

  • saved
  • restored

Whether the firewall state should be saved (into a file) or restored (from a file).

table

string

  • 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