ansible.windows.win_copy module – Copies files to remote locations on windows hosts
Note
This module is part of the ansible.windows collection (version 1.12.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 |
---|---|
Determine whether a backup should be created. When set to No backup is taken when Choices:
|
|
When used instead of This is for simple values, for anything complex or with formatting please switch to the ansible.windows.win_template module. |
|
This option controls the autodecryption of source files using vault. Choices:
|
|
Remote absolute path where the file should be copied to. If Use \ for path separators or \\ when in “double quotes”. If If If |
|
If set to If set to If set to Choices:
|
|
This flag indicates that filesystem links in the source tree, if they exist, should be followed. Choices:
|
|
If If Choices:
|
|
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 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 |
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.
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: yes
- 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: yes
- 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: yes
- 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 |
---|---|
Name of the backup file that was created. Returned: if backup=yes Sample: |
|
SHA1 checksum of the file after running copy. Returned: success, src is a file Sample: |
|
Destination file/path. Returned: changed Sample: |
|
Whether a single file copy took place or a folder copy. Returned: success Sample: |
|
Basename of the copied file. Returned: changed, src is a file Sample: |
|
Size of the target, after execution. Returned: changed, src is a file Sample: |
|
Source file used for the copy on the target machine. Returned: changed Sample: |