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 字符串	生成的 filesystem 对象应具有的属性。 要获取支持的标志，请查看目标系统上 *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 时删除，并且不会修改现有值。 选项 false true ← (默认)
follow 布尔值 在 community.general 7.1.0 中添加	此标志指示应跟踪文件系统链接（如果存在）。 follow=true 与诸如 mode 之类的参数组合时，可以修改 path。 选项 false ← (默认) true
group 字符串	应该拥有文件系统对象的组的名称，就像提供给 *chown* 一样。 如果未指定，它将使用当前用户的当前组，除非您是 root 用户，在这种情况下，它可以保留以前的拥有者。
ignore_spaces 布尔值 在 community.general 7.5.0 中添加	如果这样做只会添加或删除 = 符号之前或之后的空格，则不要更改行。 选项 false ← (默认) true
mode 任意	生成的 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。
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 / required	INI 样式文件的路径；如果需要，将创建此文件。
section 字符串	INI 文件中的节名称。当设置单个值时，如果state=present，则会自动添加。 如果省略，则option将放在第一个section之前。 如果配置格式不支持节，则也需要省略section。
section_has_values list / elements=dictionary 在 community.general 8.6.0 中添加	在可能存在的多个同名节中，选择第一个包含匹配选项和值的节。 使用state=present，如果找不到合适的节，则会添加一个新节，其中包含所需的选项。 使用state=absent，如果包含这些值，则最多删除一个section。
option string / required	匹配的section必须包含此选项。
value 字符串	匹配的section_has_values[].option必须具有此特定值。
values list / elements=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" ← (default)
unsafe_writes 布尔值	影响何时使用原子操作来防止目标文件系统对象的数据损坏或不一致读取。 默认情况下，此模块使用原子操作来防止目标文件系统对象的数据损坏或不一致读取，但有时系统的配置方式存在问题或已损坏，从而阻止了此操作。一个例子是 docker 挂载的文件系统对象，它们无法在容器内以原子方式更新，只能以不安全的方式写入。 此选项允许 Ansible 在原子操作失败时回退到不安全的文件系统对象更新方法（但是，它不会强制 Ansible 执行不安全写入）。 重要！不安全写入容易出现竞争条件，并可能导致数据损坏。 选项 false ← (默认) true
value 字符串	要与option关联的字符串值。 删除option时可以省略。 与values互斥。 value=v等效于values=[v]。
values list / elements=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)

资源链接

• 问题追踪
• 代码仓库
• 寻求帮助
• 提交 Bug 报告
• 功能请求
• 沟通