icli - Icinga Command Line Interface
icli [-v|-vv|-vvv] [-z
filter] [-h hosts] [-g hostgroups]
[-s services] [-c config] [-C] [-f
status-file] [-F rw-file]
[-lh|-ls|-lq|-ld] [-a
action[:args]] [host/service
...]
icli is a command line interface to Icinga. By
default it lists all services and their states.
Note that when supplying custom config and status file paths,
icli also works with Nagios. 100% compatibility is not
guaranteed, however.
icli only works when executed on the host running the
Icinga daemon. To use it on another host, shell aliases (like
"alias icli='ssh $icingahost
icli'") or similar are recommended.
You can narrow down the list of services you want displayed either
using filters (like "icli -z!o"),
the -h/-s arguments ("icli -h
aneurysm -s Libraries,Websites") or commandline
args ("icli
aneurysm/{Libraries,Websites}" with shell
expansion).
- -a|--action
action[:args]
- Run action on all matching hosts or services. args is a
comma-separated list of action arguments and depends on the action in
question. action may also be a one or two letter shortcut.
The following actions are supported:
- a|acknowledge
comment
- Acknowledge service problems with string comment. This creates a
sticky acknwoledgment with notification and no expire time. The comment
will not be persistent.
Note: Acknowledgement of host problems is not yet
supported.
- d|downtime
start,stop,duration,comment[,opts]
- Schedule a non-triggered host or service (depending on the filter
arguments) downtime. start and stop are timestamps and must
be formatted as YYYY-MM-DDTHH:MM:SS, where the "T" is literal.
The timestamp is assumed to be in the same time zone as the system running
icli.
If duration is 0 (zero), a fixed downtime between
start and stop is scheduled. Otherwise, a flexible
downtime which will start between start and stop and last
duration is scheduled. In this case, duration must be a
real number appended with an optional unit (s for seconds, m for
minutes, h for hours, d for days, w for weeks). If no unit is specified,
seconds are used.
If a host is selected and opts contains
"children", a downtime for all of its children will be
scheduled with the same parameters as the host's. Likewise, if
opts contains "trigger_children", a triggered downtime
for all of the host's children will be scheduled.
comment refers to the downtime's comment field and must
not contain the "," (comma) character.
- r|recheck
- Schedule an immediate recheck
- R|force_recheck
- Schedule a forced, immediate recheck
- -c|--config
config
- Read config from file
- -C|--no-colours
- Disable colours in output
- -f|--status-file
file
- Read the status from file
- -F|--rw-file
file
- Use file as external commands file.
- -g|--hostgroup
hostgroup
- Limit selection to hosts in hostgroup (comma separated list)
- -h|--host
hosts
- Limit selection to hosts (comma separated list)
- -l|--list
downtimes|hosts|services|queue
- List either services (the default) or hosts. Note that only the first
character of the argument is checked, so
"icli -lh",
"icli -ls" etc. are also fine.
- -m|--match
regex
- Limit selection to hosts/services whose plugin output matches regex
(perl regular expression, case insensitive. see perlre).
- -o|--overview
- Display "tactical overview"-style overview. By default (or when
used with "-ls") the number of all hosts
and services (both total and divided by their state) is shown.
When used with "-lh", lists
all hosts with the number of ok / warning / ... checks on each host.
- -U|--as-contact
name
- Only operate on service visible to name. Doesn't work for
-lh yet, most useful for -ls.
NOTE: This is meant to help find out which services a user has
access to. It is NOT intended as a way to restrict access and should
never be used that way.
- -s|--service
services
- Limit selection to services (comma separated lists). Can be
combined with -h/-g to further narrow down the selection,
but may also be used stand-alone.
- -v|--verbose
- Increase output verbosity. Can be combined up to -vvv
- -V|--version
- Show version information
- -x|--cut-mode
mode
- What to do with lines which are too long for the terminal: nothing,
cut off, line break (with proper indentation). The default
is line breaks
- -z|--filter
expression
- Limit selection to hosts/services passing the filter. expression is
a comma separated list of filters, only hosts/services to which all
filters apply are selected. See also "FILTER EXPRESSIONS"
SERVICE LISTING
This is the standard output method. It contains the following:
- Service description
- -v: Service Flags (Acknowledged, Flapping, Passive,
!no checks)
- Service state (ok / warning / critical / unknown)
- -v: Current attempt / Max attempts
- Plugin output
HOST LISTING
Enabled with -ld
- Host name
- Host state (ok / down / unreachable)
- -v: Current attempt / Max attempts
- Plugin output
QUEUE LISTING
Enabled with -lq
- Host name
- Service name
- Last check
- Next check
Each expression can be negated with an exclamation mark, e.g.
"!A" for all non-acknowledged services.
- A
- Check state has been acknowledged
- D
- The host this service belongs to is Down or Unreachable
- F
- Service is flapping between states
- N
- Notifications for this service are disabled
- P
- Only passive checks are enabled. Note that !P simply means that
active checks are enabled, no matter the status of passive checks
- S
- Check state is soft. For instance, it used to be OK and is now critical,
but has not reached its maximum number and caused a notification yet. Good
to find (or ignore) service problems which might just be temporary,
non-critical glitches.
- o
- Host/Service state is OK
- w
- Service state is Warning
- c
- Service state is Critical
- u
- Service state is Unknown
- p
- Host or service state is Pending
- d
- Host state is Down
- x
- Host state is Unreachable
Zero, unless errors occured.
- autodie (included with perl >= 5.10.1)
- DateTime
- DateTime::Format::Strptime
- DateTime::TimeZone
- Term::Size
It is probably not clear from the documentation when an action
will operate on hosts and when on services.
Note that this software is not yet stable. Command line options
may be changed / removed and thus break backwards compatibility at any
time.
REPORTING BUGS
Either via mail to <derf@finalrewind.org> or on
<http://github.com/derf/icinga-cli/issues>.
- "icli -r -s 'APT Updates'"
- Schedule a check of the "APT Updates" service on all hosts
having it
- "icli -lq -h aneurysm -g chaosdorf-hosts"
- List check queue for all hosts in the hostgroup
"chaosdorf-hosts", plus the host aneurysm
- "icli -z!o,!A,!S,!D"
- Show all service problems which are already hard states and have not yet
been acknowledged. Also weed out problem services on hosts which are down
anyways
Copyright (C) 2010 by Daniel Friesel
<derf@finalrewind.org>
0. You just DO WHAT THE FUCK YOU WANT TO.