knowledge/technology/tools/Ansible/modules/ansible.builtin.copy.md

ansible.builtin.copy

The copy module copies a file from the local or remote machine to a location on the remote machine.

Parameter

Parameter	Type	Default	Description
attributes	string	-	The attributes the resulting filesystem object should have. To get supported flags look at the man page for chattr on the target system. The = operator is assumed as default, otherwise + or - operators need to be included in the string.
backup	boolean	false	Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
checksum	string	-	SHA1 checksum of the file being transferred. Used to validate that the copy of the file was successful. If this is not provided, ansible will use the local calculated checksum of the src file.
content	string	-	When used instead of src, sets the contents of a file directly to the specified value. Works only when dest is a file. Creates the file if it does not exist. For advanced formatting or if content contains a variable, use the ansible.builtin.template module.
decrypt	boolean	true	This option controls the autodecryption of source files using vault.
dest	path / required	-	Remote absolute path where the file should be copied to. If src is a directory, this must be a directory too. If dest is a non-existent path and if either dest ends with “/” or src is a directory, dest is created. If dest is a relative path, the starting directory is determined by the remote host. If src and dest are files, the parent directory of dest is not created and the task fails if it does not already exist.
follow	boolean	false	This flag indicates that filesystem links in the destination, if they exist, should be followed.
force	boolean	true	Influence whether the remote file must always be replaced. If true, the remote file will be replaced when contents are different than the source. If false, the file will only be transferred if the destination does not exist.
group	string	-	Name of the group that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership.
local_follow	boolean	true	This flag indicates that filesystem links in the source tree, if they exist, should be followed.
mode	any	-	The permissions the resulting filesystem object should have. For those used to /usr/bin/chmod remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal numbers (for example, '644' or '1777') so Ansible receives a string and can do its own conversion from string into number. Adding a leading zero (for example, 0755) works sometimes, but can fail in loops and some other circumstances. Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, u+rwx or u=rw,g=r,o=r). If mode is not specified and the destination filesystem object does not exist, the default umask on the system will be used when setting the mode for the newly created filesystem object. If mode is not specified and the destination filesystem object does exist, the mode of the existing filesystem object will be used.
owner	string	-	Name of the user that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion.
src	path	-	Local path to a file to copy to the remote server. This can be absolute or relative. If path is a directory, it is copied recursively. In this case, if path ends with “/”, only inside contents of that directory are copied to destination. Otherwise, if it does not end with “/”, the directory itself with all contents is copied. This behavior is similar to the rsync command line tool.
validate	string	-	The validation command to run before copying the updated file into the final destination. A temporary file path is used to validate, passed in through ‘%s’ which must be present as in the examples below. Also, the command is passed securely so shell features such as expansion and pipes will not work.

Return Values

Value	Type	When	Description
backup_file	string	changed and if backup=yes	Name of backup file created
checksum	string	success	SHA1 checksum of the file after running copy.
dest	string	success	Destination file/path.
gid	integer	success	Group id of the file, after execution.
group	string	success	Group of the file, after execution.
md5sum	string	when supported	MD5 checksum of the file after running copy.
mode	string	success	Permissions of the target, after execution.
owner	string	success	Owner of the file, after execution.
size	integer	success	Size of the target, after execution.
uid	integer	success	Owner id of the file, after execution.

Examples

- 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