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_drivesize	Check the size (free-space) of a drive or volume.
check_files	Check various aspects of a file and/or folder.
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_disk_health

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

Jump to section:

• Command-line Arguments
• Filter keywords

Command-line Arguments

Option	Default Value	Description
filter	name != '_Total'	Filter which marks interesting items.
warning	free_pct < 20 or percent_disk_time > 80	Filter which marks items which generates a warning state.
warn		Short alias for warning
critical	free_pct < 10 or percent_disk_time > 95	Filter which marks items which generates a critical state.
crit		Short alias for critical.
ok		Filter which marks items which generates an ok state.
debug	N/A	Show debugging information in the log
show-all	N/A	Show details for all matches regardless of status (normally details are only showed for warnings and criticals).
empty-state	critical	Return status to use when nothing matched filter.
perf-config		Performance data generation configuration
escape-html	N/A	Escape any < and > characters to prevent HTML encoding
help	N/A	Show help screen (this screen)
help-pb	N/A	Show help screen as a protocol buffer payload
show-default	N/A	Show default values for a given command
help-short	N/A	Show help screen (short format).
top-syntax	${status}: ${list}	Top level syntax.
ok-syntax	%(status): All disks are healthy.	ok syntax.
empty-syntax		Empty syntax.
detail-syntax	${name}: ${free_pct}% free, ${percent_disk_time}% busy, q=${queue_length} iops=${iops}	Detail level syntax.
perf-syntax	${name}	Performance alias syntax.

filter:

Filter which marks interesting items. Interesting items are items which will be included in the check. They do not denote warning or critical state instead it defines which items are relevant and you can remove unwanted items.

Default Value: name != '_Total'

warning:

Filter which marks items which generates a warning state. If anything matches this filter the return status will be escalated to warning.

Default Value: free_pct < 20 or percent_disk_time > 80

critical:

Filter which marks items which generates a critical state. If anything matches this filter the return status will be escalated to critical.

Default Value: free_pct < 10 or percent_disk_time > 95

ok:

Filter which marks items which generates an ok state. If anything matches this any previous state for this item will be reset to ok.

empty-state:

Return status to use when nothing matched filter. If no filter is specified this will never happen unless the file is empty.

Default Value: critical

perf-config:

Performance data generation configuration TODO: obj ( key: value; key: value) obj (key:valuer;key:value)

top-syntax:

Top level syntax. Used to format the message to return can include text as well as special keywords which will include information from the checks. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).

Default Value: ${status}: ${list}

ok-syntax:

ok syntax. DEPRECATED! This is the syntax for when an ok result is returned. This value will not be used if your syntax contains %(list) or %(count).

Default Value: %(status): All disks are healthy.

empty-syntax:

Empty syntax. DEPRECATED! This is the syntax for when nothing matches the filter.

detail-syntax:

Detail level syntax. Used to format each resulting item in the message. %(list) will be replaced with all the items formated by this syntax string in the top-syntax. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).

Default Value: ${name}: ${free_pct}% free, ${percent_disk_time}% busy, q=${queue_length} iops=${iops}

perf-syntax:

Performance alias syntax. This is the syntax for the base names of the performance data.

Default Value: ${name}

Filter keywords

Option	Description
free	Free disk space in bytes
free_pct	Percentage of free disk space
iops	Total IOPS (reads + writes)
name	Drive 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
reads_per_sec	Read IOPS
split_io_per_sec	Split I/O operations per second
total_bytes_per_sec	Total bytes per second (read + write)
used	Used disk space in bytes
used_pct	Percentage of used disk space
user_free	Free disk space available to current user in bytes
write_bytes_per_sec	Bytes written per second
writes_per_sec	Write IOPS

Common options for all checks:

Option	Description
count	Number of items matching the filter.
crit_count	Number of items matched the critical criteria.
crit_list	A list of all items which matched the critical criteria.
detail_list	A special list with critical, then warning and finally ok.
list	A list of all items which matched the filter.
ok_count	Number of items matched the ok criteria.
ok_list	A list of all items which matched the ok criteria.
problem_count	Number of items matched either warning or critical criteria.
problem_list	A list of all items which matched either the critical or the warning criteria.
status	The returned status (OK/WARN/CRIT/UNKNOWN).
total	Total number of items.
warn_count	Number of items matched the warning criteria.
warn_list	A list of all items which matched the warning criteria.

check_disk_io

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

Jump to section:

• Command-line Arguments
• Filter keywords

Command-line Arguments

Option	Default Value	Description
filter	name != '_Total'	Filter which marks interesting items.
warning	percent_disk_time > 80	Filter which marks items which generates a warning state.
warn		Short alias for warning
critical	percent_disk_time > 95	Filter which marks items which generates a critical state.
crit		Short alias for critical.
ok		Filter which marks items which generates an ok state.
debug	N/A	Show debugging information in the log
show-all	N/A	Show details for all matches regardless of status (normally details are only showed for warnings and criticals).
empty-state	critical	Return status to use when nothing matched filter.
perf-config		Performance data generation configuration
escape-html	N/A	Escape any < and > characters to prevent HTML encoding
help	N/A	Show help screen (this screen)
help-pb	N/A	Show help screen as a protocol buffer payload
show-default	N/A	Show default values for a given command
help-short	N/A	Show help screen (short format).
top-syntax	${status}: ${list}	Top level syntax.
ok-syntax	%(status): All disk I/O seems ok.	ok syntax.
empty-syntax		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}	Detail level syntax.
perf-syntax	${name}	Performance alias syntax.

filter:

Filter which marks interesting items. Interesting items are items which will be included in the check. They do not denote warning or critical state instead it defines which items are relevant and you can remove unwanted items.

Default Value: name != '_Total'

warning:

Filter which marks items which generates a warning state. If anything matches this filter the return status will be escalated to warning.

Default Value: percent_disk_time > 80

critical:

Filter which marks items which generates a critical state. If anything matches this filter the return status will be escalated to critical.

Default Value: percent_disk_time > 95

ok:

Filter which marks items which generates an ok state. If anything matches this any previous state for this item will be reset to ok.

empty-state:

Return status to use when nothing matched filter. If no filter is specified this will never happen unless the file is empty.

Default Value: critical

perf-config:

Performance data generation configuration TODO: obj ( key: value; key: value) obj (key:valuer;key:value)

top-syntax:

Top level syntax. Used to format the message to return can include text as well as special keywords which will include information from the checks. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).

Default Value: ${status}: ${list}

ok-syntax:

ok syntax. DEPRECATED! This is the syntax for when an ok result is returned. This value will not be used if your syntax contains %(list) or %(count).

Default Value: %(status): All disk I/O seems ok.

empty-syntax:

Empty syntax. DEPRECATED! This is the syntax for when nothing matches the filter.

detail-syntax:

Detail level syntax. Used to format each resulting item in the message. %(list) will be replaced with all the items formated by this syntax string in the top-syntax. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).

Default Value: ${name}: ${percent_disk_time}% busy, read=${read_bytes_per_sec}B/s write=${write_bytes_per_sec}B/s q=${queue_length}

perf-syntax:

Performance alias syntax. This is the syntax for the base names of the performance data.

Default Value: ${name}

Filter keywords

Option	Description
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
reads_per_sec	Read IOPS
split_io_per_sec	Split I/O operations per second
total_bytes_per_sec	Total bytes per second (read + write)
write_bytes_per_sec	Bytes written per second
writes_per_sec	Write IOPS

Common options for all checks:

Option	Description
count	Number of items matching the filter.
crit_count	Number of items matched the critical criteria.
crit_list	A list of all items which matched the critical criteria.
detail_list	A special list with critical, then warning and finally ok.
list	A list of all items which matched the filter.
ok_count	Number of items matched the ok criteria.
ok_list	A list of all items which matched the ok criteria.
problem_count	Number of items matched either warning or critical criteria.
problem_list	A list of all items which matched either the critical or the warning criteria.
status	The returned status (OK/WARN/CRIT/UNKNOWN).
total	Total number of items.
warn_count	Number of items matched the warning criteria.
warn_list	A list of all items which matched the warning criteria.

