Icinga

6.2. Information On CGI parameters

6.2.1. Introduction
6.2.2. Executing CGIs on the command line
6.2.3. Properties / Statustypes
6.2.4. Matrix Parameters / CGIs

6.2.1. Introduction

The menu on the left side of the classical web interface contains entries which offer a quick way to the information most people need. However you can change the parameters or use other options as well. Some CGIs require an objecttype ("host", "hostgroup", "service", or "servicegroup"), often followed by one or more options. The best way is to take a look at the existing URLs and change them according to your needs.

Below you will find a table showing the parameters and the CGIs they apply to. The names of the CGIs are abbreviated. An explanation along with a hint to the source code can be found here.

Following this table is an explanation of the parameters (work in progress).

6.2.2. Executing CGIs on the command line

Instead of using your browser you may want to run the CGIs on the command line and process the results with other tools. For a first impression change to the folder containing the *.cgi modules (e.g. /usr/local/icinga/sbin), set some environment variables and execute one of the CGIs:

 $> export REMOTE_USER=icingaadmin   # or choose the appropriate user
 $> export REQUEST_METHOD='GET'      # if you enter queries
 $> export QUERY_STRING='host=all'   # see the tables below 

 $> ./status.cgi

Depending on the number of hosts this may return a lot of lines containing HTML code in between which most people will find hard to read so you should add "&csvoutput" or "&jsonoutput" to QUERY_STRING along with other arguments.

Set QUERY_STRING as needed and execute the desired CGI.

If you forgot to set the environment variables you'll receive the following lines:

 $> ./status.cgi
 getcgivars(): Unsupported REQUEST_METHOD -> ''

 I'm guessing you're trying to execute the CGI from a command line.
 In order to do that, you need to set the REQUEST_METHOD environment
 variable to either "GET", "HEAD", or "POST". When using the
 GET and HEAD methods, arguments can be passed to the CGI
 by setting the "QUERY_STRING" environment variable. If you're
 using the POST method, data is read from standard input. Also of
 note: if you've enabled authentication in the CGIs, you must set the
 "REMOTE_USER" environment variable to be the name of the user you're
 "authenticated" as.

You will find some examples here.

6.2.3. Properties / Statustypes

You can use status.cgi to show objects with one or more statustype (hoststatustype / servicestatustype) and with certain properties (hostprops / serviceprops). Each statustype / property is identified by a number (shown here and here at the end of this section). Please sum up the appropriate numbers and use the resulting value for each option.

The example shows all non-OK services which are neither in downtime nor acknowledged:

 http://localhost/icinga/cgi-bin/status.cgi?host=all&servicestatustypes=29&serviceprops=10

"29" includes PENDING services (not being checked since start up) as well.

[Note] Note

Please note that using properties will only show the objects satisfying ALL conditions whereas the objects are shown when satifying ONE of the statustypes.

6.2.4. Matrix Parameters / CGIs

