ansible.builtin.blockinfile 模块 – 插入/更新/删除由标记行包围的文本块

注意

此模块是 ansible-core 的一部分,包含在所有 Ansible 安装中。在大多数情况下,即使不指定 collections 关键字,您也可以使用简短的模块名称 blockinfile。但是,我们建议您使用 完全限定的集合名称 (FQCN) ansible.builtin.blockinfile,以便轻松链接到模块文档并避免与可能具有相同模块名称的其他集合冲突。

摘要

  • 此模块将插入/更新/删除由可自定义标记行包围的多行文本块。

参数

参数

注释

append_newline

布尔值

在 ansible-core 2.16 中添加

如果插入的块末尾没有空行,则追加一个空行。

请注意,当 state 设置为 absent 时,不会考虑此属性。

选项

  • false ← (默认)

  • true

attributes

别名:attr

字符串

生成的 文件系统对象应具有的属性。

要获取支持的标志,请查看目标系统上 chattr 的手册页。

此字符串应按 lsattr 显示的顺序包含属性。

默认情况下假定使用 = 运算符,否则需要在字符串中包含 +- 运算符。

backup

布尔值

创建包含时间戳信息的备份文件,以便在您以某种方式错误地覆盖文件后能够恢复原始文件。

选项

  • false ← (默认)

  • true

block

别名:content

字符串

要插入标记行内的文本。

如果它缺失或为空字符串,则该块将被删除,就像 state 指定为 absent 一样。

默认值: ""

create

布尔值

如果文件不存在,则创建一个新文件。

选项

  • false ← (默认)

  • true

group

字符串

应拥有文件系统对象的组的名称,就像传递给 chown 一样。

如果未指定,则它使用当前用户的当前组,除非您是 root 用户,在这种情况下,它可以保留以前的拥有权。

insertafter

字符串

如果指定且未找到开始/结束 marker 行,则该块将插入指定正则表达式的最后一个匹配项之后。

可以使用一个特殊值;EOF 用于将块插入文件末尾。

如果指定的正则表达式没有匹配项或没有传递值,则将使用 EOF 代替。

正则表达式中多行标志 (?m) 的存在控制匹配是逐行进行还是多行进行。此行为是在 ansible-core 2.14 中添加的。

insertbefore

字符串

如果指定且未找到开始/结束 marker 行,则该块将插入指定正则表达式的最后一个匹配项之前。

可以使用一个特殊值;BOF 用于将块插入文件开头。

如果指定的正则表达式没有匹配项,则该块将插入文件末尾。

正则表达式中多行标志 (?m) 的存在控制匹配是逐行进行还是多行进行。此行为是在 ansible-core 2.14 中添加的。

marker

字符串

标记行模板。

{mark} 将替换为 marker_begin(默认值=BEGIN)和 marker_end(默认值=END)中的值。

使用没有 {mark} 变量的自定义标记可能会导致在后续 playbook 运行中重复插入该块。

不支持多行标记,这将导致在后续 playbook 运行中重复插入该块。

模块会自动将换行符追加到 marker_beginmarker_end

默认值: "# {mark} ANSIBLE MANAGED BLOCK"

marker_begin

字符串

这将插入到打开的 ansible 块 marker 中的 {mark} 中。

默认值: "BEGIN"

marker_end

字符串

这将插入到关闭的 ansible 块 marker 中的 {mark} 中。

默认值: "END"

mode

任意

生成的 文件系统对象应具有的权限。

对于习惯使用 /usr/bin/chmod 的用户,请记住模式实际上是八进制数。您必须向 Ansible 提供足够的信息才能正确解析它们。为了获得一致的结果,请引用八进制数(例如,'644''1777'),以便 Ansible 接收一个字符串并可以自行将字符串转换为数字。添加前导零(例如,0755)有时有效,但在循环和其他一些情况下可能会失败。

在不遵循这些规则中的任何一个的情况下向 Ansible 提供数字将导致十进制数字,这将产生意外的结果。

从 Ansible 1.8 开始,模式可以指定为符号模式(例如,u+rwxu=rw,g=r,o=r)。

如果未指定 mode 并且目标文件系统对象**不存在**,则在为新创建的文件系统对象设置模式时,将使用系统上的默认 umask

如果未指定 mode 并且目标文件系统对象**存在**,则将使用现有文件系统对象的模式。

指定 mode 是确保文件系统对象以正确的权限创建的最佳方法。有关更多详细信息,请参阅 CVE-2020-1736。

owner

字符串

应拥有文件系统对象的用户名称,如同传递给 chown

如果未指定,则使用当前用户,除非您是 root 用户,在这种情况下,它可以保留之前的拥有者。

指定数字用户名将被视为用户 ID 而不是用户名。避免使用数字用户名以避免此混淆。

路径

别名:dest、destfile、name

路径 / 必需

要修改的文件。

在 Ansible 2.3 之前,此选项只能用作 destdestfilename

prepend_newline

布尔值

在 ansible-core 2.16 中添加

如果插入的块不在文件开头,则在其前面添加一个空行。

请注意,当 state 设置为 absent 时,不会考虑此属性。

选项

  • false ← (默认)

  • true

selevel

字符串

SELinux 文件系统对象上下文的级别部分。

这是 MLS/MCS 属性,有时称为 range

