copy

Содержание

copy#

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

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

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

При копировании можно установить права доступа, владельца и группу, даже если файл уже существует на целевой системе. Также возможно копирование части метаданных исходного объекта.
Для получения метаданных о файле или каталоге используйте модуль ansible.builtin.stat.
Для изменения метаданных используйте модуль ansible.builtin.file.
Для копирования файла с удаленного компьютера на локальный компьютер используйте модуль ansible.builtin.fetch.
Для копирования с возможностью подстановки переменных используйте модуль ansible.builtin.template.
Для копирования на компьютеры под управлением ОС Windows используйте модуль ansible.windows.win_copy.
Модуль ansible.builtin.copy не подходит для копирования каталогов, содержащих большое количество файлов (больше сотни).

Параметры#

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

attributes, attr#

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

man chattr

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

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

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

backup#

Создание резервной копии целевого файла перед заменой.

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

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

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

checksum#

Контрольная сумма SHA-1 передаваемого файла.

Используется для подтверждения успешного копирования файла.

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

content#

Альтернатива параметра src. Позволяет задать содержимое файла в значении этого параметра.

Работает только в том случае, если в значении параметра dest указан путь к файлу. Если файл не существует, он будет создан.

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

Использование переменных в параметре content приводит к непредсказуемым результатам. Для расширенного форматирования содержимого, в том числе с подстановкой значений переменных, используйте модуль ansible.builtin.template.

decrypt#

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

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

false – не расшифровывать файл;
true – расшифровывать файл.

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

dest#

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

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

Особенности поведения параметра:

если в значении параметра src указан каталог, то и в значении параметра dest тоже должен быть каталог;
если в значении параметра dest указан несуществующий путь, заканчивающийся на /, модуль создаст указанный каталог на удаленном узле;
если в значении параметра src указан каталог, на удаленном узле будет создан каталог, указанный в dest;
если в значении параметра dest указан относительный путь, начальный каталог определяется удаленным узлом;
если в значении параметров src и dest указаны пути к файлам, а целевой каталог не существует, задача завершится с ошибкой, так как в этом случае Ansible не создает структуру каталогов автоматически.

directory_mode#

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

Синтаксис допустимых значений соответствует значениям в параметре mode.

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

follow#

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

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

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

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

force#

Необходимость перезаписи файлов на управляемых узлах.

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

false – скопировать файл только если он отсутствует по указанному пути;
true – заменить файл, если его содержимое отличается от исходного.

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

group#

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

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

local_follow#

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

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

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

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

mode#

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

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

Восьмеричное число, например, 0644 или 0755. Обязательно указывать с ведущим нулем или в кавычках:
- 0644;
- '644'.
Если указать значение без кавычек или ведущего нуля, Ansible обработает его как десятичное число, что приведет к непредсказуемому результату.
Строковое значение, например, u=rw,g=r,o=r или u+rwx,g+rx,o=r.
Специальное значение preserve. При указании этого значения файл на удаленном узле получит те же права, что и исходный файл.

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

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

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

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

При рекурсивном копировании каталогов для задания прав доступа к ним используйте параметр directory_mode.

owner#

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

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

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

remote_src#

Местоположение источника, указанного в параметре src.

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

параметр поддерживает рекурсивное копирование каталогов;
remote_src=true работает только совместно с параметром modе=preserve;
механизмы автоматической расшифровки файла не будут работать, если remote_src=true.

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

false – поиск источника будет осуществляться на локальном узле;
true – поиск источника будет осуществляться на удаленном узле.

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

selevel#

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

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

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

serole#

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

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

setype#

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

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

seuser#

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

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

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

src#

Абсолютный или относительный путь к копируемому файлу или каталогу.

Особенности копирования каталогов:

каталоги копируются рекурсивно;
если путь к каталогу заканчивается на /, то копируется только его содержимое;
если путь к каталогу не заканчивается на /, то копируется и сам каталог, и его содержимое.

unsafe_writes#

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

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

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

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

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

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

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

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

validate#

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

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

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

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

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

backup_file – название файла резервной копии.

Условия: целевой файл был изменен и backup=true.
checksum – контрольная сумма SHA-1 после копирования.

Условия: успешное выполнение задачи.
dest – путь к файлу или каталогу на управляемом узле.

Условия: успешное выполнение задачи.
gid – идентификатор группы-владельца (GID) объекта файловой системы на управляемом узле.

