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。

从 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 是目录，则会递归复制它。在这种情况下，如果 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

支持：完全

在 diff 模式下运行时，将返回有关已更改内容（或可能需要在 check_mode 中更改的内容）的详细信息

platform

平台： posix

可以对其进行操作的目标操作系统/系列

safe_file_operations

支持：完全

使用 Ansible 的严格文件操作功能来确保正确的权限并避免数据损坏

vault

支持：完全

可以自动解密 Ansible vault 文件

备注

注意

另请参阅

另请参阅

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

字符串

创建的备份文件的名称。

返回： changed 和如果 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"

大小

整数

执行后目标的大小。

返回： 成功

示例： 1220

src

字符串

用于在目标机器上进行复制的源文件。

返回： 已更改

示例： "/home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source"

状态

字符串

执行后目标的状态。

返回： 成功

示例： "file"

uid

整数

执行后文件的所有者 ID。

返回： 成功

示例： 100

作者

  • Ansible 核心团队

  • Michael DeHaan