file

Содержание

file#

Модуль ansible.builtin.file управляет атрибутами файлов, каталогов и символических ссылок.

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

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

модуль ansible.builtin.file поддерживает те же параметры SELinux и управления атрибутами файлов, что и модули ansible.builtin.copy, ansible.builtin.template и ansible.builtin.assemble;
для управления файлами, каталогами и символическими ссылками на узлах под управлением ОС Windows используйте модуль ansible.windows.win_file.

Параметры#

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

access_time#

Время последнего доступа к файлу.

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

preserve – не изменять время доступа. Используется по умолчанию если параметру state присвоено одно из значений: file, directory, link, hard.
now – установить текущее системное время. Используется по умолчанию если state=touch.
YYYYMMDDHHMM.SS – конкретное время, например, 202506012030.00 (1 июня 2025 года, 20 часов 30 минут 00 секунд).

access_time_format#

Формат времени для параметра access_time.

Основано на стандартном формате Python (см. документацию time.strftime).

Значение по умолчанию: "%Y%m%d%H%M.%S".

attributes, attr#

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

man chattr

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

= – установить строго указанный набор атрибутов;
+ – добавить указанные атрибуты к существующим;
- – удалить указанные атрибуты из существующих.

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

follow#

Порядок обработки символических ссылок.

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

Если follow=true и state=link, то параметр mode будет применяться не к ссылке, а к файлу, на который она указывает (src).
При создании ссылки на несуществующий объект файловой системы установите follow=false, чтобы избежать предупреждения о проблемах с разрешениями. Предупреждающее сообщение добавляется для информирования пользователя о том, что Ansible не может установить разрешения для несуществующего объекта файловой системы.

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

false – операции применяются к символической ссылке;
true – Ansible переходит по ссылке и применяет операции к содержимому, на которое она указывает.

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

force#

Принудительное создание ссылки в двух случаях:

если ссылка символическая и исходный файл не существует (но появится позже);
если целевой объект существует и является файлом (в этом случае существующий файл по пути path будет удален, и вместо него будет создана ссылка на файл, указанный в параметре src).

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

false – не создавать ссылку;
true – создать ссылку.

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

group#

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

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

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

mode#

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

Значения могут быть следующих типов:

Восьмеричное число, например, 0644 или 0755. Обязательно указывать с ведущим нулем или в кавычках:
- 0644;
- '644'.
Если указать 644, Ansible воспримет это как десятичное число, что приведет к непредсказуемому результату.

Примечание

Добавление ведущего нуля иногда работает, но может дать сбой в циклах и некоторых других обстоятельствах.
Символьное значение, например, u=rw,g=r,o=r или u+rwx,g+rx,o=r.
Специальное значение preserve. При указании этого значения режим доступа к объекту файловой системы не изменяется.

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

если файл или каталог на управляемом узле уже существует, его режим доступа сохраняется;
если объект создается заново и параметр mode не задан, режим доступа определяется системным значением umask на удаленном узле.

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

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

modification_time#

Время последнего изменения файла.

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

preserve – не изменять время. Используется по умолчанию если параметру state присвоено одно из значений: file, directory, link, hard.
now – установить текущее системное время. Используется по умолчанию если state=touch.
YYYYMMDDHHMM.SS – конкретное время, например, 202506012030.00 (1 июня 2025 года, 20 часов 30 минут 00 секунд).

modification_time_format#

Формат времени для параметра modification_time.

Основано на стандартном формате Python (см. документацию time.strftime).

Значение по умолчанию: "%Y%m%d%H%M.%S".

owner#

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

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

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

path, dest, name#

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

Путь к объекту файловой системы на управляемом узле.

recurse#

Рекурсивная установка указанных атрибутов для содержимого каталога.

Применяется только если state=directory.

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

false – устанавливать атрибуты только каталогу;
true – установить атрибуты на каталог и его содержимое.

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

selevel#

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

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

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

serole#

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

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

setype#

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

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

seuser#

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

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

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

src#

