Ansible 核心文档

ansible.builtin.iptables 模块 – 修改 iptables 规则

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使没有指定集合关键字，也可以使用简短模块名称 iptables。但是，我们建议您使用完全限定集合名称 (FQCN) ansible.builtin.iptables 以便轻松链接到模块文档，并避免与可能具有相同模块名称的其他集合发生冲突。

概要 

ansible.builtin.iptables 用于设置、维护和检查 Linux 内核中的 IP 数据包过滤规则表。
此模块不处理规则的保存和/或加载，而仅操作内存中存在的当前规则。这与此模块在内部使用的 iptables 和 ip6tables 命令的行为相同。

参数 

参数	注释
action 字符串	规则应该追加到底部还是插入到顶部。如果规则已经存在，则链不会被修改。选择 `"append"` ← (默认) `"insert"`
chain 字符串	指定要修改的 iptables 链。这可能是用户定义的链或标准 iptables 链之一，例如 `INPUT`、`FORWARD`、`OUTPUT`、`PREROUTING`、`POSTROUTING`、`SECMARK` 或 `CONNSECMARK`。
chain_management 布尔值在 ansible-core 2.13 中添加	如果 `true` 且 `state` 为 `present`，则如果需要，将创建该链。如果 `true` 且 `state` 为 `absent`，则如果传递的唯一其他参数是 `chain` 以及可选的 `table`，则将删除该链。选择 `false` ← (默认) `true`
comment 字符串	这指定将添加到规则中的注释。
ctstate 列表 / 元素=字符串	要匹配的连接状态列表，在 conntrack 模块中。可能的值是 `INVALID`、`NEW`、`ESTABLISHED`、`RELATED`、`UNTRACKED`、`SNAT`、`DNAT`。默认值： `[]`
destination 字符串	目标规范。地址可以是网络名称、主机名、网络 IP 地址（带 /掩码）或普通 IP 地址。主机名将只解析一次，在规则提交到内核之前。请注意，指定任何需要使用远程查询（如 DNS）解析的名称都是非常糟糕的。掩码可以是网络掩码或普通数字，指定网络掩码左侧 1 的数量。因此，掩码 24 等效于 255.255.255.0。地址规范之前的 `!` 参数会反转地址的含义。
destination_port 字符串	目标端口或端口范围规范。这可以是服务名称或端口号。也可以使用格式 first:last 指定包含的范围。如果第一个端口省略，则假定为 '0'；如果最后一个端口省略，则假定为 '65535'。如果第一个端口大于第二个端口，则会互换它们。这仅在规则还指定以下协议之一时有效：tcp、udp、dccp 或 sctp。
destination_ports 列表 / 元素=字符串在 ansible-core 2.11 中添加	这指定了要在多端口模块中匹配的多个目标端口号或端口范围。它只能与协议 tcp、udp、udplite、dccp 和 sctp 一起使用。默认值： `[]`
dst_range 字符串在 Ansible 2.8 中添加	指定要匹配的 IP 范围，在 iprange 模块中。
flush 布尔值	刷新指定的表和链中的所有规则。如果没有指定链，则会清除整个表。忽略所有其他参数。选择 `false` ← (默认) `true`
fragment 字符串	这意味着该规则只引用分段数据包的第二个或更多个分段。由于无法确定此类数据包的源端口或目标端口（或 ICMP 类型），因此此类数据包将不会与指定了这些端口的任何规则匹配。当“!”参数位于 fragment 参数之前时，该规则将仅匹配头部分段或未分段的数据包。
gateway 字符串在 Ansible 2.8 中添加	这指定了发送克隆数据包的主机的 IP 地址。此选项仅在 `jump=TEE` 时有效。
gid_owner 字符串在 Ansible 2.9 中添加	指定要在按所有者规则匹配中使用的 GID 或组。
goto 字符串	这指定了处理应该在用户指定的链中继续。与 jump 参数不同，return 不会在该链中继续处理，而是在通过 jump 调用我们的链中继续处理。
icmp_type 字符串	这允许指定 ICMP 类型，可以是数字 ICMP 类型、类型/代码对，或命令 `iptables -p icmp -h` 所示的 ICMP 类型名称之一。
in_interface 字符串	接收数据包的接口的名称（仅适用于进入 `INPUT`、`FORWARD` 和 `PREROUTING` 链的数据包）。当 `!` 参数用于接口名称之前时，含义将被反转。如果接口名称以 `+` 结尾，则任何以该名称开头的接口都将匹配。如果省略此选项，则任何接口名称都将匹配。
ip_version 字符串	此规则应适用的 IP 协议版本。选择 `"ipv4"` ← (默认) `"ipv6"`
jump 字符串	这指定了规则的目标；即，如果数据包与之匹配，该怎么做。目标可以是用户定义的链（不是此规则所在的链）、立即决定数据包命运的内置特殊目标之一，或扩展（请参见下面的扩展）。如果在规则中省略此选项（并且 goto 参数未使用），则匹配该规则不会对数据包的命运有任何影响，但规则上的计数器将被递增。
limit 字符串	指定每秒允许的最大平均匹配次数。数字可以明确地指定单位，使用 `/second`、`/minute`、`/hour` 或 `/day`，或它们的部分（因此 `5/second` 与 `5/s` 相同）。
limit_burst 字符串	指定在上述限制生效之前的最大突发值。
log_level 字符串在 Ansible 2.8 中添加	根据 syslogd 定义的优先级设置日志级别。值可以是字符串或 1-8 之间的数字。此参数仅适用于 `jump=LOG`。选择 `"0"` `"1"` `"2"` `"3"` `"4"` `"5"` `"6"` `"7"` `"emerg"` `"alert"` `"crit"` `"error"` `"warning"` `"notice"` `"info"` `"debug"`
log_prefix 字符串	指定规则的日志文本。仅对 LOG 跳转有意义。
match 列表 / 元素=字符串	指定要使用的匹配项，即测试特定属性的扩展模块。匹配项构成了调用目标的条件。如果作为数组指定，则匹配项将按从前到后的顺序进行评估，并以短路方式工作，换句话说，如果一个扩展项返回 false，则评估将停止。默认值： `[]`
match_set 字符串在 ansible-core 2.11 中添加	指定由 ipset 定义的集合名称。必须与 `match_set_flags` 参数一起使用。当 `!` 参数置于前面时，它会反转规则。使用 iptables 集合扩展。
match_set_flags 字符串在 ansible-core 2.11 中添加	指定 match_set 参数所需的标志。必须与 `match_set` 参数一起使用。使用 iptables 集合扩展。在版本 2.17 中添加了选择项 `dst,dst` 和 `src,src`。选择 `"src"` `"dst"` `"src,dst"` `"dst,src"` `"dst,dst"` `"src,src"`
numeric 布尔值在 ansible-core 2.15 中添加	此参数控制 iptables 的 list -action 的运行，该操作在模块内部使用。不影响实际功能。如果 iptables 在创建链或更改策略时挂起，请使用此参数。如果为 `true`，则 iptables 在使用 list -action 时会跳过链中 IP 地址的 DNS 查找。例如，在设置策略或创建链时，内部使用列表。选择 `false` ← (默认) `true`
out_interface 字符串	将要发送数据包的接口名称（对于进入 `FORWARD`、`OUTPUT` 和 `POSTROUTING` 链的数据包）。当 `!` 参数用于接口名称之前时，含义将被反转。如果接口名称以 `+` 结尾，则任何以该名称开头的接口都将匹配。如果省略此选项，则任何接口名称都将匹配。
policy 字符串	将链的策略设置为给定的目标。只有内置链可以有策略。此参数需要 `chain` 参数。如果您指定此参数，所有其他参数将被忽略。此参数用于设置给定 `chain` 的默认策略。不要将它与 `jump` 参数混淆。选择 `"ACCEPT"` `"DROP"` `"QUEUE"` `"RETURN"`
protocol 字符串	要检查的规则或数据包的协议。指定的协议可以是 `tcp`、`udp`、`udplite`、`icmp`、`ipv6-icmp` 或 `icmpv6`、`esp`、`ah`、`sctp` 之一，也可以是特殊关键字 `all`，或者可以是代表这些协议之一或其他协议的数值。还允许来自 `/etc/protocols` 的协议名称。协议前的 `!` 参数会反转测试。数字零等效于 all。 `all` 将与所有协议匹配，并且在省略此选项时被视为默认值。
reject_with 字符串	指定在拒绝时要返回的错误数据包类型。它暗示 `jump=REJECT`。
rule_num 字符串	将规则插入为给定的规则号。这仅适用于 `action=insert`。
set_counters 字符串	这使管理员能够初始化规则的数据包和字节计数器（在 `INSERT`、`APPEND`、`REPLACE` 操作期间）。
set_dscp_mark 字符串	这允许指定要添加到数据包的 DSCP 标记。它接受整数或十六进制值。如果设置了参数，则 `jump` 设置为 `DSCP`。与 `set_dscp_mark_class` 互斥。
set_dscp_mark_class 字符串	这允许指定预定义的 DiffServ 类，该类将被转换为相应的 DSCP 标记。如果设置了参数，则 `jump` 设置为 `DSCP`。与 `set_dscp_mark` 互斥。
source 字符串	源规范。地址可以是网络名称、主机名、网络 IP 地址（带 /掩码）或普通 IP 地址。主机名将只解析一次，在规则提交到内核之前。请注意，指定任何需要使用远程查询（如 DNS）解析的名称都是非常糟糕的。掩码可以是网络掩码或普通数字，指定网络掩码左侧 1 的数量。因此，掩码 24 等效于 255.255.255.0。地址规范之前的 `!` 参数会反转地址的含义。
source_port 字符串	源端口或端口范围规范。这可以是服务名称或端口号。还可以使用格式 `first:last` 指定包含范围。如果省略第一个端口，则假定为 `0`；如果省略最后一个，则假定为 `65535`。如果第一个端口大于第二个端口，则它们将被交换。
src_range 字符串在 Ansible 2.8 中添加	指定要匹配 iprange 模块的源 IP 范围。
state 字符串	规则应该不存在还是存在。选择 `"absent"` `"present"` ← (default)
syn 字符串	这允许匹配具有设置的 SYN 位且未设置的 ACK 和 RST 位的数据包。当否定时，这将匹配所有具有设置的 RST 或 ACK 位的数据包。选择 `"ignore"` ← (default) `"match"` `"negate"`
table 字符串	此选项指定命令应该在其上操作的数据包匹配表。如果内核配置了自动模块加载，则如果该表不存在，将尝试加载该表相应的模块。选择 `"filter"` ← (default) `"nat"` `"mangle"` `"raw"` `"security"`
tcp_flags dictionary	TCP 标志规范。 `tcp_flags` 期待一个包含两个键 `flags` 和 `flags_set` 的字典。
flags 列表 / 元素=字符串	您要检查的标志列表。
flags_set 列表 / 元素=字符串	要设置的标志。
to_destination 字符串	这指定要与 `ctstate=DNAT` 一起使用的目标地址。没有它，目标地址将永远不会改变。
to_ports 字符串	这指定要使用的目标端口或端口范围，没有它，目标端口将永远不会改变。这仅在规则还指定了协议 `tcp`、`udp`、`dccp` 或 `sctp` 之一的情况下有效。
to_source 字符串	这指定要与 `ctstate=SNAT` 一起使用的源地址。没有它，源地址将永远不会改变。
uid_owner 字符串	指定要在按所有者规则匹配中使用的 UID 或用户名。从 Ansible 2.6 开始，当 `!` 参数置于前面时，它会反转规则，使其应用于除指定的用户以外的所有用户。
wait 字符串在 ansible-base 2.10 中添加	等待 N 秒，以获取 xtables 锁，防止程序的多个实例同时运行。

