ansible.builtin.iptables (v2.3.3.0-1) — module

Install Ansible via pip

Install with pip install ansible==2.3.3.0.post1

Description

Iptables is used to set up, maintain, and inspect the tables of IP packet filter rules in the Linux kernel. This module does not handle the saving and/or loading of rules, but rather only manipulates the current rules that are present in memory. This is the same as the behaviour of the "iptables" and "ip6tables" command which this module uses internally.

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# Block specific IP
- iptables:
    chain: INPUT
    source: 8.8.8.8
    jump: DROP
  become: yes

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# Forward port 80 to 8600
- iptables:
    table: nat
    chain: PREROUTING
    in_interface: eth0
    protocol: tcp
    match: tcp
    destination_port: 80
    jump: REDIRECT
    to_ports: 8600
    comment: Redirect web traffic to port 8600
  become: yes

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# Allow related and established connections
- iptables:
    chain: INPUT
    ctstate: ESTABLISHED,RELATED
    jump: ACCEPT
  become: yes

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# Tag all outbound tcp packets with DSCP mark 8
- iptables:
    chain: OUTPUT
    jump: DSCP
    table: mangle
    set_dscp_mark: 8
    protocol: tcp

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# Tag all outbound tcp packets with DSCP DiffServ class CS1
- iptables:
    chain: OUTPUT
    jump: DSCP
    table: mangle
    set_dscp_mark_class: CS1
    protocol: tcp

Inputs

    
goto:
    default: null
    description:
    - This specifies that the processing should continue in a user specified chain. Unlike
      the jump argument return will not continue processing in this chain but instead
      in the chain that called us via jump.
    required: false

jump:
    default: null
    description:
    - This specifies the target of the rule; i.e., what to do if the packet matches it.
      The target can be a user-defined chain (other than the one this rule is in), one
      of the special builtin targets which decide the fate of the packet immediately,
      or an extension (see EXTENSIONS below).  If this option is omitted in a rule (and
      the goto paramater is not used), then matching the rule will have no effect on the
      packet's fate, but the counters on the rule will be incremented.
    required: false

chain:
    description:
    - 'Chain to operate on. This option can either be the name of a user defined chain
      or any of the builtin chains: ''INPUT'', ''FORWARD'', ''OUTPUT'', ''PREROUTING'',
      ''POSTROUTING'', ''SECMARK'', ''CONNSECMARK''.'
    required: false

flush:
    description:
    - Flushes the specified table and chain of all rules. If no chain is specified then
      the entire table is purged. Ignores all other parameters.
    required: false
    version_added: '2.2'
    version_added_collection: ansible.builtin

limit:
    default: null
    description:
    - Specifies the maximum average number of matches to allow per second. The number
      can specify units explicitly, using `/second', `/minute', `/hour' or `/day', or
      parts of them (so `5/second' is the same as `5/s').
    required: false

match:
    default: []
    description:
    - Specifies a match to use, that is, an extension module that tests for a specific
      property. The set of matches make up the condition under which a target is invoked.
      Matches are evaluated first to last if specified as an array and work in short-circuit
      fashion, i.e. if one extension yields false, evaluation will stop.
    required: false

state:
    choices:
    - present
    - absent
    default: present
    description:
    - Whether the rule should be absent or present.
    required: false

table:
    choices:
    - filter
    - nat
    - mangle
    - raw
    - security
    default: filter
    description:
    - This option specifies the packet matching table which the command should operate
      on. If the kernel is configured with automatic module loading, an attempt will be
      made to load the appropriate module for that table if it is not already there.
    required: false

action:
    choices:
    - append
    - insert
    default: append
    description:
    - Whether the rule should be appended at the bottom or inserted at the top. If the
      rule already exists the chain won't be modified.
    required: false
    version_added: '2.2'
    version_added_collection: ansible.builtin

policy:
    description:
    - Set the policy for the chain to the given target. Valid targets are ACCEPT, DROP,
      QUEUE, RETURN. Only built in chains can have policies. This parameter requires the
      chain parameter. Ignores all other parameters.
    version_added: '2.2'
    version_added_collection: ansible.builtin

source:
    default: null
    description:
    - Source specification. Address can be either a network name, a hostname, a network
      IP address (with /mask), or a plain IP address. Hostnames will be resolved once
      only, before the rule is submitted to the kernel. Please note that specifying any
      name to be resolved with a remote query such as DNS is a really bad idea. The mask
      can be either a network mask or a plain number, specifying the number of 1's at
      the left side of the network mask. Thus, a mask of 24 is equivalent to 255.255.255.0.
      A "!" argument before the address specification inverts the sense of the address.
    required: false

comment:
    default: null
    description:
    - This specifies a comment that will be added to the rule
    required: false

