community.postgresql.postgresql_pg_hba 模块 – 在 pg_hba 文件中添加、删除或修改规则

注意

此模块是 community.postgresql 集合 (版本 3.9.0) 的一部分。

如果您正在使用 ansible 包，则可能已安装此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install community.postgresql。您需要其他要求才能使用此模块，请参阅 要求 获取详细信息。

要在 playbook 中使用它，请指定：community.postgresql.postgresql_pg_hba。

概要

• 该模块的基本功能是在 pg_hba 文件中创建或删除行。

• 文件中的行应采用典型的 pg_hba 格式，并且每行键（类型、数据库、用户、来源）都应唯一。如果它们不唯一，并且 SID 是“要更改的 SID”，则对于 *state=present* 只会保留一个 SID，而对于 *state=absent* 则不会保留任何 SID。

要求

执行此模块的主机需要以下要求。

• ipaddress

参数

参数	注释
address 别名：source，src 字符串	连接可以从中发出的源地址/网络。 不会用于 *type*=local 的条目。 您还可以使用关键字 all、samehost 和 samenet。 默认值： "samehost"
attributes 别名：attr 字符串	生成的档案对象应具有的属性。 要获取支持的标志，请查看目标系统上 *chattr* 的手册页。 此字符串应按 *lsattr* 显示的顺序包含属性。 默认情况下假定使用 = 运算符，否则需要在字符串中包含 + 或 - 运算符。
backup 布尔值	如果设置，则在修改 pg_hba 文件之前创建其备份。此模块在 (backup) 变量中返回备份的位置。 选项 false ← (默认) true
backup_file 字符串	将备份写入特定的备份文件，而不是临时文件。
comment 字符串 在 community.postgresql 1.5.0 中添加	将放置在规则后面的同一行中的注释。另请参见 *keep_comments_at_rules* 参数。
contype 字符串	规则的类型。如果未设置，postgresql_pg_hba 将只返回内容。 选项 "local" "host" "hostnossl" "hostssl" "hostgssenc" "hostnogssenc"
create 布尔值	如果不存在，则创建 pg_hba 文件。 如果设置为 false，则当 pg_hba 文件不存在时，会引发错误。 选项 false ← (默认) true
databases 字符串	此行适用的数据库。 默认值： "all"
dest 路径 / 必需	要修改的 pg_hba 文件的路径。
group 字符串	应拥有文件系统的组的名称，如同提供给 *chown* 一样。 如果未指定，则使用当前用户的当前组，除非您是 root 用户，在这种情况下，它可以保留之前的拥有者。
keep_comments_at_rules 布尔值 在 community.postgresql 1.5.0 中添加	如果为 true，则与规则在一行中一起存在的注释将保留在该行的后面。 如果为 false，则此类注释将与所有其他注释一样，移动到文件的开头。 选项 false ← (默认) true
method 字符串	要使用的身份验证方法。 选项 "cert" "gss" "ident" "krb5" "ldap" "md5" ← (默认) "pam" "password" "peer" "radius" "reject" "scram-sha-256" "sspi" "trust"
mode any	生成的档案对象应具有的权限。 对于习惯使用/usr/bin/chmod的用户来说，请记住模式实际上是八进制数。您必须向 Ansible 提供足够的信息才能正确解析它们。为了获得一致的结果，请用引号括起八进制数（例如，'644' 或 '1777'），以便 Ansible 接收到一个字符串，并可以自行将字符串转换为数字。添加前导零（例如，0755）有时有效，但在循环和其他一些情况下可能会失败。 如果不遵循以上任何规则，直接向 Ansible 提供数字，则最终会得到一个十进制数，这将导致意想不到的结果。 从 Ansible 1.8 开始，模式可以指定为符号模式（例如，u+rwx 或 u=rw,g=r,o=r）。 如果未指定mode并且目标文件系统对象**不存在**，则在设置新创建的文件系统对象的模式时，将使用系统上的默认umask。 如果未指定mode并且目标文件系统对象**存在**，则将使用现有文件系统对象的模式。 指定mode是确保文件系统对象以正确的权限创建的最佳方法。有关更多详细信息，请参阅 CVE-2020-1736。
netmask 字符串	源地址的网络掩码。
options 字符串	身份验证方法的其他选项。
overwrite 布尔值	在添加规则之前删除所有现有规则。（类似于所有预先存在的规则的state=absent。） 选项 false ← (默认) true
owner 字符串	应拥有文件系统对象的用户名，如同提供给chown一样。 如果未指定，则使用当前用户，除非您是 root 用户，在这种情况下，它可以保留之前的拥有者。 指定数字用户名将被认为是用户 ID 而不是用户名。避免使用数字用户名以避免此混淆。
rules 列表 / 元素=字典	对象列表，指定 pg_hba.conf 的规则。使用它可以一次管理多个规则。 每个对象都可以具有以下键（“特定于规则的参数”），这些键的处理方式与该模块的参数相同 address，comment，contype，databases，method，netmask，options，state，users 另请参阅rules_behavior。
rules_behavior 字符串	配置rules参数如何与rules参数之外的特定于规则的参数一起工作。 有关特定于规则的参数的完整列表，请参阅rules。 设置为conflict时，如果设置了rules和例如address，则会失败。 如果为combine，则普通的特定于规则的参数不会定义规则，而是用作rules参数中参数的默认值。 仅当指定了rules时才使用，否则忽略。 选项 "conflict" ← (默认) "combine"
selevel 字符串	SELinux 文件系统对象上下文的级别部分。 这是 MLS/MCS 属性，有时称为range。 设置为_default时，如果可用，它将使用策略的level部分。
serole 字符串	SELinux 文件系统对象上下文的角色部分。 设置为_default时，如果可用，它将使用策略的role部分。
setype 字符串	SELinux 文件系统对象上下文的类型部分。 设置为_default时，如果可用，它将使用策略的type部分。
seuser 字符串	SELinux 文件系统对象上下文的用户部分。 默认情况下，它使用system策略（如果适用）。 设置为_default时，如果可用，它将使用策略的user部分。
state 字符串	当state=present时，将添加/修改这些行；当state=absent时，将删除这些行。 选项 "absent" "present" ← (默认)
unsafe_writes 布尔值	影响何时使用原子操作来防止目标文件系统对象的数据损坏或不一致读取。 默认情况下，此模块使用原子操作来防止目标文件系统对象的数据损坏或不一致读取，但有时系统的配置方式或本身存在问题，会阻止此操作。一个例子是 docker 挂载的文件系统对象，无法从容器内部以原子方式更新，只能以不安全的方式写入。 此选项允许 Ansible 在原子操作失败时回退到不安全的文件系统对象更新方法（但是，它不会强制 Ansible 执行不安全写入）。 重要！不安全写入容易出现竞争条件，并可能导致数据损坏。 选项 false ← (默认) true
users 字符串	此行适用的用户。 默认值： "all"