check_drivesize

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

Jump to section:

• Sample Commands
• Command-line Arguments
• Filter keywords

Sample Commands

To edit these sample please edit this page

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

Command-line Arguments

Option	Default Value	Description
filter	mounted = 1	Filter which marks interesting items.
warning	used > 80%	Filter which marks items which generates a warning state.
warn		Short alias for warning
critical	used > 90%	Filter which marks items which generates a critical state.
crit		Short alias for critical.
ok		Filter which marks items which generates an ok state.
debug	N/A	Show debugging information in the log
show-all	N/A	Show details for all matches regardless of status (normally details are only showed for warnings and criticals).
empty-state	unknown	Return status to use when nothing matched filter.
perf-config		Performance data generation configuration
escape-html	N/A	Escape any < and > characters to prevent HTML encoding
help	N/A	Show help screen (this screen)
help-pb	N/A	Show help screen as a protocol buffer payload
show-default	N/A	Show default values for a given command
help-short	N/A	Show help screen (short format).
top-syntax	${status} ${problem_list}	Top level syntax.
ok-syntax	%(status) All %(count) drive(s) are ok	ok syntax.
empty-syntax	%(status): No drives found	Empty syntax.
detail-syntax	${drive_or_name}: ${used}/${size} used	Detail level syntax.
perf-syntax	${drive_or_id}	Performance alias syntax.
drive		The drives to check.
ignore-unreadable	N/A	DEPRECATED (manually set filter instead) Ignore drives which are not reachable by the current user.
mounted	N/A	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
total	N/A	Include the total of all matching drives

filter:

Filter which marks interesting items. Interesting items are items which will be included in the check. They do not denote warning or critical state instead it defines which items are relevant and you can remove unwanted items.

Default Value: mounted = 1

warning:

Filter which marks items which generates a warning state. If anything matches this filter the return status will be escalated to warning.

Default Value: used > 80%

critical:

Filter which marks items which generates a critical state. If anything matches this filter the return status will be escalated to critical.

Default Value: used > 90%

ok:

Filter which marks items which generates an ok state. If anything matches this any previous state for this item will be reset to ok.

empty-state:

Return status to use when nothing matched filter. If no filter is specified this will never happen unless the file is empty.

Default Value: unknown

perf-config:

Performance data generation configuration TODO: obj ( key: value; key: value) obj (key:valuer;key:value)

top-syntax:

Top level syntax. Used to format the message to return can include text as well as special keywords which will include information from the checks. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).

Default Value: ${status} ${problem_list}

ok-syntax:

ok syntax. DEPRECATED! This is the syntax for when an ok result is returned. This value will not be used if your syntax contains %(list) or %(count).

Default Value: %(status) All %(count) drive(s) are ok

empty-syntax:

Empty syntax. DEPRECATED! This is the syntax for when nothing matches the filter.

Default Value: %(status): No drives found

detail-syntax:

Detail level syntax. Used to format each resulting item in the message. %(list) will be replaced with all the items formated by this syntax string in the top-syntax. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).

Default Value: ${drive_or_name}: ${used}/${size} used

perf-syntax:

Performance alias syntax. This is the syntax for the base names of the performance data.

Default Value: ${drive_or_id}

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.

Filter keywords

Option	Description
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
free	Shorthand for total_free (Number of free bytes)
free_pct	Shorthand for total_free_pct (% free space)
fs	Shorthand alias for filesystem
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
readable	1 (true) if drive is readable
removable	1 (true) if drive is removable
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
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

Common options for all checks:

Option	Description
count	Number of items matching the filter.
crit_count	Number of items matched the critical criteria.
crit_list	A list of all items which matched the critical criteria.
detail_list	A special list with critical, then warning and finally ok.
list	A list of all items which matched the filter.
ok_count	Number of items matched the ok criteria.
ok_list	A list of all items which matched the ok criteria.
problem_count	Number of items matched either warning or critical criteria.
problem_list	A list of all items which matched either the critical or the warning criteria.
status	The returned status (OK/WARN/CRIT/UNKNOWN).
total	Total number of items.
warn_count	Number of items matched the warning criteria.
warn_list	A list of all items which matched the warning criteria.

check_files

Check various aspects of a file and/or folder.

Jump to section:

• Sample Commands
• Command-line Arguments
• Filter keywords

Sample Commands

To edit these sample please edit this page

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

Command-line Arguments

Option	Default Value	Description
filter		Filter which marks interesting items.
warning		Filter which marks items which generates a warning state.
warn		Short alias for warning
critical		Filter which marks items which generates a critical state.
crit		Short alias for critical.
ok		Filter which marks items which generates an ok state.
debug	N/A	Show debugging information in the log
show-all	N/A	Show details for all matches regardless of status (normally details are only showed for warnings and criticals).
empty-state	unknown	Return status to use when nothing matched filter.
perf-config		Performance data generation configuration
escape-html	N/A	Escape any < and > characters to prevent HTML encoding
help	N/A	Show help screen (this screen)
help-pb	N/A	Show help screen as a protocol buffer payload
show-default	N/A	Show default values for a given command
help-short	N/A	Show help screen (short format).
top-syntax	${status}: ${problem_count}/${count} files (${problem_list})	Top level syntax.
ok-syntax	%(status): All %(count) files are ok	ok syntax.
empty-syntax	No files found	Empty syntax.
detail-syntax	${name}	Detail level syntax.
perf-syntax	${name}	Performance alias syntax.
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

filter:

Filter which marks interesting items. Interesting items are items which will be included in the check. They do not denote warning or critical state instead it defines which items are relevant and you can remove unwanted items.

warning:

Filter which marks items which generates a warning state. If anything matches this filter the return status will be escalated to warning.

critical:

Filter which marks items which generates a critical state. If anything matches this filter the return status will be escalated to critical.

ok:

Filter which marks items which generates an ok state. If anything matches this any previous state for this item will be reset to ok.

empty-state:

Return status to use when nothing matched filter. If no filter is specified this will never happen unless the file is empty.

Default Value: unknown

perf-config:

Performance data generation configuration TODO: obj ( key: value; key: value) obj (key:valuer;key:value)

top-syntax:

Top level syntax. Used to format the message to return can include text as well as special keywords which will include information from the checks. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).

Default Value: ${status}: ${problem_count}/${count} files (${problem_list})

ok-syntax:

ok syntax. DEPRECATED! This is the syntax for when an ok result is returned. This value will not be used if your syntax contains %(list) or %(count).

Default Value: %(status): All %(count) files are ok

empty-syntax:

Empty syntax. DEPRECATED! This is the syntax for when nothing matches the filter.

Default Value: No files found

detail-syntax:

Detail level syntax. Used to format each resulting item in the message. %(list) will be replaced with all the items formated by this syntax string in the top-syntax. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).

Default Value: ${name}

perf-syntax:

Performance alias syntax. This is the syntax for the base names of the performance data.

Default Value: ${name}

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

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
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
line_count	Number of lines in the file (text files)
name	The name of the file
path	Path of file
size	File size
type	Type of item (file or dir)
version	Windows exe/dll file version
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)

Common options for all checks:

Option	Description
count	Number of items matching the filter.
crit_count	Number of items matched the critical criteria.
crit_list	A list of all items which matched the critical criteria.
detail_list	A special list with critical, then warning and finally ok.
list	A list of all items which matched the filter.
ok_count	Number of items matched the ok criteria.
ok_list	A list of all items which matched the ok criteria.
problem_count	Number of items matched either warning or critical criteria.
problem_list	A list of all items which matched either the critical or the warning criteria.
status	The returned status (OK/WARN/CRIT/UNKNOWN).
total	Total number of items.
warn_count	Number of items matched the warning criteria.
warn_list	A list of all items which matched the warning criteria.

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.

