ansible.builtin.copy 模块 – 将文件复制到远程位置

注意

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

概要 

ansible.builtin.copy 模块将文件或目录结构从本地或远程机器复制到远程机器上的某个位置。即使文件或目录已存在于目标系统上，也可以设置文件系统元信息（权限、所有权等）。可以根据请求复制某些元信息。
使用 ansible.builtin.stat 模块获取元信息。
使用 ansible.builtin.file 模块设置元信息。
使用 ansible.builtin.fetch 模块将文件从远程位置复制到本地计算机。
如果您需要在复制的文件中进行变量插值，请使用 ansible.builtin.template 模块。使用 content 参数中的变量会产生不可预测的结果。
对于 Windows 目标，请改用 ansible.windows.win_copy 模块。

注意

此模块具有相应的操作插件。

参数 

参数	注释
attributes 别名：attr 字符串	结果文件系统对象应具有的属性。要获取支持的标志，请查看目标系统上 `chattr` 的手册页。此字符串应按与 `lsattr` 显示的顺序相同的顺序包含属性。默认情况下假定使用 `=` 运算符，否则需要在字符串中包含 `+` 或 `-` 运算符。
backup 布尔值	创建包含时间戳信息的后备文件，以便在您以某种方式错误地覆盖文件时可以取回原始文件。选项 `false` ← (默认) `true`
checksum 字符串	正在传输的文件的 SHA1 校验和。用于验证文件的复制是否成功。如果未提供此参数，ansible 将使用 src 文件的本地计算校验和。
content 字符串	当用作 `src` 的替代时，会将文件的內容直接设置为指定的值。仅当 `dest` 为文件时才有效。如果文件不存在，则创建该文件。对于高级格式或如果 `content` 包含变量，请使用 ansible.builtin.template 模块。
decrypt 布尔值	此选项控制使用 vault 自动解密源文件。选项 `false` `true` ← (默认)
dest 路径 / 必需	应将文件复制到的远程绝对路径。如果 `src` 是目录，则此路径也必须是目录。如果 `dest` 是不存在的路径，并且 `dest` 以 `/` 结尾或 `src` 是目录，则创建 `dest`。如果 `dest` 是相对路径，则起始目录由远程主机确定。如果 `src` 和 `dest` 都是文件，则不会创建 `dest` 的父目录，如果父目录不存在，则任务失败。
directory_mode 任何	将新创建的目录的访问权限设置为给定的模式。现有目录的权限不会更改。有关接受值的语法的详细信息，请参阅 `mode`。如果未设置此参数，则目标系统的默认值决定权限。
follow 布尔值	此标志表示如果目标中存在文件系统链接，则应跟随这些链接。选项 `false` ← (默认) `true`
force 布尔值	影响是否必须始终替换远程文件。如果为 `true`，则当内容与源内容不同时，将替换远程文件。如果为 `false`，则仅当目标不存在时才传输文件。选项 `false` `true` ← (默认)
group 字符串	应拥有文件系统对象的组的名称，就像提供给 `chown` 一样。如果未指定，则使用当前用户的当前组，除非您是 root 用户，在这种情况下，它可以保留以前的所有权。
local_follow 布尔值	此标志表示如果源树中存在文件系统链接，则应跟随这些链接。选项 `false` `true`
mode 任何	目标文件或目录的权限。对于习惯使用`/usr/bin/chmod`的用户来说，请记住模式实际上是八进制数。您必须在前面添加一个前导零，以便 Ansible 的 YAML 解析器知道它是一个八进制数（例如 `0644` 或 `01777`），或者将其用引号括起来（例如 `'644'` 或 `'1777'`），以便 Ansible 接收到一个字符串并可以将其自身从字符串转换为数字。如果不遵循这些规则之一而向 Ansible 提供数字，则最终将得到一个十进制数，这将导致意外的结果。从 Ansible 1.8 开始，模式可以指定为符号模式（例如，`u+rwx` 或 `u=rw,g=r,o=r`）。从 Ansible 2.3 开始，模式也可以是特殊字符串 `preserve`。 `preserve` 表示文件将被赋予与源文件相同的权限。在进行递归复制时，另请参阅 `directory_mode`。如果未指定 `mode` 且目标文件不存在，则在设置新创建文件的模式时将使用系统上的默认 `umask`。如果未指定 `mode` 且目标文件存在，则将使用现有文件的模式。指定 `mode` 是确保文件以正确的权限创建的最佳方法。有关更多详细信息，请参阅 CVE-2020-1736。
owner 字符串	应拥有文件系统对象的用户名称，如同提供给 `chown` 一样。如果未指定，则使用当前用户，除非您是 root 用户，在这种情况下，它可以保留以前的拥有权。指定数字用户名将被视为用户 ID 而不是用户名。避免使用数字用户名以避免此混淆。
remote_src 布尔值	影响 `src` 是否需要传输或是否已远程存在。如果为 `false`，它将在控制器节点上搜索 `src`。如果为 `true`，它将在被管理的（远程）节点上搜索 `src`。 `remote_src` 从 2.8 版开始支持递归复制。 `remote_src` 仅在 2.6 版及更高版本中与 `mode=preserve` 一起使用。当 `remote_src=yes` 时，文件的自动解密不起作用。选项 `false` ← (默认) `true`
selevel 字符串	SELinux 文件系统对象上下文的级别部分。这是 MLS/MCS 属性，有时称为 `range`。当设置为 `_default` 时，它将使用策略的 `level` 部分（如果可用）。
serole 字符串	SELinux 文件系统对象上下文的角色部分。当设置为 `_default` 时，它将使用策略的 `role` 部分（如果可用）。
setype 字符串	SELinux 文件系统对象上下文的类型部分。当设置为 `_default` 时，它将使用策略的 `type` 部分（如果可用）。
seuser 字符串	SELinux 文件系统对象上下文的用户部分。默认情况下，它使用 `system` 策略（如果适用）。当设置为 `_default` 时，它将使用策略的 `user` 部分（如果可用）。
src path	要复制到远程服务器的文件的本地路径。这可以是绝对路径或相对路径。如果路径是一个目录，则会递归复制。在这种情况下，如果路径以 `/` 结尾，则仅将该目录内部的内容复制到目标。否则，如果它不以 `/` 结尾，则会复制目录本身及其所有内容。此行为类似于 `rsync` 命令行工具。
unsafe_writes 布尔值	影响何时使用原子操作来防止数据损坏或目标文件系统对象的不一致读取。默认情况下，此模块使用原子操作来防止数据损坏或目标文件系统对象的不一致读取，但有时系统会以阻止此操作的方式进行配置或损坏。一个例子是 docker 挂载的文件系统对象，无法从容器内部以原子方式更新，只能以不安全的方式写入。此选项允许 Ansible 在原子操作失败时回退到不安全的文件系统对象更新方法（但是，它不会强制 Ansible 执行不安全写入）。重要！不安全写入容易出现竞争条件，并可能导致数据损坏。选项 `false` ← (默认) `true`
validate 字符串	在将更新后的文件复制到最终目标之前运行的验证命令。使用临时文件路径进行验证，通过 `%s` 传递，该路径必须存在，如下面的示例所示。此外，命令以安全方式传递，因此 shell 功能（如扩展和管道）将不起作用。有关如何处理比此选项提供的更复杂的验证的示例，请参阅处理复杂验证。

属性 

属性	支持	描述
action	支持：完全支持	指示这具有相应的 action 插件，因此某些选项部分可以在控制器上执行
async	支持：不支持	支持与 `async` 关键字一起使用
bypass_host_loop	支持：不支持	强制执行不按主机执行的“全局”任务，这将绕过按主机进行的模板化以及串行、节流和其他循环方面的考虑条件将像使用 `run_once` 一样工作，使用的变量将来自第一个可用的主机此操作在非锁步策略之外将无法正常工作
check_mode	支持：完全支持	可以在 check_mode 下运行并返回更改状态预测，而无需修改目标，如果不支持，则将跳过该操作。
diff_mode	支持：完全支持	将在差异模式下返回有关已更改内容（或可能需要在 check_mode 下更改的内容）的详细信息
platform	平台： posix	可以对其进行操作的目标操作系统/系列
safe_file_operations	支持：完全支持	使用 Ansible 的严格文件操作功能来确保正确的权限并避免数据损坏
vault	支持：完全支持	可以自动解密 Ansible 保库文件

备注 

注意

ansible.builtin.copy 模块的递归复制功能无法扩展到大量（>数百个）文件。

另请参阅 

另请参阅

ansible.builtin.assemble: 从片段组装配置文件。
ansible.builtin.fetch: 从远程节点获取文件。
ansible.builtin.file: 管理文件和文件属性。
ansible.builtin.template: 将文件模板化到目标主机。
ansible.posix.synchronize: ansible.posix.synchronize 模块的官方文档。
ansible.windows.win_copy: ansible.windows.win_copy 模块的官方文档。

示例 

- name: Copy file with owner and permissions
  ansible.builtin.copy:
    src: /srv/myfiles/foo.conf
    dest: /etc/foo.conf
    owner: foo
    group: foo
    mode: '0644'

- name: Copy file with owner and permission, using symbolic representation
  ansible.builtin.copy:
    src: /srv/myfiles/foo.conf
    dest: /etc/foo.conf
    owner: foo
    group: foo
    mode: u=rw,g=r,o=r

- name: Another symbolic mode example, adding some permissions and removing others
  ansible.builtin.copy:
    src: /srv/myfiles/foo.conf
    dest: /etc/foo.conf
    owner: foo
    group: foo
    mode: u+rw,g-wx,o-rwx

- name: Copy a new "ntp.conf" file into place, backing up the original if it differs from the copied version
  ansible.builtin.copy:
    src: /mine/ntp.conf
    dest: /etc/ntp.conf
    owner: root
    group: root
    mode: '0644'
    backup: yes

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

- 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

- name: Copy using inline content
  ansible.builtin.copy:
    content: '# This file was moved to /etc/other.conf'
    dest: /etc/mine.conf

- name: If follow=yes, /path/to/file will be overwritten by contents of foo.conf
  ansible.builtin.copy:
    src: /etc/foo.conf
    dest: /path/to/link  # link to /path/to/file
    follow: yes

- name: If follow=no, /path/to/link will become a file and be overwritten by contents of foo.conf
  ansible.builtin.copy:
    src: /etc/foo.conf
    dest: /path/to/link  # link to /path/to/file
    follow: no

返回值 

常见的返回值已在此处记录，以下是此模块独有的字段

键	描述
backup_file 字符串	创建的备份文件名称。返回：已更改，如果 backup=yes 示例： `"/path/to/file.txt.2015-02-12@22:09~"`
checksum 字符串	运行复制后文件的 SHA1 校验和。返回：成功示例： `"6e642bb8dd5c2e027bf21dd923337cbb4214f827"`
dest 字符串	目标文件/路径。返回：成功示例： `"/path/to/file.txt"`
gid 整数	执行后文件的组 ID。返回：成功示例： `100`
group 字符串	执行后文件的组。返回：成功示例： `"httpd"`
md5sum 字符串	运行复制后文件的 MD5 校验和。返回：如果支持示例： `"2a5aeecc61dc98c4d780b14b330e3282"`
mode 字符串	执行后目标的权限。返回：成功示例： `"0644"`
owner 字符串	执行后文件的拥有者。返回：成功示例： `"httpd"`
size 整数	执行后目标的大小。返回：成功示例： `1220`
src 字符串	目标机器上复制操作使用的源文件。返回： changed 示例： `"/home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source"`
状态字符串	执行后目标的状态。返回：成功示例： `"file"`
uid 整数	执行后文件的拥有者ID。返回：成功示例： `100`

作者

Ansible核心团队
Michael DeHaan