CheckDisk

CheckDisk can check various file and disk related things.

CheckDisk is provides two disk related checks one for checking size of drives and the other for checking status of files and folders.

UNC and Network Paths

Please note that UNC and network paths are only available in each session meaning a user mounted share will not be visible to NSClient++ (since services run in their own session). But as long as NSClient++ can access the share you can still check it as you specify the UNC path. In other words the following will NOT work: check_drivesize drive=m: But the following will: check_drivesize drive=\\myserver\\mydrive

Enable module

To enable this module and and allow using the commands you need to ass CheckDisk = enabled to the [/modules] section in nsclient.ini:

[/modules]
CheckDisk = enabled

Queries

A quick reference for all available queries (check commands) in the CheckDisk module.

List of commands:

A list of all available queries (check commands)

Command	Description
check_disk_health	Combined per-drive health check (free space + I/O metrics).
check_disk_io	Check disk I/O performance metrics (throughput, IOPS, queue length, busy time).
check_disk_write	Verify that a disk is writable by creating a test file, writing to it, reading it back and deleting it.
check_drivesize	Check the size (free-space) of a drive or volume.
check_files	Check various aspects of a file and/or folder.
check_mount	Check that a filesystem is mounted with the expected fstype and options.
check_shadowcopy	Check VSS shadow-copy (Volume Shadow Copy) recency, count and shadow-storage usage per volume. Windows only.
check_share	Check Windows SMB shares: list them, or verify that specific required shares exist. Windows only.
check_single_file	Check various aspects of a single file (size, age, line count, version, …). Simpler alternative to check_files when you only need to inspect one specific file.
check_storagepool	Check Storage Spaces pool health and capacity. Windows only.
check_uncpath	Check free space on a UNC path (server share), with optional alternate credentials.

check_disk_health

Combined per-drive health check (free space + I/O metrics).

check_disk_health is a combined per-disk health check. It reports three kinds of row, each judged only on the data that is real for it:

• Space rows (has_space = 1) — one per mounted filesystem, with size/free/used/free_pct/used_pct/user_free and the I/O of the backing device.
• I/O rows (has_space = 0, has_device = 0) — devices/totals with no mounted filesystem (e.g. _Total), judged on percent_disk_time and queue.
• Device rows (has_device = 1) — one per physical disk (Windows only, from MSFT_PhysicalDisk / MSFT_Disk), judged on physical-disk health.

Space and I/O rows also carry the average I/O latency of the backing device (read_latency, write_latency, total_latency, in milliseconds over the collection interval), so a single check can join free space with the most portable saturation signal: "warn=total_latency > 20" "crit=total_latency > 50". See check_disk_io for details on how latency is measured.

The space keywords have no value at all on a row without a filesystem behind it (an I/O or device row). They render as -, every numeric comparison against them is false, and they emit no performance data, so a graph of a device row records nothing rather than a fabricated 0%. Test for it with free_pct = 'no space data', or keep using the has_space = 1 guard.

Byte-valued keywords can be formatted and scaled with format_bytes, convert_bytes and scale; see the same section under check_disk_io.

Device-state rows (Windows)

Device rows are best-effort: if the MSFT_PhysicalDisk / MSFT_Disk WMI classes are unavailable (very old Windows, or a system with no Storage provider), no device rows are produced and the check still reports space and I/O normally.

Default thresholds

By default the check is WARNING when a filesystem drops below 20% free, its disk is over 80% busy, or a physical disk reports Warning health; and CRITICAL below 10% free, over 95% busy, or when a physical disk is Unhealthy or offline.

Jump to section:

• Sample Commands
• Command-line Arguments
• Filter keywords

Sample Commands

Default check:

check_disk_health
OK: All disks are healthy.
'C: free_pct'=61%;20;10 'C: percent_disk_time'=2%;80;95 ...

Physical-disk device health:

check_disk_health appends one row per physical disk (from MSFT_PhysicalDisk / MSFT_Disk), carrying device state. These rows are identified by has_device = 1 and by default go CRITICAL on an unhealthy or offline disk and WARNING on a disk reporting Warning health.

check_disk_health "filter=has_device = 1" "detail-syntax=${friendly_name} [${media_type}]: ${health_status}, ${operational_status}"
OK: Samsung SSD 980 [SSD]: Healthy, OK, WDC WD40 [HDD]: Healthy, OK

Alerting only on SSD wear / disk failure across all physical disks:

check_disk_health "filter=has_device = 1" "crit=health_status != 'Healthy' or is_offline = 1"
CRITICAL: WDC WD40 [HDD]: Unhealthy, Unhealthy

Device-state keywords (populated on has_device = 1 rows): friendly_name, serial, media_type (HDD/SSD/SCM), health_status (Healthy/Warning/Unhealthy/Unknown), operational_status, is_offline, is_readonly, disk_number.

Command-line Arguments

Common options:

These options are shared by all filter based commands and are described on the common options page; the default values below are specific to this command.

Option	Default Value
filter	name != ‘_Total’
warning	(has_space = 1 and free_pct < 20) or percent_disk_time > 80 or (has_device = 1 and health_status = ‘Warning’)
warn
critical	(has_space = 1 and free_pct < 10) or percent_disk_time > 95 or (has_device = 1 and (health_status = ‘Unhealthy’ or is_offline = 1))
crit
ok
debug	false
show-all	false
empty-state	critical
perf-config
escape-html	false
list-separator	,
top-syntax	${status}: ${list}
ok-syntax	%(status): All disks are healthy.
empty-syntax
detail-syntax	${name}: ${free_pct} free, ${percent_disk_time}% busy, q=${queue_length} iops=${iops}
perf-syntax	${name}
byte-unit
decimal-separator
decimals	-1
thousands-separator

This command also accepts the standard help options: help, help-pb, show-default, help-short.

Filter keywords

Option	Description
convert_bytes()	Convert a byte count to a specific unit and return the numeric value (1024-based). Useful in thresholds.
disk_number	Physical disk number/index (device rows)
format_bytes()	Format a number as a human-readable byte string.
format_number()	Render a number with a fixed number of decimals, using the check’s decimal and thousands separators.
free	Free disk space in bytes (I/O-only rows have none)
free_pct	Percentage of free disk space (I/O-only rows have none)
friendly_name	Physical disk friendly name (device rows)
has_device	1 if the row carries physical-disk device state (a per-disk row), 0 otherwise (guard; no perfdata)
has_space	1 if the row has filesystem space data, 0 for I/O-only rows (e.g. _Total or a disk with no mounted filesystem)
health_status	Physical disk health: Healthy, Warning, Unhealthy or Unknown (device rows)
iops	Total IOPS (reads + writes)
is_offline	1 if the physical disk is offline (device rows)
is_readonly	1 if the physical disk is read-only (device rows)
media_type	Physical disk media type: HDD, SSD, SCM or Unspecified (device rows)
name	Drive name (e.g. C:, D:, _Total)
operational_status	Physical disk operational status, synthesised single value: Offline, OK, or the health string (device rows)
percent_disk_time	Percent of time the disk is busy
percent_idle_time	Percent of time the disk is idle
queue_length	Current disk queue length
read_bytes_per_sec	Bytes read per second
read_latency	Average read latency in milliseconds (over the collection interval)
reads_per_sec	Read IOPS
scale()	Divide a value by a divisor. Useful for arbitrary unit conversions (e.g. decimal Mbps with scale(value, 1000000)).
serial	Physical disk serial number (device rows)
size	Total disk size in bytes (I/O-only rows have none)
split_io_per_sec	Split I/O operations per second
total_bytes_per_sec	Total bytes per second (read + write)
total_latency	Average latency per I/O (read + write) in milliseconds (over the collection interval)
used	Used disk space in bytes (I/O-only rows have none)
used_pct	Percentage of used disk space (I/O-only rows have none)
user_free	Free disk space available to current user in bytes (I/O-only rows have none)
write_bytes_per_sec	Bytes written per second
write_latency	Average write latency in milliseconds (over the collection interval)
writes_per_sec	Write IOPS

This command also supports the common filter keywords: count, total, ok_count, warn_count, crit_count, problem_count, list, ok_list, warn_list, crit_list, problem_list, detail_list, sep, status.

check_disk_io

Check disk I/O performance metrics (throughput, IOPS, queue length, busy time).

check_disk_io reports disk I/O activity per logical disk (Windows) or per physical block device (Linux), plus a _Total row aggregating all disks. The data comes from a background collector that samples every 10 seconds (the collection interval setting), so each check reads the most recent interval.

The keywords fall into two groups:

• Load — reads_per_sec, writes_per_sec, iops, read_bytes_per_sec, write_bytes_per_sec, total_bytes_per_sec, split_io_per_sec: how much work the disk is doing. These have no universally meaningful thresholds — a healthy datastore may sustain thousands of IOPS while a saturated one struggles at hundreds.
• Saturation — percent_disk_time, percent_idle_time, queue_length, and the latency keywords (read_latency, write_latency, total_latency, in milliseconds): whether the storage is keeping up.

Latency keywords

Average latency per I/O is the most portable saturation signal: it is independent of the workload shape and comparable across machines. As a rule of thumb, sustained latencies above ~20 ms suggest the storage is struggling and above ~50 ms indicate a real problem. The values are averages over the collection interval and read 0 when no I/O of that kind occurred (and on the first sample after startup).

