This role helps with managing iptables rules from Ansible variables. Role variable iptables_config
defines
a list of tasks which will be run by this role. Each task calls an Ansible module similar to tasks in roles or playbooks
except that only few keywords such as when
are supported. For example, to enable
SNAT (source NAT) for all packets coming from an internal network define variable iptables_config
in
group_vars
or host_vars
as such:
iptables_config:
- # do SNAT (source NAT) for all packets coming from internal network
ansible.builtin.iptables:
chain: POSTROUTING
destination: 0.0.0.0/0
jump: SNAT
out_interface: 'eth0' # network device on external network
source: 192.168.0.0/24 # internal network
table: nat
to_source: 10.10.10.10 # ip address on external network
# persist iptables rules across reboots
iptables_persistence: true
First, if iptables_persistence
evaluates to true
, then this role will install packages (matching the distribution
specified in distribution_id
) to persist iptables rules across reboots. Next, it will run all tasks listed in
iptables_config
. Once all tasks have finished, if anything has changed and iptables_persistence
evaluates to true
(and if iptables_service_state
or ip6tables_service_state
are not set to stopped
), then all iptables rules are
stored to survive reboots.
Tested OS images
- Cloud image (
amd64
) of Debian 10 (Buster) - Cloud image (
amd64
) of Debian 11 (Bullseye) - Cloud image (
amd64
) of Debian 12 (Bookworm) - Cloud image (
amd64
) of Debian 13 (Trixie) - Cloud image (
amd64
) of CentOS 7 (Core) - Cloud image (
amd64
) of CentOS 8 (Stream) - Cloud image (
amd64
) of CentOS 9 (Stream) - Cloud image (
amd64
) of Fedora Cloud Base 40 - Cloud image (
amd64
) of Ubuntu 18.04 LTS (Bionic Beaver) - Cloud image (
amd64
) of Ubuntu 20.04 LTS (Focal Fossa) - Cloud image (
amd64
) of Ubuntu 22.04 LTS (Jammy Jellyfish) - Cloud image (
amd64
) of Ubuntu 24.04 LTS (Noble Numbat)
Available on Ansible Galaxy in Collection jm1.cloudy.
This role uses module(s) from collection jm1.ansible
and collection jm1.pkg
.
To install these collections you may follow the steps described in README.md
using the provided
requirements.yml
.
Name | Default value | Required | Description |
---|---|---|---|
distribution_id |
depends on operating system | false | List which uniquely identifies a distribution release, e.g. [ 'Debian', '10' ] for Debian 10 (Buster) |
iptables_config |
[] |
false | List of tasks to run 1 2 3, e.g. to modify iptables rules |
iptables_persistence |
false |
false | Whether iptables rules should persist across reboots |
iptables_service_enabled |
true |
false | Whether the iptables service should start on boot (only used on CentOS, Fedora and Red Hat Enterprise Linux) |
iptables_service_name |
iptables |
false | Name of the iptables service (only used on CentOS, Fedora and Red Hat Enterprise Linux) |
iptables_service_state |
started |
false | State of the iptables service (only used on CentOS, Fedora and Red Hat Enterprise Linux) |
ip6tables_service_enabled |
true |
false | Whether the ip6tables service should start on boot (only used on CentOS, Fedora and Red Hat Enterprise Linux) |
ip6tables_service_name |
ip6tables |
false | Name of the ip6tables service (only used on CentOS, Fedora and Red Hat Enterprise Linux) |
ip6tables_service_state |
started |
false | State of the ip6tables service (only used on CentOS, Fedora and Red Hat Enterprise Linux) |
Name | Description |
---|---|
jm1.pkg.setup |
Installs necessary software for module jm1.pkg.meta_pkg from collection jm1.pkg . This role is called automatically, manual execution is NOT required. |
An example host is supposed to have two network interfaces:
- device
eth0
on external network with static ip address10.10.10.10
- device
eth1
on internal network192.168.0.0/24
with any matching ip address
To enable SNAT (source NAT) for all packets coming from an internal network:
- hosts: all
become: true
vars:
# Variables are listed here for convenience and illustration.
# In a production setup, variables would be defined e.g. in
# group_vars and/or host_vars of an Ansible inventory.
# Ref.:
# https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html
# https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html
iptables_config:
- # do SNAT (source NAT) for all packets coming from internal network
ansible.builtin.iptables:
chain: POSTROUTING
destination: 0.0.0.0/0
jump: SNAT
out_interface: 'eth0'
source: 192.168.0.0/24
table: nat
to_source: 10.10.10.10
iptables_persistence: true
roles:
- name: Manage iptables rules
role: jm1.cloudy.iptables
tags: ["jm1.cloudy.iptables"]
For a complete example on how to use this role, refer to hosts lvrt-lcl-session-srv-100-pxe-server-debian11
,
lvrt-lcl-session-srv-210-tripleo-standalone
or lvrt-lcl-session-srv-300-hwfp-server-debian11
from the provided
examples inventory. The top-level README.md
describes how these hosts
can be provisioned with playbook playbooks/site.yml
.
For instructions on how to run Ansible playbooks have look at Ansible's Getting Started Guide.
GNU General Public License v3.0 or later
See LICENSE.md to see the full text.
Jakob Meng @jm1 (github, galaxy, web)
Footnotes
-
Useful Ansible modules in this context could be
iptables
andansible.posix.firewalld
. ↩ -
Tasks will be executed with
jm1.ansible.execute_module
which supports keywordwhen
only. ↩ -
Tasks will be executed with
jm1.ansible.execute_module
which supports modules and action plugins only. Some Ansible modules such asansible.builtin.meta
andansible.builtin.{include,import}_{playbook,role,tasks}
are core features of Ansible, in fact not implemented as modules and thus cannot be called fromjm1.ansible.execute_module
. Doing so causes Ansible to raise errors such asMODULE FAILURE\nSee stdout/stderr for the exact error
. In addition, Ansible does not support free-form parameters for arbitrary modules, so for example, change from- debug: msg=""
to- debug: { msg: "" }
. ↩