ctstate:
    default: []
    description:
    - 'ctstate is a list of the connection states to match in the conntrack module. Possible
      states are: ''INVALID'', ''NEW'', ''ESTABLISHED'', ''RELATED'', ''UNTRACKED'', ''SNAT'',
      ''DNAT'''
    required: false

fragment:
    default: null
    description:
    - This means that the rule only refers to second and further fragments of fragmented
      packets. Since there is no way to tell the source or destination ports of such a
      packet (or ICMP type), such a packet will not match any rules which specify them.
      When the "!" argument precedes fragment argument, the rule will only match head
      fragments, or unfragmented packets.
    required: false

protocol:
    default: null
    description:
    - The protocol of the rule or of the packet to check. The specified protocol can be
      one of tcp, udp, udplite, icmp, esp, ah, sctp or the special keyword "all", or it
      can be a numeric value, representing one of these protocols or a different one.
      A protocol name from /etc/protocols is also allowed. A "!" argument before the protocol
      inverts the test.  The number zero is equivalent to all. "all" will match with all
      protocols and is taken as default when this option is omitted.
    required: false

to_ports:
    default: null
    description:
    - 'This specifies a destination port or range of ports to use: without this, the destination
      port is never altered. This is only valid if the rule also specifies one of the
      following protocols: tcp, udp, dccp or sctp.'
    required: false

icmp_type:
    description:
    - This allows specification of the ICMP type, which can be a numeric ICMP type, type/code
      pair, or one of the ICMP type names shown by the command 'iptables -p icmp -h'
    required: false
    version_added: '2.2'
    version_added_collection: ansible.builtin

to_source:
    default: null
    description:
    - 'This specifies a source address to use with SNAT: without this, the source address
      is never altered.'
    required: false
    version_added: '2.2'
    version_added_collection: ansible.builtin

uid_owner:
    description:
    - Specifies the UID or username to use in match by owner rule.
    required: false
    version_added: '2.1'
    version_added_collection: ansible.builtin

ip_version:
    choices:
    - ipv4
    - ipv6
    default: ipv4
    description:
    - Which version of the IP protocol this rule should apply to.
    required: false

destination:
    default: null
    description:
    - Destination specification. Address can be either a network name, a hostname, a network
      IP address (with /mask), or a plain IP address. Hostnames will be resolved once
      only, before the rule is submitted to the kernel. Please note that specifying any
      name to be resolved with a remote query such as DNS is a really bad idea. The mask
      can be either a network mask or a plain number, specifying the number of 1's at
      the left side of the network mask. Thus, a mask of 24 is equivalent to 255.255.255.0.
      A "!" argument before the address specification inverts the sense of the address.
    required: false

limit_burst:
    default: null
    description:
    - Specifies the maximum burst before the above limit kicks in.
    required: false
    version_added: '2.1'
    version_added_collection: ansible.builtin

reject_with:
    description:
    - Specifies the error packet type to return while rejecting.
    required: false
    version_added: '2.1'
    version_added_collection: ansible.builtin

source_port:
    default: null
    description:
    - Source port or port range specification. This can either be a service name or a
      port number. An inclusive range can also be specified, using the format first:last.
      If the first port is omitted, '0' is assumed; if the last is omitted, '65535' is
      assumed. If the first port is greater than the second one they will be swapped.
    required: false

in_interface:
    default: null
    description:
    - Name of an interface via which a packet was received (only for packets entering
      the INPUT, FORWARD and PREROUTING chains). When the "!" argument is used before
      the interface name, the sense is inverted. If the interface name ends in a "+",
      then any interface which begins with this name will match. If this option is omitted,
      any interface name will match.
    required: false

set_counters:
    default: null
    description:
    - This enables the administrator to initialize the packet and byte counters of a rule
      (during INSERT, APPEND, REPLACE operations).
    required: false

out_interface:
    default: null
    description:
    - Name of an interface via which a packet is going to be sent (for packets entering
      the FORWARD, OUTPUT and POSTROUTING chains). When the "!" argument is used before
      the interface name, the sense is inverted. If the interface name ends in a "+",
      then any interface which begins with this name will match. If this option is omitted,
      any interface name will match.
    required: false

set_dscp_mark:
    default: null
    description:
    - This allows specifying a DSCP mark to be added to packets. It takes either an integer
      or hex value. Mutually exclusive with C(set_dscp_mark_class).
    required: false
    version_added: '2.1'
    version_added_collection: ansible.builtin

to_destination:
    default: null
    description:
    - 'This specifies a destination address to use with DNAT: without this, the destination
      address is never altered.'
    required: false
    version_added: '2.1'
    version_added_collection: ansible.builtin

destination_port:
    default: null
    description:
    - Destination port or port range specification. This can either be a service name
      or a port number. An inclusive range can also be specified, using the format first:last.
      If the first port is omitted, '0' is assumed; if the last is omitted, '65535' is
      assumed. If the first port is greater than the second one they will be swapped.
    required: false

set_dscp_mark_class:
    default: null
    description:
    - This allows specifying a predefined DiffServ class which will be translated to the
      corresponding DSCP mark. Mutually exclusive with C(set_dscp_mark).
    required: false
    version_added: '2.1'
    version_added_collection: ansible.builtin