On Windows latency is computed from the raw Avg. Disk sec/Read|Write|Transfer performance counters; on Linux from /proc/diskstats (time spent reading/writing divided by operations completed).

One accuracy caveat: the underlying counters are 32-bit and accrue time per in-flight operation, so on a disk under sustained very heavy load (high queue depth) they can wrap more than once within a long sampling window, which understates the reported latency. Perfmon has the same limitation and avoids it by sampling every second — if you monitor extremely busy disks, lower the module’s collection interval accordingly:

[/settings/disk]
collection interval=2s

Formatting byte values

The byte-rate keywords are plain byte counts, and the filter language has no arithmetic of its own, so three functions are available in both detail-syntax and threshold expressions:

Function	Description
format_bytes(value)	Human-readable string, auto-scaled to B/KB/MB/GB/… (1024-based).
format_bytes(value,unit)	Human-readable string in a fixed unit (B, K/KB, M/MB, G/GB, T/TB).
convert_bytes(value,unit)	The numeric value in that unit — use it in warn/crit.
scale(value,divisor)	Plain division, for units the byte helpers do not cover (e.g. decimal Mbps).

check_disk_io "detail-syntax=%(name): %(format_bytes(total_bytes_per_sec))/s" "warn=convert_bytes(total_bytes_per_sec,'MB') > 100"
OK: C:: 20.95MB/s, D:: 1.10MB/s

Write the argument list without a space after the comma: the command-line client splits an argument on whitespace, so format_bytes(value, 'MB') is passed as two tokens and the option fails to parse. Over REST, and in nsclient.ini, both spellings work.

Performance data labels

percent_disk_time is what this check is about, so it is graphed under the bare drive name — 'C:' — as it always has been. Every other keyword adds its own: 'C:_queue_length', 'C:_total_latency', 'C:_iops' and so on, one series per keyword rather than several sharing the drive name. check_disk_health works the same way with free_pct as its primary metric.

The name a keyword is graphed under does not depend on what else the query asks for, so a graph template can rely on it. Override the pieces per keyword with perf-config:

check_disk_io "perf-config=percent_disk_time(suffix:_busy)"

Jump to section:

• Sample Commands
• Command-line Arguments
• Filter keywords

Sample Commands

Alerting on average I/O latency:

Average latency per I/O is the most portable “is the storage keeping up?” signal: thresholds of ~20 ms (warning) and ~50 ms (critical) are meaningful regardless of workload or hardware. Values are in milliseconds.

check_disk_io "warn=total_latency > 20" "crit=total_latency > 50"
OK: C:: 11% busy, read=21967407B/s write=17167107B/s q=0, HarddiskVolume4: 0% busy, read=0B/s write=0B/s q=0, ...
'C:_total_latency'=0.172447ms;20;50 'HarddiskVolume4_total_latency'=0ms;20;50 ...

Separate read/write latency for a single disk:

check_disk_io "filter=name = 'C:'" "warn=read_latency > 20 or write_latency > 20" "crit=read_latency > 50 or write_latency > 50" "detail-syntax=${name}: r=${read_latency}ms w=${write_latency}ms"
OK: C:: r=4.08798ms w=1.47571ms
'C:_read_latency'=4.08798ms;20;50 'C:_write_latency'=1.47571ms;20;50

Latency is averaged over the collector’s sampling interval (10 seconds by default) and reads 0 when no I/O of that kind occurred during the interval — including the very first interval after startup.

Alerting on a busy disk (default thresholds):

The default check goes WARNING above 80% disk time and CRITICAL above 95%:

check_disk_io
OK: All disk I/O seems ok.
'C:'=2%;80;95 'HarddiskVolume4'=0%;80;95 ...

Command-line Arguments

Common options:

These options are shared by all filter based commands and are described on the common options page; the default values below are specific to this command.

Option	Default Value
filter	name != ‘_Total’
warning	percent_disk_time > 80
warn
critical	percent_disk_time > 95
crit
ok
debug	false
show-all	false
empty-state	critical
perf-config
escape-html	false
list-separator	,
top-syntax	${status}: ${list}
ok-syntax	%(status): All disk I/O seems ok.
empty-syntax
detail-syntax	${name}: ${percent_disk_time}% busy, read=${read_bytes_per_sec}B/s write=${write_bytes_per_sec}B/s q=${queue_length}
perf-syntax	${name}
byte-unit
decimal-separator
decimals	-1
thousands-separator

This command also accepts the standard help options: help, help-pb, show-default, help-short.

Filter keywords

Option	Description
convert_bytes()	Convert a byte count to a specific unit and return the numeric value (1024-based). Useful in thresholds.
format_bytes()	Format a number as a human-readable byte string.
format_number()	Render a number with a fixed number of decimals, using the check’s decimal and thousands separators.
iops	Total IOPS (reads + writes)
name	Logical disk name (e.g. C:, D:, _Total)
percent_disk_time	Percent of time the disk is busy
percent_idle_time	Percent of time the disk is idle
queue_length	Current disk queue length
read_bytes_per_sec	Bytes read per second
read_latency	Average read latency in milliseconds (over the collection interval)
reads_per_sec	Read IOPS
scale()	Divide a value by a divisor. Useful for arbitrary unit conversions (e.g. decimal Mbps with scale(value, 1000000)).
split_io_per_sec	Split I/O operations per second
total_bytes_per_sec	Total bytes per second (read + write)
total_latency	Average latency per I/O (read + write) in milliseconds (over the collection interval)
write_bytes_per_sec	Bytes written per second
write_latency	Average write latency in milliseconds (over the collection interval)
writes_per_sec	Write IOPS

This command also supports the common filter keywords: count, total, ok_count, warn_count, crit_count, problem_count, list, ok_list, warn_list, crit_list, problem_list, detail_list, sep, status.

check_disk_write

Verify that a disk is writable by creating a test file, writing to it, reading it back and deleting it.

About check_disk_write

check_disk_write verifies that a disk (or folder, network share, mount point, …) is actually writable by performing a full write round-trip: it creates a test file at the given path, writes a recognizable data pattern to it, flushes the data through the OS cache to the device (fsync on Unix, _commit on Windows), reads the file back and verifies the content, and finally deletes the file again. Any failure along the way — permission denied, read-only or full filesystem, data that does not read back as written, a file that cannot be deleted — is CRITICAL out of the box. It works the same on Windows and Unix.

Behaviour at a glance:

• file=<path> (alias path=) is the test file to create. Point it at a file name on the disk you want to verify (e.g. D:\temp\probe.dat or /mnt/backup/probe.dat). The file is deleted again after the test.
• The check refuses to touch a file that already exists — a leftover or unrelated file at the target path is reported as CRITICAL instead of being overwritten and deleted.
• size=<bytes> is how much data to write, either in plain bytes or with a byte unit (512, 64k, 1M). The default is 1k and the maximum is 1M — the check is a quick probe, not a benchmark. Write more than the default when you also want the timing keywords to say something meaningful about disk performance.

Default thresholds: critical has_issues = 1 (no default warning). Add time thresholds (e.g. warning=total_time > 1000) to also alert on a disk that is still writable but slow; keywords used in thresholds are emitted as performance data.

Jump to section:

• Sample Commands
• Command-line Arguments
• Filter keywords

Sample Commands

Verify that a disk is writable (write, read back and delete a 1k test file):

check_disk_write file=/tmp/nscp-write-test.dat
OK: /tmp/nscp-write-test.dat: wrote and read back 1024 bytes in 4ms

On Windows use a path on the drive you want to test:

check_disk_write file=D:\temp\nscp-write-test.dat
OK: D:\temp\nscp-write-test.dat: wrote and read back 1024 bytes in 4ms

Write more data (up to the 1M maximum) and alert when the round-trip gets slow:

check_disk_write file=/tmp/nscp-write-test.dat size=1M "warning=total_time > 1000" "critical=total_time > 5000"
OK: /tmp/nscp-write-test.dat: wrote and read back 1048576 bytes in 8ms|'/tmp/nscp-write-test.dat total_time'=8ms;1000;5000

A target that cannot be written to is CRITICAL:

check_disk_write file=/root/nscp-write-test.dat
CRITICAL: /root/nscp-write-test.dat: failed to create file: Permission denied

check_disk_write file=/no/such/dir/nscp-write-test.dat
CRITICAL: /no/such/dir/nscp-write-test.dat: failed to create file: No such file or directory

The check never touches a file it did not create itself:

check_disk_write file=/tmp/nscp-existing.dat
CRITICAL: /tmp/nscp-existing.dat: file already exists (refusing to overwrite it)

Check via NRPE:

check_nscp_client --host 192.168.56.103 --command check_disk_write --argument "file=/data/nscp-write-test.dat" --argument "size=1M"
OK: /data/nscp-write-test.dat: wrote and read back 1048576 bytes in 9ms

Command-line Arguments

Option	Default Value	Description
file		The test file to create (must not already exist; it is deleted after the test).
path		Alias for file.
size	1k	The amount of data to write, in bytes or with a byte unit (e.g. 512, 4k, 1M). Maximum is 1M.

size:

The amount of data to write, in bytes or with a byte unit (e.g. 512, 4k, 1M). Maximum is 1M.

Default Value: 1k

Common options:

These options are shared by all filter based commands and are described on the common options page; the default values below are specific to this command.

