- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# iptables – Modify iptables rules

- Synopsis

- Parameters

- Notes

- Examples

- Status

## Synopsis

- `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.

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
action string | Choices: append ← insert | Whether the rule should be appended at the bottom or inserted at the top. If the rule already exists the chain will not be modified.
chain string |  | Specify the iptables chain to modify. This could be a user-defined chain or one of the standard iptables chains, like `INPUT`, `FORWARD`, `OUTPUT`, `PREROUTING`, `POSTROUTING`, `SECMARK` or `CONNSECMARK`.
comment string |  | This specifies a comment that will be added to the rule.
ctstate list | Default: [] | `ctstate` is a list of the connection states to match in the conntrack module. Possible states are `INVALID`, `NEW`, `ESTABLISHED`, `RELATED`, `UNTRACKED`, `SNAT`, `DNAT`
destination string |  | 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.
destination_port string |  | 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. This is only valid if the rule also specifies one of the following protocols: tcp, udp, dccp or sctp.
dst_range string added in 2.8 |  | Specifies the destination IP range to match in the iprange module.
flush boolean | Choices: no yes | Flushes the specified table and chain of all rules. If no chain is specified then the entire table is purged. Ignores all other parameters.
fragment string |  | 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.
gateway string added in 2.8 |  | This specifies the IP address of host to send the cloned packets. This option is only valid when `jump` is set to `TEE`.
gid_owner string added in 2.9 |  | Specifies the GID or group to use in match by owner rule.
goto string |  | 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.
icmp_type string |  | 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'
in_interface string |  | 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.
ip_version string | Choices: ipv4 ← ipv6 | Which version of the IP protocol this rule should apply to.
jump string |  | 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 parameter 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.
limit string |  | 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').
limit_burst string |  | Specifies the maximum burst before the above limit kicks in.
log_level string added in 2.8 | Choices: 0 1 2 3 4 5 6 7 emerg alert crit error warning notice info debug | Logging level according to the syslogd-defined priorities. The value can be strings or numbers from 1-8. This parameter is only applicable if `jump` is set to `LOG`.
log_prefix string added in 2.5 |  | Specifies a log text for the rule. Only make sense with a LOG jump.
match list | Default: [] | 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.
out_interface string |  | 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.
policy string | Choices: ACCEPT DROP QUEUE RETURN | Set the policy for the chain to the given target. Only built-in chains can have policies. This parameter requires the `chain` parameter. Ignores all other parameters.
protocol string |  | 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.
reject_with string |  | Specifies the error packet type to return while rejecting. It implies "jump: REJECT"
rule_num string added in 2.5 |  | Insert the rule as the given rule number. This works only with `action=insert`.
set_counters string |  | This enables the administrator to initialize the packet and byte counters of a rule (during `INSERT`, `APPEND`, `REPLACE` operations).
set_dscp_mark string |  | This allows specifying a DSCP mark to be added to packets. It takes either an integer or hex value. Mutually exclusive with `set_dscp_mark_class`.
set_dscp_mark_class string |  | This allows specifying a predefined DiffServ class which will be translated to the corresponding DSCP mark. Mutually exclusive with `set_dscp_mark`.
source string |  | 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.
source_port string |  | 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.
src_range string added in 2.8 |  | Specifies the source IP range to match in the iprange module.
state string | Choices: absent present ← | Whether the rule should be absent or present.
syn string added in 2.5 | Choices: ignore ← match negate | This allows matching packets that have the SYN bit set and the ACK and RST bits unset. When negated, this matches all packets with the RST or the ACK bits set.
table string | Choices: filter ← nat mangle raw security | 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.
tcp_flags dictionary added in 2.4 | Default: {} | TCP flags specification. `tcp_flags` expects a dict with the two keys `flags` and `flags_set`.
| flags list |  | List of flags you want to examine.
| flags_set list |  | Flags to be set.
to_destination string |  | This specifies a destination address to use with `DNAT`. Without this, the destination address is never altered.
to_ports string |  | 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 protocol `tcp`, `udp`, `dccp` or `sctp`.
to_source string |  | This specifies a source address to use with `SNAT`. Without this, the source address is never altered.
uid_owner string |  | Specifies the UID or username to use in match by owner rule. From Ansible 2.6 when the `!` argument is prepended then the it inverts the rule to apply instead to all users except that one specified.

## Notes

Note

- This module just deals with individual rules.If you need advanced chaining of rules the recommended way is to template the iptables restore file.

## Examples

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

    - name: 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

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

    - name: Allow new incoming SYN packets on TCP port 22 (SSH).
      iptables:
        chain: INPUT
        protocol: tcp
        destination_port: 22
        ctstate: NEW
        syn: match
        jump: ACCEPT
        comment: Accept new SSH connections.

    - name: Match on IP ranges
      iptables:
        chain: FORWARD
        src_range: 192.168.1.100-192.168.1.199
        dst_range: 10.0.0.1-10.0.0.50
        jump: ACCEPT

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

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

    - name: Insert a rule on line 5
      iptables:
        chain: INPUT
        protocol: tcp
        destination_port: 8080
        jump: ACCEPT
        action: insert
        rule_num: 5

    - name: Set the policy for the INPUT chain to DROP
      iptables:
        chain: INPUT
        policy: DROP

    - name: Reject tcp with tcp-reset
      iptables:
        chain: INPUT
        protocol: tcp
        reject_with: tcp-reset
        ip_version: ipv4

    - name: Set tcp flags
      iptables:
        chain: OUTPUT
        jump: DROP
        protocol: tcp
        tcp_flags:
          flags: ALL
          flags_set:
            - ACK
            - RST
            - SYN
            - FIN

    - name: iptables flush filter
      iptables:
        chain: "{{ item }}"
        flush: yes
      with_items:  [ 'INPUT', 'FORWARD', 'OUTPUT' ]

    - name: iptables flush nat
      iptables:
        table: nat
        chain: '{{ item }}'
        flush: yes
      with_items: [ 'INPUT', 'OUTPUT', 'PREROUTING', 'POSTROUTING' ]

    - name: Log packets arriving into an user-defined chain
      iptables:
        chain: LOGGING
        action: append
        state: present
        limit: 2/second
        limit_burst: 20
        log_prefix: "IPTABLES:INFO: "
        log_level: info

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Core Team. [core]

### Red Hat Support

More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.

### Authors

- Linus Unnebäck (@LinusU) <linus@folkdatorn.se>

- Sébastien DA ROCHA (@sebastiendarocha)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.