Common options and filter keywords¶

Most check commands are built on top of the same filter engine and therefore accept the same set of command-line options and expose the same generic filter keywords. They are documented once on this page; each command’s reference page lists which of them the command accepts together with the command specific default values.

Common options¶

These options are available on all filter based commands. Default values are command specific and listed on each command’s reference page.

Option	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	Show debugging information in the log
show-all	Show details for all matches regardless of status (normally details are only showed for warnings and criticals).
empty-state	Return status to use when nothing matched filter.
perf-config	Performance data generation configuration
escape-html	Escape any < and > characters to prevent HTML encoding
list-separator	String used to separate the items of %(list), %(ok_list), %(warn_list), %(crit_list), %(problem_list) and %(detail_list).
top-syntax	Top level syntax.
ok-syntax	ok syntax.
empty-syntax	Empty syntax.
detail-syntax	Detail level syntax.
perf-syntax	Performance alias syntax.
unique-index	Unique syntax.
byte-unit	Unit to render every byte value of the message in: B, KB, MB, GB, TB, PB or EB.
decimal-separator	Character to use as the decimal separator of the message, for instance “,” for the European rendering (default “.”).
decimals	Number of decimals to render the numbers of the message with, for instance 1 to turn “25.191GB” into “25.2GB”.
thousands-separator	Character to group the thousands of the message with, for instance “.” to render 1006.85 GB as “1.006,85” (together with decimal-separator=,). Empty (the default) means no grouping.

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.

warn

Short alias for warning

critical

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

crit

Short alias for 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.

debug

Show debugging information in the log

show-all

Show details for all matches regardless of status (normally details are only showed for warnings and criticals).

empty-state

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

perf-config

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

escape-html

Escape any < and > characters to prevent HTML encoding

list-separator

String used to separate the items of %(list), %(ok_list), %(warn_list), %(crit_list), %(problem_list) and %(detail_list). Accepts the escapes \n, \r, \t and \ (a configuration file value is a single line, so a real newline cannot be written). Set to \n to render one item per line, which most Nagios compatible frontends show as long output below the summary line. The top-syntax decides what precedes the first item; templates are never escape-decoded, so reference the decoded separator as %(sep) to break before it too: –top-syntax “%(status): %(count) items:%(sep)%(list)”.

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

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

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

perf-syntax

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

unique-index

Unique syntax. Used to filter unique items (counted will still increase but messages will not repeated)

byte-unit

Unit to render every byte value of the message in: B, KB, MB, GB, TB, PB or EB. By default each value scales on its own, which is why a single line can read “140.293GB/0.983TB”; pinning the unit makes the values comparable (“140.29GB/1006.85GB”). Performance data is unaffected - its unit is chosen separately and can be set with perf-config.

decimal-separator

Character to use as the decimal separator of the message, for instance “,” for the European rendering (default “.”). Only the message is affected: performance data and the numbers you write in a filter or threshold always use “.”, as their consumers require.

decimals

Number of decimals to render the numbers of the message with, for instance 1 to turn “25.191GB” into “25.2GB”. Applies to the byte and percentage keywords and to format_bytes()/format_number(); -1 (the default) keeps the historical rendering of up to three decimals with the trailing zeros stripped. Performance data is unaffected - it is generated from the raw values so that graphs keep their full precision.

thousands-separator

Character to group the thousands of the message with, for instance “.” to render 1006.85 GB as “1.006,85” (together with decimal-separator=,). Empty (the default) means no grouping. Only the message is affected: performance data and the numbers you write in a filter or threshold are never grouped.

Standard options¶

These options are available on every command.

Option	Description
help	Show help screen (this screen)
help-pb	Show help screen as a protocol buffer payload
show-default	Show default values for a given command
help-short	Show help screen (short format).

help

Show help screen (this screen)

help-pb

Show help screen as a protocol buffer payload

show-default

Show default values for a given command

help-short

Show help screen (short format).

Common filter keywords¶

These keywords can be used in the filter expressions (filter, warning, critical, ok) and in the syntax templates (top-syntax, detail-syntax, perf-syntax, …) of every filter based command, in addition to the command specific keywords listed on each command’s reference page.

Keyword	Description
count	Number of items matching the filter.
total	Total number of items.
ok_count	Number of items matched the ok criteria.
warn_count	Number of items matched the warning criteria.
crit_count	Number of items matched the critical criteria.
problem_count	Number of items matched either warning or critical criteria.
list	A list of all items which matched the filter.
ok_list	A list of all items which matched the ok criteria.
warn_list	A list of all items which matched the warning criteria.
crit_list	A list of all items which matched the critical criteria.
problem_list	A list of all items which matched either the critical or the warning criteria.
detail_list	A special list with critical, then warning and finally ok.
sep	The decoded list-separator, for use in the top-syntax: templates are never escape-decoded (a literal C:\temp must stay a literal C:\temp), so reference %(sep) to break the line before the first list item, e.g. top-syntax=%(status): %(count) items:%(sep)%(list).
status	The returned status (OK/WARN/CRIT/UNKNOWN).