gocinga

README

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

Installation

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.

Configuration

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.

Example:

# 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

Usage

Parameters

Actions

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

Examples

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'."}]}