设置为 _default 时,它将使用策略的 level 部分(如果可用)。

serole

字符串

SELinux 文件系统对象上下文的角色部分。

设置为 _default 时,它将使用策略的 role 部分(如果可用)。

setype

字符串

SELinux 文件系统对象上下文的类型部分。

设置为 _default 时,它将使用策略的 type 部分(如果可用)。

seuser

字符串

SELinux 文件系统对象上下文的用户部分。

默认情况下,它使用 system 策略(如果适用)。

设置为 _default 时,它将使用策略的 user 部分(如果可用)。

状态

字符串

块是否存在。

选项

  • "不存在"

  • "存在" ← (默认)

unsafe_writes

布尔值

影响何时使用原子操作来防止数据损坏或目标文件系统对象的不一致读取。

默认情况下,此模块使用原子操作来防止数据损坏或目标文件系统对象的不一致读取,但有时系统配置或损坏的方式会阻止这种情况。一个例子是 Docker 挂载的文件系统对象,它们无法从容器内部以原子方式更新,只能以不安全的方式写入。

此选项允许 Ansible 在原子操作失败时回退到不安全的文件系统对象更新方法(但是,它不会强制 Ansible 执行不安全写入)。

重要!不安全写入容易受到竞争条件的影响,并可能导致数据损坏。

选项

  • false ← (默认)

  • true

验证

字符串

在将更新的文件复制到最终目标之前运行的验证命令。

使用临时文件路径进行验证,通过 %s 传递,它必须存在,如下面的示例所示。

此外,命令以安全方式传递,因此 shell 功能(如扩展和管道)将不起作用。

有关如何处理比此选项提供的更复杂的验证的示例,请参阅 处理复杂验证

属性

属性

支持

描述

check_mode

支持: 完全支持

可以在 check_mode 下运行并返回更改状态预测,而无需修改目标,如果不受支持,则操作将被跳过。

diff_mode

支持: 完全支持

在差异模式下,将返回有关已更改内容(或可能需要在 check_mode 中更改的内容)的详细信息

平台

平台: posix

可以对其进行操作的目标操作系统/系列

safe_file_operations

支持: 完全支持

使用 Ansible 的严格文件操作函数来确保正确的权限并避免数据损坏

保管库

支持: 不支持

可以自动解密 Ansible 保管库文件

注释

注意

  • 在使用 with_* 循环时,请注意,如果您未设置唯一的标记,则块将在每次迭代时被覆盖。

  • 从 Ansible 2.3 开始,dest 选项已更改为 path 作为默认值,但 dest 仍然有效。

  • 选项 follow 已在 Ansible 2.5 中删除,因为此模块修改了文件的内容,因此 follow=no 没有意义。

  • 当一个文件中应处理多个块时,您必须为每个任务更改 marker

示例

# Before Ansible 2.3, option 'dest' or 'name' was used instead of 'path'
- name: Insert/Update "Match User" configuration block in /etc/ssh/sshd_config prepending and appending a new line
  ansible.builtin.blockinfile:
    path: /etc/ssh/sshd_config
    append_newline: true
    prepend_newline: true
    block: |
      Match User ansible-agent
      PasswordAuthentication no

- name: Insert/Update eth0 configuration stanza in /etc/network/interfaces
        (it might be better to copy files into /etc/network/interfaces.d/)
  ansible.builtin.blockinfile:
    path: /etc/network/interfaces
    block: |
      iface eth0 inet static
          address 192.0.2.23
          netmask 255.255.255.0

- name: Insert/Update configuration using a local file and validate it
  ansible.builtin.blockinfile:
    block: "{{ lookup('ansible.builtin.file', './local/sshd_config') }}"
    path: /etc/ssh/sshd_config
    backup: yes
    validate: /usr/sbin/sshd -T -f %s

- name: Insert/Update HTML surrounded by custom markers after <body> line
  ansible.builtin.blockinfile:
    path: /var/www/html/index.html
    marker: "<!-- {mark} ANSIBLE MANAGED BLOCK -->"
    insertafter: "<body>"
    block: |
      <h1>Welcome to {{ ansible_hostname }}</h1>
      <p>Last updated on {{ ansible_date_time.iso8601 }}</p>

- name: Remove HTML as well as surrounding markers
  ansible.builtin.blockinfile:
    path: /var/www/html/index.html
    marker: "<!-- {mark} ANSIBLE MANAGED BLOCK -->"
    block: ""

- name: Add mappings to /etc/hosts
  ansible.builtin.blockinfile:
    path: /etc/hosts
    block: |
      {{ item.ip }} {{ item.name }}
    marker: "# {mark} ANSIBLE MANAGED BLOCK {{ item.name }}"
  loop:
    - { name: host1, ip: 10.10.1.10 }
    - { name: host2, ip: 10.10.1.11 }
    - { name: host3, ip: 10.10.1.12 }

- name: Search with a multiline search flags regex and if found insert after
  blockinfile:
    path: listener.ora
    block: "{{ listener_line | indent(width=8, first=True) }}"
    insertafter: '(?m)SID_LIST_LISTENER_DG =\n.*\(SID_LIST ='
    marker: "    <!-- {mark} ANSIBLE MANAGED BLOCK -->"

作者

  • Yaegashi Takeshi (@yaegashi)