Option	Default Value
filter
warning
warn
critical	has_issues = 1
crit
ok
debug	false
show-all	false
empty-state	unknown
perf-config
escape-html	false
list-separator	,
top-syntax	${status}: ${list}
ok-syntax	%(status): %(list)
empty-syntax	No write test performed
detail-syntax	%(path): %(message)
perf-syntax	%(path)
byte-unit
decimal-separator
decimals	-1
thousands-separator

This command also accepts the standard help options: help, help-pb, show-default, help-short.

Filter keywords

Option	Description
has_issues	1 when the write test failed, else 0
issues	Human-readable description of any problems found (empty when the write test succeeded)
message	Human readable outcome of the write test
path	Path of the test file
read_time	Time spent reading back and verifying the file (ms)
size	Number of bytes written to (and read back from) the test file
total_time	Total time for the create/write/read/delete cycle (ms)
write_time	Time spent creating, writing and flushing the file to disk (ms)

This command also supports the common filter keywords: count, total, ok_count, warn_count, crit_count, problem_count, list, ok_list, warn_list, crit_list, problem_list, detail_list, sep, status.

check_drivesize

Check the size (free-space) of a drive or volume.

Optional mounts (ignore-missing)

By default a drive named with drive= that does not exist fails the whole check:

check_drivesize drive=/data
Drive /data was not found

That is right when the mount is supposed to be there, and wrong when it is not — a removable volume, a filesystem mounted only on some hosts of a group, a share that is attached on demand. ignore-missing=true drops such drives instead:

check_drivesize drive=/data ignore-missing=true
OK: No drives found

Drives that do exist are still checked normally, so mixing the two in one call works and the missing one simply contributes nothing:

check_drivesize drive=/ drive=/data ignore-missing=true "warn=used > 90%" "crit=used > 95%"
OK All 1 drive(s) are ok|'/ used'=43.555GB;906.169;956.511;0;1006.854 '/ used %'=4%;90;95;0;100

ignore-missing=true implies empty-state=ok. Without that, a check whose drives are all missing would report UNKNOWN — trading a false CRITICAL for a false UNKNOWN, which still pages someone. Only the default is changed, so asking for something else explicitly still wins:

check_drivesize drive=/data ignore-missing=true empty-state=warning
WARNING: No drives found

On Windows, require= is unaffected. Listing a drive there is an explicit assertion that it is present, so it stays CRITICAL when absent even under ignore-missing — which is the whole point of listing it. Use drive= + ignore-missing for optional volumes and require= for mandatory ones; they compose in one call.

The same option exists on check_files (for scan paths) and check_single_file (for the file itself).

Time until full (full_in, rate)

Percent thresholds answer “how full is the disk”, but a capacity alert is really asking “how long until it is full” — a 4 TB volume at 91% may have months left while a 10 GB volume at 70% has hours. The trend keywords (full_in, rate, trend_span, trend_samples) answer that question directly. Thresholds on full_in take duration literals:

check_drivesize "warn=full_in < 5d" "crit=full_in < 12h"

The estimate is an ordinary least-squares regression of used bytes over the trend-window (default 24h), fed by the CheckDisk background collector which keeps one sample per trend interval (default 5m) for trend retention (default 7d) per drive — the same approach as Prometheus predict_linear and Zabbix timeleft. History survives agent restarts (persisted hourly and on shutdown at 30-minute granularity), and a filesystem resize discards the now-meaningless history for that drive.

Window choice is the sawtooth knob. Over a window spanning several cleanup cycles (log rotation etc.) the regression measures the net growth, which is what capacity planning wants; a short window inside one cycle reports the burst rate, which is what “something is filling the disk right now” wants. Both are legitimate; pick per check:

check_drivesize "crit=full_in < 2h" trend-window=30m   # burst detector
check_drivesize "warn=full_in < 5d" trend-window=24h   # capacity planning

never vs unknown. full_in/rate are optional numbers: while the drive is shrinking, flat, or has no usable history yet (fewer than 3 samples or less than 3x the sampling interval of span — 15 minutes at the default cadence), they simply have no value. A missing value satisfies no numeric threshold (full_in < 12h is false on a shrinking disk, in both directions), renders as never (full_in) / unknown (rate), and emits no perfdata. full_in = 'never' matches exactly when there is no projection; use trend_span/trend_samples to tell “no data yet” apart from “not growing”, e.g. warn=trend_span < 1h.

With total=true the total row reports the minimum full_in across the matched drives (the soonest-full disk is the one that matters) and the sum of their rates.

The collector can be tuned or disabled under /settings/disk: trend interval, trend retention, and trend in the disable list (disabling disk_free disables trends too, since they ride on the same fetch). Without a collector the keywords stay at their no-value forms.

Jump to section:

• Sample Commands
• Command-line Arguments
• Filter keywords

Sample Commands

To check the size of the C:\ drive and make sure it has at least 10% free space:

check_drivesize "crit=free<10%" drive=c:
L     client CRITICAL: c:: 205GB/223GB used
L     client  Performance data: 'c: free'=18GB;0;22;0;223 'c: free %'=8%;0;9;0;100

To check the size of all the drives and make sure it has at least 10% free space:

check_drivesize "crit=free<10%" drive=*
L     client OK: All drives ok
L     client  Performance data: 'C:\ free'=18GB;0;2;0;223 'C:\ free %'=8%;0;0;0;100 'D:\ free'=18GB;0;4;0;465 'D:\ free %'=3%;0;0;0;100 'M:\ free'=83GB;0;27;0;2746 'M:\ free %'=3%;0;0;0;100

To scan all drives but require that specific drives are present — going CRITICAL if a mandatory drive is missing:

    check_drivesize drive=* require=D: require=E: "crit=free<10%"
CRITICAL: Required drive(s) not found: E: | OK: All drives ok

require (alias mandatory-drives) can be repeated and matches by drive letter (with or without the trailing colon), volume label, or volume id. It is the one UsedPartitionSpace feature gap that wildcard scanning alone could not cover: drive=* silently reports OK when an expected disk has vanished, whereas require= makes that a hard CRITICAL.

To check the size of all the drives and display all values, not just problems:

check_drivesize drive=* --show-all
L     client CRITICAL: c:: 205GB/223GB used
L     client  Performance data: 'c: free'=18GB;0;22;0;223 'c: free %'=8%;0;9;0;100

To check the size of all the drives and return the value in gigabytes. By default, units on performance data will be scaled to “something appropriate”:

check_drivesize "perf-config=*(unit:g)"
L        cli CRITICAL: CRITICAL C:\\: 208.147GB/223.471GB used, D:\\: 399.607GB/465.759GB used
L        cli  Performance data: 'C:\ used'=0.00019g;0.00017;0.00019;0;0.00021 'C:\ used %'=93%;79;89;0;100 'D:\ used'=0.00038g;0.00035;0.00039;0;0.00044 'D:\ used %'=85%;79;89;0;100 'E:\ used'=0g;0;0;0;0 '\\?\Volume{d458535f-27c7-11e4-be66-806e6f6e6963}\ used'=0g;0;0;0;0 '\\?\Volume{d458535f-27c7-11e4-be66-806e6f6e6963}\ used %'=33%;79;89;0;100

To check the size of a mounted volume (c:\volume_test) and make sure it has 1M free space warn if free space is less than 10M:

   check_drivesize "crit=free<1M" "warn=free<10M" drive=c:\\volume_test
   C:: Total: 74.5G - Used: 71.2G (95%) - Free: 3.28G (5%) < critical,C:;5%;10;5;

To check the size of all volumes and make sure they have 1M space free:

check_drivesize "crit=free<1M" drive=all-volumes
L     client OK: All drives ok
L     client  Performance data: 'C:\ free'=18GB;0;2;0;223 'C:\ free %'=8%;0;0;0;100 'D:\ free'=18GB;0;4;0;465 'D:\ free %'=3%;0;0;0;100 'E:\ free'=0B;0;0;0;0 'F:\ free'=0B;0;0;0;0

To check the size of all fixed and network drives and make sure they have at least 1gig free space:

check_drivesize "crit=free<1g" drive=* "filter=type in ('fixed', 'remote')"
L     client OK: All drives ok
L     client  Performance data: 'C:\ free'=18GB;0;2;0;223 'C:\ free %'=8%;0;0;0;100 'D:\ free'=18GB;0;4;0;465 'D:\ free %'=3%;0;0;0;100 'M:\ free'=83GB;0;27;0;2746 'M:\ free %'=3%;0;0;0;100

To check all fixed and network drives but ignore C and F:

check_drivesize "crit=free<1g" drive=* "filter=type in ('fixed', 'remote')" exclude=C:\\ exclude=D:\\
L     client OK: All drives ok
L     client  Performance data: 'M:\ free'=83GB;0;27;0;2746 'M:\ free %'=3%;0;0;0;100

To restrict by filesystem type — for example, only NTFS volumes — use the filesystem keyword (alias fs). The value compared against is whatever the OS reports via GetVolumeInformation, typically uppercase: NTFS, FAT32, exFAT, ReFS, CDFS, UDF. Empty string is reported for unmounted or unreadable volumes.

check_drivesize drive=* "filter=fs = 'NTFS'"
L     client OK: All drives ok
L     client  Performance data: 'C:\ used'=205GB;...

Combine with type to scope further — for example, only fixed disks that are NTFS or ReFS:

check_drivesize drive=* "filter=type = 'fixed' and fs in ('NTFS', 'ReFS')"

Use like for case-insensitive matching, since the OS reports uppercase but a recipe written as 'ntfs' should still work:

check_drivesize drive=* "filter=filesystem like 'ntfs'"

Drop volumes whose filesystem could not be read (e.g. an empty CD/DVD drive):

check_drivesize drive=* "filter=fs != ''"

Default via NRPE:

check_nrpe --host 192.168.56.103 --command check_drivesize
C:\: 205GB/223GB used, D:\: 448GB/466GB used, M:\: 2.6TB/2.68TB used|'C:\ used'=204GB;44;22;0;223 'C:\ used %'=91%;19;9;0;100 'D:\ used'=447GB;93;46;0;465...

Check inode exhaustion (Linux) — a filesystem can be “not full” on bytes yet out of inodes:

check_drivesize drive=/ "warn=inodes_used_pct > 85" "crit=inodes_used_pct > 95" "detail-syntax=${drive} inodes ${inodes_used}/${inodes_total} (${inodes_used_pct}%)"
OK: / inodes 350474/67108864 (1%)

The inode keywords are inodes_total, inodes_free, inodes_used, inodes_free_pct and inodes_used_pct.

Treat a drive that is not mounted as OK rather than an error (ignore-missing):

check_drivesize drive=/data ignore-missing=true
OK: No drives found

Optional and mandatory drives in one call — the real one is still checked:

check_drivesize drive=/ drive=/data ignore-missing=true "warn=used > 90%" "crit=used > 95%"
OK All 1 drive(s) are ok|'/ used'=43.555GB;906.169;956.511;0;1006.854 '/ used %'=4%;90;95;0;100

Alert on time-until-full instead of a percentage (full_in, rate):

check_drivesize "warn=full_in < 5d" "crit=full_in < 12h"
OK All 1 drive(s) are ok

The projection comes from the background collector’s used-space history, so a freshly started agent reports never/unknown until a trend exists (at least 3 samples spanning 3x the sampling interval — 15 minutes at the default 5-minute cadence). A missing value fires no threshold and emits no perfdata.

Show the growth rate and projection per drive:

check_drivesize drive=/ show-all "warn=used > 99%" "detail-syntax=%(drive): %(used)/%(size) used, %(rate) (full in %(full_in), span %(trend_span)s)"
OK: /: 43.716GB/0.983TB used, 9.67MB/day (full in 14570w 5d 08:49, span 31s)

Before any history exists the same check renders the no-data forms:

check_drivesize drive=/ "detail-syntax=${drive}: ${used}/${size} used, ${rate} (full in ${full_in})" "top-syntax=${status}: ${list}"
OK: /: 43.715GB/0.983TB used, unknown (full in never)

Pick the window per purpose — long for capacity planning (net growth across log rotations), short to catch a runaway writer right now:

check_drivesize "warn=full_in < 5d" trend-window=24h    # capacity planning
check_drivesize "crit=full_in < 2h" trend-window=30m    # burst detector

Assert data sufficiency separately from the projection, and match drives with no projection at all:

check_drivesize "warn=trend_span < 1h" "crit=full_in < 12h"
check_drivesize "filter=full_in = 'never'"

Command-line Arguments

WindowsLinux

Option	Default Value	Description
drive		The drives to check.
ignore-unreadable	false	DEPRECATED (manually set filter instead) Ignore drives which are not reachable by the current user.
mounted	false	DEPRECATED (this is now default) Show only mounted rives i.e. drives which have a mount point.
magic		Magic number for use with scaling drive sizes.
exclude		A list of drives not to check
require		Drives that MUST be present: the check goes CRITICAL if any listed drive is not found, even when scanning wildcards. Alias: mandatory-drives.
mandatory-drives		Alias for require.
total	false	Include the total of all matching drives
ignore-missing	false	Silently skip drives named with drive= that do not exist, instead of failing the whole check. Intended for optional mounts. Implies empty-state=ok, so a check whose drives are all missing reports OK rather than UNKNOWN (pass empty-state= to choose a different one). Drives listed in require= are unaffected: those are still CRITICAL when absent, which is the point of listing them.
trend-window	24h	Lookback window for the full_in/rate trend keywords (e.g. 2h, 24h, 7d). A long window measures the net growth across cleanup cycles; a short one catches something filling the disk right now. Bounded by the collector’s trend retention (default 7d).

drive:

The drives to check. Multiple options can be used to check more then one drive or wildcards can be used to indicate multiple drives to check. Examples: drive=c, drive=d:, drive=*, drive=all-volumes, drive=all-drives

ignore-unreadable:

DEPRECATED (manually set filter instead) Ignore drives which are not reachable by the current user. For instance Microsoft Office creates a drive which cannot be read by normal users.

Default Value: false

mounted:

DEPRECATED (this is now default) Show only mounted rives i.e. drives which have a mount point.

Default Value: false

total:

Include the total of all matching drives

Default Value: false

ignore-missing:

Silently skip drives named with drive= that do not exist, instead of failing the whole check. Intended for optional mounts. Implies empty-state=ok, so a check whose drives are all missing reports OK rather than UNKNOWN (pass empty-state= to choose a different one). Drives listed in require= are unaffected: those are still CRITICAL when absent, which is the point of listing them.

Default Value: false

trend-window:

Lookback window for the full_in/rate trend keywords (e.g. 2h, 24h, 7d). A long window measures the net growth across cleanup cycles; a short one catches something filling the disk right now. Bounded by the collector’s trend retention (default 7d).

Default Value: 24h

Common options:

These options are shared by all filter based commands and are described on the common options page; the default values below are specific to this command.

Option	Default Value
filter	mounted = 1
warning	used > 80%
warn
critical	used > 90%
crit
ok
debug	false
show-all	false
empty-state	unknown
perf-config
escape-html	false
list-separator	,
top-syntax	${status} ${problem_list}
ok-syntax	%(status) All %(count) drive(s) are ok
empty-syntax	%(status): No drives found
detail-syntax	${drive_or_name}: ${used}/${size} used
perf-syntax	${drive_or_id}
byte-unit
decimal-separator
decimals	-1
thousands-separator

This command also accepts the standard help options: help, help-pb, show-default, help-short.

Option	Default Value	Description
drive		The drives to check.
exclude		A list of drives (mount points) not to check
total	false	Include the total of all matching drives
ignore-missing	false	Silently skip drives named with drive= that do not exist, instead of failing the whole check. Intended for optional mounts. Implies empty-state=ok, so a check whose drives are all missing reports OK rather than UNKNOWN (pass empty-state= to choose a different one).
trend-window	24h	Lookback window for the full_in/rate trend keywords (e.g. 2h, 24h, 7d). A long window measures the net growth across cleanup cycles; a short one catches something filling the disk right now. Bounded by the collector’s trend retention (default 7d).

drive:

The drives to check. Multiple options can be used to check more than one mount or wildcards can be used to indicate multiple drives to check. Examples: drive=/, drive=/home, drive=*, drive=all-drives

total:

Include the total of all matching drives

Default Value: false

ignore-missing:

Silently skip drives named with drive= that do not exist, instead of failing the whole check. Intended for optional mounts. Implies empty-state=ok, so a check whose drives are all missing reports OK rather than UNKNOWN (pass empty-state= to choose a different one).

Default Value: false

trend-window:

Lookback window for the full_in/rate trend keywords (e.g. 2h, 24h, 7d). A long window measures the net growth across cleanup cycles; a short one catches something filling the disk right now. Bounded by the collector’s trend retention (default 7d).

Default Value: 24h

Common options:

These options are shared by all filter based commands and are described on the common options page; the default values below are specific to this command.

Option	Default Value
filter	mounted = 1
warning	used > 80%
warn
critical	used > 90%
crit
ok
debug	false
show-all	false
empty-state	unknown
perf-config
escape-html	false
list-separator	,
top-syntax	${status} ${problem_list}
ok-syntax	%(status) All %(count) drive(s) are ok
empty-syntax	%(status): No drives found
detail-syntax	${drive_or_name}: ${used}/${size} used
perf-syntax	${drive_or_id}
byte-unit
decimal-separator
decimals	-1
thousands-separator

This command also accepts the standard help options: help, help-pb, show-default, help-short.

Filter keywords

WindowsLinux

Option	Description
convert_bytes()	Convert a byte count to a specific unit and return the numeric value (1024-based). Useful in thresholds.
drive	Technical name of drive
drive_or_id	Drive letter if present if not use id
drive_or_name	Drive letter if present if not use name
erasable	1 (true) if drive is erasable
filesystem	Filesystem name as reported by the OS (e.g. NTFS, FAT32, exFAT, ReFS)
flags	String representation of flags
format_bytes()	Format a number as a human-readable byte string.
format_number()	Render a number with a fixed number of decimals, using the check’s decimal and thousands separators.
free	Shorthand for total_free (Number of free bytes)
free_pct	Shorthand for total_free_pct (% free space)
fs	Shorthand alias for filesystem
full_in	Estimated seconds until the drive is full at the current growth rate, projected from the current free space. Thresholds take durations (full_in < 12h, full_in < 5d); renders as a duration (‘3d 04:00’), or ‘never’ (and no threshold fires) while the drive is shrinking or no trend exists yet. Window set by trend-window (default 24h)
hotplug	1 (true) if drive is hotplugable
id	Drive or id of drive
letter	Letter the drive is mountedd on
media_type	Get the media type
mounted	Check if a drive is mounted
name	Descriptive name of drive
rate	Growth of used space in bytes/day over the trend window, signed (negative = emptying); renders auto-scaled (‘12.3MB/day’), or ‘unknown’ until enough history exists
readable	1 (true) if drive is readable
removable	1 (true) if drive is removable
scale()	Divide a value by a divisor. Useful for arbitrary unit conversions (e.g. decimal Mbps with scale(value, 1000000)).
size	Total size of drive
total_free	Number of free bytes
total_free_pct	% free space
total_used	Number of used bytes
total_used_pct	% used space
trend_samples	Number of samples behind the trend estimate
trend_span	Seconds of history behind the trend estimate (0 = no data); use e.g. warn=trend_span < 1h to assert data sufficiency
type	Type of drive
used	Number of used bytes
used_pct	Shorthand for total_used_pct (% used space)
user_free	Free space available to user (which runs NSClient++)
user_free_pct	% free space available to user
user_used	Number of used bytes (related to user)
user_used_pct	% used space available to user
writable	1 (true) if drive is writable

