Ansible Core 文档

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 中添加	这指定要在 multiport 模块中匹配的多个目标端口号或端口范围。它只能与协议 tcp、udp、udplite、dccp 和 sctp 结合使用。默认值： `[]`
dst_range 字符串在 Ansible 2.8 中添加	指定要在 iprange 模块中匹配的目标 IP 范围。
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 set 扩展。
match_set_flags 字符串在 ansible-core 2.11 中添加	指定 match_set 参数所需的标志。必须与 `match_set` 参数一起使用。使用 iptables set 扩展。版本 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"` ←（默认）
syn 字符串	允许匹配设置了 SYN 位且未设置 ACK 和 RST 位的数据包。取反时，这会匹配所有设置了 RST 或 ACK 位的数据包。选择 `"ignore"` ←（默认） `"match"` `"negate"`
table 字符串	此选项指定命令应在其上运行的数据包匹配表。如果内核配置为自动加载模块，如果该表对应的模块尚未加载，则会尝试加载该模块。选择 `"filter"` ← (默认) `"nat"` `"mangle"` `"raw"` `"security"`
tcp_flags 字典	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 中更改）的详细信息
platform	平台: linux	可以操作的目标操作系统/系列

备注 

注意

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

示例 

- 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)

集合链接