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是“要更改的”，则对于state=present 只有一个SID，或者对于state=absent 没有SID将保留。

要求

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

• ipaddress

参数

参数	注释
address 别名：source，src 字符串	连接可能来自的源地址/网络。 不会用于type=local的条目。 您还可以使用关键字all、samehost和samenet。 默认值： "samehost"
attributes 别名：attr 字符串	生成的 filesystem 对象应具有的属性。 要获取支持的标志，请查看目标系统上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	生成的 filesystem 对象应具有的权限。 对于习惯使用/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 文件备份到的文件。 返回：已更改 示例："/tmp/pg_hba_jxobj_p"
msgs 列表 / 元素=字符串	已执行操作的文本消息列表。 返回：成功 示例：{"msgs": ["Removing", "Changed", "Writing"]}
pg_hba 列表 / 元素=字符串	pg_hba 规则的列表，其配置方式与指定 hba 文件中的配置方式相同。 返回：成功 示例： {"pg_hba": [{"db": "all", "method": "md5", "src": "samehost", "type": "host", "usr": "all"}]}

作者

• Sebastiaan Mannem (@sebasmannem)

• Felix Hamme (@betanummeric)

• Thomas Ziegler (@toydarian)

资源链接

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