This command also supports the common filter keywords: count, total, ok_count, warn_count, crit_count, problem_count, list, ok_list, warn_list, crit_list, problem_list, detail_list, sep, status.

Option	Description
convert_bytes()	Convert a byte count to a specific unit and return the numeric value (1024-based). Useful in thresholds.
drive	Technical name of drive (mount point)
drive_or_id	Mount point if present if not use device
drive_or_name	Mount point if present if not use device
erasable	1 (true) if drive is erasable
filesystem	Filesystem type as reported by the OS (e.g. ext4, xfs, btrfs, nfs)
flags	String representation of flags
format_bytes()	Format a number as a human-readable byte string.
format_number()	Render a number with a fixed number of decimals, using the check’s decimal and thousands separators.
free	Shorthand for total_free (Number of free bytes)
free_pct	Shorthand for total_free_pct (% free space)
fs	Shorthand alias for filesystem
full_in	Estimated seconds until the drive is full at the current growth rate, projected from the current free space. Thresholds take durations (full_in < 12h, full_in < 5d); renders as a duration (‘3d 04:00’), or ‘never’ (and no threshold fires) while the drive is shrinking or no trend exists yet. Window set by trend-window (default 24h)
hotplug	1 (true) if drive is hotplugable
id	Drive or id of drive (device)
inodes_free	Number of free inodes
inodes_free_pct	% free inodes
inodes_total	Total number of inodes on the filesystem
inodes_used	Number of used inodes
inodes_used_pct	% used inodes
letter	Letter the drive is mounted on (always empty on Unix)
media_type	Get the media type
mounted	Check if a drive is mounted
name	Descriptive name of drive (device)
rate	Growth of used space in bytes/day over the trend window, signed (negative = emptying); renders auto-scaled (‘12.3MB/day’), or ‘unknown’ until enough history exists
readable	1 (true) if drive is readable
removable	1 (true) if drive is removable
scale()	Divide a value by a divisor. Useful for arbitrary unit conversions (e.g. decimal Mbps with scale(value, 1000000)).
size	Total size of drive
total_free	Number of free bytes
total_free_pct	% free space
total_used	Number of used bytes
total_used_pct	% used space
trend_samples	Number of samples behind the trend estimate
trend_span	Seconds of history behind the trend estimate (0 = no data); use e.g. warn=trend_span < 1h to assert data sufficiency
type	Type of drive
used	Number of used bytes
used_pct	Shorthand for total_used_pct (% used space)
user_free	Free space available to user (which runs NSClient++)
user_free_pct	% free space available to user
user_used	Number of used bytes (related to user)
user_used_pct	% used space available to user
writable	1 (true) if drive is writable

This command also supports the common filter keywords: count, total, ok_count, warn_count, crit_count, problem_count, list, ok_list, warn_list, crit_list, problem_list, detail_list, sep, status.

check_files

Check various aspects of a file and/or folder.

Optional directories (ignore-missing)

A top-level path= that does not exist fails the check by default, so a mistyped or unmounted directory is reported rather than silently scanning nothing:

check_files path=/var/spool/exports
Path was not found: /var/spool/exports

When a directory is legitimately absent some of the time, ignore-missing=true skips it instead:

check_files path=/var/spool/exports ignore-missing=true
No files found

Paths that do exist are still scanned, so the missing one simply contributes no files rather than wiping out the result:

check_files path=/var/log path=/var/spool/exports ignore-missing=true pattern=*.log
OK: All 2 files are ok

Two details:

• It implies empty-state=ok, so a scan whose paths are all missing reports OK rather than UNKNOWN — otherwise the false CRITICAL is merely traded for a false UNKNOWN. Only the default changes; an explicit empty-state= wins.
• The skipped path is not logged as an error. Without the option a missing path writes an Invalid file specified error to the log; with it the path is expected, so it is logged at debug instead.

The same option exists on check_single_file (for the file itself) and check_drivesize (for optional mounts).

Jump to section:

• Sample Commands
• Command-line Arguments
• Filter keywords

Sample Commands

Performance

Order is somewhat important but mainly in the fact that some operations are more costly than others. For instance line_count requires us to read and count the lines in each file so choosing between the following: Fast version: filter=creation < -2d and line_count > 100

Slow version: filter=line_count > 100 and creation < -2d

The first one will be significantly faster if you have a thousand old files and 3 new ones.

On the other hand in this example filter=creation < -2d and size > 100k swapping them would not be noticeable.

Checking versions of .exe files

check_files path=c:/foo/ pattern=*.exe "filter=version != '1.0'" "detail-syntax=%(filename): %(version)" "warn=count > 1" show-all
L        cli WARNING: WARNING: 0/11 files (check_nrpe.exe: , nscp.exe: 0.5.0.16, reporter.exe: 0.5.0.16)
L        cli  Performance data: 'count'=11;1;0

Using the line count with limited recursion:

check_files path=c:/windows pattern=*.txt max-depth=1 "filter=line_count gt 100" "detail-syntax=%(filename): %(line_count)" "warn=count>0" show-all
L        cli WARNING: WARNING: 0/1 files (AsChkDev.txt: 328)
L        cli  Performance data: 'count'=1;0;0

Check file sizes

check_files path=c:/windows pattern=*.txt "detail-syntax=%(filename): %(size)" "warn=size>20k" max-depth=1
L        cli WARNING: WARNING: 1/6 files (AsChkDev.txt: 29738)
L        cli  Performance data: 'AsChkDev.txt size'=29.04101KB;20;0 'AsDCDVer.txt size'=0.02246KB;20;0 'AsHDIVer.txt size'=0.02734KB;20;0 'AsPEToolVer.txt size'=0.08789KB;20;0 'AsToolCDVer.txt size'=0.05273KB;20;0 'csup.txt size'=0.00976KB;20;0

Report a file’s checksum (keywords: md5_checksum, sha1_checksum, sha256_checksum, sha384_checksum, sha512_checksum):

check_files path=/etc pattern=hostname "top-syntax=${list}" "detail-syntax=${filename}=${sha256_checksum}"
hostname=ec4e309d512b118e0ec6451c724b6dd9eaed955a9f1cb68b7d939765ac47af4d

Alert if a file’s checksum drifts from a known-good value (integrity monitoring):

check_files path=/etc pattern=hostname "crit=md5_checksum != '63150f223f8488b21c374ae8ad13fb9c'"
OK: All 1 files are ok

Checksums are computed lazily — they are only calculated when a *_checksum keyword is used in the filter or syntax.

Folder aggregates on the total object (largest/average/smallest file, folder count):

With total, an extra summary row aggregates the matched items. Beyond the summed size, it now also exposes smallest_size, largest_size, average_size and folder_count, so thresholds on the largest or average file are expressible:

check_files path=c:/logs pattern=*.log total "filter=total = 0" "crit=total = 1 and largest_size > 100m" "detail-syntax=largest=${largest_size} avg=${average_size} folders=${folder_count}"
CRITICAL: largest=250M avg=12M folders=3
'total largest'=262144000B 'total average'=12582912B 'total folders'=3

These four keywords are meaningful on the total object (they aggregate across everything add-ed into it); on an individual file row they read as 0.

Skip a scan path that does not exist (ignore-missing):

check_files path=/var/spool/exports ignore-missing=true
No files found

Command-line Arguments

Option	Default Value	Description
path		The path to search for files under.
file		Alias for path.
paths		A comma separated list of paths to scan
pattern	.	The pattern of files to search for (works like a filter but is faster and can be combined with a filter).
max-depth		Maximum depth to recurse
total	filter	Include the total of either (filter) all files matching the filter or (all) all files regardless of the filter
ignore-missing	false	Silently skip top-level paths that do not exist, instead of failing the whole check. Intended for directories that are legitimately absent some of the time. Implies empty-state=ok, so a scan whose paths are all missing reports OK rather than UNKNOWN (pass empty-state= to choose a different one).

path:

The path to search for files under. Notice that specifying multiple path will create an aggregate set you will not check each path individually.In other words if one path contains an error the entire check will result in error.

pattern:

The pattern of files to search for (works like a filter but is faster and can be combined with a filter).

Default Value: *.*

total:

Include the total of either (filter) all files matching the filter or (all) all files regardless of the filter

Default Value: filter

ignore-missing:

Silently skip top-level paths that do not exist, instead of failing the whole check. Intended for directories that are legitimately absent some of the time. Implies empty-state=ok, so a scan whose paths are all missing reports OK rather than UNKNOWN (pass empty-state= to choose a different one).

