Behavior of ansible.builtin.copy backup=yes on symbolic links

Answer to the question

When ansible.builtin.copy is run with backup=yes, the module first follows any symbolic links that appear in the src path (the default follow=True setting). It then creates a timestamped backup of the *target file* that the link points to. The destination on the remote host is overwritten with a regular file copy of that target; the original symlink is lost. This behavior is identical in Ansible 2.9 and 2.10 because the default follow flag did not change between those releases.

Thus, backup=yes does not preserve a symlink – it replaces it with a regular file. A checksum comparison between the backup and the source target will match, but that only verifies file contents, not that the restored path is a symlink.

Why checksum alone isn’t enough

• Checksums compare bytes; they cannot distinguish a symlink from its target file.
• After a copy run the destination is a file, so any checksum match merely confirms that the file contents are identical to the original target.

How to verify the behavior on your system

1. Create a test symlink:

   ln -s /etc/hosts /tmp/hosts_link
   

2. Run a playbook that copies the link back to the same location with backup:

   - hosts: localhost
     tasks:
       - name: Copy symlink with backup
         ansible.builtin.copy:
           src: /tmp/hosts_link
           dest: /tmp/hosts_link
           backup: yes
   

3. Inspect the backup file:

   ls -l /tmp/hosts_link.bak.*
   # The output should show a regular file (e.g., "-rw-r--r--")
   

4. Confirm the destination is no longer a symlink:

   ls -l /tmp/hosts_link
   # Should display a regular file, not a link
   

Preserving a symlink

• Use the file module with state: link to create or maintain a link.
• If you need copy but want to keep the link, set follow: false (available in newer Ansible versions) so the module copies the link itself instead of its target.

What to ask next

If your goal is to keep the symlink semantics intact across runs, do you want to switch to the file module or enable follow: false in your copy task?