Check file-count

Overview

Counts the number of files matching a glob pattern and alerts when the count exceeds the configured thresholds. Can filter by modification time range, restrict to files or directories only, and supports SMB shares.

Important Notes:

  • SMB share access requires the optional PySmbClient and smbprotocol Python modules

  • Recursive globs (**) can cause high memory usage on large directory trees

  • The --filename and --url parameters are mutually exclusive

  • Thresholds support Nagios ranges. Use --warning 1 to check for file existence (warn if missing) or --warning '~:0' to check for file absence (warn if present)

  • --timerange accepts Nagios range syntax in seconds. Only files whose modification time falls within this range are counted

  • Depending on the file and user (e.g. running as icinga), sudo (sudoers) may be needed

Data Collection:

  • Uses Python’s pathlib.Path.glob() for local files and lib.smb for SMB shares

  • Applies os.stat() once per item to determine type and modification time, minimizing syscalls

  • When both --warning and --critical thresholds are simple numeric values, the check breaks early once the threshold is exceeded (to save time and resources on directories with millions of files)

Fact Sheet

Fact

Value

Check Plugin Download

https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/file-count

Nagios/Icinga Check Name

check_file_count

Check Interval Recommendation

Every minute

Can be called without parameters

Yes

Runs on

Cross-platform

Compiled for Windows

Yes

3rd Party Python modules

PySmbClient, smbprotocol

Help

usage: file-count [-h] [-V] [--always-ok] [-c CRIT] [--filename FILENAME]
                  [--only-dirs] [--only-files] [--password PASSWORD]
                  [--pattern PATTERN] [--timeout TIMEOUT]
                  [--timerange TIMERANGE] [-u URL] [--username USERNAME]
                  [-w WARN]

Counts the number of files matching a glob pattern and alerts when the count
exceeds the configured thresholds. Can filter by modification time range,
restrict to files or directories only, and supports SMB shares.

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  --always-ok           Always returns OK.
  -c, --critical CRIT   CRIT threshold for the number of matching files.
  --filename FILENAME   File or directory name to check (supports glob
                        patterns). Beware of recursive globs. Mutually
                        exclusive with --url.
  --only-dirs           Only count directories, ignoring files.
  --only-files          Only count files, ignoring directories.
  --password PASSWORD   Password for SMB authentication.
  --pattern PATTERN     SMB search pattern to match directory or file names.
                        Use `*` for multiple characters and `?` for a single
                        character. Does not support regex. Default: *
  --timeout TIMEOUT     Network timeout in seconds. Default: 3
  --timerange TIMERANGE
                        Only count files modified within this time range in
                        seconds.
  -u, --url URL         SMB URL of the file or directory to check, starting
                        with `smb://`. Mutually exclusive with --filename.
  --username USERNAME   Username for SMB authentication.
  -w, --warning WARN    WARN threshold for the number of matching files.

Usage Examples

# check the existence of a file; if missing warn
./file-count --filename '/path/to/file' --warning 1

# check the absence of a file; if present warn
./file-count --filename '/path/to/file' --warning '~:0'

# check that there are at least 5 `.md` files, else warn
./file-count --filename '/path/to/*.md' --warning 5

# check that there are at least 5 files modified in the last 10 seconds, else warn
./file-count --filename '/path/to/file/*' --warning 5 --timerange 5

# check a SMB share
./file-count  --username USER --password mysecret --pattern '*' --timeout 3 --url smb://\\server\path

Output:

Found 1 matching file (thresholds 1/None)|'file_count'=1;1;;0;

States

  • OK if the file count is within the given thresholds (Nagios ranges).

  • WARN if the file count is outside --warning.

  • CRIT if the file count is outside --critical.

  • --always-ok suppresses all alerts and always returns OK.

Perfdata / Metrics

Name

Type

Description

file_count

Number

Count of files matching the glob pattern and filters.

Credits, License