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

~

sregex

Strict regular expression match (case-sensitive)

!~

snregex

Strict 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:

Function Example Description

age(<column>)

age(last_check)

Subtract value from current unix timestamp to get the age in seconds.

calc(<column>, <operator>, <value>)

calc(last_check, '*', 1000)

Apply a mathematical operation.

concat(<column>|<text>, …​)

concat(name, ';', state)

Combine multiple columns into one.

duration(<column>)

duration(execution_time)

Convert amount of seconds into human readable duration.

fmt('format', <column>|<text>, …​)

fmt('%.1f', execution_time)

Applies format string to column value(s).

lc(<column>)

lc(host_name)

Make column lower case.

lower(<column>)

lower(host_name)

Make column lower case.

s(<column>, <regex>, <replacement>)

s(host_name, '/\..*$/', '')

Apply regex replacement. Note: you cannot use backreferences like $1 in the replacement string for security reasons.

substr(<column>, <offset> [, <length>])

substr(name, 0, 3)

Extract substring.

unit(<column>, <unit>)

unit(calc(rta, '*', 1000), 's')

Set the unit for this column. (used by grafana with the thruk datasource)

uc(<column>)

uc(host_name)

Make column upper case.

upper(<column>)

upper(host_name)

Make column upper case.

utc(<column>, [<format>])

utc(last_check, '%Y-%m-%d %H:%M:%S %Z')

Convert unix timestamp to UTC date.

date(<column>, [<format>])

date(last_check, '%Y-%m-%d %H:%M:%S %Z')

Convert unix timestamp to date in local timezone.

hoststate(<column>)

hoststate(state)

Convert numeric host state into text representation, ex.: 0 → UP, 1 → DOWN, …​

servicestate(<column>)

servicestate(state)

Convert numeric service state into text representation, ex.: 0 → OK, 1 → WARNING, …​

Example: 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 aggregation 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

  • uniq: return uniq rows only once (uniqueness is calculated over all 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)'

ex.: list unique custom variable values from all services

  %> thruk r '/services?columns=uniq(),_DEVICE_ID&sort=_DEVICE_ID'

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.

Wrapped JSON

Wrapped JSON wraps the result into a hash containing additional metadata.

  %> thruk r /wrapped_json/hosts?columns=name,last_check

Will return something like:

{
   "data" : [...], # data as returned by the json format
   "meta" : {
      "columns" : [{
            "name" : "last_check"
            "type" : "time"
         },
         ...
      ]
   }
}

In case the unit is known (ex.: in perf_data) , it will be added to the column meta information as config hash.

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, summarized below:

GET retrieve resources, e.g.: GET /thruk/reports to list all reports.

POST

update/create resources or trigger actions, e.g.: POST /thruk/reports to create a new report.

PUT

overwrite an existing resource, e.g.: PUT /thruk/reports/1 to update an entire existing report. Thruk does not distinguish between POST and PUT. You can use PUT for all POST URLs and vice versa.

PATCH

replace parts of an existing resource, e.g.: PATCH /thruk/reports/1 to set specific attributes of an existing report.

DELETE

remove an existing resource, e.g.: DELETE /thruk/reports/1 to remove the report entirely.

Long Running Requests

Some REST requests may take longer than the usual timeout of 40 seconds. In this case you can start a background REST request. Then in a separate request, the result of the initial REST request can be retrieved as soon as it is ready.

  %> curl -k -d "" 'https://username:password@localhost/thruk/r/config/check?background=1'

This returns something like:

  {
    "job_id" : "737aa",
    "message" : "request started in background with job id: 737aa",
    "result_url" : "/thruk/jobs/737aa/output",
    "success" : true
  }

Then you can make use of the follow feature of curl to retrieve the result once it is ready.

  %> curl -k -L https://omdadmin:omd@localhost/demo/thruk/r/thruk/jobs/1263d/output

If the result takes more than 30 seconds to compute, it will return a 302 redirect every 30 seconds until it is completed.

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: https://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

string

file name of changed file

output

string

diff output

peer_key

string

id as defined in Thruk::Backend component configuration

