blockinfile

blockinfile#

Модуль ansible.builtin.blockinfile используется для вставки, обновления или удаления многострочного текстового блока в файле. Этот блок заключен между маркерными строками, что позволяет легко найти и повторно использовать его.

Дополнительно модуль может изменить атрибуты и режим доступа к файлу, а также создать его резервную копию перед заменой.

Особенности работы#

Особенности использования модуля ansible.builtin.blockinfile:

  • при использовании циклов (loop) обязательно задавайте уникальные маркеры для каждого элемента, иначе блоки будут перезаписываться;

  • при использовании модуля несколько раз для вставки различных блоков в один файл задайте уникальные маркеры для каждого блока с помощью параметра marker.

Параметры#

Модуль принимает следующие параметры:

attributes, attr#

Изменение атрибутов файла, в который вставляется блок. Чтобы узнать о поддерживаемых атрибутах, обратитесь к руководству chattr в целевой системе:

man chattr

Этот параметр представляет собой строку, содержащую атрибуты в порядке, принятом в выводе команды lsattr на целевой системе. Строка также может включать один из следующих операторов:

  • = – установить строго указанный набор атрибутов;

  • + – добавить указанные атрибуты к существующим;

  • - – удалить указанные атрибуты из существующих.

Если оператор не указан, используется оператор =. Это значит, что будут сброшены все установленные ранее атрибуты, кроме явно указанных в строке.

backup#

Создание резервной копии файла, указанного в path, включая метку времени.

Возможные значения:

  • false – не создавать резервную копию;

  • true – создать резервную копию и только потом заменить существующий файл на отредактированный модулем.

Значение по умолчанию: false.

block, content#

Текст, который будет вставлен между маркерными строками.

Если значение не задано или указана пустая строка, то блок будет удален. Эквивалентно state=absent.

Значение по умолчанию: "" (пустая строка).

create#

Создание файла, если он не существует.

Возможные значения:

  • false – не создавать файл. Если файл отсутствует, работа модуля завершится без ошибок и изменений.

  • true – создать файл.

Значение по умолчанию: false.

group#

Название группы, которой будет принадлежать файл. Параметр работает как утилита chown.

Если значение не задано, используется основная (primary) группа пользователя, от имени которого выполняется задача. При выполнении задачи с привилегиями root предыдущая группа-владелец может быть сохранена.

insertafter#

Регулярное выражение, определяющее куда будет вставлен блок, если в файле нет маркеров. Блок вставится после последнего совпадения с регулярным выражением.

Если совпадений не найдено, используется специальное значение EOF. При значении EOF блок вставляется в конец файла.

Наличие флага многострочности (?m) в регулярном выражении определяет, будет ли поиск выполняться построчно или с использованием нескольких строк.

insertbefore#

Регулярное выражение, определяющее куда будет вставлен блок, если в файле нет маркеров. Блок вставится перед последним совпадением с регулярным выражением.

Если совпадений не найдено, блок будет вставлен в конец файла.

При значении BOF блок вставляется в начало файла.

Наличие флага многострочности (?m) в регулярном выражении определяет, будет ли поиск выполняться построчно или с использованием нескольких строк.

marker#

Шаблон строки, которая используется для создания маркерных строк, окружающих вставляемый блок в файле.

Содержит переменную mark, которая будет заменена на значение из параметра marker_begin или marker_end.

Использование собственного маркера без переменной mark может привести к тому, что модуль будет вставлять блок повторно при последующих запусках сценария, потому что он не найдет существующий маркер.

Параметр не поддерживает многострочные маркеры. Если использовать маркер из нескольких строк, это приведет к повторному добавлению блока при каждом запуске, как и при отсутствии переменной mark.

Примечание

Модуль автоматически добавляет символ новой строки после маркера.

Значение по умолчанию: # {mark} ANSIBLE MANAGED BLOCK.

marker_begin#

Текст, вставляемый вместо переменной mark в начало открывающей маркерной строки.

Значение по умолчанию: BEGIN.

marker_end#

Текст, вставляемый вместо переменной mark в начало закрывающей маркерной строки.

Значение по умолчанию: END.

mode#

Режим доступа к файлу.

Поддерживаемые форматы значения:

  • Восьмеричное число, например, 0644 или 0755. Обязательно указывать с ведущим нулем или в кавычках:

    • 0644;

    • '644'.

    Если указать значение без кавычек или ведущего нуля, Ansible обработает его как десятичное число, что приведет к непредсказуемому результату.

  • Строковое значение, например, u=rw,g=r,o=r или u+rwx,g+rx,o=r.

Поведение по умолчанию:

  • если файл уже существует, режим доступа сохраняется;

  • если файл не существует, режим доступа определяется системным значением umask на управляемом узле.

Предупреждение

Рекомендуется всегда явно задавать значение параметра mode, чтобы избежать назначения небезопасных или непредсказуемых режимов доступа. См. описание уязвимости CVE-2020-1736.

owner#

Название учетной записи пользователя-владельца файла. Параметр работает как утилита chown.

Если значение параметра не указано, владельцем становится активный пользователь. При выполнении задачи с привилегиями root предыдущий владелец будет сохранен.

Если используется числовое значение, владельцем становится пользователь с указанным идентификатором. Во избежание непредсказуемых назначений избегайте числовых значений.