Default Value: false

Common options:

These options are shared by all filter based commands and are described on the common options page; the default values below are specific to this command.

Option	Default Value
filter
warning
warn
critical
crit
ok
debug	false
show-all	false
empty-state	unknown
perf-config
escape-html	false
list-separator	,
top-syntax	${status}: ${problem_count}/${count} files (${problem_list})
ok-syntax	%(status): All %(count) files are ok
empty-syntax	No files found
detail-syntax	${name}
perf-syntax	${name}
byte-unit
decimal-separator
decimals	-1
thousands-separator

This command also accepts the standard help options: help, help-pb, show-default, help-short.

Filter keywords

Option	Description
access	Last access time
access_l	Last access time (local time)
access_u	Last access time (UTC)
age	Seconds since file was last written
average_size	Average matched file size (aggregate; use on the total object)
creation	When file was created
creation_l	When file was created (local time)
creation_u	When file was created (UTC)
extension	The filename extension
file	The name of the file
filename	The name of the file
folder_count	Number of matched folders (aggregate; use on the total object)
largest_size	Largest matched file size (aggregate; use on the total object)
line_count	Number of lines in the file (text files)
md5_checksum	MD5 checksum of the file content (hex)
name	The name of the file
path	Path of file
sha1_checksum	SHA-1 checksum of the file content (hex)
sha256_checksum	SHA-256 checksum of the file content (hex)
sha384_checksum	SHA-384 checksum of the file content (hex)
sha512_checksum	SHA-512 checksum of the file content (hex)
size	File size
smallest_size	Smallest matched file size (aggregate; use on the total object)
type	Type of item (file or dir)
version	Windows exe/dll file version (empty on Unix)
write	Alias for written
written	When file was last written to
written_l	When file was last written to (local time)
written_u	When file was last written to (UTC)

This command also supports the common filter keywords: count, total, ok_count, warn_count, crit_count, problem_count, list, ok_list, warn_list, crit_list, problem_list, detail_list, sep, status.

check_mount

Check that a filesystem is mounted with the expected fstype and options.

About check_mount

check_mount verifies that filesystems are mounted, and optionally that they are mounted with the expected filesystem type and options. It reads the live mount table (/proc/self/mounts via getmntent) so it reflects the actual running state, not /etc/fstab. It is implemented on Unix only; on Windows it reports that it is not supported.

Behaviour at a glance:

• With no mount= it inspects every real mount (pseudo-filesystems such as proc, sysfs, cgroup, tmpfs overlays … are skipped).
• With mount=<path> it inspects only that mount point, and reports CRITICAL not mounted when nothing is mounted there.
• fstype=<type> requires the mount to use that filesystem type; a mismatch is flagged as an expected fstype differs issue.
• options=<a,b,c> requires each listed mount option to be present; any missing option is flagged as a missing options issue.

Default thresholds: warning has_issues = 1, critical issues like 'not mounted'. So a missing filesystem is CRITICAL while a fstype/options mismatch is WARNING out of the box; override warning= / critical= to change that.

Jump to section:

• Sample Commands
• Command-line Arguments
• Filter keywords

Sample Commands

Check that every real filesystem is mounted as expected:

check_mount
OK: mounts are as expected

Check a single mount point:

check_mount mount=/
OK: mounts are as expected

Require a specific filesystem type (warns when it differs):

check_mount mount=/ fstype=zfs
WARNING: mount / expected fstype differs: zfs != ext4

Require specific mount options (e.g. that / is mounted read-write with noatime):

check_mount mount=/ options=rw,noatime
WARNING: mount / missing options: noatime

A mount point that is not mounted is CRITICAL:

check_mount mount=/does/not/exist
CRITICAL: mount /does/not/exist not mounted

Check via NRPE:

check_nscp_client --host 192.168.56.103 --command check_mount --argument "mount=/data" --argument "fstype=ext4"
OK: mounts are as expected

Command-line Arguments

Option	Default Value	Description
mount		The mount point to check (omit to check all real mounts)
options		The mount options to expect (comma separated)
fstype		The filesystem type to expect

Common options:

These options are shared by all filter based commands and are described on the common options page; the default values below are specific to this command.

Option	Default Value
filter
warning	has_issues = 1
warn
critical	issues like ‘not mounted’
crit
ok
debug	false
show-all	false
empty-state	unknown
perf-config
escape-html	false
list-separator	,
top-syntax	${status}: ${problem_list}
ok-syntax	%(status): mounts are as expected
empty-syntax	check_mount found nothing matching this filter
detail-syntax	mount ${mount} ${issues}
perf-syntax	${mount}
byte-unit
decimal-separator
decimals	-1
thousands-separator

This command also accepts the standard help options: help, help-pb, show-default, help-short.

Filter keywords

Option	Description
device	Device backing this mount
fstype	Filesystem type of this mount
has_issues	1 when any issue was found, else 0
issues	Issues found (empty when the mount is as expected)
mount	Path of the mounted folder
options	Mount options

This command also supports the common filter keywords: count, total, ok_count, warn_count, crit_count, problem_count, list, ok_list, warn_list, crit_list, problem_list, detail_list, sep, status.

check_shadowcopy

Available on Windows only.

Check VSS shadow-copy (Volume Shadow Copy) recency, count and shadow-storage usage per volume. Windows only.

About check_shadowcopy

check_shadowcopy verifies Volume Shadow Copy Service (VSS) snapshots — the data behind “Previous Versions”, scheduled restore points and many backup products. It answers “does each volume still have a recent shadow copy, and is shadow storage healthy?”, which is often the first sign that a backup / snapshot job has silently stopped running.

It reads Win32_ShadowCopy (one row per snapshot) and groups it by volume, then joins per-volume usage from Win32_ShadowStorage. One row is produced per volume that has at least one shadow copy.

newest is seconds, so threshold it with durations: newest > 26h, newest > 2d.

Defaults: WARNING when newest > 26h, CRITICAL when newest > 50h — i.e. tuned for roughly daily snapshots; loosen them (newest > 8d) for weekly schedules. The empty state is OK: a volume with no shadow copies is common and not inherently a problem. If snapshots are required, pass empty-state=critical so their absence is alerted.

Caveats: shadow copies are transient (VSS deletes the oldest when storage fills), so a shrinking copies or rising used_pct is an early warning that older restore points are being aged out. max_size is 0 when shadow storage is configured as “unbounded”, which makes used_pct inert by design.

Jump to section:

• Sample Commands
• Command-line Arguments
• Filter keywords

Sample Commands

Default check on a volume with recent snapshots:

check_shadowcopy
OK: \\?\Volume{4c2b...}\: 12 copies, newest 2026-07-11 07:00:03 UTC

Default check on a host with no shadow copies (empty state is OK):

check_shadowcopy
OK: No shadow copies found

Require snapshots to exist — alert when there are none:

check_shadowcopy empty-state=critical
CRITICAL: No shadow copies found

Alert when the newest snapshot is stale (weekly schedule):

check_shadowcopy "warning=newest > 8d" "critical=newest > 15d"
OK: \\?\Volume{4c2b...}\: 4 copies, newest 2026-07-09 02:00:01 UTC

Alert when shadow storage is nearly full (oldest restore points about to age out):

check_shadowcopy "warning=used_pct > 80" "critical=used_pct > 95"
WARNING: \\?\Volume{4c2b...}\: 20 copies, newest 2026-07-11 07:00:03 UTC

Require at least a minimum number of restore points per volume:

check_shadowcopy "critical=copies < 3"
OK: \\?\Volume{4c2b...}\: 12 copies, newest 2026-07-11 07:00:03 UTC

Custom output with counts and storage usage:

check_shadowcopy "top-syntax=%(status): %(list)" "detail-syntax=%(volume): %(copies) copies, %(used) of %(max_size) used (%(used_pct)%)"
OK: \\?\Volume{4c2b...}\: 12 copies, 1610612736 of 10737418240 used (15%)

Over NRPE against a remote host:

check_nscp_client --host 192.168.56.103 --command check_shadowcopy --argument "warning=newest > 26h"
OK: \\?\Volume{4c2b...}\: 12 copies, newest 2026-07-11 07:00:03 UTC

Command-line Arguments

Common options:

These options are shared by all filter based commands and are described on the common options page; the default values below are specific to this command.

Option	Default Value
filter
warning	newest > 26h
warn
critical	newest > 50h
crit
ok
debug	false
show-all	false
empty-state	ok
perf-config
escape-html	false
list-separator	,
top-syntax	${status}: ${list}
ok-syntax	%(status): All %(count) volume(s) have recent shadow copies.
empty-syntax	%(status): No shadow copies found
detail-syntax	${volume}: ${copies} copies, newest ${newest_date}
perf-syntax	${volume}
byte-unit
decimal-separator
decimals	-1
thousands-separator

This command also accepts the standard help options: help, help-pb, show-default, help-short.

Filter keywords

Option	Description
allocated	Shadow storage currently allocated in bytes
convert_bytes()	Convert a byte count to a specific unit and return the numeric value (1024-based). Useful in thresholds.
copies	Number of shadow copies on this volume
format_bytes()	Format a number as a human-readable byte string.
format_number()	Render a number with a fixed number of decimals, using the check’s decimal and thousands separators.
max_size	Shadow storage maximum in bytes (0 if unbounded/unresolved)
newest	Seconds since the newest shadow copy (-1 if unknown); threshold with durations, e.g. newest > 26h
newest_date	Timestamp of the newest shadow copy on this volume (UTC)
scale()	Divide a value by a divisor. Useful for arbitrary unit conversions (e.g. decimal Mbps with scale(value, 1000000)).
used	Shadow storage used on this volume in bytes
used_pct	Percentage of the shadow-storage maximum in use (0 when max_size is unbounded)
volume	Volume the shadow copies belong to (VolumeName device path)