Parameter avail cmd config ext hgram hist notif out log status map sum tac trends
ahas   X                        
alerttypes                       X    
assumeinitialstates X                         X
assumestateretention X       X                 X
assumestatesduringnotrunning X                         X
attr [4]   X                        
backtrack X       X                 X
breakdown         X                  
broadcast_notification   X                        
childoptions   X                        
cmd_mod   X                        
cmd_typ   X                        
columns                   X        
com_author   X                        
com_data   X                        
com_id   X                        
contact             X              
createimage         X                  
csvoutput X   [2] [2]     [2] [2] [2] [2]   [2]    
displaytype                       X    
down_id   X                        
eday X       X             X   X
ehour X       X             X   X
embedded X     X X X X X X X X X X  
emin X       X             X   X
emon X       X             X   X
end_time   X         X[5]              
esec X       X             X   X
eyear X       X             X   X
fixed   X                        
force_check   X                        
force_notification   X                        
full_log_entries X                          
get_date_parts X                          
graphevents         X                  
graphstatetypes         X                  
host X X   X X X X     X   X   X
hostgroup X X   X   X[5] X[5]     X   X    
hostprops                   X        
hoststates                       X    
hoststatustypes                   X        
hours   X                        
includesoftstates X                          
initialassumedhoststate X                         X
initialassumedservicestate X                         X
initialstateslogged         X                  
input         X                 X
item_name [5]     X                     X
jsonoutput [2][3] X   X X     X X X X   X X  
limit [5]     X X   X X   X X   X    
minutes   X                        
navbarsearch                   X        
newstatesonly         X                  
nodowntime           X                
noflapping           X                
nofrills           X     X          
noheader X     X X X X X X X X X X X
not_dly   X                        
notimebreaks           X     X          
nosystem           X                
oldestfirst [6]                 X          
order [5]           X X              
performance_data   X                        
persistent   X                        
plugin_output   X                        
plugin_state   X                        
ptc   X                        
report                       X    
report_type X                          
rpttimeperiod X                          
sched_dly   X                        
sday X       X             X    
search_string [5]     X                      
send_notification   X                        
service X X   X X X X             X
servicefilter                   X        
servicegroup X X   X   X[5] X[5]     X   X    
serviceprops                   X        
servicestates                       X    
servicestatustypes                   X        
service_divisor               X            
shour X       X             X    
showscheduleddowntime X                          
show_log_entries X                          
smin X       X             X    
smon X       X             X    
sortoption       X           X        
sorttype       X           X        
ssec X       X             X    
standardreport                       X    
start [5]     X X   X X   X X        
start_time   X         X[5]              
statetype           X                
statetypes                       X    
sticky_ack   X                        
style                   X        
syear X       X             X   X
t1 X       X             X   X
t2 X       X             X   X
timeperiod X       X   X[5]         X   X
ts_end [5]           X X              
ts_start [5]           X X              
trigger   X                        
type     X X   X X              

Parameter Details

Further information regarding the several parameters is given below. For a detailed understanding please have a look at the source code.