Условия: успешное выполнение задачи.
group – название группы-владельца после выполнения задачи.

Условия: успешное выполнение задачи.
md5sum – контрольная сумма MD5 после копирования.

Условия: если поддерживается на целевом узле.
mode – режим доступа к файлу или каталогу в восьмеричной системе счисления.

Условия: успешное выполнение задачи.
owner – название учетной записи пользователя-владельца объекта файловой системы на управляемом узле.

Условия: успешное выполнение задачи.
size – размер файла или каталога в байтах.

Условия: успешное выполнение задачи.
src – путь к исходному файлу или каталогу.

Условия: изменение файла или каталога.
state – состояние объекта файловой системы на управляемом узле после выполнения задачи.

Условия: успешное выполнение задачи.
uid – идентификатор пользователя-владельца (UID) объекта файловой системы после выполнения задачи.

Условия: успешное выполнение задачи.

Атрибуты#

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

Атрибут	Описание
`action`	Модуль имеет соответствующее расширение действия (action plugin), которое выполняет работу на управляющем узле.
`async`	Модуль не поддерживает асинхронное выполнение.
`bypass_host_loop`	Модуль не поддерживает глобальное выполнение задачи.
`check_mode`	Модуль работает в режиме проверки (`check_mode`) в полном объеме. Режим проверки позволяет узнать, что произойдет при выполнении указанных действий с объектами файловой системы.
`diff_mode`	Модуль поддерживает режим сравнения (`diff_mode`) в полном объеме и возвращает подробную информацию о сделанных изменениях.
`platform`	Модуль поддерживает только POSIX-совместимые ОС.
`safe_file_operations`	Модуль использует строгие механизмы Ansible для работы с файлами чтобы обеспечить правильные разрешения и предотвратить повреждение данных.
`vault`	Модуль поддерживает автоматическую расшифровку исходных файлов с использованием хранилища секретов.

Примеры#

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

Копирование файла с указанием владельца и прав доступа в числовом виде#

Следующий пример описывает копирование файла astra-automation.list с указанием владельца root, группы root и прав доступа в числовом виде 0644:

---
- name: Copy file with owner and permissions
  ansible.builtin.copy:
    src: /common/astra-automation.list
    dest: /etc/apt/sources.list.d/astra-automation.list
    owner: root
    group: root
    mode: '0644'

Копирование файла с указанием владельца и прав доступа в символьном виде#

Следующий пример описывает копирование файла astra-automation.list с указанием владельца root, группы root и прав доступа в символьном виде u=rw,g=r,o=r:

---
- name: Copy file with owner and permission, using symbolic representation
  ansible.builtin.copy:
    src: /common/astra-automation.list
    dest: /etc/apt/sources.list.d/astra-automation.list
    owner: root
    group: root
    mode: u=rw,g=r,o=r

Копирование файла с созданием резервной копии#

Следующий пример описывает копирование файла astra-automation.list с созданием резервной копии:

---
- name: Copy a new "astra-automation.list" file into place, backing up the original if it differs from the copied version
  ansible.builtin.copy:
    src: /common/astra-automation.list
    dest: /etc/apt/sources.list.d/astra-automation.list
    owner: root
    group: root
    mode: '0644'
    backup: true

Копирование файла с выполнением проверки#

Следующий пример описывает копирование файла sudoers с выполнением проверки синтаксиса файла:

---
- name: Copy a new "sudoers" file into place, after passing validation with visudo
  ansible.builtin.copy:
    src: /configs/sudoers
    dest: /etc/sudoers
    validate: /usr/sbin/visudo -csf %s

Копирование файла с удаленного узла на тот же узел#

Следующий пример описывает копирование файла sudoers, находящегося на удаленном узле, в тот же каталог, но с новым именем:

---
- name: Copy a "sudoers" file on the remote machine for editing
  ansible.builtin.copy:
    src: /etc/sudoers
    dest: /etc/sudoers.edit
    remote_src: yes
    validate: /usr/sbin/visudo -csf %s

Создание нового файла с содержимым, указанным в задаче#

Следующий пример описывает создание файла info.txt на удаленном узле с содержимым, указанным в параметре content:

---
- name: Copy using inline content
  ansible.builtin.copy:
    content: '# This is a simple info file created by Ansible.'
    dest: /tmp/info.txt