Ansible Core 文档

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

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使不指定 collections 关键字，您也可以使用简短的模块名称 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 中添加	指定在 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 集合扩展。
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` 将匹配所有协议，并且在省略此选项时默认为此值。
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 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	支持：完全支持	可以在检查模式下运行并返回更改状态预测，而无需修改目标，如果不支持，则将跳过该操作。
diff_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)

集合链接