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

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使不指定 集合关键字，您也可以使用简短的模块名称 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 文件系统对象上下文的 role 部分。

当设置为 _default 时，它将使用策略的 role 部分（如果可用）。

setype

字符串

SELinux 文件系统对象上下文的 type 部分。

当设置为 _default 时，它将使用策略的 type 部分（如果可用）。

seuser

字符串

SELinux 文件系统对象上下文的 user 部分。

默认情况下，它使用 system 策略（如果适用）。

当设置为 _default 时，它将使用策略的 user 部分（如果可用）。

src

path

要复制到远程服务器的文件的本地路径。

可以是绝对路径或相对路径。

如果路径是目录，则会递归复制。在这种情况下，如果路径以 / 结尾，则仅将该目录内部的内容复制到目标位置。否则，如果它不以 / 结尾，则将目录本身及其所有内容复制。此行为类似于 rsync 命令行工具。

unsafe_writes

布尔值

影响何时使用原子操作来防止数据损坏或目标文件系统对象的不一致读取。

默认情况下，此模块使用原子操作来防止数据损坏或目标文件系统对象的不一致读取，但有时系统会以阻止此操作的方式进行配置或损坏。一个例子是 docker 挂载的文件系统对象，它们不能从容器内部以原子方式更新，只能以不安全的方式写入。

此选项允许 Ansible 在原子操作失败时回退到不安全的文件系统对象更新方法（但是，它不会强制 Ansible 执行不安全的写入）。

重要！不安全的写入容易受到竞争条件的影响，并可能导致数据损坏。

选项

  • false ← (默认)

  • true

validate

字符串

在将更新后的文件复制到最终目标之前运行的验证命令。

使用临时文件路径进行验证，通过 %s 传递，它必须像以下示例中那样存在。

此外，该命令以安全方式传递，因此 shell 功能（如扩展和管道）将不起作用。

有关如何处理比此选项提供的更复杂的验证的示例，请参阅 处理复杂验证。

属性

属性

支持

描述

action

支持：完全支持

表示它具有相应的 action 插件，因此选项的某些部分可以在控制器上执行

async

支持：不支持

支持与 async 关键字一起使用

bypass_host_loop

支持：不支持

强制执行不按主机执行的“全局”任务，这将绕过按主机的模板化以及 serial、throttle 和其他循环考虑因素

条件将按使用 run_once 的方式工作，使用的变量将来自第一个可用的主机

此操作在非锁步策略之外通常无法正常工作

check_mode

支持：完全支持

可以在 check_mode 下运行并返回更改状态预测而无需修改目标，如果不受支持，则操作将被跳过。

diff_mode

支持：完全支持

将在差异模式下返回有关已更改内容（或可能需要在 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

字符串

创建的备份文件名称。

已返回：已更改且如果 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