This command also supports the common filter keywords: count, total, ok_count, warn_count, crit_count, problem_count, list, ok_list, warn_list, crit_list, problem_list, detail_list, sep, status.

check_share

Available on Windows only.

Check Windows SMB shares: list them, or verify that specific required shares exist. Windows only.

About check_share

check_share inspects the host’s SMB shares (Windows Win32_Share). It has two modes:

• List mode (no share=): enumerate every share on the host — useful for inventory or show-all output.
• Required mode (one or more share=<name>): verify that specific shares exist. Each requested share becomes a row with an exists flag, and the check is CRITICAL when a required share is missing (default crit=not exists).

This complements check_uncpath, which checks a remote share’s free space, with the server-side “are my shares published?” view.

Each share (or requested share name) becomes one row in the filter.

Defaults: crit=not exists (inert in list mode, since every listed share exists), empty-state OK (a host with no shares is not inherently a problem). Windows share names are case-insensitive, so share=public matches a Public share.

Jump to section:

• Sample Commands
• Command-line Arguments
• Filter keywords

Sample Commands

List all shares on the host:

check_share
OK: All 3 share(s) ok.|'count'=3

Verify a required share exists (present → OK):

check_share share=C$
OK: C$ (type=disk, path=C:\, exists=1)|'count'=1

Verify a required share exists (missing → CRITICAL):

check_share share=Public
CRITICAL: Public (type=disk, path=, exists=0)|'count'=1

Require several shares at once:

check_share share=Public share=Profiles share=Software
OK: All 3 share(s) ok.|'count'=3

Alert if any non-administrative share is unexpectedly published:

check_share "crit=is_admin = 0" "top-syntax=%(status): %(problem_list)" "detail-syntax=%(name) -> %(path)"
OK: All 5 share(s) ok.

List only non-admin (user-created) shares with their paths:

check_share "filter=is_admin = 0" "top-syntax=%(status): %(list)" "detail-syntax=%(name) (%(type)) -> %(path)"
OK: Public (disk) -> C:\Shared, Profiles (disk) -> D:\Profiles

Over NRPE against a file server:

check_nscp_client --host 192.168.56.103 --command check_share --argument "share=Public" --argument "share=Profiles"
OK: All 2 share(s) ok.

Command-line Arguments

Option	Default Value	Description
share		Require a specific share to exist (repeatable). The check is CRITICAL when a requested share is missing. When omitted, all shares are listed instead.

Common options:

These options are shared by all filter based commands and are described on the common options page; the default values below are specific to this command.

Option	Default Value
filter
warning
warn
critical	not exists
crit
ok
debug	false
show-all	false
empty-state	ok
perf-config
escape-html	false
list-separator	,
top-syntax	${status}: ${list}
ok-syntax	%(status): All %(count) share(s) ok.
empty-syntax	%(status): No shares found
detail-syntax	${name} (type=${type}, path=${path}, exists=${exists})
perf-syntax	${name}
byte-unit
decimal-separator
decimals	-1
thousands-separator

This command also accepts the standard help options: help, help-pb, show-default, help-short.

Filter keywords

Option	Description
description	Share description / comment
exists	1 if the share exists (0 for a requested-but-missing share)
is_admin	1 for an administrative share (C$, ADMIN$, IPC$)
name	Share name (e.g. C$, Public)
path	Local path the share maps to (empty for IPC$)
type	Share kind: disk, printer, device, ipc or unknown

This command also supports the common filter keywords: count, total, ok_count, warn_count, crit_count, problem_count, list, ok_list, warn_list, crit_list, problem_list, detail_list, sep, status.

check_single_file

Check various aspects of a single file (size, age, line count, version, …). Simpler alternative to check_files when you only need to inspect one specific file.

About check_single_file

check_single_file is a focused variant of check_files for inspecting a single, known path. There is no path + pattern scan and no recursion — you point it at one file and apply a filter / threshold to its attributes (size, age, version, line_count, …).

Behaviour at a glance:

• If file= (or its alias path=) is missing → UNKNOWN with No file specified (use file=<path>).
• If the file does not exist (or the path points at a directory) → UNKNOWN with File not found: <path>.
• Otherwise the single file is fed to the filter and warn / crit decide the status. With no thresholds the result is OK confirming the file exists.

Files that are legitimately absent (ignore-missing)

By default a missing file fails the check, which is what you want when the file is supposed to be there:

check_single_file file=/var/reports/nightly.csv
File not found: /var/reports/nightly.csv

Some files are only there some of the time — a lock file, a report written after a run, a spool entry. ignore-missing=true returns OK instead, naming the path so the result cannot be mistaken for “the file was inspected and was fine”:

check_single_file file=/var/reports/nightly.csv ignore-missing=true
File not found (ignored): /var/reports/nightly.csv

A file that is present is checked exactly as before; the option only affects the missing case.

The same option exists on check_files (for scan paths) and check_drivesize (for optional mounts).

Jump to section:

• Sample Commands
• Command-line Arguments
• Filter keywords

Sample Commands

Confirm a file exists (no thresholds)

check_single_file file=C:/Windows/System32/notepad.exe
L        cli OK: notepad.exe (size=201728, age=12345)

Warn when a log file grows too large

check_single_file file=C:/logs/app.log "warn=size > 10M" "crit=size > 100M"
L        cli OK: app.log (size=524288, age=42)

Warn when a file becomes stale (age in seconds)

check_single_file file=C:/windows/WindowsUpdate.log "warn=age > 5m" "crit=age > 1h"
L        cli CRITICAL: WindowsUpdate.log (size=276, age=917)

Check a specific binary’s version

check_single_file file="C:/Windows/System32/notepad.exe" "crit=version != '1.2.3.4'" "detail-syntax=%(filename): %(version)"
L        cli CRITICAL: notepad.exe: 6.2.26100.8115

Custom output formatting

The same top-syntax / detail-syntax / ok-syntax keys as check_files are accepted. Because there is exactly one item, %(list) in the top template expands to the detail line for that single file:

check_single_file file=C:/windows/WindowsUpdate.log "warn=size > 1M" "top-syntax=%(status) %(list)" "detail-syntax=%(filename) is %(size) bytes, last written %(written)"
L        cli OK: OK WindowsUpdate.log is 276 bytes, last written 2026-04-30 11:42:36

path= works as an alias for file=

This makes it easy to migrate command lines from check_files:

check_single_file path=C:/Windows/win.ini
L        cli OK: win.ini (size=92, age=873123)

Treat a file that is not there yet as OK (ignore-missing):

check_single_file file=/tmp/no-such-report.csv ignore-missing=true
File not found (ignored): /tmp/no-such-report.csv

Command-line Arguments

Option	Default Value	Description
file		The file to check.
path		Alias for file.
ignore-missing	false	Return OK instead of failing when the file does not exist. Intended for files that are legitimately absent some of the time, such as a lock file or a report that is only written after a run.

ignore-missing:

Return OK instead of failing when the file does not exist. Intended for files that are legitimately absent some of the time, such as a lock file or a report that is only written after a run.

Default Value: false

Common options:

These options are shared by all filter based commands and are described on the common options page; the default values below are specific to this command.

Option	Default Value
filter
warning
warn
critical
crit
ok
debug	false
show-all	false
empty-state	ok
perf-config
escape-html	false
list-separator	,
top-syntax	%(status): %(list)
ok-syntax	%(status): %(filename) is ok
empty-syntax	No file inspected
detail-syntax	%(filename) (size=%(size), age=%(age))
perf-syntax	%(filename)
byte-unit
decimal-separator
decimals	-1
thousands-separator

This command also accepts the standard help options: help, help-pb, show-default, help-short.

Filter keywords

Option	Description
access	Last access time
access_l	Last access time (local time)
access_u	Last access time (UTC)
age	Seconds since file was last written
average_size	Average matched file size (aggregate; use on the total object)
creation	When file was created
creation_l	When file was created (local time)
creation_u	When file was created (UTC)
extension	The filename extension
file	The name of the file
filename	The name of the file
folder_count	Number of matched folders (aggregate; use on the total object)
largest_size	Largest matched file size (aggregate; use on the total object)
line_count	Number of lines in the file (text files)
md5_checksum	MD5 checksum of the file content (hex)
name	The name of the file
path	Path of file
sha1_checksum	SHA-1 checksum of the file content (hex)
sha256_checksum	SHA-256 checksum of the file content (hex)
sha384_checksum	SHA-384 checksum of the file content (hex)
sha512_checksum	SHA-512 checksum of the file content (hex)
size	File size
smallest_size	Smallest matched file size (aggregate; use on the total object)
type	Type of item (file or dir)
version	Windows exe/dll file version (empty on Unix)
write	Alias for written
written	When file was last written to
written_l	When file was last written to (local time)
written_u	When file was last written to (UTC)

This command also supports the common filter keywords: count, total, ok_count, warn_count, crit_count, problem_count, list, ok_list, warn_list, crit_list, problem_list, detail_list, sep, status.

check_storagepool

