community.openwrt.find module – Return a list of files based on specific criteria on OpenWrt targets

Note

This module is part of the community.openwrt collection (version 1.12.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.find.

New in community.openwrt 1.12.0

Synopsis

  • Return a list of files based on specific criteria. Multiple criteria are AND’d together.

  • This module loosely mimics ansible.builtin.find. It reads the filesystem directly and does not use the find command.

Note

This module has a corresponding action plugin.

Parameters

Parameter

Comments

age

string

Select files whose age is equal to or greater than the specified time.

Use a negative age to find files equal to or less than the specified time.

You can choose seconds, minutes, hours, days, or weeks by specifying the first letter of any of those words, for example 1w. Unqualified values are in seconds.

age_stamp

string

Choose the file property against which to compare age.

Choices:

  • "atime"

  • "ctime"

  • "mtime" ← (default)

depth

integer

Set the maximum number of levels to descend into.

Setting recurse=false overrides this value, which is effectively depth 1.

Default is unlimited depth.

exact_mode

boolean

Restrict mode matching to exact matches only, and not as a minimum set of permissions to match.

Choices:

  • false

  • true ← (default)

excludes

aliases: exclude

list / elements=string

One or more shell or regex patterns, which type is controlled by use_regex.

Items whose basenames match an excludes pattern are culled from patterns matches.

Default: []

file_type

string

Type of file to select.

Choices:

  • "any"

  • "directory"

  • "file" ← (default)

  • "link"

  • "block"

  • "char"

  • "socket"

  • "pipe"

follow

boolean

Set this to true to follow symlinks found while searching.

The paths in paths are always followed when they are symlinks to directories.

Choices:

  • false ← (default)

  • true

hidden

boolean

Set this to true to include hidden files, otherwise they are ignored.

When false, hidden directories are not descended into either.

Choices:

  • false ← (default)

  • true

limit

integer

Limit the maximum number of matching paths returned. After finding this many, the module stops looking.

Default is unlimited.

mode

string

Choose objects matching a specified permission, as an octal string such as "0644".

Symbolic modes are not supported.

paths

aliases: name, path

list / elements=string / required

List of paths of directories to search. All paths must be absolute.

patterns

aliases: pattern

list / elements=string

One or more shell or regex patterns, which type is controlled by use_regex.

The patterns restrict the list of files to be returned to those whose basenames match at least one of the patterns specified.

The pattern is matched against the file base name, excluding the directory.

When using regular expressions, the pattern must match the entire file name, not just parts of it.

This parameter expects a list, which can be either comma separated or YAML. If any of the patterns contain a comma, make sure to put them in a list to avoid splitting the patterns in undesirable ways.

When empty, all names are selected.

Default: []

recurse

boolean

If true, recursively descend into the directories looking for files.

Choices:

  • false ← (default)

  • true

size

string

Select files whose size is equal to or greater than the specified size.

Use a negative size to find files equal to or less than the specified size.

Unqualified values are in bytes but b, k, m, g, and t can be appended to specify bytes, kibibytes, mebibytes, gibibytes, and tebibytes, respectively.

Size is only evaluated for regular files.

use_regex

boolean

If false, the patterns are shell globs.

If true, they are POSIX extended regular expressions. Note that these are not Python regular expressions, so constructs such as non-greedy quantifiers or \d are not available.

Choices:

  • false ← (default)

  • true

Attributes

Attribute

Support

Description

check_mode

Support: full

This action does not modify state.

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: N/A

This action does not modify state.

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.

See Also

See also

ansible.builtin.find

The official documentation on the ansible.builtin.find module.

community.openwrt.stat

Retrieve file or file system status on OpenWrt targets.

Examples

- name: Recursively find /tmp files older than 2 days
  community.openwrt.find:
    paths: /tmp
    age: 2d
    recurse: true

- name: Recursively find /tmp files older than 4 weeks and equal or greater than 1 megabyte
  community.openwrt.find:
    paths: /tmp
    age: 4w
    size: 1m
    recurse: true

- name: Recursively find /tmp files with last access time greater than 3600 seconds
  community.openwrt.find:
    paths: /tmp
    age: 3600
    age_stamp: atime
    recurse: true

- name: Find /etc/config files ending with .bak or -opkg
  community.openwrt.find:
    paths: /etc/config
    patterns: '*.bak,*-opkg'

- name: Find the same files with a regular expression
  community.openwrt.find:
    paths: /etc/config
    patterns: '.*(\.bak|-opkg)'
    use_regex: true

- name: Find all directories in /etc, excluding init.d and rc.d
  community.openwrt.find:
    paths: /etc
    file_type: directory
    excludes: 'init.d,rc.d'

- name: Find executable scripts, stopping at the first one
  community.openwrt.find:
    paths: /usr/sbin
    mode: "0755"
    limit: 1

Return Values

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

Key

Description

examined

integer

Number of filesystem objects looked at.

Returned: success

Sample: 34

files

list / elements=dictionary

All matches found with the specified criteria.

Returned: success

atime

integer

Last access time in seconds since epoch.

Returned: success

Sample: 1701788400

ctime

integer

Last change time in seconds since epoch.

Returned: success

Sample: 1701788400

gid

integer

Numeric group ID of the owner.

Returned: success

Sample: 0

inode

integer

Inode number of the file.

Returned: success

Sample: 12345

isblk

boolean

Whether the path is a block device.

Returned: success

Sample: false

ischr

boolean

Whether the path is a character device.

Returned: success

Sample: false

isdir

boolean

Whether the path is a directory.

Returned: success

Sample: false

isfifo

boolean

Whether the path is a FIFO.

Returned: success

Sample: false

islnk

boolean

Whether the path is a symbolic link.

Returned: success

Sample: false

isreg

boolean

Whether the path is a regular file.

Returned: success

Sample: true

issock

boolean

Whether the path is a socket.

Returned: success

Sample: false

mode

string

Unix permissions of the file in octal.

Returned: success

Sample: "0644"

mtime

integer

Last modification time in seconds since epoch.

Returned: success

Sample: 1701788400

integer

Number of hard links to the file.

Returned: success

Sample: 1

path

string

The full path to the file.

Returned: success

Sample: "/etc/config/network"

size

integer

Size of the file in bytes.

Returned: success

Sample: 1024

uid

integer

Numeric user ID of the owner.

Returned: success

Sample: 0

matched

integer

Number of matches.

Returned: success

Sample: 14

skipped_paths

dictionary

Skipped paths and reasons they were skipped.

Returned: success

Sample: {"/laskdfj": "'/laskdfj' is not a directory"}

Authors

  • Alexei Znamensky (@russoz)