Путь к файлу, на который будет указывать ссылка.

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

применяется только если state=link или state=hard;
при state=link допускается указание несуществующего пути;
относительные пути интерпретируются относительно целевого пути (path), что аналогично поведению команды ln -s SRC DEST.

state#

Желаемое состояние объекта файловой системы.

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

absent – удалить объект файловой системы. Если при удалении каталога задан параметр diff, в секции вывода path_contents будет указан список удаленных файлов и каталогов.
directory – создать промежуточные подкаталоги, если они не существуют.
file – изменить атрибуты и режим доступа существующего файла.

Особенности работы:
- если не указано других параметров, возвращает текущее значение параметра path;
- если указаны другие параметры (например, mode), и файл существует, он будет изменен;
- если файл не существует – он не будет создан.
Примечание

Если вы хотите создать файл, установите значение touch или используйте модуль ansible.builtin.copy или ansible.builtin.template.
hard – создать или изменить жесткую ссылку.
link – создать или изменить символическую ссылку.
touch – создать пустой файл, если он не существует. Если файл или каталог существует, обновить время последнего доступа и изменения (аналогично тому, как работает touch в командной строке).

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

directory при recurse=true;
file во всех остальных случаях.

unsafe_writes#

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

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

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

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

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

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

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

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

Возвращаемые значения#

В этом списке указаны только возвращаемые значения, специфичные для модуля ansible.builtin.file.

dest – файл или путь назначения, который был передан с помощью параметра path.

Условия: параметр state установлен в значение touch, hard или link.
path – файл или путь назначения, который был передан с помощью параметра path.

Условия: параметр state установлен в значение absent, directory или file.

Атрибуты#

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

Атрибут	Описание
`check_mode`	Модуль работает в режиме проверки (`check_mode`) в полном объеме.
`diff_mode`	Модуль частично поддерживает режим сравнения (`diff_mode`) и показывает только изменение атрибутов и режима доступа. Изменения содержимого файлов не отображаются.
`platform`	Модуль поддерживает только POSIX-совместимые ОС.

Примеры#

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

Изменение атрибутов файла#

Следующий пример демонстрирует изменение владельцев и режима доступа к файлу:

---
- name: Change file ownership, group and permissions
  ansible.builtin.file:
    path: /etc/example_directory/example_file
    owner: root
    group: root
    mode: "0644"

Создание ссылки#

Следующий пример демонстрирует создание символической ссылки /opt/log/example_link, указывающей на файл /var/log/example_file:

---
- name: Create a symbolic link
  ansible.builtin.file:
    src: /var/log/example_file
    dest: /opt/log/example_link
    owner: root
    group: adm
    state: link

Изменение прав доступа файла#

Следующий пример демонстрирует изменение режима доступа к файлу /etc/example_file:

---
- name: Touch the same file, but add/remove some permissions
  ansible.builtin.file:
    path: /etc/example_file
    state: touch
    mode: u+rw,g-wx,o-rwx

Создание каталога#

Следующий пример демонстрирует создание каталога /etc/example_directory/:

---
- name: Create a directory if it does not exist
  ansible.builtin.file:
    path: /etc/example_directory
    state: directory
    mode: "0755"

Обновление времени последнего изменения файла#

Следующий пример демонстрирует обновление времени последнего изменения файла /etc/example_file:

---
- name: Update modification time of given file
  ansible.builtin.file:
    path: /etc/example_file
    state: file
    modification_time: now

Установка времени последнего доступа#

Следующий пример демонстрирует установку времени последнего доступа с использованием фильтра ansible.builtin.strftime:

---
- name: Set access time based on seconds from epoch value
  ansible.builtin.file:
    path: /etc/example_file
    state: file
    access_time: '{{ "%Y%m%d%H%M.%S" | ansible.builtin.strftime(seconds=0) }}'

Удаление файла#

Следующий пример демонстрирует удаление файла /etc/example_file:

---
- name: Delete file
  ansible.builtin.file:
    path: /etc/example_file
    state: absent