Parameter Description Possible Values Example Notes
ahas The command will affects host and its services   ahas  
alerttypes Show host and/or service alerts 1=host alerts; 2=service alerts; 3=host and service alerts alerttypes=3  
assumeinitialstates   yes; no    
assumestatesduringnotrunning   yes; no    
assumestateretention   yes; no    
attr Reset modified attributes and don't set them in the future. 0 attr=0 see note [4].
backtrack How many archive log files will be searched to determine the initial states 0-n backtrack=1 Please keep in mind that processing of the files may take a while
breakdown Breakdown data by timeperiod 0=monthly; 1=day of month; 2=day of week; 3=hourly breakdown=2  
broadcast_notification Send notification to all contacts (non-escalated and escalated)   broadcast_notification  
childoptions Downtime handling for child hosts 0=doesn't affect child hosts; 1=schedule triggered downtime; 2=schedule non-triggered downtime childoptions=1  
cmd_mod Command mode      
cmd_typ Command type 0 - 169, 999 cmd_typ=160 For details see .../include/common.h
columns Number of overview columns >= 1   Default is 3
com_author Comment author a valid user com_author=icingaadmin May depend on the setting of "lock_author_names" in cgi.cfg
com_data Comment contents an urlencoded string    
com_id Comment id      
contact A valid contact as mail recipient      
createimage     createimage  
csvoutput Specify whether or not the report output should be in csv format yes;no   This option automatically sets "noheader". Added to nearly all CGIs (see note [2])
displaytype Type of alert report 1=recent alerts; 2=alert totals; 3=top alerts; 4=hostgroup alert totals; 5=host alert totals; 6=service alert totals; 7=servicegroup alert totals    
down_id Downtime id      
eday End of custom timeperiod (day)     Only valid when using "custom" timeperiod
ehour End of custom timeperiod (hour)     Only valid when using "custom" timeperiod
embedded Omit some HTML code and SSI header/footer   embedded  
emin End of custom timeperiod (minute)     Only valid when using "custom" timeperiod
emon End of custom timeperiod (month)     Only valid when using "custom" timeperiod
end_time End time of the fixed downtime     Format "MM-DD-YYYY HH:MI"
esec End of custom timeperiod (second)     Only valid when using "custom" timeperiod
eyear End of custom timeperiod (year)     Only valid when using "custom" timeperiod
fixed Whether or not the downtime will be fixed 0=flexible, >0=fixed    
force_check The service check will be forced   forcecheck  
force_notification Send notification regardless of restrictions (timeperiods or else)   force_notification  
full_log_entries Show full or "condensed" log entries   full_log_entries Default is "condensed" view
get_date_parts Get custom time ranges   get_date_parts  
graphevents Which objects should be graphed in what state   graphevents=112 (all service problems) A boolean OR of: 1=Host up; 2=Host down; 4=Host unreachable; 8=Service OK; 16=Service Warning; 32=Service Unknown; 64=Service Critical
graphstatetypes Graph hard and/or soft states 1=soft states; 2=hard states; 3=hard and soft states graphstatetypes=3  
host Select all hosts or a specific host whose services should be displayed all; <host name> host=monitor special characters in the name have to be urlencoded (i.e. "%20" instead of a blank)
hostgroup Select all hostgroups or one specific hostgroup whose hosts and services should be displayed all; <hostgroup name> hostgroup=linux-boxes special characters in the name have to be urlencoded (i.e. "%20" instead of a blank)
hostprops Select the hosts (including the services) matching the given bit pattern. Note that the hosts have to match ALL conditions specified   hostprops=131088 (active checks being disabled) A boolean OR of the states specified in include/cgiutils.c [1] (HOST AND SERVICE FILTER PROPERTIES)
hoststates The state the hosts should be in 1 - 7 hoststates=3 (hosts in problem state) A boolean OR of the states: 1=DOWN; 2=UNREACHABLE; 4=UP
hoststatustypes The state the host should be in 1 - 15 hoststatustypes=12 (hosts in problem state) A boolean OR of the states: 1=Pending; 2=Up; 4=Down; 8=Unreachable
hours Duration of the flexible downtime in full hours (see minutes) >= 0   Only valid if defining a flexible downtime
includesoftstates Include soft states yes; no includesoftstate=yes Default: don't include soft states
initialassumedhoststate        
initialassumedservicestate        
initialstateslogged        
input        
item_name Search for exact match of specified string (for regex search see search_string)   item_name=localhost [5]
jsonoutput Specify whether or not the report output should be in json format yes;no   This option automatically sets "noheader". Added to nearly all CGIs (see note [2])
limit Number of items to display per page 1-n limit=10 Used for paging-ability [5]. The summary.cgi doesn't have pagination, default=25.
minutes Duration of the flexible downtime (see hours) >= 0    
navbarsearch        
newstatesonly Only display new states yes; no newstatesonly=yes Default: display all states
nodowntime Don't display downtimes   nodowntime  
noflapping Don't display flapping alerts   noflapping  
nofrills Don't display frills   nofrills  
noheader Omit global status information and only show status details   noheader  
not_dly Delay notification for n minutes >= 0    
notimebreaks Don't display timebreaks      
nosystem Don't display system messages   nosystem Default: display system (process) messages
oldestfirst Reverse sort order   oldestfirst Default: show most recent entries first; see note [6]
order Specify sort order new2old, old2new order=old2new Default: show most recent entries first; see note [5]
performance_data The string sent as the performance data      
persistent The comment will be persistent if this option is set   persistent  
plugin_output The string sent as the plugin output     The length is limited by the value of MAX_INPUT_LENGTH (set during compile time)
plugin_state Specify the state the plugin should have 0=OK; 1=Warning; 2=Critical; 3=Unknown plugin_state=2  
ptc The command will be propagated to child hosts   ptc  
report Create report   report  
report_type Select the report type hostgroups; servicegroups; hosts; services report_type=hostgroups  
rpttimeperiod Specify a timeperiod which is used for the availability report One of the defined timeperiods   Use the short name from the timeperiod definition
sched_dly Delay command scheduling by n minutes >= 0    
sday Start of custom timeperiod (day)      
search_string Find object with given string using regular expressions     [5]
send_notification Send a notification for the acknowledgement 0=disabled, 1=enabled (default) send_notification [5] cmd.cgi requires 0|1 vars, if not set, default is 1. View Bug #2926 for additional information.
service Select all services or a specific service which should be displayed all; <service description> service=PING Special characters in the name have to be urlencoded (i.e. "%20" instead of a blank)
servicefilter Select only services matching the given pattern   servicefilter=Current; servicefilter=[PL] The pattern is case sensitive. Regular expressions seemed to work up to Icinga 1.6; see search_string
servicegroup Select all servicegroup or one specific servicegroup whose hosts and services should be displayed all; <servicegroup name> servicegroup=disk Special characters in the name have to be urlencoded (i.e. "%20" instead of a blank)
serviceprops Select the services matching the given bit pattern. Note that the services have to match ALL conditions specified   serviceprops=131088 (active checks being disabled) A boolean OR of the states specified in include/cgiutils.c [1] (HOST AND SERVICE FILTER PROPERTIES)
servicestates State the services should be in   servicestates=56 (services in problem state) A boolean OR of the states: 8=Warning; 16=Unknown; 32=Critical; 64=OK
servicestatustypes State the services should be in 1 - 31 servicestatustype=28 (services in problem state) A boolean OR of the states: 1=Pending; 2=OK, 4=Warning; 8=Unknown; 16=Critical
service_divisor Importance of services in relation to hosts >=1   Services are 1/n important as hosts. Default: n=4
shour Start of custom timeperiod (hour)     Only valid when using "custom" timeperiod
showscheduleddowntime Display scheduled downtimes yes; no   Default: yes
show_log_entries Display log entries   show_log_entries Default: don't show log entries
smin Start of custom timeperiod (minute)     Only valid when using "custom" timeperiod
smon Start of custom timeperiod (month)     Only valid when using "custom" timeperiod
sortoption Specify the column to sort on 1-n sortoption=3 Default is column 1
sorttype Specify the sort order on the column specified by "sortoption=<n>" 1=ascending; 2=decending sorttype=2  
ssec Start of custom timeperiod (second)     Only valid when using "custom" timeperiod
standardreport Standard report 1=recent alerts; 2=recent host alerts; 3=recent service alerts; 4=top host alert producers; 5=top service alert producers    
start Resultcounter     [5] Result counter for pagination.
start_time Start of the fixed downtime     Format "MM-DD-YYYY HH:MI" (may depend on your local settings, but unsure about that)
statetype Hard and/or soft states 0=hard and soft states; 1=soft states; 2=hard states statetype=2  
statetypes Hard and/or soft states 1=soft states; 2=hard states; 3=hard and soft states statetypes=2  
sticky_ack The acknowledgement will be "sticky" 0=disabled, 1=enabled (default) sticky_ack [5] cmd.cgi requires 0|1 vars, if not set, default is 1. View Bug #2926 for additional information.
style Specify the information to be shown overview; detail; summary; grid; hostdetail   only applies to objecttypes "hostgroups" and "servicegroups";hostdetail=host status details; detail=service status details; summary=status summary; grid=status grid;
syear Start of custom timeperiod (year)     Only valid when using "custom" timeperiod
t1 Start point of a custom timeperiod   t1=1296109300 Unix timestamp
t2 End point of a custom timeperiod   t2=1296189360 Unix timestamp
timeperiod Timeperiod which should be used for the availability report today; yesterday; thisweek; lastweek; thismonth; lastmonth; thisquarter; lastquarter; thisyear; lastyear; last24hours; last7days; last31days; custom timeperiod=lastmonth  
trigger The downtime will be triggered by downtime id <n> A valid downtime id    
ts_end Data is shown up to ts_end (unix timestamp) A valid unix timestamp   [5]
ts_start Data is shown starting at ts_start (unix timestamp) A valid unix timestamp   [5]
type Objecttype hosts; hostgroups; services; servicegroups; contacts; contactgroups; timeperiods; commands; hostescalations; serviceescalations; hostdependencies; servicedependencies type=hosts  
[Note] Note