POST /config/discard

Reverts stashed configuration changes. Alias for /config/revert

GET /config/files

returns all config files

Attribute Type Unit Description

content

string

raw file content

hex

string

hex sum for this file

mtime

time

unix timestamp of last modification

path

string

filesystem path

peer_key

string

id as defined in Thruk::Backend component configuration

readonly

boolean

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

…​

string

object attributes like defined in the source config files

:FILE

string

filename and line number

:ID

string

internal uniq id

:PEER_KEY

string

id of remote site

:PEER_NAME

string

name of remote site

:READONLY

boolean

flag whether file is readonly

:TEMPLATES

array_of_strings

list of used template

:TYPE

string

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

…​

string

object attributes like defined in the source config files

:FILE

string

filename and line number

:ID

internal uniq id

:PEER_KEY

string

id of remote site

:PEER_NAME

string

name of remote site

:READONLY

boolean

flag whether file is readonly

:TYPE

string

object type, ex.: host

POST /config/objects

Create a new object. Besides the actual object configuration, this requires 2 special parameters, :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

array_of_strings

list of errors encountered

failed

boolean

boolean flag whether configuration check has failed or not

peer_key

string

id as defined in Thruk::Backend component configuration

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: https://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.

Additional attributes added by Thruk:

Attribute Type Unit Description

in_host_notification_period

boolean

Whether the contact is currently in its host notification period

in_service_notification_period

boolean

Whether the contact is currently in its service notification period

modified_attributes_list

array_of_strings

A list of all modified attributes

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: https://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 /contacts/totals

hash of livestatus contacts totals statistics.

Attribute Type Unit Description

total

number

total number of contacts

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.

Additional attributes added by Thruk:

Attribute Type Unit Description

num_services_hard_crit

number

Number of services in hard CRITICAL state

num_services_hard_ok

number

Number of services in hard OK state

num_services_hard_unknown

number

Number of services in hard UNKNOWN state

num_services_hard_warn

number

Number of services in hard WARNING state

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 whether downtimes should count as outages

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

Attribute Type Unit Description

host

string

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: https://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 whether downtimes should count as outages

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

Attribute Type Unit Description

class

string

host/service status

duration

number

s

outage duration in seconds

end

time

unix timestamp of outage end

host

string

host name

plugin_output

string

last plugin output during outage

service

string

service description (only for service outages)

start

time

unix timestamp of outage start

type

string

log entry type

GET /hostgroups/<name>/stats

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

Additional attributes added by Thruk:

Attribute Type Unit Description

active_checks_disabled_active

number

Hosts with active checks disabled that are active

active_checks_disabled_passive

number

Hosts with active checks disabled that are passive

down

number

Number of hosts in DOWN state

down_and_ack

number

Number of hosts in DOWN state with acknowledgement

down_and_disabled_active

number

Number of hosts in DOWN state with active checks disabled

down_and_disabled_passive

number

Number of hosts in DOWN state with passive checks disabled

down_and_scheduled

number

Number of hosts in DOWN state with scheduled downtime

down_and_unhandled

number

Number of unhandled hosts in DOWN state

down_hard

number

Number of hosts in hard DOWN state

down_soft

number

Number of hosts in soft DOWN state

eventhandler_disabled

boolean

Whether event handler is disabled

flapping

boolean

Whether the host is flapping

flapping_disabled

boolean

Whether flap detection is disabled

hard

string

Hard state as string

notifications_disabled

boolean

Whether notifications are disabled

outages

number

Number of current outages

passive_checks_disabled

boolean

Whether passive checks are disabled

pending

number

Number of pending hosts

pending_and_disabled

number

Number of pending hosts with checks disabled

GET /hosts

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

Additional attributes added by Thruk:

Attribute Type Unit Description

accept_passive_checks

boolean

Whether passive host checks are accepted (0/1)

action_url_expanded

string

The action url with the most important macros expanded

check_freshness

number

Whether freshness checks are activated (0/1)

check_options

number

The current check option: forced, normal, freshness (0-2)

checks_enabled

number

