This package on the Python Package Index Tests Documentation Status

pretiac: PREtty Typed Icinga2 Api Client

For more information about the project, please read the API documentation.

pretiac stands for PRE tty T yped I cinga2 A pi C lient. This project is a fork / extension of the TeraIT-at/icinga2apic api client. The client class of icinga2apic was renamed to pretiac.raw_client.RawClient. pretaic provides an additional client (pretiac.client.Client), which is typed. Pydantic is used to validate the Icinga2 REST API and to convert the JSON output into Python data types.

Authenticating Icinga 2 API Users with TLS Client Certificates

Source: Blog post at icinga.com

Icinga 2 supports a second authentication mechanism: TLS client certificates. This is a feature of TLS that also allows the client to send a certificate, just like the server does, allowing the server to authenticate the client as well.

You can start by generating a private key and a certificate signing request (CSR) with the icinga2 pki new-cert command:

icinga2 pki new-cert \
    --cn my-api-client \
    --key my-api-client.key.pem \
    --csr my-api-client.csr.pem

This writes the key and CSR to the files my-api-client.key.pem and my-api-client.csr.pem respectively. Note that you can also use other methods to generate these files. It is only important that the CSR contains a meaningful common name (CN). This allows you to also generate the private key on a hardware security token for example.

Next, the CSR has to be signed by the Icinga CA. This can be achieved by copying the CSR file to the Icinga master and running the following command:

icinga2 pki sign-csr \
    --csr my-api-client.csr.pem \
    --cert my-api-client.cert.pem

This generates a certificate, however, so far, Icinga 2 does not know what to do with this certificate. To fix this, a new ApiUser object has to be created that connects the certificate and its common name with some permissions.

object ApiUser "my-api-client" {
    client_cn = "my-api-client"
    permissions = [ "*" ]
}

After reloading the Icinga 2 configuration, the certificate is now ready to use. The following example uses curl, but any HTTPS client that supports client certificates will do.

Command line interface

Usage: pretiac [OPTIONS] COMMAND [ARGS]...

  Command line interface for the Icinga2 API.

Options:
  -d, --debug  Increase debug verbosity (use up to 3 times): -d: info -dd:
               debug -ddd: verbose.
  --help       Show this message and exit.

Commands:
  actions      There are several actions available for Icinga 2 provided...
  check        Execute checks and send it to the monitoring server.
  config       Manage configuration packages and stages.
  dump-config  Dump the configuration of the pretiac client.
  events       Subscribe to an event stream.
  objects      Manage configuration objects.
  status       Retrieve status information and statistics for Icinga 2.
  types        Retrieve the configuration object types.
  variables    Request information about global variables.

pretiac actions

Usage: pretiac actions [OPTIONS] COMMAND [ARGS]...

  There are several actions available for Icinga 2 provided by the
  ``/v1/actions`` URL endpoint.

Options:
  --help  Show this message and exit.

Commands:
  send-service-check-result  Send a check result for a service and create...

pretiac actions send-service-check-result

Usage: pretiac actions send-service-check-result [OPTIONS] SERVICE

  Send a check result for a service and create the host or the service if
  necessary.

Options:
  --plugin-output TEXT     The plugin main output. Does **not** contain the
                           performance data.
  --performance-data TEXT  The performance data.
  --exit-status TEXT       For services: ``0=OK``, ``1=WARNING``,
                           ``2=CRITICAL``, ``3=UNKNOWN``, for hosts: ``0=UP``,
                           ``1=DOWN``.
  --host TEXT              The name of the host.
  --help                   Show this message and exit.

pretiac config

Usage: pretiac config [OPTIONS] COMMAND [ARGS]...

  Manage configuration packages and stages.

  Manage configuration packages and stages based on configuration files and
  directory trees.

Options:
  --help  Show this message and exit.

Commands:
  delete  Delete a configuration package or a configuration stage entirely.
  show

pretiac config delete

Usage: pretiac config delete [OPTIONS] PACKAGE [STAGE]

  Delete a configuration package or a configuration stage entirely.

Options:
  --help  Show this message and exit.

pretiac objects

Usage: pretiac objects [OPTIONS] COMMAND [ARGS]...

  Manage configuration objects.

Options:
  --help  Show this message and exit.

Commands:
  delete-host     Delete a host, along with all its associated services.
  delete-service  Delete a service.
  list            List the different configuration object types.

pretiac objects delete-host

Usage: pretiac objects delete-host [OPTIONS] HOST

  Delete a host, along with all its associated services.

Options:
  --help  Show this message and exit.

pretiac objects delete-service

Usage: pretiac objects delete-service [OPTIONS] HOST SERVICE

  Delete a service.

Options:
  --help  Show this message and exit.

pretiac objects list

Usage: pretiac objects list [OPTIONS] {ApiUser|CheckCommand|Dependency|Endpoin
                            t|EventCommand|Host|HostGroup|Notification|Notific
                            ationCommand|ScheduledDowntime|Service|ServiceGrou
                            p|TimePeriod|User|UserGroup|Zone}

  List the different configuration object types.

Options:
  --help  Show this message and exit.

The most important functions and classes

pretiac.get_default_client() → Client[source]

Get the default client.

This function intentionally has no input parameters. Use the function set_default_client() to set a new configured client.

However, this function loads a client configured by configuration files in the following order (if the function set_default_client() was not called before):

  1. The file path in the environment variable PRETIAC_CONFIG_FILE.

  2. The configuration file in the home folder ~/.pretiac.yml.

  3. The configuration file at /etc/pretiac/config.yml.

---
api_endpoint_host: localhost
api_endpoint_port: 5665
client_private_key: /etc/pretiac/api-client.key.pem
client_certificate: /etc/pretiac/api-client.cert.pem
ca_certificate: /etc/pretiac/ca.crt
new_host_defaults:
    templates: [passive-host]
new_service_defaults:
    templates: [passive-service]
    attrs:
        check_interval: monthly

The complete API:

Indices and tables