Ansible is one of the most powerful, free, open-source configuration management, automation, and orchestration tools.

One of the significant features of Ansible is its cross-platform management capabilities. Ansible allows us to automatically manage both Unix-based and Windows machines in simple declarative language and commands.

In this post, we will learn about the win_copy module, a powerful Ansible module that is developed for Windows systems only.

Ansible Win_Copy Module

The win_copy module is part of Ansible’s Windows collection which contains a set of modules that is developed for interacting and managing the Windows machines using Ansible.

The win_copy module, in this case, allows us to use Ansible to copy the files to and from the Windows machines with ease. Using this module, we can transfer the files directly from an Ansible controller or any other specified location to a remote Windows host.

Module Parameters

The module supports various parameters that allow us to customize its functionality. The following are some essential parameters that you need to know before using this module:

Src – It specifies a local path to a file to copy to the remote server; it can be absolute or relative. If the path provides is a directory, the module copies the directory recursively to the specified destination.

Dest – It defines the remote absolute path to copy the specified files. If the src parameter is a directory, the dest parameter must be a directory too.

Backup – If it is set to true, the module creates a backup file, including the timestamp information, to get the original file back if clobbered incorrectly.

The given parameters are some of the most common parameters that you must interact with when working with the win_copy module. You can reference the documentation to check the other supported parameters.

Installing the Ansible Collection

Before using the win_copy module, we must ensure that the appropriate Ansible collection is installed. This collection provides the required modules to manage the Windows machines. We can install it using the ansible-galaxy command:

Let us now proceed and explore some basics on how to use the win_copy module.

Using the Win_Copy Module

Basic Usage

The most straightforward method of using the win_copy module is to copy a file from your Ansible control machine to a Windows target.

This should copy the “config.ini” file that is specified on the controller filesystem to the path that is defined in the Windows node.

Using with Content Parameter

We also have access to the content parameter in the win_copy module that allows us to specify the inline content instead of the “src” file.

An example usage is as follows:

Copying the Directories

To copy an entire directory, specify the directory path for “src” as demonstrated in the following playbook example:

Note: The trailing slash at the end of the “src” directory path is essential as it tells Ansible to copy the directory recursively, including the “src” directory itself.

Preserving the Filenames

To copy a given file while preserving the filename, you can provide the “dest” parameter to the target directory as follows:

In this case, the module copies the “config.ini” file to the C:\Temp under the same name as the original file.

Creating Backup

To create a backup of the file before copying, you can use the backup parameter as follows:

This should copy the “config.ini” file to the specified location while renaming the destination file. It also creates a file backup in case it gets destroyed.

Conditional Copy

We can use the “when” clause to copy a file only when a specific condition is met as demonstrated in the following example:

Using the Check Mode

If you first want to test out the changes that occur when running a given playbook, you can use the –check flag when running the playbook. This forces the win_copy module to report what changes would occur without actually performing them.

Copying the Large Files

For large files, consider using the “ansible.windows.win_get_url” module instead. It lets us fetch the large files directly from the remote locations to the Windows targets without routing them through the Ansible controller.

Conclusion

We learned how to use the win_copy module in Ansible to copy the files from an Ansible controller or any specified location to a Windows target host.