属性 

属性	支持	描述
check_mode	支持: 完全支持	可以在 check_mode 模式下运行并返回更改状态预测，而不会修改目标，如果不支持，则会跳过操作。
diff_mode	支持: 不支持	在 diff 模式下，将返回有关更改内容（或可能在 check_mode 模式下需要更改的内容）的详细信息。
平台	平台: linux	可以操作的目标操作系统/系列。

备注 

注意

此模块仅处理单个规则。如果您需要高级的规则链，建议的方法是模板化 iptables restore 文件。

示例 

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

- name: Forward port 80 to 8600
  ansible.builtin.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
  ansible.builtin.iptables:
    chain: INPUT
    ctstate: ESTABLISHED,RELATED
    jump: ACCEPT
  become: yes

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

- name: Match on IP ranges
  ansible.builtin.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: Allow source IPs defined in ipset "admin_hosts" on port 22
  ansible.builtin.iptables:
    chain: INPUT
    match_set: admin_hosts
    match_set_flags: src
    destination_port: 22
    jump: ALLOW

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

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

# Create the user-defined chain ALLOWLIST
- iptables:
    chain: ALLOWLIST
    chain_management: true

# Delete the user-defined chain ALLOWLIST
- iptables:
    chain: ALLOWLIST
    chain_management: true
    state: absent

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

# Think twice before running following task as this may lock target system
- name: Set the policy for the INPUT chain to DROP
  ansible.builtin.iptables:
    chain: INPUT
    policy: DROP

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

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

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

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

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

- name: Allow connections on multiple ports
  ansible.builtin.iptables:
    chain: INPUT
    protocol: tcp
    destination_ports:
      - "80"
      - "443"
      - "8081:8083"
    jump: ACCEPT

作者

Linus Unnebäck (@LinusU)
Sébastien DA ROCHA (@sebastiendarocha)

集合链接