ansible.builtin.iptables module – Modify iptables rules

action

string

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.

Choices:

• "append" ← (default)
• "insert"

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.

chain_management

boolean

added in ansible-core 2.13

If true and state is present, the chain will be created if needed.

If true and state is absent, the chain will be deleted if the only other parameter passed are chain and optionally table.

Choices:

• false ← (default)
• true

comment

string

This specifies a comment that will be added to the rule.

ctstate

list / elements=string

A list of the connection states to match in the conntrack module.

Possible values are INVALID, NEW, ESTABLISHED, RELATED, UNTRACKED, SNAT, DNAT.

Default: []

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.

destination_ports

list / elements=string

added in ansible-core 2.11

This specifies multiple destination port numbers or port ranges to match in the multiport module.

It can only be used in conjunction with the protocols tcp, udp, udplite, dccp and sctp.

Default: []

dst_range

string

added in Ansible 2.8

Specifies the destination IP range to match in the iprange module.

flush

boolean

Flushes the specified table and chain of all rules.

If no chain is specified then the entire table is purged.

Ignores all other parameters.

Choices:

• false ← (default)
• true

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 the fragment argument, the rule will only match head fragments, or unfragmented packets.

gateway

string

added in Ansible 2.8

This specifies the IP address of the host to send the cloned packets.

This option is only valid when jump is set to TEE.

gid_owner

string

added in Ansible 2.9

Specifies the GID or group to use in the 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

Which version of the IP protocol this rule should apply to.

Choices:

• "ipv4" ← (default)
• "ipv6"

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 that 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 Ansible 2.8

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.

Choices:

• "0"
• "1"
• "2"
• "3"
• "4"
• "5"
• "6"
• "7"
• "emerg"
• "alert"
• "crit"
• "error"
• "warning"
• "notice"
• "info"
• "debug"

log_prefix

string

Specifies a log text for the rule. Only makes sense with a LOG jump.

match

list / elements=string

Specifies a match to use, that is, an extension module that tests for a specific property.

The set of matches makes 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, the evaluation will stop.

Default: []

match_set

string

added in ansible-core 2.11

Specifies a set name that can be defined by ipset.

Must be used together with the match_set_flags parameter.

When the ! argument is prepended then it inverts the rule.

Uses the iptables set extension.

match_set_flags

string

added in ansible-core 2.11

Specifies the necessary flags for the match_set parameter.

Must be used together with the match_set parameter.

Uses the iptables set extension.

Choices dst,dst and src,src added in version 2.17.

Choices:

• "src"
• "dst"
• "src,dst"
• "dst,src"
• "dst,dst"
• "src,src"

numeric

boolean

added in ansible-core 2.15

This parameter controls the running of the list -action of iptables, which is used internally by the module

Does not affect the actual functionality. Use this if iptables hang when creating a chain or altering policy

If true, then iptables skips the DNS-lookup of the IP addresses in a chain when it uses the list -action

Listing is used internally for example when setting a policy or creating a chain

Choices:

• false ← (default)
• true

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

Set the policy for the chain to the given target.

Only built-in chains can have policies.

This parameter requires the chain parameter.

If you specify this parameter, all other parameters will be ignored.

This parameter is used to set the default policy for the given chain. Do not confuse this with jump parameter.

Choices:

• "ACCEPT"
• "DROP"
• "QUEUE"
• "RETURN"

protocol

string

The protocol of the rule or of the packet to check.

The specified protocol can be one of tcp, udp, udplite, icmp, ipv6-icmp or icmpv6, 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

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.

If the parameter is set, jump is set to DSCP.

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.

If the parameter is set, jump is set to DSCP.

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 Ansible 2.8

Specifies the source IP range to match the iprange module.

state

string

Whether the rule should be absent or present.

Choices:

• "absent"
• "present" ← (default)

syn

string

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.

Choices:

• "ignore" ← (default)
• "match"
• "negate"

table

string

This option specifies the packet matching table on which the command should operate.

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.

Choices:

• "filter" ← (default)
• "nat"
• "mangle"
• "raw"
• "security"

tcp_flags

dictionary

TCP flags specification.

tcp_flags expects a dict with the two keys flags and flags_set.

flags

list / elements=string

List of flags you want to examine.

flags_set

list / elements=string

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

wait

string

added in ansible-base 2.10

Wait N seconds for the xtables lock to prevent multiple instances of the program from running concurrently.

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode

platform

Platform: linux

Target OS/families that can be operated against