# 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](../../../applications/cli/system/chattr.md) 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
```yaml
- 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
```