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).
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.
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 |
---|---|
Please note that using properties will only show the objects satisfying ALL conditions whereas the objects are shown when satifying ONE of the statustypes. |
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 |
---|---|
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 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.
© 2009-2012 Icinga Development Team, http://www.icinga.org