W3cubDocs

/Ansible

win_copy - Copies files to remote locations on windows hosts

New in version 1.9.2.

Synopsis

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

Options

parameter required default choices comments
content
(added in 2.3)
 no
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 template module.
dest
 yes
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
(added in 2.3)
 no yes
  • yes
  • no
If set to yes, the file will only be transferred if the content is different than destination.
If set to no, the file will only be transferred if the destination does not exist.
If set to no, no checksuming of the content is performed which can help improve performance on larger files.
local_follow
(added in 2.4)
 no yes
  • yes
  • no
This flag indicates that filesystem links in the source tree, if they exist, should be followed.
remote_src
(added in 2.3)
 no no
  • yes
  • no
If False, it will search for src at originating/master machine, if True it will go to the remote/target machine for the src.
src
 yes
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.

Examples

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

- name: Copy a single file keeping the filename
  win_copy:
    src: /src/myfiles/foo.conf
    dest: c:\temp\

- name: Copy folder to c:\temp (results in C:\Temp\temp_files)
  win_copy:
    src: files/temp_files
    dest: c:\Temp

- name: Copy folder contents recursively
  win_copy:
    src: files/temp_files/
    dest: c:\Temp

- name: Copy a single file where the source is on the remote host
  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
  win_copy:
    src: C:\temp
    dest: C:\ansible
    remote_src: True

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

Return Values

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

name description returned type sample
src
source file used for the copy on the target machine
 changed string /home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source
original_basename
basename of the copied file
 changed, src is a file string foo.txt
dest
destination file/path
 changed string C:\Temp\
checksum
sha1 checksum of the file after running copy
 success, src is a file string 6e642bb8dd5c2e027bf21dd923337cbb4214f827
operation
whether a single file copy took place or a folder copy
 success string file_copy
size
size of the target, after execution
 changed, src is a file int 1220

Notes

Note

  • For non-Windows targets, use the copy module instead.
  • 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 win_get_url instead.

Status

This module is flagged as stableinterface which means that the maintainers for this module guarantee that no backward incompatible interface changes will be made.

Maintenance Info

For more information about Red Hat’s this support of this module, please refer to this knowledge base article<https://access.redhat.com/articles/rhel-top-support-policies>

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

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