Jump to section:

• Sample Commands
• Command-line Arguments
• Filter keywords

Sample Commands

To edit these sample please edit this page

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)

Command-line Arguments

Option	Default Value	Description
filter		Filter which marks interesting items.
warning		Filter which marks items which generates a warning state.
warn		Short alias for warning
critical		Filter which marks items which generates a critical state.
crit		Short alias for critical.
ok		Filter which marks items which generates an ok state.
debug	N/A	Show debugging information in the log
show-all	N/A	Show details for all matches regardless of status (normally details are only showed for warnings and criticals).
empty-state	ok	Return status to use when nothing matched filter.
perf-config		Performance data generation configuration
escape-html	N/A	Escape any < and > characters to prevent HTML encoding
help	N/A	Show help screen (this screen)
help-pb	N/A	Show help screen as a protocol buffer payload
show-default	N/A	Show default values for a given command
help-short	N/A	Show help screen (short format).
top-syntax	%(status): %(list)	Top level syntax.
ok-syntax	%(status): %(filename) is ok	ok syntax.
empty-syntax	No file inspected	Empty syntax.
detail-syntax	%(filename) (size=%(size), age=%(age))	Detail level syntax.
perf-syntax	%(filename)	Performance alias syntax.
file		The file to check.
path		Alias for file.

filter:

Filter which marks interesting items. Interesting items are items which will be included in the check. They do not denote warning or critical state instead it defines which items are relevant and you can remove unwanted items.

warning:

Filter which marks items which generates a warning state. If anything matches this filter the return status will be escalated to warning.

critical:

Filter which marks items which generates a critical state. If anything matches this filter the return status will be escalated to critical.

ok:

Filter which marks items which generates an ok state. If anything matches this any previous state for this item will be reset to ok.

empty-state:

Return status to use when nothing matched filter. If no filter is specified this will never happen unless the file is empty.

Default Value: ok

perf-config:

Performance data generation configuration TODO: obj ( key: value; key: value) obj (key:valuer;key:value)

top-syntax:

Top level syntax. Used to format the message to return can include text as well as special keywords which will include information from the checks. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).

Default Value: %(status): %(list)

ok-syntax:

ok syntax. DEPRECATED! This is the syntax for when an ok result is returned. This value will not be used if your syntax contains %(list) or %(count).

Default Value: %(status): %(filename) is ok

empty-syntax:

Empty syntax. DEPRECATED! This is the syntax for when nothing matches the filter.

Default Value: No file inspected

detail-syntax:

Detail level syntax. Used to format each resulting item in the message. %(list) will be replaced with all the items formated by this syntax string in the top-syntax. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).

Default Value: %(filename) (size=%(size), age=%(age))

perf-syntax:

Performance alias syntax. This is the syntax for the base names of the performance data.

Default Value: %(filename)

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
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
line_count	Number of lines in the file (text files)
name	The name of the file
path	Path of file
size	File size
type	Type of item (file or dir)
version	Windows exe/dll file version
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)

Common options for all checks:

Option	Description
count	Number of items matching the filter.
crit_count	Number of items matched the critical criteria.
crit_list	A list of all items which matched the critical criteria.
detail_list	A special list with critical, then warning and finally ok.
list	A list of all items which matched the filter.
ok_count	Number of items matched the ok criteria.
ok_list	A list of all items which matched the ok criteria.
problem_count	Number of items matched either warning or critical criteria.
problem_list	A list of all items which matched either the critical or the warning criteria.
status	The returned status (OK/WARN/CRIT/UNKNOWN).
total	Total number of items.
warn_count	Number of items matched the warning criteria.
warn_list	A list of all items which matched the warning criteria.

Configuration

Path / Section	Description
/settings/disk

/settings/disk

Key	Default Value	Description
disable		Disable automatic checks

# 
[/settings/disk]

Disable automatic checks

A comma separated list of checks to disable in the collector: disk_io, disk_free. 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=