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 字符串	生成的 filesystem 对象应具有的属性。要获取支持的标志，请查看目标系统上的 chattr 的手册页。此字符串应包含与 lsattr 显示的顺序相同的属性。默认情况下假设使用 `=` 运算符，否则需要在字符串中包含 `+` 或 `-` 运算符。
backup 布尔值	创建一个包含时间戳信息的备份文件，以便在您以某种方式错误地覆盖它时可以取回原始文件。选项 `false` ← （默认） `true`
checksum 字符串	正在传输的文件的 SHA1 校验和。用于验证文件副本是否成功。如果未提供此项，ansible 将使用 src 文件的本地计算校验和。
content 字符串	当代替 `src` 使用时，直接将文件的内容设置为指定的值。仅当 `dest` 是文件时才有效。如果文件不存在，则创建该文件。对于高级格式或 `content` 包含变量的情况，请使用 ansible.builtin.template 模块。
decrypt 布尔值	此选项控制使用 Vault 自动解密源文件。选项 `false` `true` ← （默认）
dest path / 必需	应将文件复制到的远程绝对路径。如果 `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`。从 2.8 版本开始，`remote_src` 支持递归复制。从 2.6 版本开始，`remote_src` 仅适用于 `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	支持：完全	表示它具有对应的操作插件，因此可以在控制器上执行某些选项部分
async	支持：无	支持与 `async` 关键字一起使用
bypass_host_loop	支持：无	强制执行不按主机执行的“全局”任务，这将绕过按主机模板和串行，限制和其他循环注意事项条件语句将像使用 `run_once` 一样工作，使用的变量将来自第一个可用的主机此操作通常不会在锁定步骤策略之外工作
check_mode	支持：完全	可以在 check_mode 中运行并返回更改状态预测，而无需修改目标，如果不支持，则会跳过该操作。
diff_mode	支持：完全	在差异模式下，将返回有关已更改（或在 check_mode 中可能需要更改）的内容的详细信息
platform	平台： posix	可以对其进行操作的目标操作系统/系列
safe_file_operations	支持：完全	使用 Ansible 严格的文件操作功能，以确保正确的权限并避免数据损坏
vault	支持：完全	可以自动解密 Ansible Vault 文件

备注 

注意

ansible.builtin.copy 模块的递归复制功能不适用于大量（>数百个）文件。

另请参阅 

另请参阅

ansible.builtin.assemble: 从片段组装配置文件。
ansible.builtin.fetch: 从远程节点提取文件。
ansible.builtin.file: 管理文件和文件属性。
ansible.builtin.template: 将文件模板化到目标主机。
ansible.posix.synchronize: rsync 的包装器，使 playbook 中的常见任务快速而轻松。
ansible.windows.win_copy: 将文件复制到 Windows 主机上的远程位置。

示例 

- 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 字符串	目标机器上用于复制的源文件。返回: 已更改示例: `"/home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source"`
state 字符串	执行后的目标状态。返回：成功示例: `"file"`
uid 整数	执行后的文件所有者 ID。返回：成功示例： `100`

作者

Ansible 核心团队
Michael DeHaan