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参数之前时，规则只匹配头部片段或未分段的数据包。
网关 字符串 在 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（存在）。 选项 "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 字符串	这指定要与 DNAT 一起使用的目标地址。 没有这个，目标地址永远不会改变。
to_ports 字符串	这指定要使用的目标端口或端口范围，没有这个，目标端口永远不会改变。 只有当规则也指定了协议 tcp、udp、dccp 或 sctp 之一的情况下，此选项才有效。
to_source 字符串	这指定要与 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 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)

集合链接

• 问题跟踪器
• 代码库（源代码）
• 通信