ansible.windows.win_copy module – Copies files to remote locations on windows hosts

Note

This module is part of the ansible.windows collection (version 2.5.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install ansible.windows.

To use it in a playbook, specify: ansible.windows.win_copy.

Synopsis

  • The win_copy module copies a file on the local box to remote windows locations.
  • For non-Windows targets, use the ansible.builtin.copy module instead.

Note

This module has a corresponding action plugin.

Parameters

Parameter

Comments

backup

boolean

Determine whether a backup should be created.

When set to true, create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.

No backup is taken when remote_src=False and multiple files are being copied.

Choices:

  • false ← (default)
  • true

content

string

When used instead of src, sets the contents of a file directly to the specified value.

This is for simple values, for anything complex or with formatting please switch to the ansible.windows.win_template module.

decrypt

boolean

This option controls the autodecryption of source files using vault.

Choices:

  • false
  • true ← (default)

dest

path / required

Remote absolute path where the file should be copied to.

If src is a directory, this must be a directory too.

Use \ for path separators or \\ when in “double quotes”.

If dest ends with \ then source or the contents of source will be copied to the directory without renaming.

If dest is a nonexistent path, it will only be created if dest ends with “/” or “\”, or src is a directory.

If src and dest are files and if the parent directory of dest doesn’t exist, then the task will fail.

force

boolean

If set to true, the file will only be transferred if the content is different than destination.

If set to false, the file will only be transferred if the destination does not exist.

If set to false, no checksuming of the content is performed which can help improve performance on larger files.

Choices:

  • false
  • true ← (default)

local_follow

boolean

This flag indicates that filesystem links in the source tree, if they exist, should be followed.

Choices:

  • false
  • true ← (default)

remote_src

boolean

If false, it will search for src at originating/controller machine.

If true, it will go to the remote/target machine for the src.

Choices:

  • false ← (default)
  • true

src

path

Local path to a file to copy to the remote server; can be absolute or relative.

If path is a directory, it is copied (including the source folder name) recursively to dest.

If path is a directory and ends with “/”, only the inside contents of that directory are copied to the destination. Otherwise, if it does not end with “/”, the directory itself with all contents is copied.

If path is a file and dest ends with “\”, the file is copied to the folder with the same filename.

Required unless using content.

Notes

Note

  • Currently win_copy does not support copying symbolic links from both local to remote and remote to remote.
  • It is recommended that backslashes \ are used instead of / when dealing with remote paths.
  • Because win_copy runs over WinRM, it is not a very efficient transfer mechanism. If sending large files consider hosting them on a web service and using ansible.windows.win_get_url instead.
  • When using become with a user that is not an Administrator, the remote temp directory must be set to one that is accessible to both the become and connection user with ansible_remote_tmp. See the examples for more information.

See Also

See also

ansible.builtin.assemble

Assemble configuration files from fragments.

ansible.builtin.copy

Copy files to remote locations.

ansible.windows.win_get_url

Downloads file from HTTP, HTTPS, or FTP to node.

community.windows.win_robocopy

Synchronizes the contents of two directories using Robocopy.

Examples

- name: Copy a single file
  ansible.windows.win_copy:
    src: /srv/myfiles/foo.conf
    dest: C:\Temp\renamed-foo.conf

- name: Copy a single file, but keep a backup
  ansible.windows.win_copy:
    src: /srv/myfiles/foo.conf
    dest: C:\Temp\renamed-foo.conf
    backup: true

- name: Copy a single file keeping the filename
  ansible.windows.win_copy:
    src: /src/myfiles/foo.conf
    dest: C:\Temp\

- name: Copy folder to C:\Temp (results in C:\Temp\temp_files)
  ansible.windows.win_copy:
    src: files/temp_files
    dest: C:\Temp

- name: Copy folder contents recursively
  ansible.windows.win_copy:
    src: files/temp_files/
    dest: C:\Temp

- name: Copy a single file where the source is on the remote host
  ansible.windows.win_copy:
    src: C:\Temp\foo.txt
    dest: C:\ansible\foo.txt
    remote_src: true

- name: Copy a folder recursively where the source is on the remote host
  ansible.windows.win_copy:
    src: C:\Temp
    dest: C:\ansible
    remote_src: true

- name: Set the contents of a file
  ansible.windows.win_copy:
    content: abc123
    dest: C:\Temp\foo.txt

- name: Copy a single file as another user
  ansible.windows.win_copy:
    src: NuGet.config
    dest: '%AppData%\NuGet\NuGet.config'
  vars:
    ansible_become_user: user
    ansible_become_password: pass
    # The tmp dir must be set when using win_copy as another user
    # This ensures the become user will have permissions for the operation
    # Make sure to specify a folder both the ansible_user and the become_user have access to (i.e not %TEMP% which is user specific and requires Admin)
    ansible_remote_tmp: 'c:\tmp'

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

backup_file

string

Name of the backup file that was created.

Returned: if backup=yes

Sample: "C:\\Path\\To\\File.txt.11540.20150212-220915.bak"

checksum

string

SHA1 checksum of the file after running copy.

Returned: success, src is a file

Sample: "6e642bb8dd5c2e027bf21dd923337cbb4214f827"

dest

string

Destination file/path.

Returned: changed

Sample: "C:\\Temp\\"

operation

string

Whether a single file copy took place or a folder copy.

Returned: success

Sample: "file_copy"

original_basename

string

Basename of the copied file.

Returned: changed, src is a file

Sample: "foo.txt"

size

integer

Size of the target, after execution.

Returned: changed, src is a file

Sample: 1220

src

string

Source file used for the copy on the target machine.

Returned: changed

Sample: "/home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source"

Authors

  • Jon Hawkesworth (@jhawkesworth)
  • Jordan Borean (@jborean93)

© 2012–2018 Michael DeHaan
© 2018–2024 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/ansible/windows/win_copy_module.html