Whether checks are enabled (0/1)

childs

array_of_strings

A list of all direct children of the host

comments

array_of_strings

A list of the ids of all comments

comments_info

string

A list of all comments with id, author, comment, entry_type and entry_time

comments_with_info

string

A list of all comments with id, author, comment, entry_type, expires and expire_time

custom_variable_names

array_of_strings

A list of the names of all custom variables

custom_variable_values

array_of_strings

A list of the values of the custom variables

custom_variables

array_of_strings

A dictionary of the custom variables

downtimes_info

string

A list of the ids of all downtimes with additional info

downtimes_with_info

number

Number of downtimes with additional info

groups

array_of_strings

A list of all host groups this host is in

hard_state

number

The hard state of the host

icon_image_expanded

string

The icon image with the most important macros expanded

in_check_period

boolean

Whether this host is currently in its check period (0/1)

in_notification_period

boolean

Whether this host is currently in its notification period (0/1)

is_executing

boolean

Whether there is a check currently running (0/1)

latency

number

Host check latency in seconds

modified_attributes_list

array_of_strings

A list of all modified attributes

notes_expanded

string

The notes with the most important macros expanded

notes_url_expanded

string

The notes url with the most important macros expanded

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> supports wildcards for: <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 whether downtimes should count as outages

  • includesoftstates - 0/1 whether 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. supports wildcards for: <name>

Attribute Type Unit Description

check_command

string

name of the check_command including arguments

command_line

string

full expanded command line (if possible)

error

string

contains the error if expanding failed for some reason

host_name

string

host name

peer_key

string

id as defined in Thruk::Backend component configuration

peer_name

string

name as defined in Thruk::Backend component configuration

peer_section

string

section as defined in Thruk::Backend component configuration

GET /hosts/<name>/config

Returns configuration for given host. You will find available attributes here: https://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> supports wildcards for: <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 whether downtimes should count as outages

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

Attribute Type Unit Description

class

string

host/service status

duration

number

s

outage duration in seconds

end

time

unix timestamp of outage end

host

string

host name

plugin_output

string

last plugin output during outage

start

time

unix timestamp of outage start

type

string

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 whether downtimes should count as outages

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

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

Attribute Type Unit Description

host

string

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 whether downtimes should count as outages

  • includesoftstates - 0/1 whether 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

string

host name

plugin_output

string

last plugin output during outage

start

time

unix timestamp of outage start

type

string

log entry type

GET /hosts/stats

hash of livestatus host statistics.

Attribute Type Unit Description

active_checks_disabled_active

number

number of active hosts which have active checks disabled

active_checks_disabled_passive

number

number of passive hosts which have active checks disabled

down

number

number of down hosts

down_and_ack

number

number of down hosts which are acknowledged

down_and_disabled_active

number

number of active down hosts which have active checks disabled

down_and_disabled_passive

number

number of passive down hosts which have active checks disabled

down_and_scheduled

number

number of down hosts which are in a scheduled downtime

down_and_unhandled

number

number of unhandled down hosts

down_hard

number

number of hard down hosts

down_hard_unhandled

number

number of unhandled hard down hosts

down_soft

number

number of soft down hosts

eventhandler_disabled

number

number of hosts with eventhandlers disabled

flapping

number

number of flapping hosts

flapping_disabled

number

number of hosts with flapping detection disabled

hard

number

number of hosts in hard state

notifications_disabled

number

number of hosts with notifications disabled

outages

number

number of network outages

passive_checks_disabled

number

number of hosts which do not accept passive check results

pending

number

number of pending hosts

pending_and_disabled

number

number of pending hosts with active checks disabled

pending_and_scheduled

number

number of pending hosts which are in a scheduled downtime

plain_down

number

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

plain_pending

number

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

plain_unreachable

number

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

plain_up

number

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

soft

number

number of hosts in soft state

total

number

total number of hosts

total_active

number

total number of active hosts

total_passive

number

total number of passive hosts

unreachable

number

number of unreachable hosts

unreachable_and_ack

number

number of unreachable hosts which are acknowledged

unreachable_and_disabled_active

number

number of active unreachable hosts which have active checks disabled

unreachable_and_disabled_passive

number

number of passive unreachable hosts which have active checks disabled

unreachable_and_scheduled

number

number of unreachable hosts which are in a scheduled downtime

unreachable_and_unhandled

number

number of unhandled unreachable hosts

unreachable_hard

number

number of unreachable hosts in hard state

unreachable_hard_unhandled

number

number of unhandled unreachable hosts in hard state

unreachable_soft

number

number of unreachable hosts in soft state

up

number

number of up hosts

up_and_disabled_active

number

number of active up hosts which have active checks disabled

up_and_disabled_passive

number

number of passive up hosts which have active checks disabled

up_and_scheduled

number

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

number of down hosts

down_and_unhandled

number

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

pending

number

number of pending hosts

total

number

total number of hosts

unreachable

number

number of unreachable hosts

unreachable_and_unhandled

number

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

up

number

number of up hosts

GET /index

lists all available rest urls.

Attribute Type Unit Description

description

string

description of the url

protocol

string

protocol to use for this url

url

string

the rest url

GET /lmd/sites

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

Attribute Type Unit Description

addr

string

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

string

contains the real address if using federation

federation_key

string

contains the real peer key if using federation

federation_name

string

contains the real name if using federation

federation_type

string

contains the real backend type if using federation

federation_version

string

contains the real backend version if using federation

flags

array_of_strings

contains the lmd flags for this backend

idling

boolean

flag if the connection is in idle mode

key

string

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

string

name of the site

parent

string

parent id for lmd federation setups

peer_key

string

id as defined in Thruk::Backend component configuration

peer_name

string

name as defined in Thruk::Backend component configuration

queries

number

number of queries received

response_time

number

s

response time in seconds

section

thruks section

status

string

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

Additional attributes added by Thruk:

Attribute Type Unit Description

attempt

number

Current attempt number when this log entry was generated

class

number

The class of the message as integer (0:info, 1:state, 2:program, 3:notification, 4:passive, 5:command)

command_name

string

Command name associated with this log entry

comment

string

Comment text from the log entry

contact_name

string

Contact name associated with this log entry

host_name

string

Host name associated with this log entry

lineno

number

Line number of the log entry in the log file

message

string

Log message text

options

string

Options string from the log entry

peer_key

string

id as defined in Thruk::Backend component configuration

peer_name

string

name as defined in Thruk::Backend component configuration

plugin_output

string

Plugin output from the log entry

service_description

string

Service description associated with this log entry

state

number

State of the host or service at the time of the log entry

state_type

string

State type (HARD or SOFT)

time

time

Timestamp of the log entry (unix timestamp)

type

string

Type of the log entry

GET /processinfo

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

Additional attributes added by Thruk:

Attribute Type Unit Description

check_external_commands

number

Whether the core accepts external commands (0/1)

data_source_version

string

Version of the data source (livestatus version)

nagios_pid

number

The process ID of the monitoring core

obsess_over_hosts

boolean

Whether the core obsesses over hosts (0/1)

obsess_over_services

boolean

Whether the core obsesses over services (0/1)

peer_addr

string

Address of the peer (ip:port or unix socket)

peer_key

string

id as defined in Thruk::Backend component configuration

peer_name

string

name as defined in Thruk::Backend component configuration

GET /processinfo/stats

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

Additional attributes added by Thruk:

Attribute Type Unit Description

cached_log_messages

number

Number of cached log messages

connections

number

Number of connections

connections_rate

number

Connections per second

forks

number

Number of forks

forks_rate

number

Forks per second

host_checks

number

Number of host checks

host_checks_rate

number

Host checks per second

log_messages

number

Number of log messages

log_messages_rate

number

Log messages per second

neb_callbacks

number

Number of NEB callbacks

neb_callbacks_rate

number

NEB callbacks per second

requests

number

Number of requests

requests_rate

number

Requests per second

service_checks

number

Number of service checks

service_checks_rate

number

Service checks per second

GET /servicegroups

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

Additional attributes added by Thruk:

Attribute Type Unit Description

num_services_hard_crit

number

Number of services in hard CRITICAL state

num_services_hard_ok

number

Number of services in hard OK state

num_services_hard_unknown

number

Number of services in hard UNKNOWN state

num_services_hard_warn

number

Number of services in hard WARNING state

peer_key

string

id as defined in Thruk::Backend component configuration

peer_name

string

name as defined in Thruk::Backend component configuration

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 whether downtimes should count as outages

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

Attribute Type Unit Description

host

string

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

string

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: https://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 whether downtimes should count as outages

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

Attribute Type Unit Description

class

string

host/service status

duration

number

s

outage duration in seconds

end

time

unix timestamp of outage end

host

string

host name

plugin_output

string

last plugin output during outage

service

string

service description (only for service outages)

start

time

unix timestamp of outage start

type

string

log entry type

GET /servicegroups/<name>/stats

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

Additional attributes added by Thruk:

Attribute Type Unit Description

active_checks_disabled_active

number

Services with active checks disabled that are active

active_checks_disabled_passive

number

Services with active checks disabled that are passive

critical

number

Number of services in CRITICAL state

critical_and_ack

number

Number of services in CRITICAL state with acknowledgement

critical_and_disabled_active

number

Number of services in CRITICAL state with active checks disabled

critical_and_disabled_passive

number

Number of services in CRITICAL state with passive checks disabled

critical_and_scheduled

number

Number of services in CRITICAL state with scheduled downtime

critical_and_unhandled

number

Number of unhandled services in CRITICAL state

critical_hard

number

Number of services in hard CRITICAL state

critical_hard_unhandled

number

Number of unhandled services in hard CRITICAL state

critical_on_down_host

number

Number of services in CRITICAL state on down hosts

critical_soft

number

Number of services in soft CRITICAL state

eventhandler_disabled

boolean

Whether event handler is disabled

flapping

number

Number of services that are flapping

flapping_disabled

boolean

Whether flap detection is disabled

hard

number

Number of services in hard state

notifications_disabled

boolean

Whether notifications are disabled

ok

number

Number of services in OK state

ok_and_disabled_active

number

Number of services in OK state with active checks disabled

ok_and_disabled_passive

number

Number of services in OK state with passive checks disabled

GET /services

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

Additional attributes added by Thruk:

Attribute Type Unit Description

accept_passive_checks

boolean

Whether passive service checks are accepted (0/1)

action_url_expanded

string

The action url with the most important macros expanded

check_options

string

The current check option: forced, normal, freshness (0-2)

checks_enabled

boolean

Whether checks are enabled (0/1)

comments

string

A list of the ids of all comments

comments_info

string

A list of all comments with id, author, comment, entry_type and entry_time

comments_with_info

string

A list of all comments with id, author, comment, entry_type, expires and expire_time

custom_variable_names

array_of_strings

A list of the names of all custom variables

custom_variable_values

array_of_strings

A list of the values of the custom variables

GET /services/<host>/<service>

lists services for given host and name. alias for /services?host_name=<host_name>&description=<service> supports wildcards for: <host> and <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 whether downtimes should count as outages

  • includesoftstates - 0/1 whether 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. supports wildcards for: <host> and <service>

Attribute Type Unit Description

check_command

string

name of the check_command including arguments

command_line

string

full expanded command line (if possible)

error

string

contains the error if expanding failed for some reason

host_name

string

host name

peer_key

string

id as defined in Thruk::Backend component configuration

peer_name

string

name as defined in Thruk::Backend component configuration

peer_section

string

section as defined in Thruk::Backend component configuration

service_description

string

service name

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

Returns configuration for given service. You will find available attributes here: https://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 whether downtimes should count as outages

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

Attribute Type Unit Description

class

string

host/service status

duration

number

s

outage duration in seconds

end

time

unix timestamp of outage end

host

string

host name

plugin_output

string

last plugin output during outage

service

string

service description (only for service outages)

start

time

unix timestamp of outage start

type

string

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 whether downtimes should count as outages

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

Attribute Type Unit Description

host

string

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

string

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 whether downtimes should count as outages

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

Attribute Type Unit Description

class

string

host/service status

duration

number

s

outage duration in seconds

end

time

unix timestamp of outage end

host

string

host name

plugin_output

string

last plugin output during outage

service

string

service description (only for service outages)

start

time

unix timestamp of outage start

type

string

log entry type

GET /services/stats

livestatus service statistics.

Attribute Type Unit Description

active_checks_disabled_active

number

number of active services which have active checks disabled

active_checks_disabled_passive

number

number of passive services which have active checks disabled

critical

number

number of critical services

critical_and_ack

number

number of critical services which are acknowledged

critical_and_disabled_active

number

number of active critical services which have active checks disabled

critical_and_disabled_passive

number

number of passive critical services which have active checks disabled

critical_and_scheduled

number

number of critical services which are in a scheduled downtime

critical_and_unhandled

number

number of unhandled critical services

critical_hard

number

number of critical services in hard state

critical_hard_unhandled

number

number of unhandled critical services in hard state

critical_on_down_host

number

number of unhandled critical services on down hosts

critical_soft

number

number of critical services in soft state

eventhandler_disabled

number

number of services with eventhandlers disabled

flapping

number

number of flapping services

flapping_disabled

number

number of services with flapping detection disabled

hard

number

number of services in hard state

notifications_disabled

number

number of services with notifications disabled

ok

number

number of ok services

ok_and_disabled_active

number

number of active ok services which have active checks disabled

ok_and_disabled_passive

number

number of passive ok services which have active checks disabled

ok_and_scheduled

number

number of ok services which are in a scheduled downtime

passive_checks_disabled

number

number of services which do not accept passive check results

pending

number

number of pending services

pending_and_disabled

number

number of pending services with active checks disabled

pending_and_scheduled

number

number of pending services which are in a scheduled downtime

plain_critical

number

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

plain_ok

number

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

plain_pending

number

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

plain_unknown

number

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

plain_warning

number

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

soft

number

number of services in soft state

total

number

total number of services

total_active

number

total number of active services

total_passive

number

total number of passive services

unknown

number

number of unknown services

unknown_and_ack

number

number of unknown services which are acknowledged

unknown_and_disabled_active

number

number of active unknown services which have active checks disabled

unknown_and_disabled_passive

number

number of passive unknown services which have active checks disabled

unknown_and_scheduled

number

number of unknown services which are in a scheduled downtime

unknown_and_unhandled

number

number of unhandled unknown services

unknown_hard

number

number of unknown services in hard state

unknown_hard_unhandled

number

number of unhandled unknown services in hard state

unknown_on_down_host

number

number of unhandled unknown services on down hosts

unknown_soft

number

number of unknown services in soft state

warning

number

number of warning services

warning_and_ack

number

number of warning services which are acknowledged

warning_and_disabled_active

number

number of active warning services which have active checks disabled

warning_and_disabled_passive

number

number of passive warning services which have active checks disabled

warning_and_scheduled

number

number of warning services which are in a scheduled downtime

warning_and_unhandled

number

number of unhandled warning services

warning_hard

number

number of warning services in hard state

warning_hard_unhandled

number

number of unhandled warning services in hard state

warning_on_down_host

number

number of unhandled warning services on down hosts

warning_soft

number

number of warning services in soft state

GET /services/totals

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

Attribute Type Unit Description

critical

number

number of critical services

critical_and_unhandled

number

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

ok

number

number of ok services

pending

number

number of pending services

total

number

total number of services

unknown

number

number of unknown services

unknown_and_unhandled

number

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

warning

number

number of warning services

warning_and_unhandled

number

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

GET /sites

lists configured backends

Attribute Type Unit Description

addr

string

address for this connection

connected

boolean

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

federation_addr

string

contains the real address if using federation

federation_key

string

contains the real peer key if using federation

federation_name

string

contains the real name if using federation

federation_type

string

contains the real backend type if using federation

federation_version

string

contains the real backend version if using federation

id

string

id for this backend

last_error

time

error message if backend is not connected

localtime

time

current local unix timestamp of thruk host

name

string

name of the backend

section

string

section name

status

boolean

0 (OK), 1 (DOWN)

type

string

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

string

rest api version

thruk_version

string

thruk version

thruk_release_date

string

thruk release date

localtime

time

current server unix timestamp / epoch

project_root

string

thruk root folder

etc_path

string

configuration folder

var_path

string

variable data folder

extra_version

string

might contain omd version

extra_link

string

contains link from extra_versions product

GET /thruk/api_keys

lists api keys

Attribute Type Unit Description

comment

string

comment of this api key

created

time

unixtimestamp of when the key was created

digest

string

used hash algorithm

file

string

path to stored file

force_user

string

super user keys can enforce a specific user

hashed_key

string

hashed private key

last_from

time

ip address of last usage

last_used

time

unixtimestamp of last usage

roles

array_of_strings

list of roles this key is limited too

superuser

string

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

user

string

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

array_of_strings

list of backend ids used for the last calculation

bp_backend

string

id of backend which hosts the business process

create_host_object

boolean

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

draft

string

flag whether this is a draft only

filter

array_of_strings

list of enabled filters

id

string

primary id

last_check

time

timestamp of last check result submited

last_state_change

time

timestamp of last state change

name

string

name of this business proces

nodes

string

all nodes of this business process

rankDir

string

flag whether this business process is horizontal or vertical

state_type

boolean

flag if this business process uses hard or soft state types

status

number

current status

status_text

string

current status text

template

string

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.

POST /thruk/bp/<nr>/refresh

recalculate business processes status for given number.

GET /thruk/broadcasts

lists broadcasts

Attribute Type Unit Description

annotation

string

annotation icon for this broadcast

author

string

author of the broadcast

authoremail

string

authors E-Mail address, mainly used as macro

contactgroups

array_of_strings

list of contactgroups if broadcast should be limited to specific groups

contacts

array_of_strings

list of contacts if broadcast should be limited to specific contacts

expires

string

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

expires_ts

time

expire data as unix timestamp

file

string

filename

frontmatter

string

hash list of extraceted frontmatter variables

hide_before

string

do not show broadcast before this date

hide_before_ts

time

hide_before as unix timestamp

loginpage

boolean

flag whether broadcast should be displayed on the loginpage as well

macros

array_of_strings

hash list of macros

name

string

name of this broadcast, mostly used for templates

panorama

boolean

flag whether broadcast should be displayed on panorama dashboards

raw_text

string

raw broadcast text

template

string

flag whether this broadcast is a template

text

string

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

string

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

string

internal id for this node

node_url

string

url to access this node directly

pids

array_of_strings

list of current process ids of this node

response_time

number

s

response time in seconds

version

string

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/jobs

lists thruk jobs.

Attribute Type Unit Description

cmd

string

the executed command line or perl code

end

time

timestamp when the job finished

forward

string

url to forward when the job is done

host_id

number

thruk node id this job is run on

host_name

string

hostname of the node

id

number

job id

is_running

boolean

flag whether the job is still running

message

string

current status text

percent

number

%

percent of completion

perl_res

string

contains the perl result in case this was a perl job

pid

number

process id

rc

number

return code

remaining

number

s

remaining seconds for the job to complete

show_output

boolean

flag whether output console will be displayed

start

time

timestamp when the job started

stderr

string

stderr output

stdout

string

stdout output

time

number

s

duration in seconds

user

string

username of the owner

GET /thruk/jobs/<id>

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

GET /thruk/jobs/<id>/output

get thruk job output for given id.

Will return the plain result of a finished job as initially requested. In case jobs takes longer than 30 seconds, this will return 302 redirects to itself until the job succeeds. So if you follow those redirect, you will get the final result as soon as its calculated.

GET /thruk/logcache/stats

lists logcache statistics

Attribute Type Unit Description

cache_version

string

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

string

flag whether logcache is enabled for this backend or not

index_size

number

bytes

used size of index in bytes

items

string

number of items/rows

key

string

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

string

current lock mode

name

string

peer name

reorder_duration

number

s

duration of last reorder run in seconds

status

string

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/panorama

lists all panorama dashboards.

Attribute Type Unit Description

file

string

filename of the dashboard

file_version

string

version of dashboard format

id

internal id

maintenance

string

maintenance reason (only if in maintenance mode)

nr

number

number of the dashboard

objects

number

number of objects

panlet_<nr>

string

panlet definition

readonly

boolean

flag whether this dashboard is read-only

scripted

boolean

flag whether this is a scripted dashboard

tab

string

structure of global dashboard settings

ts

time

timestamp of last modification

user

string

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

array_of_strings

list of backends this downtime is used for

childoptions

boolean

flag used for the downtime command

comment

string

comment used for the downtime command

created_by

string

username who created this downtime

duration

number

minutes

duration in minutes

edited_by

string

username who last edited this downtime

error

string

contains the error message if something got wrong with this downtime

file

number

file number

fixed

boolean

flag whether this should create a fixed downtime

flex_range

number

minutes

range in minutes for flexible downtimes

host

array_of_strings

list of hostnames

hostgroup

array_of_strings

list of hostgroups

last_changed

time

unix timestamp of last change

schedule

array_of_strings

list of schedules

service

array_of_strings

list of services

servicegroup

array_of_strings

list of servicegroups

target

string

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

array_of_strings

list of backends used in this report

cc

string

email cc address if this report is send by mail

desc

string

report description

error

string

contains error messages (optional)

failed

boolean

flag whether the report failed to generate last time

is_public

boolean

flag whether the report is public or not

name

string

name of the report

nr

number

number of the report

params

string

reporting parameters

permissions

string

user/group permission

readonly

boolean

flag whether the report is read-only

send_types

array_of_strings

list of cron entries

template

string

template of the report

to

string

email to address if this report is send by mail

user

string

owner

POST /thruk/reports

create new report.

GET /thruk/reports/<nr>

report for given number.

Attribute Type Unit Description

backends

array_of_strings

list of selected backends.

cc

string

carbon-copy for report email.

desc

string

description.

error

string

contains error messages (optional)

failed

boolean

failed flag.

is_public

boolean

flag for public reports.

name

string

name of the report.

nr

string

primary id.

params

string

report parameters.

permissions

string

user/group permission

readonly

boolean

readonly flag.

send_types

array_of_strings

list of crontab entries.

template

string

report template.

to

string

email address the report email.

user

string

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

string

remote address of user

digest

string

used hash algorithm

fake

boolean

flag whether this is a fake session or not

file

string

file name the session data file

hashed_key

string

hashed session id

oauth_groups

string

groups/roles as provided by the oauth server

roles

string

extra session roles

username

string

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

number

total number of business processes

business_process_worker_total

number

total number of worker processes used to calculate business processes

sessions_active_5min_total

number

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

sessions_total

number

total number of thruk sessions

sessions_uniq_user_5min_total

number

total number of uniq users active during the last 5 minutes

sessions_uniq_user_total

number

total number of uniq users

users_locked_total

number

total number of locked thruk users

users_total

number

total number of thruk users

GET /thruk/users

lists thruk user profiles.

Attribute Type Unit Description

alias

string

alias name

can_submit_commands

boolean

flag whether this account is allowed to submit commands

email

string

email address

groups

array_of_strings

list of contactgroups

has_thruk_profile

boolean

flag whether this account has a thruk profile or not

id

string

username

last_login

time

timestamp of last successfull login

locked

boolean

flag whether account is locked or not

roles

array_of_strings

list of roles for this user

tz

string

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.

Additional attributes added by Thruk:

Attribute Type Unit Description

peer_key

string

id as defined in Thruk::Backend component configuration

peer_name

string

name as defined in Thruk::Backend component configuration

GET /timeperiods/<name>

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

Attribute Type Unit Description

peer_key

string

id as defined in Thruk::Backend component configuration

peer_name

string

name as defined in Thruk::Backend component configuration

GET /timeperiods/<name>/config

Returns configuration for given timeperiod. You will find available attributes here: https://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