path, dest, destfile, name#

Обязательный параметр.

Полный путь к изменяемому файлу.

selevel#

Уровень изменяемого файла в контексте безопасности SELinux.

Представляет собой MLS/MCS-атрибут, также известный как range, который задает уровень доступа к объекту в системе с включенным SELinux.

Если установлено значение _default, будет использован уровень по умолчанию из политики SELinux для данного файла (если такая политика определена).

serole#

Роль изменяемого файла в контексте безопасности SELinux.

Если установлено значение _default, будет использована роль по умолчанию из политики SELinux для данного файла (если такая политика определена).

setype#

Тип изменяемого файла в контексте безопасности SELinux.

Если установлено значение _default, будет использован тип по умолчанию из политики SELinux для данного файла (если такая политика определена).

seuser#

Пользователь изменяемого файла в контексте безопасности SELinux.

Если значение не указано, используется системная политика определения пользователя.

Если установлено значение _default, будет использован пользователь по умолчанию из политики SELinux для данного файла (если такая политика определена).

state#

Действие, которое необходимо сделать с блоком.

Возможные значения:

  • absent – удалить;

  • present – вставить или обновить.

Значение по умолчанию: present.

unsafe_writes#

Использование атомарной записи для предотвращения повреждения данных или несогласованного чтения целевого файлового объекта.

По умолчанию модуль использует атомарные операции записи, при которых данные сначала записываются во временный файл, а затем временный файл заменяет целевой. Это исключает возможность считывания неполных или поврежденных данных другим процессом во время записи.

На некоторых системах (например, при работе с томами Docker) атомарные операции могут быть недоступны или вызывать ошибки. В этом случае установка значения true позволяет Ansible выполнить небезопасную (неатомарную) запись напрямую в целевой файл.

Предупреждение

Небезопасная запись может привести к состоянию гонки и повреждению данных.

Возможные значения:

  • false – атомарные операции обязательны. При их невозможности задача завершится с ошибкой.

  • true – если атомарная запись невозможна, будет использован небезопасный способ записи.

Значение по умолчанию: false.

validate#

Шаблон команды для проверки корректности файла.

Путь к временному файлу, используемому для проверки, подставляется автоматически вместо последовательности символов %s, которая должна присутствовать в шаблоне. Если проверка проходит без ошибок, временный файл заменяет собой файл, указанный в path. В противном случае задача завершается ошибкой.

Команда проверки запускается безопасно, поэтому расширения оболочки и конвейеры (pipes) не будут работать.

Атрибуты#

Атрибуты определяют функции Ansible, которые может использовать модуль.

Атрибут

Описание

check_mode

Модуль работает в режиме проверки (check_mode) в полном объеме.

diff_mode

Модуль поддерживает режим сравнения (diff_mode) в полном объеме и возвращает подробную информацию о сделанных изменениях.

platform

Модуль поддерживает только POSIX-совместимые ОС.

safe_file_operations

Модуль использует строгие механизмы работы с файлами Ansible для обеспечения правильных разрешений и предотвращения повреждения данных.

vault

Модуль не поддерживает автоматическую расшифровку исходных файлов с использованием хранилища секретов.

Примеры#

Для изучения возможностей модуля ознакомьтесь с приведенными ниже примерами.

Вставка блока в sshd_config#

Следующий пример показывает добавление блока в файл /etc/ssh/sshd_config:

---
# ...
  tasks:
    - name: Inserting a block into a file sshd_config
      ansible.builtin.blockinfile:
        path: /etc/ssh/sshd_config
        block: |
          Match User ansible-agent
          PasswordAuthentication no

В результате выполнения задачи в файл /etc/ssh/sshd_config будет добавлен следующий блок:

# BEGIN ANSIBLE MANAGED BLOCK
Match User ansible-agent
PasswordAuthentication no
# END ANSIBLE MANAGED BLOCK

Вставка блока HTML#

Следующий пример показывает добавление блока HTML в файл /var/www/html/index.html после регулярного выражения <body>:

---
# ...
  tasks:
    - name: Inserting a HTML block
      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>

В результате выполнения задачи в файл /var/www/html/index.html будет добавлен следующий блок:

<!-- BEGIN ANSIBLE MANAGED BLOCK -->
<h1>Welcome to localhost</h1>
<p>Last updated on 2025-07-23T17:30:00+0000</p>
<!-- END ANSIBLE MANAGED BLOCK -->

Удаление блока#

Следующий пример показывает удаление блока из файла /var/www/html/index.html:

---
# ...
  tasks:
    - name: Deleting a block
      ansible.builtin.blockinfile:
        path: /var/www/html/index.html
        marker: "<!-- {mark} ANSIBLE MANAGED BLOCK -->"
        block: ""

Вставка нескольких блоков#

Следующий пример показывает добавление нескольких блоков в файл /etc/hosts:

---
# ...
  tasks:
    - name: Inserting multiple blocks
      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 }

В результате выполнения задачи в файл /etc/hosts будут добавлены следующие блоки:

# BEGIN ANSIBLE MANAGED BLOCK host1
10.10.1.10 host1
# END ANSIBLE MANAGED BLOCK host1

# BEGIN ANSIBLE MANAGED BLOCK host2
10.10.1.11 host2
# END ANSIBLE MANAGED BLOCK host2