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 5.8.3).
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
andiptables-restore
(orip6tables-save
andip6tables-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 |
---|---|
Save or restore the values of all packet and byte counters. When Choices:
|
|
Which version of the IP protocol this module should apply to. Choices:
|
|
Specify the path to the By default, |
|
For state=restored, ignored otherwise. If Choices:
|
|
The file the iptables state should be saved to. The file the iptables state should be restored from. |
|
Whether the firewall state should be saved (into a file) or restored (from a file). Choices:
|
|
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:
|
|
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 toANSIBLE_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: 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 |
---|---|
Whether or not the wanted state has been successfully restored. Returned: always Sample: |
|
The current state of the firewall when module starts. Returned: always Sample: |
|
The state the module restored, whenever it is finally applied or not. Returned: always Sample: |
|
The iptables state the module saved. Returned: always Sample: |
|
The iptables we have interest for when module starts. Returned: always Sample: |
|
Policies and rules for all chains of the named table. Returned: success |
Collection links
Issue Tracker Repository (Sources) Submit a bug report Request a feature Communication