Available on Windows only.

Check Storage Spaces pool health and capacity. Windows only.

Checks the health and capacity of Windows Storage Spaces pools, read from MSFT_StoragePool in the root\Microsoft\Windows\Storage WMI namespace. The primordial pool (the reservoir of unpooled physical disks) is excluded, so only real Storage Spaces are reported.

The capacity keywords (capacity, used, free, free_pct, used_pct) are emitted as performance data when used in thresholds.

Defaults: WARNING on Warning health or < 20% free; CRITICAL on Unhealthy health or < 10% free. If the Storage namespace/class is unavailable (no Storage Spaces, older Windows) the check reports no pools and returns OK — it never fails just because the feature is absent. This is a natural companion to the physical-disk device state exposed by check_disk_health.

Jump to section:

• Sample Commands
• Command-line Arguments
• Filter keywords

Sample Commands

Check Storage Spaces pool health and capacity (Windows):

check_storagepool
OK: All storage pools are healthy.
'Pool1 free_pct'=64%;20;10 'Pool1 capacity'=8.0T;; 'Pool1 used'=2.9T;;

By default the check is WARNING when a pool reports Warning health or drops below 20% free, and CRITICAL when a pool is Unhealthy or below 10% free. A system with no Storage Spaces pools returns OK.

Alert only on pool health, ignoring capacity:

check_storagepool "warn=health_status = 'Warning'" "crit=health_status = 'Unhealthy' or is_readonly = 1" "detail-syntax=${name}: ${health_status} (${operational_status})"
CRITICAL: Data: Unhealthy (Unhealthy)

Keywords: name, health_status (Healthy/Warning/Unhealthy/Unknown), operational_status, capacity, used, free, free_pct, used_pct, is_readonly.

Command-line Arguments

Common options:

These options are shared by all filter based commands and are described on the common options page; the default values below are specific to this command.

Option	Default Value
filter
warning	health_status = ‘Warning’ or free_pct < 20
warn
critical	health_status = ‘Unhealthy’ or free_pct < 10
crit
ok
debug	false
show-all	false
empty-state	ok
perf-config
escape-html	false
list-separator	,
top-syntax	${status}: ${list}
ok-syntax	%(status): All storage pools are healthy.
empty-syntax	%(status): No storage pools found
detail-syntax	${name}: ${health_status}, ${used}/${capacity} used
perf-syntax	${name}
byte-unit
decimal-separator
decimals	-1
thousands-separator

This command also accepts the standard help options: help, help-pb, show-default, help-short.

Filter keywords

Option	Description
capacity	Total pool capacity in bytes
convert_bytes()	Convert a byte count to a specific unit and return the numeric value (1024-based). Useful in thresholds.
format_bytes()	Format a number as a human-readable byte string.
format_number()	Render a number with a fixed number of decimals, using the check’s decimal and thousands separators.
free	Unallocated (free) pool space in bytes
free_pct	Percentage of free pool space
health_status	Pool health: Healthy, Warning, Unhealthy or Unknown
is_readonly	1 if the pool is read-only
name	Storage pool friendly name
operational_status	Pool operational status, synthesised single value: OK, ReadOnly, or the health string
scale()	Divide a value by a divisor. Useful for arbitrary unit conversions (e.g. decimal Mbps with scale(value, 1000000)).
used	Allocated (used) pool space in bytes
used_pct	Percentage of used pool space

This command also supports the common filter keywords: count, total, ok_count, warn_count, crit_count, problem_count, list, ok_list, warn_list, crit_list, problem_list, detail_list, sep, status.

check_uncpath

Check free space on a UNC path (server share), with optional alternate credentials.

Checks free space on a UNC path (\\server\share), optionally authenticating with alternate credentials. This fills a gap check_drivesize cannot: it only sees OS-mounted drives and cannot take an arbitrary UNC path or supply credentials.

The space keywords (size, free, used, user_free, free_pct, used_pct) are emitted as performance data when used in thresholds.

Options: path= (repeatable), user=, password=. Defaults mirror check_drivesize (used_pct > 80 warning, > 90 critical). On Windows the free space comes from GetDiskFreeSpaceEx, with an optional WNetAddConnection2 for alternate credentials that is disconnected after the query. On non-Windows the path must already be mounted (alternate-credential UNC access is Windows-only).

Jump to section:

• Sample Commands
• Command-line Arguments
• Filter keywords

Sample Commands

Check free space on a UNC path:

check_uncpath path=\\fileserver\data "crit=used_pct > 90"
OK: \\fileserver\data: 1.2T/2.0T used (800G free)
'\\fileserver\data used_pct'=60%;80;90 '\\fileserver\data free'=800G;;

Unlike check_drivesize (which only sees OS-mounted drives), check_uncpath takes an arbitrary \\server\share and reports quota-aware free space.

With alternate credentials (Windows):

check_uncpath path=\\fileserver\backups user=DOMAIN\svc password=secret "crit=free < 100g"
OK: \\fileserver\backups: 400G/2.0T used (1.6T free)

user/password map to a temporary WNetAddConnection2 before the query and are disconnected afterwards. user_free reports the free space available to the querying account (honouring per-user quotas) as distinct from the share’s total free.

Multiple paths:

check_uncpath path=\\a\share path=\\b\share "crit=free_pct < 10" "top-syntax=${status}: ${problem_list}"

Command-line Arguments

Option	Default Value	Description
path		The UNC path(s) to check, e.g. \server\share. Repeat for multiple.
user		Optional user name for alternate credentials (Windows).
password		Optional password for alternate credentials (Windows).

Common options:

These options are shared by all filter based commands and are described on the common options page; the default values below are specific to this command.

Option	Default Value
filter
warning	used_pct > 80
warn
critical	used_pct > 90
crit
ok
debug	false
show-all	false
empty-state	unknown
perf-config
escape-html	false
list-separator	,
top-syntax	${status}: ${list}
ok-syntax	%(status): All UNC paths are ok.
empty-syntax	%(status): No paths checked
detail-syntax	${path}: ${used}/${size} used (${free} free)
perf-syntax	${path}
byte-unit
decimal-separator
decimals	-1
thousands-separator

This command also accepts the standard help options: help, help-pb, show-default, help-short.

Filter keywords

Option	Description
convert_bytes()	Convert a byte count to a specific unit and return the numeric value (1024-based). Useful in thresholds.
format_bytes()	Format a number as a human-readable byte string.
format_number()	Render a number with a fixed number of decimals, using the check’s decimal and thousands separators.
free	Free space on the share in bytes
free_pct	Percentage of free space
path	The UNC path being checked
scale()	Divide a value by a divisor. Useful for arbitrary unit conversions (e.g. decimal Mbps with scale(value, 1000000)).
size	Total size of the share in bytes
used	Used space on the share in bytes
used_pct	Percentage of used space
user_free	Free space available to the querying user (quota-aware) in bytes

This command also supports the common filter keywords: count, total, ok_count, warn_count, crit_count, problem_count, list, ok_list, warn_list, crit_list, problem_list, detail_list, sep, status.

Configuration

Path / Section	Description
/settings/disk

/settings/disk

Key	Default Value	Description
collection interval	10s	Collection interval
disable		Disable automatic checks
max collection errors	10	Maximum consecutive collection errors
trend interval	5m	Trend sampling interval
trend retention	7d	Trend history retention

# 
[/settings/disk]
collection interval=10s
max collection errors=10
trend interval=5m
trend retention=7d

Collection interval

How often disk I/O and disk free data is sampled. All rates (IOPS, bytes/sec) and latencies reported by check_disk_io and check_disk_health are averages over one such interval, so lowering it makes them react faster and follow short spikes more closely, at the cost of more frequent sampling. Duration, e.g. 10s.

Key	Description
Path:	/settings/disk
Key:	collection interval
Advanced:	Yes (means it is not commonly used)
Default value:	10s

Sample:

[/settings/disk]
# Collection interval
collection interval=10s

Disable automatic checks

A comma separated list of checks to disable in the collector: disk_io, disk_free, trend. Please note disabling these will mean part of NSClient++ will no longer function as expected.

Key	Description
Path:	/settings/disk
Key:	disable
Advanced:	Yes (means it is not commonly used)
Default value:	N/A

Sample:

[/settings/disk]
# Disable automatic checks
disable=

Maximum consecutive collection errors

How many consecutive failed fetches disable a collection (disk I/O or disk free) for the rest of the process lifetime. A single failure is not treated as the source being unavailable, since the collector retries on the next interval and any success resets the count. Set to 0 to retry forever.

Key	Description
Path:	/settings/disk
Key:	max collection errors
Advanced:	Yes (means it is not commonly used)
Default value:	10

Sample:

[/settings/disk]
# Maximum consecutive collection errors
max collection errors=10

Trend sampling interval

How often a used-space sample is kept per drive for the check_drivesize trend keywords (full_in/rate). Duration, e.g. 5m.

Key	Description
Path:	/settings/disk
Key:	trend interval
Advanced:	Yes (means it is not commonly used)
Default value:	5m

Sample:

[/settings/disk]
# Trend sampling interval
trend interval=5m

Trend history retention

How much used-space history is kept per drive; bounds the largest useful trend-window. Duration, e.g. 7d.

Key	Description
Path:	/settings/disk
Key:	trend retention
Advanced:	Yes (means it is not commonly used)
Default value:	7d

Sample:

[/settings/disk]
# Trend history retention
trend retention=7d