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 中添加	这指定要匹配的多个目标端口号或端口范围，在 multiport 模块中。 它只能与协议 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将匹配所有协议，并且在省略此选项时将作为默认值。
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下更改的内容）的详细信息。
平台	平台：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)

收藏链接

• 问题追踪器
• 代码仓库
• 通信