Starting with 1.8 the 'scroll' parameter was added to status.cgi to save and restore the current scroll position. This is minor, as only used as internal variable when using refresh_type=javascript in cgi.cfg

Abbreviations, CGIs, Links

Abbreviations used in the first table, relations to CGI and menu items, and links to the source code in <icinga-core>/cgis.

Abbreviation CGI Menu item(s) Source Code
avail avail.cgi Availability avail.c
cmd cmd.cgi N/A cmd.c
config config.cgi Configuration config.c
ext extinfo.cgi Comments, Downtime, Process Info, Performance Info, Schedulung Info extinfo.c
hgram histogram.cgi Alert Histogram histogram.c
hist history.cgi Alert History history.c
notif notifications.cgi Notifications notifications.c
out outages.cgi Network Outages outages.c
log showlog.cgi Event Log showlog.c
status status.cgi Hostgroup Overview, Servicegroup Overview, Host Problems, Service Problems status.c
map statusmap.cgi Status Map statusmap.c
summary summary.cgi Alert Summary summary.c
tac tac.cgi N/A tac.c
trends trends.cgi Trends trends.c

Excerpt from include/cgiutils.h

/****************** HOST AND SERVICE FILTER PROPERTIES  *******************/

#define HOST_SCHEDULED_DOWNTIME         1
#define HOST_NO_SCHEDULED_DOWNTIME      2
#define HOST_STATE_ACKNOWLEDGED         4
#define HOST_STATE_UNACKNOWLEDGED       8
#define HOST_CHECKS_DISABLED            16
#define HOST_CHECKS_ENABLED             32
#define HOST_EVENT_HANDLER_DISABLED     64
#define HOST_EVENT_HANDLER_ENABLED      128
#define HOST_FLAP_DETECTION_DISABLED    256
#define HOST_FLAP_DETECTION_ENABLED     512
#define HOST_IS_FLAPPING                1024
#define HOST_IS_NOT_FLAPPING            2048
#define HOST_NOTIFICATIONS_DISABLED     4096
#define HOST_NOTIFICATIONS_ENABLED      8192
#define HOST_PASSIVE_CHECKS_DISABLED    16384
#define HOST_PASSIVE_CHECKS_ENABLED     32768
#define HOST_PASSIVE_CHECK              65536
#define HOST_ACTIVE_CHECK               131072
#define HOST_HARD_STATE                 262144
#define HOST_SOFT_STATE                 524288
#define HOST_STATE_HANDLED              1048576
#define HOST_NOT_ALL_CHECKS_DISABLED    2097152

