Try SpotterCopy files to remote locations
| "added in version" historical of ansible.builtin"
Authors: Ansible Core Team, Michael DeHaan
This plugin has a corresponding action plugin.
pipInstall with pip install ansible-core==2.16.5
The M(ansible.builtin.copy) module copies a file or a directory structure from the local or remote machine to a location on the remote machine. File system meta-information (permissions, ownership, etc.) may be set, even when the file or directory already exists on the target system. Some meta-information may be copied on request.
Get meta-information with the M(ansible.builtin.stat) module.
Set meta-information with the M(ansible.builtin.file) module.
Use the M(ansible.builtin.fetch) module to copy files from remote locations to the local box.
If you need variable interpolation in copied files, use the M(ansible.builtin.template) module. Using a variable with the O(content) parameter produces unpredictable results.
For Windows targets, use the M(ansible.windows.win_copy) module instead.
- 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
src:
description:
- 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 C(rsync) command line tool.
type: path
dest:
description:
- Remote absolute path where the file should be copied to.
- If O(src) is a directory, this must be a directory too.
- If O(dest) is a non-existent path and if either O(dest) ends with "/" or O(src)
is a directory, O(dest) is created.
- If O(dest) is a relative path, the starting directory is determined by the remote
host.
- If O(src) and O(dest) are files, the parent directory of O(dest) is not created
and the task fails if it does not already exist.
required: true
type: path
mode:
description:
- The permissions of the destination file or directory.
- For those used to C(/usr/bin/chmod) remember that modes are actually octal numbers.
You must either add a leading zero so that Ansible's YAML parser knows it is an
octal number (like V(0644) or V(01777)) or quote it (like V('644') or V('1777'))
so Ansible receives a string and can do its own conversion from string into number.
Giving Ansible a number without following one 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, V(u+rwx)
or V(u=rw,g=r,o=r)).
- As of Ansible 2.3, the mode may also be the special string V(preserve).
- V(preserve) means that the file will be given the same permissions as the source
file.
- When doing a recursive copy, see also O(directory_mode).
- If O(mode) is not specified and the destination file B(does not) exist, the default
C(umask) on the system will be used when setting the mode for the newly created
file.
- If O(mode) is not specified and the destination file B(does) exist, the mode of
the existing file will be used.
- Specifying O(mode) is the best way to ensure files are created with the correct
permissions. See CVE-2020-1736 for further details.
type: raw
force:
default: true
description:
- Influence whether the remote file must always be replaced.
- If V(true), the remote file will be replaced when contents are different than the
source.
- If V(false), the file will only be transferred if the destination does not exist.
type: bool
version_added: '1.1'
version_added_collection: ansible.builtin
group:
description:
- Name of the group that should own the filesystem object, as would be fed to I(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.
type: str
owner:
description:
- Name of the user that should own the filesystem object, as would be fed to I(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.
type: str
backup:
default: false
description:
- Create a backup file including the timestamp information so you can get the original
file back if you somehow clobbered it incorrectly.
type: bool
version_added: '0.7'
version_added_collection: ansible.builtin
follow:
default: false
description:
- This flag indicates that filesystem links in the destination, if they exist, should
be followed.
type: bool
version_added: '1.8'
version_added_collection: ansible.builtin
serole:
description:
- The role part of the SELinux filesystem object context.
- When set to V(_default), it will use the C(role) portion of the policy if available.
type: str
setype:
description:
- The type part of the SELinux filesystem object context.
- When set to V(_default), it will use the C(type) portion of the policy if available.
type: str
seuser:
description:
- The user part of the SELinux filesystem object context.
- By default it uses the V(system) policy, where applicable.
- When set to V(_default), it will use the C(user) portion of the policy if available.
type: str
content:
description:
- When used instead of O(src), sets the contents of a file directly to the specified
value.
- Works only when O(dest) is a file. Creates the file if it does not exist.
- For advanced formatting or if O(content) contains a variable, use the M(ansible.builtin.template)
module.
type: str
version_added: '1.1'
version_added_collection: ansible.builtin
decrypt:
default: true
description:
- This option controls the autodecryption of source files using vault.
type: bool
version_added: '2.4'
version_added_collection: ansible.builtin
selevel:
description:
- The level part of the SELinux filesystem object context.
- This is the MLS/MCS attribute, sometimes known as the C(range).
- When set to V(_default), it will use the C(level) portion of the policy if available.
type: str
checksum:
description:
- 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.
type: str
version_added: '2.5'
version_added_collection: ansible.builtin
validate:
description:
- 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.
- For an example on how to handle more complex validation than what this option provides,
see R(handling complex validation,complex_configuration_validation).
type: str
attributes:
aliases:
- attr
description:
- The attributes the resulting filesystem object should have.
- To get supported flags look at the man page for I(chattr) on the target system.
- This string should contain the attributes in the same order as the one displayed
by I(lsattr).
- The C(=) operator is assumed as default, otherwise C(+) or C(-) operators need to
be included in the string.
type: str
version_added: '2.3'
version_added_collection: ansible.builtin
remote_src:
default: false
description:
- Influence whether O(src) needs to be transferred or already is present remotely.
- If V(false), it will search for O(src) on the controller node.
- If V(true) it will search for O(src) on the managed (remote) node.
- O(remote_src) supports recursive copying as of version 2.8.
- O(remote_src) only works with O(mode=preserve) as of version 2.6.
- Autodecryption of files does not work when O(remote_src=yes).
type: bool
version_added: '2.0'
version_added_collection: ansible.builtin
local_follow:
default: true
description:
- This flag indicates that filesystem links in the source tree, if they exist, should
be followed.
type: bool
version_added: '2.4'
version_added_collection: ansible.builtin
unsafe_writes:
default: false
description:
- Influence when to use atomic operation to prevent data corruption or inconsistent
reads from the target filesystem object.
- By default this module uses atomic operations to prevent data corruption or inconsistent
reads from the target filesystem objects, but sometimes systems are configured or
just broken in ways that prevent this. One example is docker mounted filesystem
objects, which cannot be updated atomically from inside the container and can only
be written in an unsafe manner.
- This option allows Ansible to fall back to unsafe methods of updating filesystem
objects when atomic operations fail (however, it doesn't force Ansible to perform
unsafe writes).
- IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption.
type: bool
version_added: '2.2'
version_added_collection: ansible.builtin
directory_mode:
description:
- Set the access permissions of newly created directories to the given mode. Permissions
on existing directories do not change.
- See O(mode) for the syntax of accepted values.
- The target system's defaults determine permissions when this parameter is not set.
type: raw
version_added: '1.5'
version_added_collection: ansible.builtin
backup_file: description: Name of backup file created. returned: changed and if backup=yes sample: /path/to/file.txt.2015-02-12@22:09~ type: str checksum: description: SHA1 checksum of the file after running copy. returned: success sample: 6e642bb8dd5c2e027bf21dd923337cbb4214f827 type: str dest: description: Destination file/path. returned: success sample: /path/to/file.txt type: str gid: description: Group id of the file, after execution. returned: success sample: 100 type: int group: description: Group of the file, after execution. returned: success sample: httpd type: str md5sum: description: MD5 checksum of the file after running copy. returned: when supported sample: 2a5aeecc61dc98c4d780b14b330e3282 type: str mode: description: Permissions of the target, after execution. returned: success sample: '0644' type: str owner: description: Owner of the file, after execution. returned: success sample: httpd type: str size: description: Size of the target, after execution. returned: success sample: 1220 type: int src: description: Source file used for the copy on the target machine. returned: changed sample: /home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source type: str state: description: State of the target, after execution. returned: success sample: file type: str uid: description: Owner id of the file, after execution. returned: success sample: 100 type: int