属性

属性	支持	描述
check_mode	支持：完全支持	可以在 check_mode 下运行，并在不修改目标的情况下返回更改状态预测。
diff_mode	支持：完全支持	在差异模式下，将返回有关已更改内容（或可能需要在 check_mode 中更改的内容）的详细信息。

备注

注意

• 默认身份验证假设在主机上，您正在以具有读取和修改文件的适当权限的帐户登录或使用 sudo 命令登录。

• 此模块还返回 pg_hba 信息。您只需指定dest即可使用此模块仅检索它。信息可以在返回的数据中 key pg_hba 下找到，它是一个列表，每个规则包含一个字典。

• 如果需要更改规则，此模块将对生成的pg_hba文件进行排序。如果手动创建的 hba 文件排序不正确，这可能会产生意想不到的结果。例如，首先为网络创建规则，然后为该网络范围内的 ip 创建规则。在这种情况下，“特定于 ip 的规则”将永远不会命中，它在pg_hba文件中已过期。在community.postgresql.postgresql_pg_hba模块重写pg_hba文件之后，特定于 ip 的规则将排序在范围规则之上。然后它将命中，这将产生意想不到的结果。

另请参阅

另请参阅

PostgreSQL pg_hba.conf 文件参考

PostgreSQL pg_hba.conf 文件文档的完整参考。

示例

- name: Grant users joe and simon access to databases sales and logistics from ipv6 localhost ::1/128 using peer authentication
  community.postgresql.postgresql_pg_hba:
    dest: /var/lib/postgres/data/pg_hba.conf
    contype: host
    users: joe,simon
    source: ::1
    databases: sales,logistics
    method: peer
    create: true

- name: Grant user replication from network 192.168.0.100/24 access for replication with client cert authentication
  community.postgresql.postgresql_pg_hba:
    dest: /var/lib/postgres/data/pg_hba.conf
    contype: host
    users: replication
    source: 192.168.0.100/24
    databases: replication
    method: cert

- name: Revoke access from local user mary on database mydb
  community.postgresql.postgresql_pg_hba:
    dest: /var/lib/postgres/data/pg_hba.conf
    contype: local
    users: mary
    databases: mydb
    state: absent

- name: Grant some_user access to some_db, comment that and keep other rule-specific comments attached to their rules
  community.postgresql.postgresql_pg_hba:
    dest: /var/lib/postgres/data/pg_hba.conf
    contype: host
    users: some_user
    databases: some_db
    method: md5
    source: ::/0
    keep_comments_at_rules: true
    comment: "this rule is an example"

- name: Replace everything with a new set of rules
  community.postgresql.postgresql_pg_hba:
    dest: /var/lib/postgres/data/pg_hba.conf
    overwrite: true # remove preexisting rules

    # custom defaults
    rules_behavior: combine
    contype: hostssl
    address: 2001:db8::/64
    comment: added in bulk

    rules:
    - users: user1
      databases: db1
      # contype, address and comment come from custom default
    - users: user2
      databases: db2
      comment: added with love # overwrite custom default for this rule
      # contype and address come from custom default
    - users: user3
      databases: db3
      # contype, address and comment come from custom default

返回值

常用返回值已记录在此处，以下是此模块独有的字段

键	描述
backup_file 字符串	原始 pg_hba 文件备份到的文件。 已返回：changed 示例："/tmp/pg_hba_jxobj_p"
msgs 列表 / 元素=字符串	已执行操作的文本消息列表。 已返回：success 示例：{"msgs": ["Removing", "Changed", "Writing"]}
pg_hba 列表 / 元素=字符串	pg_hba 规则的列表，它们已在指定 hba 文件中配置。 已返回：success 示例：{"pg_hba": [{"db": "all", "method": "md5", "src": "samehost", "type": "host", "usr": "all"}]}

作者

• Sebastiaan Mannem (@sebasmannem)

• Felix Hamme (@betanummeric)

• Thomas Ziegler (@toydarian)

集合链接

• 问题追踪器
• 代码库（源代码）
• 报告问题
• 通信