community.general.ini_file 模块 – 调整 INI 文件中的设置

注意

此模块是 community.general 集合（版本 10.1.0）的一部分。

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

要安装它，请使用：ansible-galaxy collection install community.general。

要在 playbook 中使用它，请指定：community.general.ini_file。

概要 

管理（添加、删除、更改）INI 风格文件中的单个设置，而无需使用 ansible.builtin.template 或 ansible.builtin.assemble 等模块管理整个文件。
如果缺少节，则添加它们。
此模块会向文件添加缺少的结尾换行符，以符合 POSIX 标准，即使不需要应用其他修改。

参数 

参数	注释
allow_no_value 布尔值	允许没有值且没有“=”符号的选项。选择 `false` ← (默认) `true`
attributes 别名: attr 字符串	结果文件系统对象应具有的属性。要获取支持的标志，请查看目标系统上 `chattr` 的手册页。此字符串应包含与 `lsattr` 显示的顺序相同的属性。默认情况下假定为 `=` 运算符，否则需要在字符串中包含 `+` 或 `-` 运算符。
backup 布尔值	创建一个包含时间戳信息的备份文件，这样如果以某种方式错误地破坏了它，您可以恢复原始文件。选择 `false` ← (默认) `true`
create 布尔值	如果设置为 `false`，如果文件不存在，该模块将失败。默认情况下，如果文件丢失，它将创建该文件。选择 `false` `true` ← (默认)
exclusive 布尔值在 community.general 3.6.0 中添加	如果设置为 `true`（默认），当 `state=absent` 时，所有匹配的 `option` 行都将被删除，或者当 `state=present` 时，将被替换。如果设置为 `false`，当 `state=present` 时，只会添加指定的 `value`/`values`，当 `state=absent` 时，只会删除指定的 `value`/`values`，并且不会修改现有的行。选择 `false` `true` ← (默认)
follow 布尔值在 community.general 7.1.0 中添加	此标志指示应跟随文件系统链接（如果存在）。当与 `mode` 等参数结合使用时，`follow=true` 可以修改 `path`。选择 `false` ← (默认) `true`
group 字符串	应拥有文件系统对象的所有者的组的名称，就像提供给 `chown` 一样。如果未指定，它将使用当前用户的当前组，除非您是 root 用户，在这种情况下，它可以保留以前的所有权。
ignore_spaces 布尔值在 community.general 7.5.0 中添加	如果这样做只会添加或删除 `=` 符号之前或之后的空格，则不要更改行。选择 `false` ← (默认) `true`
mode 任意	结果文件系统对象应具有的权限。对于那些习惯使用 `/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。
modify_inactive_option 布尔值在 community.general 8.0.0 中添加	默认情况下，此模块会替换与给定选项匹配的注释行。将此选项设置为 `false` 以避免这种情况。当您想保留用于文档目的的注释示例 `key=value` 对时，此功能很有用。选择 `false` `true` ← (默认)
no_extra_spaces 布尔值	请勿在“=”符号前后插入空格。选择 `false` ← (默认) `true`
option 字符串	如果设置（更改 `value` 时必需），这是选项的名称。如果添加/删除整个 `section`，则可以省略。
owner 字符串	应该拥有文件系统对象的用户的名称，如同提供给 `chown` 命令一样。如果未指定，则使用当前用户，除非您是 root 用户，在这种情况下，它可以保留先前的所有权。指定数字用户名将被视为用户 ID 而不是用户名。避免使用数字用户名以避免这种混淆。
path 别名：dest path / 必需	INI 样式文件的路径；如果需要，将创建此文件。
section 字符串	INI 文件中的节名称。当设置单个值时，如果 `state=present`，则会自动添加此节。如果省略，则 `option` 将放置在第一个 `section` 之前。如果配置格式不支持节，则也需要省略 `section`。
section_has_values list / 元素=dictionary 在 community.general 8.6.0 中添加	在可能具有相同名称的多个节中，选择第一个包含匹配选项和值的节。如果 `state=present`，如果没有找到合适的节，则将添加一个新节，包括所需的选项。如果 `state=absent`，则最多删除一个包含值的 `section`。
option string / 必需	匹配的 `section` 必须包含此选项。
value 字符串	匹配的 `section_has_values[].option` 必须具有此特定值。
values list / 元素=string	要与 `section_has_values[].option` 关联的字符串值。与 `section_has_values[].value` 互斥。 `section_has_values[].value=v` 等同于 `section_has_values[].values=[v]`。
selevel 字符串	SELinux 文件系统对象上下文的级别部分。这是 MLS/MCS 属性，有时称为 `range`。当设置为 `_default` 时，如果策略中可用，它将使用策略的 `level` 部分。
serole 字符串	SELinux 文件系统对象上下文的角色部分。当设置为 `_default` 时，如果策略中可用，它将使用策略的 `role` 部分。
setype 字符串	SELinux 文件系统对象上下文的类型部分。当设置为 `_default` 时，如果策略中可用，它将使用策略的 `type` 部分。
seuser 字符串	SELinux 文件系统对象上下文的用户部分。默认情况下，它使用 `system` 策略（如果适用）。当设置为 `_default` 时，如果策略中可用，它将使用策略的 `user` 部分。
state 字符串	如果设置为 `absent` 且 `exclusive` 设置为 `true`，则将删除所有匹配的 `option` 行。如果设置为 `absent` 且 `exclusive` 设置为 `false`，则将删除指定的 `option=value` 行，但不会触及其他具有相同名称的 `option`。如果设置为 `present` 且 `exclusive` 设置为 `false`，则将添加指定的 `option=values` 行，但不会触及其他具有相同名称的 `option`。如果设置为 `present` 且 `exclusive` 设置为 `true`，则将添加所有给定的 `option=values` 行，并删除其他具有相同名称的 `option`。选择 `"absent"` `"present"` ←（默认）
unsafe_writes 布尔值	影响何时使用原子操作来防止数据损坏或从目标文件系统对象读取不一致的数据。默认情况下，此模块使用原子操作来防止数据损坏或从目标文件系统对象读取不一致的数据，但有时系统配置或损坏的方式会阻止这样做。一个例子是 Docker 挂载的文件系统对象，它们无法从容器内部原子更新，只能以不安全的方式写入。此选项允许 Ansible 在原子操作失败时回退到不安全的文件系统对象更新方法（但是，它不会强制 Ansible 执行不安全的写入）。重要提示！不安全的写入会受到竞争条件的影响，并可能导致数据损坏。选择 `false` ← (默认) `true`
value 字符串	要与 `option` 关联的字符串值。删除 `option` 时可以省略。与 `values` 互斥。 `value=v` 等同于 `values=[v]`。
values list / 元素=string 在 community.general 3.6.0 中添加	要与 `option` 关联的字符串值。删除 `option` 时可以省略。与 `value` 互斥。 `value=v` 等同于 `values=[v]`。

属性 

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

注释 

注意

虽然可以添加一个 option 而不指定 value，但这没有任何意义。
从 community.general 3.2.0 开始，读取文件时会丢弃 UTF-8 BOM 标记。

示例 

- name: Ensure "fav=lemonade is in section "[drinks]" in specified file
  community.general.ini_file:
    path: /etc/conf
    section: drinks
    option: fav
    value: lemonade
    mode: '0600'
    backup: true

- name: Ensure "temperature=cold is in section "[drinks]" in specified file
  community.general.ini_file:
    path: /etc/anotherconf
    section: drinks
    option: temperature
    value: cold
    backup: true

- name: Add "beverage=lemon juice" is in section "[drinks]" in specified file
  community.general.ini_file:
    path: /etc/conf
    section: drinks
    option: beverage
    value: lemon juice
    mode: '0600'
    state: present
    exclusive: false

- name: Ensure multiple values "beverage=coke" and "beverage=pepsi" are in section "[drinks]" in specified file
  community.general.ini_file:
    path: /etc/conf
    section: drinks
    option: beverage
    values:
      - coke
      - pepsi
    mode: '0600'
    state: present

- name: Add "beverage=lemon juice" outside a section in specified file
  community.general.ini_file:
    path: /etc/conf
    option: beverage
    value: lemon juice
    state: present

- name: Remove the peer configuration for 10.128.0.11/32
  community.general.ini_file:
    path: /etc/wireguard/wg0.conf
    section: Peer
    section_has_values:
      - option: AllowedIps
        value: 10.128.0.11/32
    mode: '0600'
    state: absent

- name: Add "beverage=lemon juice" outside a section in specified file
  community.general.ini_file:
    path: /etc/conf
    option: beverage
    value: lemon juice
    state: present

- name: Update the public key for peer 10.128.0.12/32
  community.general.ini_file:
    path: /etc/wireguard/wg0.conf
    section: Peer
    section_has_values:
      - option: AllowedIps
        value: 10.128.0.12/32
    option: PublicKey
    value: xxxxxxxxxxxxxxxxxxxx
    mode: '0600'
    state: present

- name: Remove the peer configuration for 10.128.0.11/32
  community.general.ini_file:
    path: /etc/wireguard/wg0.conf
    section: Peer
    section_has_values:
      - option: AllowedIps
        value: 10.4.0.11/32
    mode: '0600'
    state: absent

- name: Update the public key for peer 10.128.0.12/32
  community.general.ini_file:
    path: /etc/wireguard/wg0.conf
    section: Peer
    section_has_values:
      - option: AllowedIps
        value: 10.4.0.12/32
    option: PublicKey
    value: xxxxxxxxxxxxxxxxxxxx
    mode: '0600'
    state: present

作者

Jan-Piet Mens (@jpmens)
Ales Nosek (@noseka1)