Ansible Core 文档

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_begin` 和 `marker_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+rwx` 或 `u=rw,g=r,o=r`）。如果未指定 `mode` 并且目标文件系统对象不存在，则在为新创建的文件系统对象设置模式时，将使用系统上的默认 `umask`。如果未指定 `mode` 并且目标文件系统对象存在，则将使用现有文件系统对象的模式。指定 `mode` 是确保使用正确的权限创建文件系统对象的最佳方法。有关更多详细信息，请参阅 CVE-2020-1736。
owner 字符串	应该拥有该文件系统对象的用户的名称，就像提供给 `chown` 一样。如果未指定，它将使用当前用户，除非您是 root 用户，在这种情况下它可以保留之前的拥有者。指定数字用户名将被假定为用户 ID 而不是用户名。避免使用数字用户名以避免这种混淆。
path 别名：dest，destfile，name path / required	要修改的文件。在 Ansible 2.3 之前，此选项只能用作 `dest`、 `destfile` 和 `name`。
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` 部分。
state 字符串	块是否应该存在。选择 `"absent"` `"present"` ←（默认）
unsafe_writes 布尔值	影响何时使用原子操作来防止数据损坏或从目标文件系统对象读取不一致的数据。默认情况下，此模块使用原子操作来防止数据损坏或从目标文件系统对象读取不一致的数据，但有时系统配置或只是损坏的方式会阻止这种情况。一个例子是 docker 挂载的文件系统对象，它无法从容器内部进行原子更新，只能以不安全的方式写入。此选项允许 Ansible 在原子操作失败时回退到更新文件系统对象的不安全方法（但是，它不会强制 Ansible 执行不安全写入）。重要！不安全写入会受到竞争条件的影响，并可能导致数据损坏。选择 `false` ← (默认) `true`
validate 字符串	将更新后的文件复制到最终目的地之前要运行的验证命令。临时文件路径用于验证，通过 `%s` 传递，该路径必须像下面的示例中一样存在。此外，该命令是安全传递的，因此 shell 功能（如扩展和管道）将不起作用。有关如何处理比此选项提供的更复杂的验证的示例，请参阅处理复杂的验证。

属性 

属性	支持	描述
check_mode	支持：完整	可以在 check_mode 中运行并返回已更改的状态预测，而无需修改目标，如果不支持，则会跳过该操作。
diff_mode	支持：完整	在 diff 模式下，将返回有关已更改的内容（或可能需要在 check_mode 中更改的内容）的详细信息
platform	平台： posix	可以操作的目标操作系统/系列
safe_file_operations	支持：完整	使用 Ansible 严格的文件操作函数来确保正确的权限并避免数据损坏
vault	支持：无	可以自动解密 Ansible vault 文件

注释 

注意

当使用 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)

集合链接