_                      _
  | |_ ___ _ __ _ __ ___ (_)_ __   __ _  __ _
  | __/ _ \ '__| '_ ` _ \| | '_ \ / _` |/ _` |
  | ||  __/ |  | | | | | | | | | | (_| | (_| |
   \__\___|_|  |_| |_| |_|_|_| |_|\__, |\__,_|
                                  |___/
  https://github.com/seibert-media/terminga


- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


A TUI for Icinga2.


Dependencies
------------

    - Python 3.7+
    - python-requests


Installation
------------

Clone this repo and run `terminga`. Don't forget the configuration, of
course.


Configuration
-------------

Create ~/.terminga, which consists of a JSON dict:

    {
        "icinga_url": "https://icinga-terminga-proxy.your-company.com",
        "ssl_verify": true,
        "api_auth": {
            "username": "myapiuser",
            "password": "myapiuserspassword"
        },
        "external_tool": "mytool -s __SELECTION__ -o __TOOL_OUTPUT__",
        "group_filters": {
            "host_groups": ["is_customer-no", "on_premise-no"],
            "service_groups": ["is_customer-no", "on_premise-no"]
        },
        "hide_ack_from_broken": true,
        "jump_to_first_unhandled": true,
        "default_ack_duration": "1d",
        "default_downtime_duration": "1d",
        "show_detailed_output_on_startup": false,
        "size_of_item_area": 10
    }

Use a valid API user, not your regular Icinga user.

Instead of "password", you can specify "pass_command", the output of
this command will then be used as password.

"ssl_verify" allows disabling ssl verification when connecting to icinga.
This is needed if you don't use a reverse proxy infront of your icinga2
instance, but are connecting to your icinga2 api port directly. If using
the default "true", you can omit this key entirely.

"external_tool" contains a path to a user-supplied script and this
setting is optional. It will be invoked when you press "e" in terminga.
"__SELECTION__" will be replaced by the path to a file that contains
your selection: First line is host name, second line service name, third
line check output (with lines separated by \r rather than \n). This
repeats for each selected item, i.e. your script will only be called
once, no matter how many items you selected. (terminga will remove this
file after your tool has quit.)

When launching "external_tool", the string "__TOOL_OUTPUT__" will be
replaced with a path to a file where your tool can store its own output
string. (terminga will remove this file after your tool has quit.) This
is relevant when using the "!" feature: When asked to enter a comment,
e.g. when setting ACKs or downtimes, you can specify "!" as a comment.
This will cause terminga to launch your external tool. Whatever your
tool has written to the "__TOOL_OUTPUT__" file will then be used as the
actual comment.

The purpose of the "!" feature is to allow you to create issues in your
ticket system from terminga: You select some Icinga alerts, then press
"a" or "d", use "!" as a comment and then your external tool can do
whatever magic it needs to create a ticket -- and finally it can write
the ID of the ticket or its URL to the "__TOOL_OUTPUT__" file.

(Note that "-s" and "-o" in the config snippet above are only examples.
You don't need to use them and terminga doesn't care, it will only
replace the special strings.)

You will want to use terminga-proxy on your Icinga server, if you're
still running a version of Icinga2 that leaks memory on API requests:

https://github.com/seibert-media/terminga-proxy

"group_filters" is optional, too. It can be used to view only those host
and service objects that belong to certain groups (must be configured
within Icinga).

"hide_ack_from_broken" is an optional setting. If set to "true",
acknowledged problems will not be shown if the "only show broken" filter
is enabled (it can be toggled by pressing "b").

"jump_to_first_unhandled" is an optional setting. If set to "true", then
the cursor will jump to the first non-ACKed item on screen refreshes. It
probably only makes sense to use this together with
"hide_ack_from_broken" set to "false".

"default_ack_duration" and "default_downtime_duration" set the
corresponding default expiry times. If unset, "default_ack_duration"
defaults to the string "none" (no expiry) and
"default_downtime_duration" defaults to "1d".

"show_detailed_output_on_startup" is optional. If set to "false",
detailed check output will not be shown and you must press the
appropriate key to do so (see help page).

"size_of_item_area" configures the number of items to show above the
pane showing detailed output. Defaults to 10.