#define SERVICE_SCHEDULED_DOWNTIME      1
#define SERVICE_NO_SCHEDULED_DOWNTIME   2
#define SERVICE_STATE_ACKNOWLEDGED      4
#define SERVICE_STATE_UNACKNOWLEDGED    8
#define SERVICE_CHECKS_DISABLED         16
#define SERVICE_CHECKS_ENABLED          32
#define SERVICE_EVENT_HANDLER_DISABLED  64
#define SERVICE_EVENT_HANDLER_ENABLED   128
#define SERVICE_FLAP_DETECTION_ENABLED  256
#define SERVICE_FLAP_DETECTION_DISABLED 512
#define SERVICE_IS_FLAPPING             1024
#define SERVICE_IS_NOT_FLAPPING         2048
#define SERVICE_NOTIFICATIONS_DISABLED  4096
#define SERVICE_NOTIFICATIONS_ENABLED   8192
#define SERVICE_PASSIVE_CHECKS_DISABLED 16384
#define SERVICE_PASSIVE_CHECKS_ENABLED  32768
#define SERVICE_PASSIVE_CHECK           65536
#define SERVICE_ACTIVE_CHECK            131072
#define SERVICE_HARD_STATE              262144
#define SERVICE_SOFT_STATE              524288
#define SERVICE_STATE_HANDLED           1048576
#define SERVICE_NOT_ALL_CHECKS_DISABLED 2097152

Excerpt from include/statusdata.h

/*************************** SERVICE STATES ***************************/
#define SERVICE_PENDING  1
#define SERVICE_OK       2
#define SERVICE_WARNING  4
#define SERVICE_UNKNOWN  8
#define SERVICE_CRITICAL 16

/**************************** HOST STATES ****************************/
#define HOST_PENDING     1
#define HOST_UP          2
#define HOST_DOWN        4
#define HOST_UNREACHABLE 8

[1] Logical OR means that the numbers are added and only the objects will be displayed satisfying ALL conditions (properties).

[2] Available starting with Icinga 1.4.

[3] avail, log, notif, out, status, sum: all views/reports support jsonoutput; config: all types except command expansion; ext: all views except hostgroup/servicegroup info (always without performance data); tac: data output in json format. More details in the Icinga wiki.

[4] Available starting with Icinga 1.7.

[5] Available starting with Icinga 1.8.

[6] Removed starting with Icinga 1.8.