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.

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)

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