community.openwrt.file module – Manage files and file properties on OpenWrt targets

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.file.

Synopsis

  • The community.openwrt.file module sets attributes of files, symlinks, and directories.

  • It can also create or remove files, directories, and symbolic/hard links.

Note

This module has a corresponding action plugin.

Parameters

Parameter

Comments

diff_peek

string

Internal parameter for diff operations.

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

boolean

Force creation of symlinks when the target does not exist.

Force conversion between different link types.

Choices:

  • false ← (default)

  • true

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.

original_basename

aliases: _original_basename

string

Original basename to use when path is a directory.

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.

path

aliases: dest, name

string / required

Path to the file being managed.

recurse

boolean

Recursively set the specified file attributes on directory contents.

Only works with state=directory.

Choices:

  • false ← (default)

  • true

src

string

Path of the file to link to.

Required for state=link and state=hard.

For symbolic links, if not specified, the realpath of path is used.

state

string

Desired state of the file.

If not specified, defaults to file if the path is a file, directory if recurse is set, or the current state otherwise.

Choices:

  • "absent"

  • "directory"

  • "file"

  • "hard"

  • "link"

  • "touch"

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.

Examples

- name: Create a directory
  community.openwrt.file:
    path: /etc/config/custom
    state: directory
    mode: '0755'

- name: Create a symbolic link
  community.openwrt.file:
    src: /etc/config/network
    path: /tmp/network.link
    state: link

- name: Remove a file
  community.openwrt.file:
    path: /tmp/tempfile
    state: absent

- name: Touch a file
  community.openwrt.file:
    path: /tmp/touched
    state: touch

Return Values

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

Key

Description

appears_binary

boolean

Whether the file appears to be binary.

Returned: when diff_peek is specified

Sample: false

path

string

Path to the file or directory.

Returned: always

Sample: "/etc/config/network"

state

string

The state of the file or directory.

Returned: always

Sample: "file"

Authors

  • Markus Weippert (@gekmihesg)