Salt firewalld 执行模块完全指南：用 Salt 声明式管理 firewalld 防火墙

Salt firewalld 执行模块完全指南用 Salt 声明式管理 firewalld 防火墙【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址: https://gitcode.com/gh_mirrors/sa/salt本指南以 Salt 仓库中 salt/modules/firewalld.py 为技术蓝本系统讲解 firewalld 执行模块自 Salt 2015.2.0 引入提供的全部函数区域zone与服务service管理、端口与端口转发、伪装masquerade、ICMP 拦截、接口/源绑定以及 rich rules。读者将掌握通过salt * firewalld.xxx命令行实时操作防火墙并结合 salt/states/firewalld.py 中的firewalld.present/firewalld.service状态实现幂等的声明式防火墙配置。模块定位与加载前提firewalld 执行模块是对 firewalld 官方命令行工具firewall-cmd的一层薄封装每个函数最终都拼接并执行一条对应的firewall-cmd命令。模块能否加载由__virtual__()函数决定salt/modules/firewalld.pydef __virtual__(): if salt.utils.path.which(firewall-cmd): return True return ( False, The firewalld execution module cannot be loaded: the firewall-cmd binary is not in the path., )也就是说只有目标 minion 上存在firewall-cmd可执行文件即已安装并启动 firewalld 的 RHEL/CentOS/Fedora 等发行版时模块才会被 Salt 加载器暴露为firewalld.*函数否则调用会直接得到模块不可用的提示。模块内部的核心执行函数为__firewall_cmd(cmd)salt/modules/firewalld.py它调用cmd.run_all执行firewall-cmd 参数若返回码非 0则抛出CommandExecutionError错误信息优先取 stderr其次取 stdout若执行成功返回命令的 stdout 文本。而__mgmt(name, _type, action)salt/modules/firewalld.py是new_zone、delete_zone、new_service、delete_service四个函数的公共骨架它们固定拼接--permanent参数注释明确说明这 4 个函数必须使用 permanent 选项否则结果就是错的统一生成形如--new-zonexxx --permanent的命令。基础信息查询以下函数用于获取 firewalld 的版本与预定义对象清单是最常用的诊断工具函数底层命令返回内容firewalld.versionfirewall-cmd --versionfirewalld 版本字符串firewalld.reload_rulesfirewall-cmd --reload重新加载防火墙规则使永久配置成为新的运行时配置不丢失状态信息2016.11.0 加入firewalld.default_zonefirewall-cmd --get-default-zone当前默认区域名firewalld.get_zones(permanentTrue)firewall-cmd --get-zones [--permanent]预定义区域名列表split 后的数组firewalld.get_services(permanentTrue)firewall-cmd --get-services [--permanent]预定义服务名列表firewalld.get_icmp_types(permanentTrue)firewall-cmd --get-icmptypes [--permanent]预定义 ICMP 类型列表命令行调用示例salt * firewalld.version salt * firewalld.reload_rules salt * firewalld.default_zone salt * firewalld.get_zones salt * firewalld.get_services salt * firewalld.get_icmp_types注意这些get系列函数默认携带--permanent永久配置。若想查看运行时配置可显式传permanentFalse例如salt * firewalld.get_zones False。区域Zone管理firewalld 的核心抽象是区域——一组适用于特定接口/来源的规则集合。模块提供了区域的生命周期管理函数创建与删除区域# 新建区域默认会执行 --reload 使配置生效 salt * firewalld.new_zone my_zone # 创建区域但暂不重载restartFalse salt * firewalld.new_zone my_zone False # 删除区域 salt * firewalld.delete_zone my_zone # 删除区域但不重载 salt * firewalld.delete_zone my_zone Falsenew_zone/delete_zone通过__mgmt执行--new-zone名 --permanent/--delete-zone名 --permanent当restartTrue默认且底层命令返回success时会额外调用firewall-cmd --reload让永久配置立即生效salt/modules/firewalld.py。设置默认区域salt * firewalld.set_default_zone damian对应命令为firewall-cmd --set-default-zonedamian该操作同时作用于永久与运行时配置。查看区域# 列出所有区域的全部配置默认 permanent salt * firewalld.list_zones # 列出指定区域的全部配置 salt * firewalld.list_all salt * firewalld.list_all my_zonelist_zones与list_all使用私有解析器__parse_zone(cmd)salt/modules/firewalld.py把firewall-cmd --list-all-zones/--list-all的文本输出解析为嵌套字典顶层键是区域名其值是该区域的各属性target、interfaces、services、ports、masquerade、forward-ports、icmp-blocks、rich rules等映射到字符串列表。解析逻辑以行首非制表符、以^[a-z0-9]开头区分区域名行与属性行属性行再按:切分键值缩进行追加到前一个属性值中。单元测试 tests/pytests/unit/modules/test_firewalld.py 验证了将--list-all-zones文本解析为结构化字典的行为也验证了空响应时返回{}。服务Service管理服务是对一组端口/协议的命名抽象如ssh、http可被多个区域引用。服务的新建与删除salt * firewalld.new_service my_service salt * firewalld.new_service my_service False # 不重载 salt * firewalld.delete_service my_service salt * firewalld.delete_service my_service False与区域管理相同默认在成功后执行--reload。服务的端口与协议定义2016.11.0 起模块支持直接定义服务内部的端口与协议对应firewall-cmd --permanent --servicexxx ...系列命令# 为服务添加/移除端口 salt * firewalld.add_service_port zone 80 salt * firewalld.remove_service_port zone 80 salt * firewalld.get_service_ports zone # 为服务添加/移除协议 salt * firewalld.add_service_protocol zone ssh salt * firewalld.remove_service_protocol zone ssh salt * firewalld.get_service_protocols zone值得注意的是add_service_port/remove_service_port在执行前会先调用get_services(permanentTrue)校验服务存在性若服务不存在直接抛出CommandExecutionError(The service does not exist.)salt/modules/firewalld.py避免静默失败。在区域中增删服务# 向默认区域添加服务 salt * firewalld.add_service ssh # 向指定区域添加服务 salt * firewalld.add_service ssh my_zone # 从默认区域移除服务 salt * firewalld.remove_service ssh # 从指定区域移除服务 salt * firewalld.remove_service ssh dmz # 列出区域已启用的服务默认区域 salt * firewalld.list_services # 列出指定区域的服务 salt * firewalld.list_services my_zone这些函数都接受可选的zone与permanent参数省略zone时作用于默认区域permanentTrue默认时追加--permanent。端口与端口转发端口开放# 在 internal 区域开放 443/tcp默认永久生效 salt * firewalld.add_port internal 443/tcp # 移除端口 salt * firewalld.remove_port internal 443/tcp # 列出区域端口 salt * firewalld.list_ports internaladd_port还有一个特别的force_masquerade参数salt/modules/firewalld.py当传入True且目标区域尚未启用伪装时会先自动调用add_masquerade(zone)再开放端口——适用于 NAT/网关类场景下端口必须配合伪装才能生效的情况。端口转发# 在 public 区域将 TCP 80 端口转发到 443 salt * firewalld.add_port_fwd public 80 443 tcp # 移除转发 salt * firewalld.remove_port_fwd public 80 443 tcp # 列出区域的所有转发规则 salt * firewalld.list_port_fwd publicadd_port_fwd(zone, src, dest, prototcp, dstaddr, permanentTrue, force_masqueradeFalse)会拼接为firewall-cmd --zonezone --add-forward-portportsrc:protoproto:toportdest:toaddrdstaddr [--permanent]其中dstaddr为空时toaddr后面为空串即不限定目标地址。list_port_fwd会把--list-forward-ports的输出按:拆分并整理为包含Source port、Protocol、Destination port、Destination address四个键的字典列表。add_port_fwd同样支持force_masquerade便于在网关场景自动补齐伪装设置。伪装Masquerade与 ICMP 控制伪装开关# 查询默认区域是否启用伪装 salt * firewalld.get_masquerade # 查询指定区域 salt * firewalld.get_masquerade dmz # 启用默认区域 / 指定区域 salt * firewalld.add_masquerade salt * firewalld.add_masquerade dmz # 停用 salt * firewalld.remove_masquerade salt * firewalld.remove_masquerade dmzget_masquerade的判定方式值得一提salt/modules/firewalld.py它复用list_all解析出的区域信息只要任一区域的masquerade属性取值为no即返回False否则返回True。ICMP 类型拦截与放行# 在 zone 区域拦截 echo-reply salt * firewalld.block_icmp zone echo-reply # 放行即移除拦截 salt * firewalld.allow_icmp zone echo-reply # 列出区域当前的 ICMP 拦截 salt * firewalld.list_icmp_block zoneblock_icmp与allow_icmp都先通过get_icmp_types(permanent)校验 ICMP 类型是否合法非法时记录 error 日志并返回Falsesalt/modules/firewalld.py同时具备幂等性——若目标状态已存在则返回success而不重复下发命令。运行时与永久配置firewalld 存在运行时配置与永久配置两套状态运行时配置即时生效但重启后丢失永久配置持久化到磁盘但需 reload 才生效。模块通过统一约定管理这对关系所有add_*/remove_*/new_*/delete_*函数默认带permanentTrue追加--permanent即写入永久配置需要立即生效时可显式调用reload_rules--reload或依赖new_zone/new_service等函数内置的自动 reload若希望保留当前运行时配置并落盘可使用# 将当前运行时配置写入永久配置2016.3.0 加入 salt * firewalld.make_permanent对应命令为firewall-cmd --runtime-to-permanent在手工调试完临时规则后一键固化的运维场景非常实用。接口与来源绑定将网络接口或来源 IP 段绑定到区域是区域路由的核心手段# 列出/添加/移除绑定到 zone 的接口2016.3.0 加入 salt * firewalld.get_interfaces zone salt * firewalld.add_interface zone eth0 salt * firewalld.remove_interface zone eth0 # 列出/添加/移除绑定到 zone 的来源网段 salt * firewalld.get_sources zone salt * firewalld.add_source zone 192.168.1.0/24 salt * firewalld.remove_source zone 192.168.1.0/24add_interface/remove_interface与add_source/remove_source都会先查询当前绑定状态并打 info 日志already bound / not bound但不会阻止命令继续下发最终结果仍以firewall-cmd返回为准。Rich Rules富规则Rich rules 是 firewalld 最灵活的规则表达方式支持按源地址、端口、协议等条件组合放行/拒绝# 列出区域的富规则2016.11.0 加入 salt * firewalld.get_rich_rules zone # 添加一条富规则 salt * firewalld.add_rich_rule zone rule # 移除富规则 salt * firewalld.remove_rich_rule zone rule底层分别对应--list-rich-rules、--add-rich-rulerule、--remove-rich-rulerule。由于富规则通过 shell 执行规则字符串需用单引号包裹。状态模块从命令到幂等声明式配置如果说执行模块提供的是命令能力那么 salt/states/firewalld.py 提供的firewalld.present与firewalld.service状态2015.8.0 引入则是面向 SLS 的声明式能力状态会比对当前配置与期望配置仅下发差异变更并在有变更时自动调用firewalld.reload_rules重载。firewalld.present定义区域整体状态present支持block_icmp、default、masquerade、ports、port_fwd、services、interfaces、sources、rich_rules九类属性每类都配套对应的prune_*开关置True时删除未列出的多余项实现全量收敛prune_services目前默认True以保持兼容未来版本将改为False。参考 SLS 示例public: firewalld.present: - name: public - block_icmp: - echo-reply - echo-request - default: False - masquerade: True - ports: - 22/tcp - 25/tcpmy_zone: firewalld.present: - name: public - masquerade: True - port_fwd: - 22:2222:tcp - 80:443:tcp:192.168.0.1端口转发使用源端口:目标端口:协议[:目标地址]的紧凑语法由状态模块中的_parse_forward解析为ForwardingMapping对象再与firewalld.list_port_fwd的当前结果做集合差集运算salt/states/firewalld.py。public: firewalld.present: - name: public - interfaces: - eth0 - sources: - 192.168.1.0/24该示例会把public区域绑定到 eth0 与192.168.1.0/24来源配合prune_interfaces: True/prune_sources: True时还会把区域从其他所有接口/来源上解绑。rich_rules 的写法与firewall-cmd --list-rich-rules的输出格式一致例如saltzone: firewalld.present: - name: saltzone - rich_rules: - rule service namesaltmaster accept - sources: - 10.0.0.0/8状态模块内部通过_normalize_rich_rules对富规则做归一化——把单引号包裹的属性值统一转为双引号rule familyipv4 source address192.168.0.0/16 port port22 protocoltcp accept从而与firewall-cmd的实际输出精确比对、避免误判已存在salt/states/firewalld.py。对应单元测试 tests/pytests/unit/states/test_firewalld.py 验证了多种引号写法的富规则都能被正确归一化并识别为已是期望状态。firewalld.service定义服务端口/协议saltmaster: firewalld.service: - name: saltmaster - ports: - 4505/tcp - 4506/tcp该状态2016.11.0 加入确保服务存在并只包含指定的端口与协议服务不存在时先new_service(name, restartFalse)创建再通过get_service_ports/get_service_protocols与期望集合做差集增量调用add_service_port/remove_service_port/add_service_protocol/remove_service_protocol最后有变更时执行 reload。上面的示例定义了一个名为saltmaster、包含 4505/4506 TCP 端口的新服务——这正是 Salt Master 与 Minion 之间通信使用的端口。定义服务后即可在区域中启用它例如允许来自10.0.0.0/8网段的 minion 访问 Salt Mastersaltzone: firewalld.present: - name: saltzone - services: - saltmaster - sources: - 10.0.0.0/8测试模式与返回约定状态模块完整遵循 Salt 状态约定testTrue时只计算差异、返回result: None与will change提示而不实际下发无差异时返回name is already in the desired state.并置result: True有差异时执行变更并返回old/new对照的changes字典。状态测试tests/pytests/unit/states/test_firewalld.py验证了 masquerade 开/关场景下的完整返回结构。底层实现要点小结命令装配所有函数通过 f-string 或format拼接firewall-cmd参数--permanent统一追加在命令末尾输出解析list_zones/list_all走__parse_zone文本解析器其余函数多用split()/splitlines()拆分成列表错误处理任何firewall-cmd非零返回码都会转为CommandExecutionError并在信息中包含 stderr/stdout便于在 Salt 事件与日志中定位问题幂等设计block_icmp/allow_icmp等函数会先查询现状已满足目标时直接返回success配合状态层的集合差集比对实现全链路幂等版本里程碑模块主体 2015.2.0 引入masquerade/端口/转发/ICMP 相关函数 2015.8.0 加入make_permanent、接口/来源绑定 2016.3.0 加入服务端口/协议、rich rules、reload_rules2016.11.0 加入。实际使用时可先以salt * firewalld.list_all摸清各区域现状再用firewalld.present状态批量收敛配置涉及 NAT 转发时记得配合force_masquerade: True或显式启用 masquerade避免规则已加但不生效的典型陷阱。【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址: https://gitcode.com/gh_mirrors/sa/salt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考