community.openwrt.copy module – Copy files to remote OpenWrt devices

Note

This module is part of the community.openwrt collection (version 0.5.0).

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 community.openwrt.

To use it in a playbook, specify: community.openwrt.copy.

Synopsis

• The community.openwrt.copy module copies a file from the Ansible controller to remote OpenWrt devices.

• The content parameter supports Jinja2 variable interpolation.

Note

This module has a corresponding action plugin.

Parameters

Parameter	Comments
backup boolean	Create a backup file including the timestamp information so you can get the original file back if you clobbered it incorrectly. Choices: false ← (default) true
content string	When used instead of src, sets the contents of a file directly to the specified value. Works only when dest is a file. Creates the file if it does not exist. Do not specify together with src (only one is used if both are provided).
dest path / required	Remote absolute path where the file is copied to. If dest is a directory, the file is copied into that directory using the source file name. If dest ends with “/”, it is treated as a directory and is created if it does not exist. If dest is a relative path, the starting directory is determined by the remote host. The parent directory of dest must exist or the task fails.
directory_mode string	Permissions to set on directories that are created during the copy operation. Used when dest ends with “/” and the directory structure needs to be created. Follows the same format rules as mode. If not specified, directories are created with system default permissions.
follow boolean	Whether to follow symlinks when setting file attributes. When false, symlinks are not followed and attributes are set on the link itself (where supported). When true, attributes are set on the symlink target. Affects how mode, owner, and group are applied. Choices: false ← (default) true
force aliases: thirsty boolean	Determines whether the remote file must always be replaced. If true, the remote file is replaced when contents are different from the source. If false, the file is only transferred if the destination does not exist. Choices: false true ← (default)
group string	Group name that should own the file or directory. Passed directly to the chgrp command. If not specified, group ownership is not changed. Not applied to symlinks when follow=false.
mode string	Permissions for the file or directory. Can be specified as an octal number (for example, '0644', '1777') or symbolic mode (like 'u+rwx'). When using octal notation, quote the value to ensure it is treated as a string. If not specified, permissions may be determined by the system default umask or remain unchanged. Not applied to symlinks when follow=false.
owner string	User name that should own the file or directory. Passed directly to the chown command. If not specified, ownership is not changed. Not applied to symlinks when follow=false.
src path	Local path to a file to copy to the remote server. Can be absolute or relative. When relative, the file is searched in the files/ directory of the role or playbook. Only regular files are supported. Directories cannot be copied recursively. Do not specify together with content (only one is used if both are provided).
validate string	Command to run to validate the file before copying it into place. The file path is substituted for %s in the command. The command must include %s or the validation fails. The command is executed through printf substitution, so shell features like pipes do not work. If the validation command fails, the copy operation is aborted.

Attributes

Attribute	Support	Description
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target.
diff_mode	Support: full	Returns details on what has changed (or possibly needs changing in check_mode), when in diff mode.
platform	Platform: OpenWrt	Target platform for this module.
safe_file_operations	Support: none This module uses basic shell commands for file operations and does not implement Ansible’s atomic file operation functions.	Uses Ansible’s strict file operation functions to ensure proper permissions and avoid data corruption.

Notes

Note

• This module does not support recursive directory copy. Only regular files can be copied.

• Supports check_mode.

Examples

- name: Copy file with owner and permissions
  community.openwrt.copy:
    src: /srv/myfiles/foo.conf
    dest: /etc/foo.conf
    owner: root
    group: root
    mode: '0644'

- name: Copy file from controller, creating backup
  community.openwrt.copy:
    src: /mine/ntp.conf
    dest: /etc/ntp.conf
    owner: root
    group: root
    mode: '0644'
    backup: true

- name: Copy inline content to file
  community.openwrt.copy:
    content: |
      # Managed by Ansible
      option enabled '1'
      option hostname 'openwrt'
    dest: /etc/config/system
    mode: '0644'

- name: Copy file only if it does not exist
  community.openwrt.copy:
    src: /srv/myfiles/foo.conf
    dest: /etc/foo.conf
    force: false

- name: Copy file and validate
  community.openwrt.copy:
    src: /etc/uci-defaults/template
    dest: /etc/uci-defaults/custom
    validate: sh -n %s

- name: Copy file from Ansible files directory
  community.openwrt.copy:
    src: myconfig.txt
    dest: /etc/config/myapp
    mode: '0600'

Return Values

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

Key	Description
backup_file string	Name of backup file created. Returned: changed and if backup=true Sample: "/etc/foo.conf.2025-11-30@10:30:15~"
checksum string	SHA1 checksum of the source file. Returned: success Sample: "6e642bb8dd5c2e027bf21dd923337cbb4214f827"
dest string	Destination file/path. Returned: success Sample: "/etc/foo.conf"
md5sum string	MD5 checksum of the source file. Returned: when supported Sample: "2a5aeecc61dc98c4d780b14b330e3282"
src string	Source file used for the copy on the target machine. After the action plugin transfers the file, this is the path on the remote device. Returned: changed Sample: "/tmp/.ansible/tmp/source"
state string	State of the target file after execution. Returned: success Sample: "file"

Authors

• Markus Weippert (@gekmihesg)

• Alexei Znamensky (@russoz)

Collection links

• Issue Tracker
• Repository (Sources)
• Report an issue
• Communication