command module
Version: v1.3.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: May 28, 2019 License: MIT Imports: 9 Imported by: 0


icinga-cli: CLI Tool for Icinga, written in go


First you need to install golang for your system, the instructions for your system can be found on the golang.org Getting Started page

After you installed go, verify that your installation is working:

$ go version
go version go1.12 darwin/amd64

Now simply run go get to install the tool to your system:

$ go get gitlab.com/sambadevi/icinga-cli

You need to have $GOPATH in your $PATH to be able to access the binaries in $GOPATH/bin, you might want to add this line to your .zshrc (syntax may differ for .bashrc)

$ export PATH=${GOPATH//://bin:}/bin:$PATH

If calling icinga-cli results in a command not found error you need to reload/restart your shell.


There are three ways to configure this tool, ordered by priority:

  1. CLI Parameters
  2. Environment Variables
  3. Configuration file ~/.icinga-config.yml or ~/.icinga-config.yaml (.yml will be preferred if both exist)

CLI-Parameters will overwrite Environment Variables, Environment Variables will overwrite the Configuration file

Your final configuration will be a combination from the given parameters, your environment variables and the configuration file.


# Set ICINGA_API environment variable
$ export ICINGA_API="https:/myicinga.example.com/v1"

# Set "access" in configuration file
$ echo 'access: "myUser:myPassword"' > ~/.icinga-config.yml

# Show current configuration of icinga-cli
$ icinga-cli -c
Access-Token:     myUser:myPassword                # <- This is from the config file
Icinga-User:      myUser
Downtime-Author:  myUser                           # <- defaults to icinga-username
Icinga-Password:  myPassword
Icinga-API:       https://myicinga.example.com  # <- This is from the env variable
Icinga-Host:      myicinga.example.com:5665

# Show current configuration but set user to myOtherUser
$ icinga-cli -c -u myOtherUser
Access-Token:     myOtherUser:myPassword                # <- This is from the config file
Icinga-User:      myOtherUser
Downtime-Author:  myUser                           # <- defaults to icinga-username
Icinga-Password:  myPassword
Icinga-API:       https://myicinga.example.com  # <- This is from the env variable
Icinga-Host:      myicinga.example.com:5665
via Parameters

Simply use the --user/-u, --password/-p and --api flags to setup your environment

via Environment variables

You can set the ICINGA_ACCESS, ICINGA_API and ICINGA_AUTHOR variables to the corresponding values.

ICINGA_ACCESS is using your user and password in the following format user:password.

ICINGA_API is the url to your Icinga API, including the API version (/v1 in this example) ICINGA_AUTHOR is the name which will be added to scheduled downtimes as author

$ export ICINGA_ACCESS="myUser:myPassword"
$ export ICINGA_API="https://myicinga.example.com"
$ export ICINGA_AUTHOR="Dave Developer"
via Configuration file

You can also set your ~/.icinga-config.yml configuration in YAML format, the same rules apply as for the environment variables:

# ~/.icinga-config.yml
access: "myUser:myPassword"
api: https://myicinga.example.com
author: Dave Developer
From command

ìcinga-cli --save-config will save your current config at $HOME/.icinga-config.yml you can use the -p, -u, --api, --author parameters to specify the config fields.

# using the last configuration from "via Environment variables" but overriding myUser with apiUser and changing author as well
$ icinga-cli --save-config -u apiUser --author "Generic API User"
$ cat ~/.icinga-config.yml
# config file created with icinga-cli --save-config
access: "apiUser:myPassword"
api: https://myicinga.example.com
author: Generic API User


Option Example Description
--add, -a --add myserver.com Add a new entry to your configured Icinga System
--delete, -d --delete myserver.com Remove an entry from your configured Icinga System
--list, -l List entries of the given type (see -t / --type)
General Configuration
Option Example Description
--api --api https://myicinga.example.com The api to connect with
--author --author "Dave Developer" Author for scheduled downtimes
--password, -p --password myPassword The password to authenticate with
--user, -u --user myUser The user to authenticate as
Entry Configuration
Option Example Description
--duration --duration 10m Downtime duration (accepted formats: ms, s, m, h, d. Example: 1d for one day, 22m for 22 minutes, 10ms for 10 milliseconds)
--message, -m --message "Fixing stuff" Add a message as downtime-comment
--path --path /some-path The URL path to check
--role --role webserver The role (vars.os) which will be given to this entry
--start --start "05 Jun 11 12:32" optional start time in DD Mon YY HH:MM format (time in 24 hour format.)
--type --type downtime Type of entry to use (host, downtime)
Miscellaneous Options
Option Description
--show-config, -c Displays the current configuration, combined from parameters, environment and user configuration
--save-config Save the currently set configuration to ~/.icinga-config.yml, accepts the same parameters as any command
--dry-run Prints the resulting URL and Payload but does not send any data to the server
--help, -h Displays the Usage information
--skip-tls Skips SSL Certificate verification (if you are using self-signed certificates or your certificate expired)
--verbose, -v Verbose mode, displays additional INFO and WARN messages

To add an entry you need the role flag to be set, currently --role will set the vars.os field of your new icinga-object

# Add an entry with role "webserver" for otherserver.example.com
$ icinga-cli -a otherserver.example.com --role webserver -v
# ... some verbose lines inbetween ...
# The response should be
2019/03/18 23:59:05 [INFO] Response: {"results":[{"code":200.0,"status":"Object was created"}]}

To delete an entry you just need to specifiy the name of the server which you would like to remove

# Delete an entry
$ icinga-cli -d deleteme.example.com -v
# ... some verbose lines inbetween ...
# The response should be
2019/03/19 00:02:51 [INFO] Response: {"results":[{"code":200.0,"errors":[],"name":"deleteme.example.com","status":"Object was deleted.","type":"Host"}]}

Add a downtime for any given host and any service registered on the host (host.name == downtime.example.com)

# Add a 20 minute downtime for downtime.example.com
$ icinga-cli -a downtime.example.com --type downtime --duration "20m" -v
... a lot of lines with (hopefully) status: successfully scheduled ...

Delete any downtimes registered for a given host

# Remove downtimes for downtime.example.com
$ icinga-cli -d downtime.example.com --type downtime -v
# ... some verbose lines inbetween ...
{"results":[{"code":200.0,"status":"Successfully removed all downtimes for object 'downtime.example.com'."}]}


The Go Gopher

There is no documentation for this package.

Source Files


Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL