1. Home
  2. Documentation
  3. Advanced
  4. REST API

REST API

new in release v2.24

Thruk offers a rest api to expose various aspects of Thruk itself and livestatus information.

The api can be either accessed by http(s) at http://your_webserver/thruk/r/ or by cli client:

  %> thruk r /hostgroups

Versions

Right now, there is only version 1 of the rest api, so you can either use the generic url http://your_webserver/thruk/r/ or the version specific http://your_webserver/thruk/r/v1/.

Authentication

Basic Auth

Basic authentication is possible with the rest API but not recommended. Use API keys instead. This is a limitation of the apache configuration which cannot set the remote user if supplied, but pass through the request if not.

  %> curl -gk 'https://username:password@localhost/thruk/r/hosts'

Cookies from the cookie authentication are valid as well if you are logged in already and will return the results with permissions of the current user.

API Key

The web rest api accepts the api key as http header. You can create API keys from the user profile page if api_keys_enabled is enabled in your thruk config or with the rest api itself using the /thruk/api_keys endpoint.

  %> curl -H 'X-Thruk-Auth-Key: apikey' \
          -gk 'https://localhost/thruk/r/hosts'

Superuser API Key

A superuser API key (previously named system api key) can be created by admins and is not bound to a specific user. Instead you can set a username with the X-Thruk-Auth-User HTTP header. This makes superuser api keys very powerful and they should be handled with the same care as the secret key. A superuser key can still be restricted to certain roles.

  %> curl -H 'X-Thruk-Auth-Key: apikey' \
          -H 'X-Thruk-Auth-User: automation' \
          -d 'comment=test' \
          -gk 'https://localhost/thruk/r/hosts/localhost/cmd/schedule_host_downtime'

Secret Key

The web rest api accepts the secret key as http header. The secret key is usually found in /var/lib/thruk/secret.key or var/thruk/secret.key when using OMD.

  %> curl -H 'X-Thruk-Auth-Key: secretkey' \
          -H 'X-Thruk-Auth-User: thrukadmin' \
          -gk 'https://localhost/thruk/r/hosts'

Since the secretkey gives you superadminpower. You can set the context of the result to any user you like with the X-Thruk-Auth-User HTTP header.

Command Line

When using the cli clients, use the -A option like:

  %> thruk -A user r /

Having command line access gives you superadminpower as well, so you can set the user context to any user you need with the -A switch.

Parameters

You can pass parameters mostly along with POST and PATCH requests. When using the cli tool, you can utilize the -d parameter with key/value pairs or with json data. Or you can mix those options.

use key/value pairs:

  %> thruk r -m PATCH -d max_check_attempts=3 -d first_notification_delay=10 /hosts/localhost/config

use json structure:

  %> thruk r -m PATCH -d "{'max_check_attempts':3, 'first_notification_delay':10}" /hosts/localhost/config

Using curl, you can set parameters like this:

  %> curl -d "alias=test" -d "max_check_attempts=3" http://your_webserver/thruk/r/hosts/localhost/config

or you can use json data as well:

  %> curl --header "Content-Type: application/json" \
          --X PATCH \
          --data '{"max_check_attempts":3, "first_notification=delay":10}' \
          http://your_webserver/thruk/r/hosts/localhost/config

Filtering

All pages offer filtering using query parameters:

  %> thruk r '/hosts?name=localhost'

Other operators besides equals like regular expressions are possible with the bracket syntax:

ex.: return all hosts starting with literal m:

  %> thruk r '/hosts?name[regex]=^m'

ex.: list all services which are currently in a downtime:

  %> thruk r '/services?scheduled_downtime_depth[gte]=1'

Curl requires you to set the globoff option:

  %> curl -gk 'https://user:pass@localhost/thruk/r/hosts?name[regex]=^t'

ex.: numeric filter using the operators <, >, >= or <= will be expanded like described in relative timestamps.

list session which had been active within the last 10minutes

  %> thruk r '/thruk/sessions?columns=username,max(active)&active[gte]=-10m'

Possible operators with their alias:

Operator Alias Description

=

eq

Equal match

!=

ne

Not equal match

~

Regular expression match (case-sensitive)

!~

Negated regular expression match (case-sensitive)

~~

regex

Regular expression match (case-insensitive)

!~~

nregex

Negated regular expression match (case-insensitive)

>

gt

Greater than numeric comparisson

<

lt

Lower than numeric comparisson

>=

gte

Greater or equal numeric comparisson. contains in list context

<=

lte

Lower or equal numeric comparisson. contains not in list context

!>=

notin

contains not in list context

You can use the alias name to workaround urlencoding issues.

Complex Filtering

Complex filtering logic is possible by using a simple query language which supports logical operators. The query can be passed urlencoded with the q parameter. An alternative to url encoding is using a special quote syntax by encapsulating the query in ***. Everything between *** will be automatically url encoded. (You still need to get quoting right).

  %> thruk r '/hosts?q=***name = "test" or name = "other"***'

Another example, fetch all hosts from hostgroups linux and windows which are not ok.

  %> thruk r '/hosts?q=***(groups >= "linux" or groups >= "windows") and status != 0***'

Example using curl:

  %> curl -d 'q=***name = "test"***' 'http://.../thruk/r/hosts'

If you need * in the query itself, any other three characters will do as well:

  %> thruk r '/notifications?q=///message = "test" or name = "other"///

Lexical filter can use the same time expands as normal filter:

  %> thruk r '/services?q=***last_check <= "-7d"***'

This will translate to a filter, selecting all services having a last_check date lower than now - 7 days. Note the quotes around the value.

Sorting

All pages can sort list results by using the sort parameter. The sort parameter can be used multiple times or use comma-separated lists. The order is ascending unless prefixed with an minus.

ex.: sort by name ascending and status descending:

  %> thruk r /hosts?sort=name,-state

Limits

All pages offer limits and offset through the limit and offset parameter.

The offset starts a 0, so offset=1 strips of the first item and starts the result with the second one. For example show 10 hosts starting with the item 101:

  %> thruk r /hosts?limit=10&offset=100

Columns

All pages offer setting columns with the columns parameter.

ex.: return name and state for all hosts:

  %> thruk r /hosts?columns=name,state

Rename columns by appending :name like this:

  %> thruk r /hosts?columns=name:host_name,state:status

or by adding as aliasname

  %> thruk r '/hosts?columns=name:host_name,state as status'

Note: If the column contains special characters, use backticks to enclose the column name, ex.:

  %> thruk r '/hosts?columns=`Disk C:\`'

or:

  %> thruk r '/hosts?columns=`Disk C:\` as size'

Performance Data Columns

Thruk will expand performance data into separate columns for host/service queries.

Ex.: a host with the check_icmp check has the performance data put into the coresponding columns, so the following (shorted) json will be returned.

There are 2 columns for each performance value. One with the value itself and one with the unit.

There is also a hash containing the expanded performance values.

Those columns can be used for filtering or to only select specific performance data columns.

  %> thruk r /hosts?limit=1

[
   {
...
      "name" : "icmp checked host",
...
      "perf_data" : "rta=0.030ms;3000.000;5000.000;0; pl=0%;80;100;;",
      "perf_data_expanded" : [
         {
            "crit" : "5000.000",
            "max" : "",
            "min" : "0",
            "name" : "rta",
            "orig" : "rta=0.030ms;3000.000;5000.000;0;",
            "parent" : "",
            "unit" : "ms",
            "value" : "0.030",
            "warn" : "3000.000"
         },
         {
            "crit" : "100",
            "max" : "",
            "min" : "",
            "name" : "pl",
            "orig" : "pl=0%;80;100;;",
            "parent" : "",
            "unit" : "%",
            "value" : "0",
            "warn" : "80"
         }
      ],
      "pl" : "0",
      "pl_unit" : "%",
      "rta" : "0.030",
      "rta_unit" : "ms"
...
   }
]
Filter by performance values

Those columns can also be used for filtering. Ex. get all hosts having packing loss greater zero.

%> thruk r '/hosts?columns=pl,name&pl[gte]=0'

Custom Data Columns

Thruk will expand custom data values into separate columns for host/service queries.

Those columns can be used for filtering or to only select specific custom values.

  %> thruk r '/hosts?limit=1&_WORKER=local'
[
   {
...
      "_THRUK_BP_ID" : "666",
      "_THRUK_NODE_ID" : "node1",
      "_WORKER" : "local",
      "custom_variable_names" : [
         "THRUK_BP_ID",
         "THRUK_NODE_ID",
         "WORKER"
      ],
      "custom_variable_values" : [
         "666",
         "node1",
         "local"
      ],
      "custom_variables" : {
         "THRUK_BP_ID" : "666",
         "THRUK_NODE_ID" : "node1",
         "WORKER" : "local"
      },
...
      "name" : "host with custom variables",
...
   }
]
Host custom variables

Host custom variables are accessible with the _HOST prefix for example like.:

%> thruk r '/services?columns=_HOSTWORKER&description'

Calculations

Simple calculations (+, -, *, /) can be achieved by using those operators in the columns selection.

ex.: sum the number of problems for each host

  %> thruk r '/hosts?columns=name,num_services_crit+num_services_unknown+num_services_warn as num_services_problems'

Functions

Transformation Functions

Transformation functions can be used to adjust result data.

Available transformations functions are:

  • upper: make column upper case

  • uc: alias for upper

  • lower: make column lower case

  • lc: alias for lower

  • substr: extract substring (substr(columnname, offset [, length]))

  • calc: apply mathematical operation (calc(column, op , value) ex.: calc(last_check, '*', 1000))

  • s: apply regex replacement (s(column, regex, replace) ex.: s(host_name, '/\..*$/', '') Note: you cannot use backreferences like $1 in the replacement string for security reasons.

  • unit: set the unit for this column (unit(column, unit) ex.: unit(calc(rta, "*", 1000), "s")

ex.: return first 3 characters from upper case host name.

  %> thruk r '/hosts?columns=upper(substr(name, 0, 3)) as host'

Aggregation Functions

Aggregation functions can be used to get statistical information.

Available aggregaton functions are:

  • count: total number of matches

  • avg: calculated average for numerical columns

  • sum: calculated sum for numerical columns

  • min: calculated minimum value for numerical columns

  • max: calculated maximum value for numerical columns

ex.: return average latency over all hosts

  %> thruk r '/hosts?columns=avg(latency)'

The query can include group by columns without aggregations functions,

ex.: list average execution time over all services grouped by state.

  %> thruk r '/services?columns=avg(execution_time),state&sort=avg(execution_time)'

Rename columns by appending :name

  %> thruk r '/thruk/sessions?columns=count(*):sessions'

Renaming can be combined with grouping columns.

  %> thruk r '/services?columns=avg(execution_time):avg_exec_time,host_name'

The group by column can be renamed as well:

  %> thruk r '/services?columns=avg(execution_time),peer_name:site'

Aggregation functions can be used in filter (alias cannot be used in filter):

  %> thruk r '/services?columns=avg(execution_time):exec_time&avg(execution_time)[gt]=0'

Disaggregation Functions

Disaggregation functions create multiple result rows from a single attribute.

Available disaggregation functions are:

  • to_rows: allocate result rows from list column

  • as_rows: alias for to_rows

  %> thruk r '/hosts?columns=name,to_rows(services) as services'

Of course, this example could be achieved easier but creating a query on the services table, but you get the idea.

Mixing Functions

When mixing aggregation and transformation functions, apply the aggregation function as the outer most function, as for example in:

  %> thruk r '/hosts/localhost?columns=avg(unit(calc(latency,/,1000), "ms"))'

When mixing disaggregation and transformation functions, apply the disaggregation function as the inner most function, as for example in:

  %> thruk r '/hosts/localhost?columns=upper(name),upper(to_rows(services))'

Backends / Sites

If you have multiple sites connected to Thruk, you may want to talk only to specific sites. There are multiple methods to set the backends for your request. You can combine multiple sites with commas.

  • Use a path prefix /sites/<sitename,…​>:

      %> thruk r /sites/test,prod/hosts

  • Use the backends option with the cli client:

      %> thruk r -b test,prod /hosts

  • Set the backends url parameter:

      %> thruk r /hosts?backends=test,prod
All Sites

Thruk uses all backends unless they are configured as hidden=yes. In that case you can force selecting all backends with the /sites/ALL/ prefix.
Local Sites

In case you want to send queries only to local backends (those using a unix socket connection) you can use the /sites/LOCAL/ prefix.

Error Handling

Failed rest requests return a hash result along with a HTTP error code:

  %> thruk r /none
  {
    "code" : 404,
    "message" : "unknown rest path"
    "description" : "optional additional error messages"
  }

Output Formats

JSON

JSON is the default output format.

CSV

CSV output is available via /csv/ path prefix. Column names will be automatically added as first (commented) line. This can be disabled with the headers=0 parameter.

Escaping and nested objects
Support for nested objects and escaping of semicolons is limited. Nested Objects will fallback to json encoding. If possible, use json format which is faster and more reliable. 
  %> thruk r /csv/hosts?columns=name,state
  %> thruk r '/csv/hosts?columns=name,state&headers=0'
  %> thruk r /hosts?columns=name,state --csv
  %> curl -g http://localhost/thruk/r/csv/hosts/stats

XLS

Excel output is available via /xls/ path prefix.

  %> thruk r /xls/hosts?columns=name,state
  %> thruk r /hosts?columns=name,state --xls

Table

Human readable table output is available via /human/ or /text/ path prefix.

  %> thruk r /human/hosts?columns=name,state
  %> thruk r /hosts?columns=name,state --human
  %> thruk r /hosts?columns=name,state --text
  %> thruk r /hosts?columns=name,state -t

HTTP Methods

HTTP Methods are implemented according to RFC2616 which is in short:

GET retrieve ressources, ex.: GET /thruk/reports to list all reports.

POST

update/create ressources or trigger actions, ex.: POST /thruk/reports to create a new report.

PUT

overwrite existing ressource, ex.: PUT /thruk/reports/1 to update an entire existing report. Thruk makes no difference between POST and PUT. You can use PUT for all POST urls and vice versa.

PATCH

replace parts of existing ressource, ex.: PATCH /thruk/reports/1 to set specific attributes of an existing report.

DELETE

remove existing ressource, ex.: DELETE /thruk/reports/1 to remove the report entirely.

Object configuration notes

To create brand new object configurations (e.g hosts), you MUST use POST /config/objects as documented further down.

POST /*/<name>/config is only used for overwriting existing objects.

After object configuration changes, use the following sequence of steps (similar to the GUI object config tool):

1) GET /config/diff

a) At this point you can revert the changes by using POST /config/revert

2) POST /config/save

3) POST /config/check

4) POST /config/reload

Make sure to check the output of each step

Endpoints

You can find lots of examples on the REST API examples page.

The complete list of available external commands can be found on the REST API commands page.

See examples and detailed description for all other available rest api urls:

GET /

lists all available rest urls. alias for /index

GET /alerts

lists alerts based on logfiles. alias for /logs?type[~]=^(HOST|SERVICE) ALERT

GET /checks/stats

lists host / service check statistics.

Attribute Type Unit Description

hosts_active_15_perc

number

%

percent of active hosts during the last 15 minutes

hosts_active_15_sum

number

amount of active hosts during the last 15 minutes

hosts_active_1_perc

number

%

same for last minute

hosts_active_1_sum

number

same for last minute

hosts_active_5_perc

number

%

same for last 5 minutes

hosts_active_5_sum

number

same for last 5 minutes

hosts_active_60_perc

number

%

same for last 60 minutes

hosts_active_60_sum

number

same for last 60 minutes

hosts_active_all_perc

number

%

percent of total active hosts

hosts_active_all_sum

number

amount of total active hosts

hosts_active_state_change_avg

number

%

average percent state change

hosts_active_state_change_max

number

%

maximum state change over all active hosts

hosts_active_state_change_min

number

%

minimum state change over all active hosts

hosts_active_state_change_sum

number

%

sum state change over all hosts

hosts_active_sum

number

number of active hosts

hosts_execution_time_avg

number

s

average execution time over all hosts

hosts_execution_time_max

number

s

maximum execution time over all hosts

hosts_execution_time_min

number

s

minimum execution time over all hosts

hosts_execution_time_sum

number

s

sum execution time over all hosts

hosts_latency_avg

number

host latency average

hosts_latency_max

number

minimum host latency

hosts_latency_min

number

minimum host latency

hosts_latency_sum

number

sum latency over all hosts

hosts_passive_15_perc

number

%

percent of passive hosts during the last 15 minutes

hosts_passive_15_sum

number

amount of passive hosts during the last 15 minutes

hosts_passive_1_perc

number

%

same for last minute

hosts_passive_1_sum

number

same for last minute

hosts_passive_5_perc

number

%

same for last 5 minutes

hosts_passive_5_sum

number

same for last 5 minutes

hosts_passive_60_perc

number

%

same for last 60 minutes

hosts_passive_60_sum

number

same for last 60 minutes

hosts_passive_all_perc

number

%

percent of total passive hosts

hosts_passive_all_sum

number

amount of total passive hosts

hosts_passive_state_change_avg

number

%

average percent state change for passive hosts

hosts_passive_state_change_max

number

%

maximum state change over all passive hosts

hosts_passive_state_change_min

number

%

minimum state change over all passive hosts

hosts_passive_state_change_sum

number

%

sum state change over all passive hosts

hosts_passive_sum

number

number of passive hosts

services_active_15_perc

number

%

percent of active services during the last 15 minutes

services_active_15_sum

number

amount of active services during the last 15 minutes

services_active_1_perc

number

%

same for last minute

services_active_1_sum

number

same for last minute

services_active_5_perc

number

%

same for last 5 minutes

services_active_5_sum

number

same for last 5 minutes

services_active_60_perc

number

%

same for last 60 minutes

services_active_60_sum

number

same for last 60 minutes

services_active_all_perc

number

%

percent of total active services

services_active_all_sum

number

amount of total active services

services_active_state_change_avg

number

%

average percent state change

services_active_state_change_max

number

%

maximum state change over all active services

services_active_state_change_min

number

%

minimum state change over all active services

services_active_state_change_sum

number

%

sum state change over all services

services_active_sum

number

number of active services

services_execution_time_avg

number

s

average execution time over all services

services_execution_time_max

number

s

maximum execution time over all services

services_execution_time_min

number

s

minimum execution time over all services

services_execution_time_sum

number

s

sum execution time over all services

services_latency_avg

number

services latency average

services_latency_max

number

minimum services latency

services_latency_min

number

minimum services latency

services_latency_sum

number

sum latency over all services

services_passive_15_perc

number

%

percent of passive services during the last 15 minutes

services_passive_15_sum

number

amount of passive services during the last 15 minutes

services_passive_1_perc

number

%

same for last minute

services_passive_1_sum

number

same for last minute

services_passive_5_perc

number

%

same for last 5 minutes

services_passive_5_sum

number

same for last 5 minutes

services_passive_60_perc

number

%

same for last 60 minutes

services_passive_60_sum

number

same for last 60 minutes

services_passive_all_perc

number

%

percent of total passive services

services_passive_all_sum

number

amount of total passive services

services_passive_state_change_avg

number

%

average percent state change for passive services

services_passive_state_change_max

number

%

maximum state change over all passive services

services_passive_state_change_min

number

%

minimum state change over all passive services

services_passive_state_change_sum

number

%

sum state change over all passive services

services_passive_sum

number

number of passive services

POST /cmd

Sends any command.

Required arguments:

  • cmd

Optional arguments:

  • host

  • hostgroup

  • service

  • servicegroup

  • contact

  • contactgroup

GET /commands

lists livestatus commands. see https://www.naemon.io/documentation/usersguide/livestatus.html#commands for details.

GET /commands/<name>

lists commands for given name. alias for /commands?name=<name>

GET /commands/<name>/config

Returns configuration for given command. You will find available attributes here: http://www.naemon.io/documentation/usersguide/objectdefinitions.html#command

POST /commands/<name>/config

Replace command configuration completely, use PATCH to only update specific attributes.

PATCH /commands/<name>/config

Update command configuration partially.

DELETE /commands/<name>/config

Deletes given command from configuration.

GET /comments

lists livestatus comments. see https://www.naemon.io/documentation/usersguide/livestatus.html#comments for details.

GET /comments/<id>

lists comments for given id. alias for /comments?id=<id>

POST /config/check

Returns result from config check. This check does require changes to be saved to disk before running the check.

GET /config/diff

Optional arguments:

  • ignore_whitespace

Returns differences between filesystem and stashed config changes.

Attribute Type Unit Description

file

file name of changed file

output

diff output

peer_key

backend id when having multiple sites connected

POST /config/discard

Reverts stashed configuration changes. Alias for /config/revert

GET /config/files

returns all config files

Attribute Type Unit Description

content

raw file content

hex

hex sum for this file

mtime

time

unix timestamp of last modification

path

filesystem path

peer_key

backend id when having multiple sites connected

readonly

readonly flag

GET /config/fullobjects

Returns list of all objects with templates expanded. Used templates are saved to the :TEMPLATES attribute

Attribute Type Unit Description

…​

object attributes like defined in the source config files

:FILE

filename and line number

:ID

internal uniq id

:PEER_KEY

id of remote site

:PEER_NAME

name of remote site

:READONLY

flag whether file is readonly

:TEMPLATES

list of used template

:TYPE

object type, ex.: host

GET /config/objects

Returns list of all objects with their raw config. Use /config/fullobjects to get the full expanded config.

Attribute Type Unit Description

…​

object attributes like defined in the source config files

:FILE

filename and line number

:ID

internal uniq id

:PEER_KEY

id of remote site

:PEER_NAME

name of remote site

:READONLY

flag whether file is readonly

:TYPE

object type, ex.: host

POST /config/objects

Create new object. Besides the actual object config, requires 2 special paramters :FILE and :TYPE.

PATCH /config/objects

Change attributes for all matching objects. This is a very powerful url, for example you could change all hosts which have max_check_attempts=3 to max_check_attempts=5 with this command:

thruk r -m PATCH -d max_check_attempts=5 '/config/objects?:TYPE=host&max_check_attempts=3'

DELETE /config/objects

Delete objects based on filters. This is a very powerful url, without filter, all objects would be removed. Ex.: remove all contacts matching a name:

thruk r -m DELETE '/config/objects?contact_name=test'

POST /config/objects/<id>

Replace object configuration completely.

PATCH /config/objects/<id>

Update object configuration partially.

DELETE /config/objects/<id>

Remove given object from configuration.

GET /config/precheck

Returns result from Thruks config precheck. The precheck does not require changes to be saved to disk before running the check.

Attribute Type Unit Description

errors

list of errors encountered

failed

boolean flag wether configuration check has failed or not

peer_key

backend id when having multiple sites connected

POST /config/reload

Reloads configuration with the configured reload command.

POST /config/revert

Reverts stashed configuration changes.

POST /config/save

Saves stashed configuration changes to disk.

GET /contactgroups

lists livestatus contactgroups. see https://www.naemon.io/documentation/usersguide/livestatus.html#contactgroups for details.

GET /contactgroups/<name>

lists contactgroups for given name. alias for /contactgroups?name=<name>

POST /contactgroups/<name>/cmd/…​

external commands are documented in detail on a separate commands page. list of supported commands:

GET /contactgroups/<name>/config

Returns configuration for given contactgroup. You will find available attributes here: http://www.naemon.io/documentation/usersguide/objectdefinitions.html#contactgroup

POST /contactgroups/<name>/config

Replace contactgroup configuration completely, use PATCH to only update specific attributes.

PATCH /contactgroups/<name>/config

Update contactgroup configuration partially.

DELETE /contactgroups/<name>/config

Deletes given contactgroup from configuration.

GET /contacts

lists livestatus contacts. see https://www.naemon.io/documentation/usersguide/livestatus.html#contacts for details.

GET /contacts/<name>

lists contacts for given name. alias for /contacts?name=<name>

POST /contacts/<name>/cmd/…​

external commands are documented in detail on a separate commands page. list of supported commands:

GET /contacts/<name>/config

Returns configuration for given contact. You will find available attributes here: http://www.naemon.io/documentation/usersguide/objectdefinitions.html#contact

POST /contacts/<name>/config

Replace contact configuration completely, use PATCH to only update specific attributes.

PATCH /contacts/<name>/config

Update contact configuration partially.

DELETE /contacts/<name>/config

Deletes given contact from configuration.

GET /downtimes

lists livestatus downtimes. see https://www.naemon.io/documentation/usersguide/livestatus.html#downtimes for details.

GET /downtimes/<id>

lists downtimes for given id. alias for /downtimes?id=<id>

GET /hostgroups

lists livestatus hostgroups. see https://www.naemon.io/documentation/usersguide/livestatus.html#hostgroups for details.

GET /hostgroups/<name>

lists hostgroups for given name. alias for /hostgroups?name=<name>

GET /hostgroups/<name>/availability

list availability for this hostgroup.

Optional arguments:

  • type - both | hosts | services

  • timeperiod - last24hours | lastmonth | thismonth | …​

  • start - unix timestamp

  • end - unix timestamp

  • withdowntimes - 0/1 wheter downtimes should count as outages

  • includesoftstates - 0/1 wheter soft states should be used as well

Attribute Type Unit Description

host

host name

scheduled_time_down

number

s

total seconds in state down (during downtimes)

scheduled_time_down_percent

number

%

time down in percent of total time (during downtimes)

scheduled_time_indeterminate

number

s

total seconds unknown (during downtimes)

scheduled_time_indeterminate_percent

number

%

time unknown in percent of total time (during downtimes)

scheduled_time_unreachable

number

s

total seconds in state unreachable (during downtimes)

scheduled_time_unreachable_percent

number

%

time unreachable in percent of total time (during downtimes)

scheduled_time_up

number

s

total seconds in state up (during downtimes)

scheduled_time_up_percent

number

%

time up in percent of total time (during downtimes)

time_down

number

s

total seconds in state down

time_down_percent

number

%

time down in percent of total time

time_indeterminate_nodata

number

s

total seconds without any data

time_indeterminate_nodata_percent

number

%

time without any data in percent of total time

time_indeterminate_notrunning

number

s

total seconds during core not running

time_indeterminate_notrunning_percent

number

%

time during core not running in percent of total time

time_indeterminate_outside_timeperiod

number

s

total seconds outside the given timeperiod

time_indeterminate_outside_timeperiod_percent

number

%

time outside the given timeperiod in percent of total time

time_unreachable

number

s

total seconds in state unreachable

time_unreachable_percent

number

%

time unreachable in percent of total time

time_up

number

s

total seconds in state up

time_up_percent

number

%

time up in percent of total time

POST /hostgroups/<name>/cmd/…​

external commands are documented in detail on a separate commands page. list of supported commands:

GET /hostgroups/<name>/config

Returns configuration for given hostgroup. You will find available attributes here: http://www.naemon.io/documentation/usersguide/objectdefinitions.html#hostgroup

POST /hostgroups/<name>/config

Replace hostgroups configuration completely, use PATCH to only update specific attributes.

PATCH /hostgroups/<name>/config

Update hostgroup configuration partially.

DELETE /hostgroups/<name>/config

Deletes given hostgroup from configuration.

GET /hostgroups/<name>/outages

list of outages for this hostgroup.

Optional arguments:

  • type - both | hosts | services

  • timeperiod - last24hours | lastmonth | thismonth | …​

  • start - unix timestamp

  • end - unix timestamp

  • withdowntimes - 0/1 wheter downtimes should count as outages

  • includesoftstates - 0/1 wheter soft states should be used as well

Attribute Type Unit Description

class

host/service status

duration

number

s

outage duration in seconds

end

time

unix timestamp of outage end

host

host name

in_downtime

0/1 flag wether this outage is in a downtime

plugin_output

last plugin output during outage

service

service description (only for service outages)

start

time

unix timestamp of outage start

type

log entry type

GET /hostgroups/<name>/stats

hash of livestatus hostgroup statistics. alias for /hosts/stats?groups[gte]=<name>

GET /hosts

lists livestatus hosts. see https://www.naemon.io/documentation/usersguide/livestatus.html#hosts for details.

GET /hosts/<name>

lists hosts for given name. alias for /hosts?name=<name>

GET /hosts/<name>/alerts

lists alerts for given host. alias for /logs?type[~]=^(HOST|SERVICE) ALERT&host_name=<name>

GET /hosts/<name>/availability

list availability for this host.

Optional arguments:

  • timeperiod - last24hours | lastmonth | thismonth | …​

  • start - unix timestamp

  • end - unix timestamp

  • withdowntimes - 0/1 wheter downtimes should count as outages

  • includesoftstates - 0/1 wheter soft states should be used as well

Attribute Type Unit Description

scheduled_time_down

number

s

total seconds in state down (during downtimes)

scheduled_time_down_percent

number

%

time down in percent of total time (during downtimes)

scheduled_time_indeterminate

number

s

total seconds unknown (during downtimes)

scheduled_time_indeterminate_percent

number

%

time unknown in percent of total time (during downtimes)

scheduled_time_unreachable

number

s

total seconds in state unreachable (during downtimes)

scheduled_time_unreachable_percent

number

%

time unreachable in percent of total time (during downtimes)

scheduled_time_up

number

s

total seconds in state up (during downtimes)

scheduled_time_up_percent

number

%

time up in percent of total time (during downtimes)

time_down

number

s

total seconds in state down

time_down_percent

number

%

time down in percent of total time

time_indeterminate_nodata

number

s

total seconds without any data

time_indeterminate_nodata_percent

number

%

time without any data in percent of total time

time_indeterminate_notrunning

number

s

total seconds during core not running

time_indeterminate_notrunning_percent

number

%

time during core not running in percent of total time

time_indeterminate_outside_timeperiod

number

s

total seconds outside the given timeperiod

time_indeterminate_outside_timeperiod_percent

number

%

time outside the given timeperiod in percent of total time

time_unreachable

number

s

total seconds in state unreachable

time_unreachable_percent

number

%

time unreachable in percent of total time

time_up

number

s

total seconds in state up

time_up_percent

number

%

time up in percent of total time

POST /hosts/<name>/cmd/…​

external commands are documented in detail on a separate commands page. list of supported commands:

GET /hosts/<name>/commandline

displays commandline for check command of given hosts.

Attribute Type Unit Description

check_command

name of the check_command including arguments

command_line

full expanded command line (if possible)

error

contains the error if expanding failed for some reason

host_name

host name

peer_key

backend id when having multiple sites connected

peer_name

name of remote site

GET /hosts/<name>/config

Returns configuration for given host. You will find available attributes here: http://www.naemon.io/documentation/usersguide/objectdefinitions.html#host

POST /hosts/<name>/config

Replace host configuration completely, use PATCH to only update specific attributes.

PATCH /hosts/<name>/config

Update host configuration partially.

DELETE /hosts/<name>/config

Deletes given host from configuration.

GET /hosts/<name>/notifications

lists notifications for given host. alias for /logs?class=3&host_name=<name>

GET /hosts/<name>/outages

list of outages for this host.

Optional arguments:

  • type - both | hosts | services

  • timeperiod - last24hours | lastmonth | thismonth | …​

  • start - unix timestamp

  • end - unix timestamp

  • withdowntimes - 0/1 wheter downtimes should count as outages

  • includesoftstates - 0/1 wheter soft states should be used as well

Attribute Type Unit Description

class

host/service status

duration

number

s

outage duration in seconds

end

time

unix timestamp of outage end

host

host name

in_downtime

0/1 flag wether this outage is in a downtime

plugin_output

last plugin output during outage

start

time

unix timestamp of outage start

type

log entry type

GET /hosts/<name>/services

lists services for given host. alias for /services?host_name=<name>

GET /hosts/availability

list availability for all hosts.

Optional arguments:

  • type - both | hosts | services

  • timeperiod - last24hours | lastmonth | thismonth | …​

  • start - unix timestamp

  • end - unix timestamp

  • withdowntimes - 0/1 wheter downtimes should count as outages

  • includesoftstates - 0/1 wheter soft states should be used as well

supports hostgroup filter, ex. GET /hosts/availability?hostgroup=foo

Attribute Type Unit Description

host

host name

scheduled_time_down

number

s

total seconds in state down (during downtimes)

scheduled_time_down_percent

number

%

time down in percent of total time (during downtimes)

scheduled_time_indeterminate

number

s

total seconds unknown (during downtimes)

scheduled_time_indeterminate_percent

number

%

time unknown in percent of total time (during downtimes)

scheduled_time_unreachable

number

s

total seconds in state unreachable (during downtimes)

scheduled_time_unreachable_percent

number

%

time unreachable in percent of total time (during downtimes)

scheduled_time_up

number

s

total seconds in state up (during downtimes)

scheduled_time_up_percent

number

%

time up in percent of total time (during downtimes)

time_down

number

s

total seconds in state down

time_down_percent

number

%

time down in percent of total time

time_indeterminate_nodata

number

s

total seconds without any data

time_indeterminate_nodata_percent

number

%

time without any data in percent of total time

time_indeterminate_notrunning

number

s

total seconds during core not running

time_indeterminate_notrunning_percent

number

%

time during core not running in percent of total time

time_indeterminate_outside_timeperiod

number

s

total seconds outside the given timeperiod

time_indeterminate_outside_timeperiod_percent

number

%

time outside the given timeperiod in percent of total time

time_unreachable

number

s

total seconds in state unreachable

time_unreachable_percent

number

%

time unreachable in percent of total time

time_up

number

s

total seconds in state up

time_up_percent

number

%

time up in percent of total time

GET /hosts/outages

list of outages for all hosts.

Optional arguments:

  • type - both | hosts | services

  • timeperiod - last24hours | lastmonth | thismonth | …​

  • start - unix timestamp

  • end - unix timestamp

  • withdowntimes - 0/1 wheter downtimes should count as outages

  • includesoftstates - 0/1 wheter soft states should be used as well

Attribute Type Unit Description

class

host/service status

duration

number

s

outage duration in seconds

end

time

unix timestamp of outage end

host

host name

in_downtime

0/1 flag wether this outage is in a downtime

plugin_output

last plugin output during outage

start

time

unix timestamp of outage start

type

log entry type

GET /hosts/stats

hash of livestatus host statistics.

Attribute Type Unit Description

active_checks_disabled_active

number of active hosts which have active checks disabled

active_checks_disabled_passive

number of passive hosts which have active checks disabled

down

number of down hosts

down_and_ack

number of down hosts which are acknowledged

down_and_disabled_active

number of active down hosts which have active checks disabled

down_and_disabled_passive

number of passive down hosts which have active checks disabled

down_and_scheduled

number of down hosts which are in a scheduled downtime

down_and_unhandled

number of unhandled down hosts

eventhandler_disabled

number of hosts with eventhandlers disabled

flapping

number of flapping hosts

flapping_disabled

number of hosts with flapping detection disabled

notifications_disabled

number of hosts with notifications disabled

outages

number of network outages

passive_checks_disabled

number of hosts which do not accept passive check results

pending

number of pending hosts

pending_and_disabled

number of pending hosts with active checks disabled

pending_and_scheduled

number of pending hosts which are in a scheduled downtime

plain_down

number of down hosts which are not acknowleded or in a downtime

plain_pending

number of pending hosts which are not acknowleded or in a downtime

plain_unreachable

number of unreachable hosts which are not acknowleded or in a downtime

plain_up

number of up hosts which are not acknowleded or in a downtime

total

total number of hosts

total_active

total number of active hosts

total_passive

total number of passive hosts

unreachable

number of unreachable hosts

unreachable_and_ack

number of unreachable hosts which are acknowledged

unreachable_and_disabled_active

number of active unreachable hosts which have active checks disabled

unreachable_and_disabled_passive

number of passive unreachable hosts which have active checks disabled

unreachable_and_scheduled

number of unreachable hosts which are in a scheduled downtime

unreachable_and_unhandled

number of unhandled unreachable hosts

up

number of up hosts

up_and_disabled_active

number of active up hosts which have active checks disabled

up_and_disabled_passive

number of passive up hosts which have active checks disabled

up_and_scheduled

number of up hosts which are in a scheduled downtime

GET /hosts/totals

hash of livestatus host totals statistics. its basically a reduced set of /hosts/stats.

Attribute Type Unit Description

down

number of down hosts

down_and_unhandled

number of down hosts which are neither acknowledged nor in scheduled downtime

pending

number of pending hosts

total

total number of hosts

unreachable

number of unreachable hosts

unreachable_and_unhandled

number of unreachable hosts which are neither acknowledged nor in scheduled downtime

up

number of up hosts

GET /index

lists all available rest urls.

Attribute Type Unit Description

description

description of the url

protocol

protocol to use for this url

url

the rest url

GET /lmd/sites

lists connected sites. Only available if LMD (use_lmd) is enabled.

Attribute Type Unit Description

addr

address of the remote site

bytes_received

number

bytes

total bytes received from this site

bytes_send

number

bytes

total bytes send to this site

federation_addr

contains the real address if using federation

federation_key

contains the real peer key if using federation

federation_name

contains the real name if using federation

federation_type

contains the real backend type if using federation

idling

flag if the connection is in idle mode

key

primary id of this site

last_error

time

last error message

last_online

time

timestamp when the site was last time online

last_query

time

timestamp of the last received query for this site

last_update

time

timestamp of the last update

lmd_last_cache_update

time

same as last_update

name

name of the site

parent

parent id for lmd federation setups

peer_key

same as key

peer_name

same as name

queries

number of queries received

response_time

number

s

response time in seconds

section

thruks section

status

connection status of this site

GET /logs

lists livestatus logs. see https://www.naemon.io/documentation/usersguide/livestatus.html#log for details.

GET /notifications

lists notifications based on logfiles. alias for /logs?class=3

GET /processinfo

lists livestatus sites status. see https://www.naemon.io/documentation/usersguide/livestatus.html#status for details.

GET /processinfo/stats

lists livestatus sites statistics. see https://www.naemon.io/documentation/usersguide/livestatus.html#status for details.

GET /servicegroups

lists livestatus servicegroups. see https://www.naemon.io/documentation/usersguide/livestatus.html#servicegroups for details.

GET /servicegroups/<name>

lists servicegroups for given name. alias for /servicegroups?name=<name>

GET /servicegroups/<name>/availability

list availability for this servicegroup.

Optional arguments:

  • type - both | hosts | services

  • timeperiod - last24hours | lastmonth | thismonth | …​

  • start - unix timestamp

  • end - unix timestamp

  • withdowntimes - 0/1 wheter downtimes should count as outages

  • includesoftstates - 0/1 wheter soft states should be used as well

Attribute Type Unit Description

host

host name

scheduled_time_critical

number

s

total seconds in state critical (during downtimes)

scheduled_time_critical_percent

number

%

time critical in percent of total time (during downtimes)

scheduled_time_indeterminate

number

s

total seconds unknown (during downtimes)

scheduled_time_indeterminate_percent

number

%

time unknown in percent of total time (during downtimes)

scheduled_time_ok

number

s

total seconds in state ok (during downtimes)

scheduled_time_ok_percent

number

%

time ok in percent of total time (during downtimes)

scheduled_time_unknown

number

s

total seconds in state unknown (during downtimes)

scheduled_time_unknown_percent

number

%

time unknown in percent of total time (during downtimes)

scheduled_time_warning

number

s

total seconds in state warning (during downtimes)

scheduled_time_warning_percent

number

%

time warning in percent of total time (during downtimes)

service

service description

time_critical

number

s

total seconds in state critical

time_critical_percent

number

%

time critical in percent of total time

time_indeterminate_nodata

number

s

total seconds without any data

time_indeterminate_nodata_percent

number

%

time without any data in percent of total time (during downtimes)

time_indeterminate_notrunning

number

s

total seconds during core not running

time_indeterminate_notrunning_percent

number

%

time during core not running in percent of total time

time_indeterminate_outside_timeperiod

number

s

total seconds outside the given timeperiod

time_indeterminate_outside_timeperiod_percent

number

%

time outside the given timeperiod in percent of total time

time_ok

number

s

total seconds in state ok

time_ok_percent

number

%

time ok in percent of total time

time_unknown

number

s

total seconds in state unknown

time_unknown_percent

number

%

time unknown in percent of total time

time_warning

number

s

total seconds in state warning

time_warning_percent

number

%

time warning in percent of total time

POST /servicegroups/<name>/cmd/…​

external commands are documented in detail on a separate commands page. list of supported commands:

GET /servicegroups/<name>/config

Returns configuration for given servicegroup. You will find available attributes here: http://www.naemon.io/documentation/usersguide/objectdefinitions.html#servicegroup

POST /servicegroups/<name>/config

Replace servicegroup configuration completely, use PATCH to only update specific attributes.

PATCH /servicegroups/<name>/config

Update servicegroup configuration partially.

DELETE /servicegroups/<name>/config

Deletes given servicegroup from configuration.

GET /servicegroups/<name>/outages

list of outages for this servicegroup.

Optional arguments:

  • type - both | hosts | services

  • timeperiod - last24hours | lastmonth | thismonth | …​

  • start - unix timestamp

  • end - unix timestamp

  • withdowntimes - 0/1 wheter downtimes should count as outages

  • includesoftstates - 0/1 wheter soft states should be used as well

Attribute Type Unit Description

class

host/service status

duration

number

s

outage duration in seconds

end

time

unix timestamp of outage end

host

host name

in_downtime

0/1 flag wether this outage is in a downtime

plugin_output

last plugin output during outage

service

service description (only for service outages)

start

time

unix timestamp of outage start

type

log entry type

GET /servicegroups/<name>/stats

hash of livestatus servicegroup statistics. alias for /services/stats?service_groups[gte]=<name>

GET /services

lists livestatus services. see https://www.naemon.io/documentation/usersguide/livestatus.html#services for details. there is an alias /services.

GET /services/<host>/<service>

lists services for given host and name. alias for /services?host_name=<host_name>&description=<service>

GET /services/<host>/<service>/availability

list of outages for this service.

Optional arguments:

  • type - both | hosts | services

  • timeperiod - last24hours | lastmonth | thismonth | …​

  • start - unix timestamp

  • end - unix timestamp

  • withdowntimes - 0/1 wheter downtimes should count as outages

  • includesoftstates - 0/1 wheter soft states should be used as well

Attribute Type Unit Description

scheduled_time_critical

number

s

total seconds in state critical (during downtimes)

scheduled_time_critical_percent

number

%

time critical in percent of total time (during downtimes)

scheduled_time_indeterminate

number

s

total seconds unknown (during downtimes)

scheduled_time_indeterminate_percent

number

%

time unknown in percent of total time (during downtimes)

scheduled_time_ok

number

s

total seconds in state ok (during downtimes)

scheduled_time_ok_percent

number

%

time ok in percent of total time (during downtimes)

scheduled_time_unknown

number

s

total seconds in state unknown (during downtimes)

scheduled_time_unknown_percent

number

%

time unknown in percent of total time (during downtimes)

scheduled_time_warning

number

s

total seconds in state warning (during downtimes)

scheduled_time_warning_percent

number

%

time warning in percent of total time (during downtimes)

time_critical

number

s

total seconds in state critical

time_critical_percent

number

%

time critical in percent of total time

time_indeterminate_nodata

number

s

total seconds without any data

time_indeterminate_nodata_percent

number

%

time without any data in percent of total time (during downtimes)

time_indeterminate_notrunning

number

s

total seconds during core not running

time_indeterminate_notrunning_percent

number

%

time during core not running in percent of total time

time_indeterminate_outside_timeperiod

number

s

total seconds outside the given timeperiod

time_indeterminate_outside_timeperiod_percent

number

%

time outside the given timeperiod in percent of total time

time_ok

number

s

total seconds in state ok

time_ok_percent

number

%

time ok in percent of total time

time_unknown

number

s

total seconds in state unknown

time_unknown_percent

number

%

time unknown in percent of total time

time_warning

number

s

total seconds in state warning

time_warning_percent

number

%

time warning in percent of total time

POST /services/<host>/<service>/cmd/…​

external commands are documented in detail on a separate commands page. list of supported commands:

GET /services/<host>/<service>/commandline

displays commandline for check command of given services.

Attribute Type Unit Description

check_command

name of the check_command including arguments

command_line

full expanded command line (if possible)

error

contains the error if expanding failed for some reason

host_name

host name

peer_key

backend id when having multiple sites connected

peer_name

name of remote site

service_description

service name

GET /services/<host>/<service>/config

Returns configuration for given service. You will find available attributes here: http://www.naemon.io/documentation/usersguide/objectdefinitions.html#service

POST /services/<host>/<service>/config

Replace service configuration completely, use PATCH to only update specific attributes.

PATCH /services/<host>/<service>/config

Update service configuration partially.

DELETE /services/<host>/<service>/config

Deletes given service from configuration.

GET /services/<host>/<service>/outages

list of outages for this service.

Optional arguments:

  • type - both | hosts | services

  • timeperiod - last24hours | lastmonth | thismonth | …​

  • start - unix timestamp

  • end - unix timestamp

  • withdowntimes - 0/1 wheter downtimes should count as outages

  • includesoftstates - 0/1 wheter soft states should be used as well

Attribute Type Unit Description

class

host/service status

duration

number

s

outage duration in seconds

end

time

unix timestamp of outage end

host

host name

in_downtime

0/1 flag wether this outage is in a downtime

plugin_output

last plugin output during outage

service

service description (only for service outages)

start

time

unix timestamp of outage start

type

log entry type

GET /services/availability

list availability for all services.

Optional arguments:

  • type - both | hosts | services

  • timeperiod - last24hours | lastmonth | thismonth | …​

  • start - unix timestamp

  • end - unix timestamp

  • withdowntimes - 0/1 wheter downtimes should count as outages

  • includesoftstates - 0/1 wheter soft states should be used as well

Attribute Type Unit Description

host

host name

scheduled_time_critical

number

s

total seconds in state critical (during downtimes)

scheduled_time_critical_percent

number

%

time critical in percent of total time (during downtimes)

scheduled_time_indeterminate

number

s

total seconds unknown (during downtimes)

scheduled_time_indeterminate_percent

number

%

time unknown in percent of total time (during downtimes)

scheduled_time_ok

number

s

total seconds in state ok (during downtimes)

scheduled_time_ok_percent

number

%

time ok in percent of total time (during downtimes)

scheduled_time_unknown

number

s

total seconds in state unknown (during downtimes)

scheduled_time_unknown_percent

number

%

time unknown in percent of total time (during downtimes)

scheduled_time_warning

number

s

total seconds in state warning (during downtimes)

scheduled_time_warning_percent

number

%

time warning in percent of total time (during downtimes)

service

service description

time_critical

number

s

total seconds in state critical

time_critical_percent

number

%

time critical in percent of total time

time_indeterminate_nodata

number

s

total seconds without any data

time_indeterminate_nodata_percent

number

%

time without any data in percent of total time (during downtimes)

time_indeterminate_notrunning

number

s

total seconds during core not running

time_indeterminate_notrunning_percent

number

%

time during core not running in percent of total time

time_indeterminate_outside_timeperiod

number

s

total seconds outside the given timeperiod

time_indeterminate_outside_timeperiod_percent

number

%

time outside the given timeperiod in percent of total time

time_ok

number

s

total seconds in state ok

time_ok_percent

number

%

time ok in percent of total time

time_unknown

number

s

total seconds in state unknown

time_unknown_percent

number

%

time unknown in percent of total time

time_warning

number

s

total seconds in state warning

time_warning_percent

number

%

time warning in percent of total time

GET /services/outages

list of outages for all services.

Optional arguments:

  • type - both | hosts | services

  • timeperiod - last24hours | lastmonth | thismonth | …​

  • start - unix timestamp

  • end - unix timestamp

  • withdowntimes - 0/1 wheter downtimes should count as outages

  • includesoftstates - 0/1 wheter soft states should be used as well

Attribute Type Unit Description

class

host/service status

duration

number

s

outage duration in seconds

end

time

unix timestamp of outage end

host

host name

in_downtime

0/1 flag wether this outage is in a downtime

plugin_output

last plugin output during outage

service

service description (only for service outages)

start

time

unix timestamp of outage start

type

log entry type

GET /services/stats

livestatus service statistics.

Attribute Type Unit Description

active_checks_disabled_active

number of active services which have active checks disabled

active_checks_disabled_passive

number of passive services which have active checks disabled

critical

number of critical services

critical_and_ack

number of critical services which are acknowledged

critical_and_disabled_active

number of active critical services which have active checks disabled

critical_and_disabled_passive

number of passive critical services which have active checks disabled

critical_and_scheduled

number of critical services which are in a scheduled downtime

critical_and_unhandled

number of unhandled critical services

critical_on_down_host

number of unhandled critical services on down hosts

eventhandler_disabled

number of services with eventhandlers disabled

flapping

number of flapping services

flapping_disabled

number of services with flapping detection disabled

notifications_disabled

number of services with notifications disabled

ok

number of ok services

ok_and_disabled_active

number of active ok services which have active checks disabled

ok_and_disabled_passive

number of passive ok services which have active checks disabled

ok_and_scheduled

number of ok services which are in a scheduled downtime

passive_checks_disabled

number of services which do not accept passive check results

pending

number of pending services

pending_and_disabled

number of pending services with active checks disabled

pending_and_scheduled

number of pending services which are in a scheduled downtime

plain_critical

number of critical services which are not acknowleded or in a downtime

plain_ok

number of ok services which are not acknowleded or in a downtime

plain_pending

number of pending services which are not acknowleded or in a downtime

plain_unknown

number of unknown services which are not acknowleded or in a downtime

plain_warning

number of warning services which are not acknowleded or in a downtime

total

total number of services

total_active

total number of active services

total_passive

total number of passive services

unknown

number of unknown services

unknown_and_ack

number of unknown services which are acknowledged

unknown_and_disabled_active

number of active unknown services which have active checks disabled

unknown_and_disabled_passive

number of passive unknown services which have active checks disabled

unknown_and_scheduled

number of unknown services which are in a scheduled downtime

unknown_and_unhandled

number of unhandled unknown services

unknown_on_down_host

number of unhandled unknown services on down hosts

warning

number of warning services

warning_and_ack

number of warning services which are acknowledged

warning_and_disabled_active

number of active warning services which have active checks disabled

warning_and_disabled_passive

number of passive warning services which have active checks disabled

warning_and_scheduled

number of warning services which are in a scheduled downtime

warning_and_unhandled

number of unhandled warning services

warning_on_down_host

number of unhandled warning services on down hosts

GET /services/totals

livestatus service totals statistics. its basically a reduced set of /services/stats.

Attribute Type Unit Description

critical

number of critical services

critical_and_unhandled

number of critical services which are neither acknowledged nor in scheduled downtime

ok

number of ok services

pending

number of pending services

total

total number of services

unknown

number of unknown services

unknown_and_unhandled

number of unknown services which are neither acknowledged nor in scheduled downtime

warning

number of warning services

warning_and_unhandled

number of warning services which are neither acknowledged nor in scheduled downtime

GET /sites

lists configured backends

Attribute Type Unit Description

addr

address for this connection

connected

flag wether sites is connected (1) or not (0)

federation_addr

contains the real address if using federation

federation_key

contains the real peer key if using federation

federation_name

contains the real name if using federation

federation_type

contains the real backend type if using federation

id

id for this backend

last_error

time

error message if backend is not connected

localtime

time

current local unix timestamp of thruk host

name

name of the backend

section

section name

status

0 (OK), 1 (DOWN)

type

type of the backend

POST /system/cmd/…​

external commands are documented in detail on a separate commands page. list of supported commands:

GET /thruk

hash of basic information about this thruk instance

Attribute Type Unit Description

rest_version

rest api version

thruk_version

thruk version

thruk_release_date

thruk release date

localtime

time

current server unix timestamp / epoch

project_root

thruk root folder

etc_path

configuration folder

var_path

variable data folder

extra_version

might contain omd version

extra_link

contains link from extra_versions product

GET /thruk/api_keys

lists api keys

Attribute Type Unit Description

comment

comment of this api key

created

unixtimestamp of when the key was created

digest

used hash algorithm

file

path to stored file

force_user

super user keys can enforce a specific user

hashed_key

hashed private key

last_from

time

ip address of last usage

last_used

time

unixtimestamp of last usage

roles

list of roles this key is limited too

superuser

flag wether this a global superuser key and not bound to a specific user

user

username of key owner

POST /thruk/api_keys

create new api key.

Optional arguments:

  • comment

  • superuser (flag to create superuser api key)

  • username (requires admin privileges, assigns key to specific user)

  • roles (restrict roles to given list)

  • force_user (sets username in combination with super user flag)

GET /thruk/api_keys/<id>

alias for /thruk/api_keys?hashed_key=<id>

DELETE /thruk/api_keys/<id>

remove key for given id.

GET /thruk/bp

lists business processes.

Attribute Type Unit Description

affected_peers

list of backend ids used for the last calculation

bp_backend

id of backend which hosts the business process

create_host_object

0 - do no create a host object, 1 - create naemon host object

draft

flag wether this is a draft only

filter

list of enabled filters

id

primary id

last_check

time

timestamp of last check result submited

last_state_change

time

timestamp of last state change

name

name of this business proces

nodes

all nodes of this business process

rankDir

flag wheter this business process is horizontal or vertical

state_type

flag if this business process uses hard or soft state types

status

current status

status_text

current status text

template

naemon template used for the generated object

time

number

s

calculation duration

POST /thruk/bp

create new business process.

GET /thruk/bp/<nr>

business processes for given number. alias for /thruk/bp?id=<nr>

POST /thruk/bp/<nr>

update business processes configuration for given number.

PATCH /thruk/bp/<nr>

update business processes configuration partially for given number.

DELETE /thruk/bp/<nr>

remove business processes for given number.

GET /thruk/broadcasts

lists broadcasts

Attribute Type Unit Description

annotation

annotation icon for this broadcast

author

author of the broadcast

authoremail

authors E-Mail address, mainly used as macro

contactgroups

list of contactgroups if broadcast should be limited to specific groups

contacts

list of contacts if broadcast should be limited to specific contacts

expires

expire date after which the broadcast won’t be displayed anymore

expires_ts

time

expire data as unix timestamp

file

filename

frontmatter

hash list of extraceted frontmatter variables

hide_before

do not show broadcast before this date

hide_before_ts

time

hide_before as unix timestamp

loginpage

flag wether broadcast should be displayed on the loginpage as well

macros

hash list of macros

name

name of this broadcast, mostly used for templates

panorama

flag wether broadcast should be displayed on panorama dashboards

raw_text

raw broadcast text

template

flag wether this broadcast is a template

text

processed broadcast message

POST /thruk/broadcasts

create new broadcast.

GET /thruk/broadcasts/<file>

alias for /thruk/broadcasts?file=<file>

POST /thruk/broadcasts/<file>

update entire broadcast for given file.

PATCH /thruk/broadcasts/<file>

update attributes for given broadcast.

DELETE /thruk/broadcasts/<file>

remove broadcast for given file.

GET /thruk/cluster

lists cluster nodes

Attribute Type Unit Description

hostname

host name of the cluster node

last_contact

time

timestamp of last successful contact

last_error

time

text of last error message

maintenance

Flag whether this node is in maintenance mode

node_id

internal id for this node

node_url

url to access this node directly

pids

list of current process ids of this node

response_time

number

s

response time in seconds

version

version information of this node

GET /thruk/cluster/<id>

return cluster state for given node.

See /thruk/cluster/ for the description of the attributes.

GET /thruk/cluster/heartbeat

should not be used, use POST method instead

POST /thruk/cluster/heartbeat

send cluster heartbeat to all other nodes

POST /thruk/cluster/restart

restarts all cluster nodes sequentially

GET /thruk/config

lists configuration information

GET /thruk/editor

lists editor sections.

GET /thruk/editor/files

lists editor files and path.

GET /thruk/jobs

lists thruk jobs.

Attribute Type Unit Description

cmd

the executed command line or perl code

end

time

timestamp when the job finished

forward

url to forward when the job is done

host_id

thruk node id this job is run on

host_name

hostname of the node

id

job id

is_running

flag whether the job is still running

message

current status text

percent

number

%

percent of completion

perl_res

contains the perl result in case this was a perl job

pid

process id

rc

return code

remaining

remaining seconds for the job to complete

show_output

flag whether output console will be displayed

start

time

timestamp when the job started

stderr

stderr output

stdout

stdout output

time

number

s

duration in seconds

user

username of the owner

GET /thruk/jobs/<id>

get thruk job status for given id. alias for /thruk/jobs?id=<id>

GET /thruk/logcache/stats

lists logcache statistics

Attribute Type Unit Description

cache_version

db schema version

compact_duration

number

s

duration of last compact run in seconds

compact_till

time

timestamp marker where last compact run finished

data_size

number

bytes

used size of data in bytes

enabled

flag wether logcache is enabled for this backend or not

index_size

number

bytes

used size of index in bytes

items

number of items/rows

key

peer key

last_compact

time

timestamp of last compact run

last_entry

time

timestamp of last log entry

last_reorder

time

timestamp of last optimize run

last_update

time

timestamp of last update run

mode

current lock mode

name

peer name

reorder_duration

number

s

duration of last reorder run in seconds

status

human readable status

update_duration

number

s

duration of last update run in seconds

POST /thruk/logcache/update

runs the logcache delta update.

GET /thruk/metrics

alias for /thruk/stats

GET /thruk/nc/nodes

alias for /thruk/node-control/nodes

GET /thruk/node-control/nodes

lists node control nodes.

Attribute Type Unit Description

ansible_fqdn

full qualified domain from ansible facts

cleaning

flag 1/0 if the nodes is running cleanup right now

cleaning_failed

flag 1/0 wether last cleanup job failed

cpu_cores

number of cpu cores

cpu_perc

number

%

current cpu usage in percent

facts

ansible facts as nested data structure

gathering

flag 1/0 if node is gathering facts right now

host_name

nodes host name

installing

flag 1/0 if node is installing omd right now

installing_failed

flag 1/0 if last install failed

last_error

text of last job error

last_error_ts

time

timestamp of last error

last_gather_runtime

time

duration of last facts gathering job

last_job

last job id

logs

nested list of available log files

machine_type

machine type from ansible

memfree

free memory in MB

memtotal

total memory in MB

omd_available_versions

list of available omd versions

omd_cleanable

list of unused omd versions

omd_disk_free

bytes

free disk space in bytes

omd_disk_total

bytes

total disk space in bytes

omd_site

omd site name

omd_status

nested structure of omd services with their states

omd_version

current used omd version

omd_versions

available omd versions

os_name

operating systems name

os_sec_updating

flag 1/0 if security updates are beeing installed right now

os_security

list of available security updates

os_updates

list of available os updates

os_updating

flag 1/0 if os updates are beeing installed right now

os_version

version number of operating system

peer_key

backend id when having multiple sites connected

peer_name

name of this backend

peer_type

peer connection type

run_all

flag 0/1 if install/update/cleanup is running right now

section

peer backend section

updating

flag 0/1 if update is running right now

updating_failed

flag 0/1 if last update failed

GET /thruk/panorama

lists all panorama dashboards.

Attribute Type Unit Description

file

filename of the dashboard

file_version

version of dashboard format

id

internal id

maintenance

maintenance reason (only if in maintenance mode)

nr

number of the dashboard

objects

number of objects

panlet_<nr>

panlet definition

readonly

flag whether this dashboard is read-only

scripted

flag whether this is a scripted dashboard

tab

structure of global dashboard settings

ts

time

timestamp of last modification

user

owner of this dashboard

GET /thruk/panorama/<nr>

returns panorama dashboard for given number. alias for /thruk/panorama?nr=<nr>

POST /thruk/panorama/<nr>/maintenance

Puts given dashboard into maintenance mode.

Required arguments:

  • text

DELETE /thruk/panorama/<nr>/maintenance

removes maintenance mode from given dashboard.

GET /thruk/recurring_downtimes

lists recurring downtimes.

Attribute Type Unit Description

backends

list of backends this downtime is used for

childoptions

flag used for the downtime command

comment

comment used for the downtime command

created_by

username who created this downtime

duration

number

minutes

duration in minutes

edited_by

username who last edited this downtime

error

contains the error message if something got wrong with this downtime

file

file number

fixed

flag whether this should create a fixed downtime

flex_range

number

minutes

range in minutes for flexible downtimes

host

list of hostnames

hostgroup

list of hostgroups

last_changed

time

unix timestamp of last change

schedule

list of schedules

service

list of services

servicegroup

list of servicegroups

target

sets the type of the downtime, ex. host or hostgroup

POST /thruk/recurring_downtimes

create new downtime.

GET /thruk/recurring_downtimes/<file>

alias for /thruk/recurring_downtimes?file=<file>

POST /thruk/recurring_downtimes/<file>

update entire downtime for given file.

PATCH /thruk/recurring_downtimes/<file>

update attributes for given downtime.

DELETE /thruk/recurring_downtimes/<file>

remove downtime for given file.

GET /thruk/reports

list of reports.

Attribute Type Unit Description

backends

list of backends used in this report

cc

email cc address if this report is send by mail

desc

report description

error

contains error messages (optional)

failed

flag wheter the report failed to generate last time

is_public

flag wheter the report is public or not

name

name of the report

nr

number of the report

params

reporting parameters

permissions

user/group permission

readonly

flag wheter the report is read-only

send_types

list of cron entries

template

template of the report

to

email to address if this report is send by mail

user

owner

POST /thruk/reports

create new report.

GET /thruk/reports/<nr>

report for given number.

Attribute Type Unit Description

backends

list of selected backends.

cc

carbon-copy for report email.

desc

description.

error

contains error messages (optional)

failed

failed flag.

is_public

flag for public reports.

name

name of the report.

nr

primary id.

params

report parameters.

permissions

user/group permission

readonly

readonly flag.

send_types

list of crontab entries.

template

report template.

to

email address the report email.

user

owner of the report.

POST /thruk/reports/<nr>

update entire report for given number.

PATCH /thruk/reports/<nr>

update attributes for given number.

DELETE /thruk/reports/<nr>

remove report for given number.

POST /thruk/reports/<nr>/generate

generate report for given number.

GET /thruk/reports/<nr>/report

return the actual report file in binary format.

GET /thruk/sessions

lists thruk sessions.

Attribute Type Unit Description

active

time

timestamp when session was last time used

address

remote address of user

digest

used hash algorithm

fake

flag whether this is a fake session or not

file

file name the session data file

hashed_key

hashed session id

roles

extra session roles

username

username of this session

GET /thruk/sessions/<id>

get thruk sessions status for given id. alias for /thruk/sessions?id=<id>

GET /thruk/stats

lists thruk statistics.

Attribute Type Unit Description

business_process_duration_seconds

number

s

business process calculation duration in seconds

business_process_last_update

time

timestamp of last business process calculation

business_process_total

total number of business processes

business_process_worker_total

total number of worker processes used to calculate business processes

sessions_active_5min_total

total number of active thruk sessions (active during the last 5 minutes)

sessions_total

total number of thruk sessions

sessions_uniq_user_5min_total

total number of uniq users active during the last 5 minutes

sessions_uniq_user_total

total number of uniq users

users_locked_total

total number of locked thruk users

users_total

total number of thruk users

GET /thruk/users

lists thruk user profiles.

Attribute Type Unit Description

alias

alias name

can_submit_commands

flag wether this account is allowed to submit commands

email

email address

groups

list of contactgroups

has_thruk_profile

flag wether this account has a thruk profile or not

id

username

last_login

time

timestamp of last successfull login

locked

flag wether account is locked or not

roles

list of roles for this user

tz

users selected timezone

GET /thruk/users/<id>

get thruk profile for given user. alias for /thruk/users?id=<id>

POST /thruk/users/<id>/cmd/…​

external commands are documented in detail on a separate commands page. list of supported commands:

GET /thruk/whoami

show current profile information. alias for /thruk/users?id=<id>

GET /timeperiods

lists livestatus timeperiods. see https://www.naemon.io/documentation/usersguide/livestatus.html#timeperiods for details.

GET /timeperiods/<name>

lists timeperiods for given name. alias for /timeperiods?name=<name>

GET /timeperiods/<name>/config

Returns configuration for given timeperiod. You will find available attributes here: http://www.naemon.io/documentation/usersguide/objectdefinitions.html#timeperiod

POST /timeperiods/<name>/config

Replace timeperiod configuration completely, use PATCH to only update specific attributes.

PATCH /timeperiods/<name>/config

Update timeperiods configuration partially.

DELETE /timeperiods/<name>/config

Deletes given timeperiod from configuration.

Edit page on GitHub