Advanced Topics

Icinga2 Integration

The Shutdown Manager takes advantage of the existing Icinga2 trust infrastructure. Commands executed by the Shutdown Manager can either run directly on the master node (e.g., for shutting down VMs via the vSphere API), or on agents (e.g., calling /usr/bin/halt on physical machines).

Note

Shutdown Commands are executed with the same permissions as the icinga2 daemon itself. This could mean that by default your Icinga2 Agent does not have enough permissions to shut down its own host.

The shutdown of a host is triggered by calling the dedicated API endpoint “shutdown-host”. It takes as parameters:

• A host with an agent, in the form of a monitoring filter (e.g. "filter": "host.name==\"myagent.example.com\"")

• A shutdown_command with arguments to be performed on the destination machine

The shutdown_command parameter MUST contain the ordered list of arguments that the command should execute. The first argument must be the command itself. (e.g. ["/usr/bin/systemctl", "poweroff", "-i"])

Full example:

curl -k -u $USER:$PW \
    -H 'X-HTTP-Method-Override: POST' \
    -H 'Accept: application/json' \
    -X POST 'https://192.0.2.14:5665/v1/actions/shutdown-host' \
    -d '{
           "type": "Host",
           "filter": "host.name==\"myagent.example.com\"",
           "shutdown_command": ["/usr/bin/systemctl", "poweroff", "-i"]
        }'

Depending on the run-on-agent setting of the associated shutdown commant, it will either be executed directly on the master node, or otherwise passed to the specified agent and subsequently executed there.

Shutdown Host Permissions

The shutdown of a given host using the configuration described in the previous sections can also be initiated by calling the /v1/actions/shutdown-host endpoint of an Icinga2 master or satellite node.

If you want to add your own automation for shutting down hosts, you will need to configure a valid Icinga2 API user and grant the actions/shutdown-host permissions as in this example:

object ApiUser "shutdown-automation" {
  password = "secret"
  permission = "actions/shutdown-host"
}

Note

Users with all permissions (”*”) will also be able to initiate shutdown procedures for eligible hosts!

You can then authenticate yourself to the Icinga2 API via BasicAuth.

Shutdown Management Rest API

Shutdown can be executed on an host using a REST API. Currently, the following calls are available.

Trigger Shutdown Definition

Endpoint: trigger-shutdown-definition

This endpoint enables you to trigger an asynchronous run of a shutdown definition via a REST API call. The call is non blocking and the shutdown will be performed in background.

Parameters: * id: The ID of the shutdown definition

Example:

curl -u root:xxx -H 'Accept: application/json' https://localhost/neteye/shutdownmanager/api/trigger-shutdown-definition?id=1