Skip to content

Latest commit

 

History

History
156 lines (126 loc) · 9.36 KB

README.md

File metadata and controls

156 lines (126 loc) · 9.36 KB
Raw

Ansible Role jm1.cloudy.iptables

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

Available on Ansible Galaxy in Collection jm1.cloudy.

Requirements

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.

Variables

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)

Dependencies

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.

Example Playbook

An example host is supposed to have two network interfaces:

  • device eth0 on external network with static ip address 10.10.10.10
  • device eth1 on internal network 192.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.

License

GNU General Public License v3.0 or later

See LICENSE.md to see the full text.

Author

Jakob Meng @jm1 (github, galaxy, web)

Footnotes

  1. Useful Ansible modules in this context could be iptables and ansible.posix.firewalld. ↩

  2. Tasks will be executed with jm1.ansible.execute_module which supports keyword when only. ↩

  3. Tasks will be executed with jm1.ansible.execute_module which supports modules and action plugins only. Some Ansible modules such as ansible.builtin.meta and ansible.builtin.{include,import}_{playbook,role,tasks} are core features of Ansible, in fact not implemented as modules and thus cannot be called from jm1.ansible.execute_module. Doing so causes Ansible to raise errors such as MODULE 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: "" }. ↩