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 文件系统对象上下文的角色部分。

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

setype

字符串

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

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

seuser

字符串

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

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

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

src

path

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

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

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

支持：完全支持

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

platform

平台： posix

可以操作的目标操作系统/系列

safe_file_operations

支持：完全支持

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

vault

支持：完全支持

可以自动解密 Ansible 保险库文件

注释

注意

另请参阅

另请参阅

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

字符串

运行 copy 后的文件的 SHA1 校验和。

返回： 成功

示例： "6e642bb8dd5c2e027bf21dd923337cbb4214f827"

dest

字符串

目标文件/路径。

返回： 成功

示例： "/path/to/file.txt"

gid

整数

执行后的文件组 ID。

返回： 成功

示例： 100

group

字符串

执行后的文件组。

返回： 成功

示例： "httpd"

md5sum

字符串

运行 copy 后的文件的 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