ansible.windows.win_copy - Copies files to remote locations on windows hosts
This plugin is part of the ansible.windows collection (version 1.3.0).
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.
This module has a corresponding action plugin.
Parameters
Parameter Choices/Defaults Comments boolean
- no ←
- yes
Determine whether a backup should be created.
When set to yes, 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.
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.
boolean
- no
- yes ←
This option controls the autodecryption of source files using vault.
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.
boolean
- no
- yes ←
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.
boolean
- no
- yes ←
This flag indicates that filesystem links in the source tree, if they exist, should be followed.
boolean
- no ←
- yes
If no, it will search for src at originating/controller machine.
If yes, it will go to the remote/target machine for the 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
- 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
- community.general.assemble
The official documentation on the community.general.assemble module.
- ansible.builtin.copy
The official documentation on the ansible.builtin.copy module.
- ansible.windows.win_get_url
The official documentation on the ansible.windows.win_get_url module.
- community.windows.win_robocopy
The official documentation on the community.windows.win_robocopy module.
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 Returned Description string
if backup=yes Name of the backup file that was created.
Sample:
C:\Path\To\File.txt.11540.20150212-220915.bak
string
success, src is a file SHA1 checksum of the file after running copy.
Sample:
6e642bb8dd5c2e027bf21dd923337cbb4214f827
string
changed Destination file/path.
Sample:
C:\Temp\
string
success Whether a single file copy took place or a folder copy.
Sample:
file_copy
string
changed, src is a file Basename of the copied file.
Sample:
foo.txt
integer
changed, src is a file Size of the target, after execution.
Sample:
1220
string
changed Source file used for the copy on the target machine.
Sample:
/home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source
Authors
- Jon Hawkesworth (@jhawkesworth)
- Jordan Borean (@jborean93)