Page tree
Skip to end of metadata
Go to start of metadata


1. Create host and/or provide ID and UUID of a existing host

See Hosts (API)

2. Get host data

This step only needs to be performed if the host's UUID is not yet known.


URL: https://123.123.123.123/hosts/loadHostById/${HostID}.json?angular=true

Method: GET

Answer: JSON

Sample answer
{
    "host": {
        "id": 1,
        "uuid": "c36b8048-93ce-4385-ac19-ab5c90574b77",
        "container_id": 1,
        "name": "default host",
        "description": null,
        "hosttemplate_id": 1,
        "address": "localhost",
        "command_id": null,
        "eventhandler_command_id": null,
        "timeperiod_id": null,
        "check_interval": null,
        "retry_interval": null,
        "max_check_attempts": null,
        "first_notification_delay": null,
        "notification_interval": null,
        "notify_on_down": null,
        "notify_on_unreachable": null,
        "notify_on_recovery": null,
        "notify_on_flapping": null,
        "notify_on_downtime": null,
        "flap_detection_enabled": null,
        "flap_detection_on_up": null,
        "flap_detection_on_down": null,
        "flap_detection_on_unreachable": null,
        "low_flap_threshold": null,
        "high_flap_threshold": null,
        "process_performance_data": null,
        "freshness_checks_enabled": null,
        "freshness_threshold": null,
        "passive_checks_enabled": null,
        "event_handler_enabled": null,
        "active_checks_enabled": null,
        "retain_status_information": null,
        "retain_nonstatus_information": null,
        "notifications_enabled": null,
        "notes": null,
        "priority": null,
        "check_period_id": null,
        "notify_period_id": null,
        "tags": null,
        "own_contacts": 0,
        "own_contactgroups": 0,
        "own_customvariables": 0,
        "host_url": null,
        "satellite_id": 0,
        "host_type": 1,
        "disabled": 0,
        "usage_flag": 0,
        "created": "2015-01-15T19:26:32+01:00",
        "modified": "2020-07-15T11:54:14+02:00",
        "hosts_to_containers_sharing": [
            {
                "id": 1,
                "containertype_id": 1,
                "name": "root",
                "parent_id": null,
                "lft": 1,
                "rght": 20,
                "_joinData": {
                    "id": 1,
                    "host_id": 1,
                    "container_id": 1
                }
            }
        ],
        "is_satellite_host": false,
        "allow_edit": true
    },
    "_csrfToken": null
}


3. Get agent services / check for configured agent

URL: https://123.123.123.123/agentconnector/getServicesToCreateByHostUuid/${HostUUID}.json

Method: GET

Answer: JSON

The following is the default return if no agent has been configured for this host. It does not have to be saved.

Sample answer
{
    "servicesToCreate": "",
    "mode": "",
    "config": "",
    "system": "windows",
    "error": "",
    "_csrfToken": null
}


If no agent has been configured, go to step 4.

If an agent has already been configured, go to Edit Agent configuration.


4. Submit agent configuration

Decide whether the agent should be created in pull or push mode.

Agent in Pull-Mode

Get standard configuration

URL: https://123.123.123.123/agentconfigs/config/${HostID}.json?angular=true

Method: GET

Answer: JSON

Sample answer
{
    "host": {
        "id": 1,
        "uuid": "c36b8048-93ce-4385-ac19-ab5c90574b77",
        "name": "default host",
        "address": "localhost",
        "container_id": 1,
        "hosts_to_containers_sharing": [
            {
                "id": 1,
                "containertype_id": 1,
                "name": "root",
                "parent_id": null,
                "lft": 1,
                "rght": 20,
                "_joinData": {
                    "id": 1,
                    "host_id": 1,
                    "container_id": 1
                }
            }
        ]
    },
    "config": {
        "port": 3333,
        "use_https": 0,
        "insecure": 1,
        "basic_auth": 0,
        "proxy": 1,
        "username": "",
        "password": "",
        "push_noticed": 0
    },
    "_csrfToken": null
}


Save configuration

URL: https://123.123.123.123/agentconfigs/add.json?angular=true

Method: POST

Content-Type: application/json

Answer: JSON

Example query content
{
    "Agentconfig": {
        "host_id": 1,
        "port": 3333,
        "use_https": false,
        "basic_auth": 0,
        "username": "",
        "password": ""
    }
}
Sample answer
{
    "id": 5,
    "_csrfToken": null
}


Insert the new configuration into the agent's configuration file and restart it.


Agent in Push-Mode

Insert the new configuration into the agent's configuration file and restart it.


5. Get agent services

Before proceeding, you should be sure that the agent is running and accessible!


URL: https://123.123.123.123/agentconnector/getServicesToCreateByHostUuid/${HostUUID}.json

Method: GET

Answer: JSON

Sample response with an error
{
    "servicesToCreate": "",
    "mode": "could-be-pull",
     "config": "",
     "system": "windows",
     "error": "cURL error 7: Failed to connect to localhost port 3333: Connection refused (see https:\/\/curl.haxx.se\/libcurl\/c\/libcurl-errors.html)",
     "_csrfToken": null
}

If an error occurs as in the example answer above, it does not have to be final.

In the event of an error, please make 2-3 further inquiries. openITCOCKPIT will try to reach the agent with / without SSL and with / without proxy.

If this or another error does not disappear after 4 requests, there may be an error in the configuration of the agent or it cannot be reached.

The value in the "mode" field indicates the detected agent configuration. Even if errors have occurred, it is relatively certain that the agent is configured in "mode" mode. (Possible values for errors: "could-be-pull" or "could-be-push")

If there is nothing in "error" or in "servicesToCreate" or the agent is configured in push mode, a request should be made every 10 seconds for up to 2 minutes, since openITCOCKPIT must wait until the agent sends the first results.

To continue, "error" in the answer must be empty and "servicesToCreate" filled!


Sample response with no errors
{
    "servicesToCreate": {
        "Agent": [
            {
                "name": "OITC_AGENT_ACTIVE",
                "servicetemplate_id": 50
            }
        ],
        "SystemLoad": [
            {
                "name": "System Load",
                "servicetemplate_id": 52
            }
        ],
        "MemoryUsage": [
            {
                "name": "Memory Usage",
                "servicetemplate_id": 53
            }
        ],
        "SwapUsage": [
            {
                "name": "SWAP Usage",
                "servicetemplate_id": 54
            }
        ],
        "DiskUsage": [
            {
                "name": "Disk Usage /",
                "servicetemplate_id": 56,
                "agent_wizard_option_description": "/"
            },
            {
                "name": "Disk Usage /rpool",
                "servicetemplate_id": 56,
                "agent_wizard_option_description": "/rpool"
            }
        ],
        "DiskIO": [
            {
                "name": "Disk Load loop0",
                "servicetemplate_id": 55,
                "agent_wizard_option_description": "loop0"
            },
            {
                "name": "Disk Load sdb",
                "servicetemplate_id": 55,
                "agent_wizard_option_description": "sdb"
            }
        ],
        "NetStats": [
            {
                "name": "Network Device Status vmbr0",
                "servicetemplate_id": 61,
                "agent_wizard_option_description": "vmbr0"
            },
            {
                "name": "Network Device Status eth0",
                "servicetemplate_id": 61,
                "agent_wizard_option_description": "eth0"
            }
        ],
        "NetIO": [
            {
                "name": "Network Stats vmbr0",
                "servicetemplate_id": 60,
                "agent_wizard_option_description": "vmbr0"
            },
            {
                "name": "Network Stats eth0",
                "servicetemplate_id": 60,
                "agent_wizard_option_description": "eth0"
            }
        ],
        "Temperature": [
            {
                "name": "Device Temperature coretemp",
                "servicetemplate_id": 58,
                "agent_wizard_option_description": "coretemp"
            }
        ],
        "CpuTotalPercentage": [
            {
                "name": "Total CPU Percentage",
                "servicetemplate_id": 51
            }
        ],
        "Process": [
            {
                "name": "Check Process /sbin/init",
                "servicetemplate_id": 62,
                "agent_wizard_option_description": "/sbin/init"
            },
            {
                "name": "Check Process /lib/systemd/systemd --user",
                "servicetemplate_id": 62,
                "agent_wizard_option_description": "/lib/systemd/systemd --user"
            },
            {
                "name": "Check Process /lib/systemd/systemd-logind",
                "servicetemplate_id": 62,
                "agent_wizard_option_description": "/lib/systemd/systemd-logind"
            }
        ],
        "SystemdService": [
            {
                "name": "Check systemd service running apache2.service",
                "servicetemplate_id": 64,
                "agent_wizard_option_description": "apache2.service"
            },
            {
                "name": "Check systemd service running apparmor.service",
                "servicetemplate_id": 64,
                "agent_wizard_option_description": "apparmor.service"
            }
        ]
    },
    "mode": "pull",
    "config": "",
    "system": "linux",
    "error": "",
    "_csrfToken": null
}


The value in the "mode" field indicates the detected agent configuration. (Possible values without errors: "pull" or "push")

The value in the "system" field specifies the agent's host system. Depending on the system, the paths in the file system for the agent configuration differ. (Possible answers: "windows", "linux", "macos")

In "servicesToCreate" the available checks are sorted by groups (e.g. SystemdServices or DiskUsage).

6. Save agent services

Checks for the services to be created must be extracted from "servicesToCreate" and transmitted in a new post request in the array "serviceConfigs".

The groupings (such as SystemdServices or DiskUsage) can be ignored.

The "hostId" field contains the previously used host ID.

The string "false" should be assigned to the "tryAutosslInPullMode" field. If AutoSSL was activated before, "true" should of course be specified here.


URL: https://123.123.123.123/agentconnector/createServices.json?angular=true

Method: POST

Content-Type: application/json

Answer: JSON

Example query content
{
    "serviceConfigs": [
        {
            "name": "Total CPU Percentage",
            "servicetemplate_id": 51
        },
        {
            "name": "System Load",
            "servicetemplate_id": 52
        },
        {
            "name": "Memory Usage",
            "servicetemplate_id": 53
        },
        {
            "name": "SWAP Usage",
            "servicetemplate_id": 54
        },
        {
            "name": "Disk Usage /",
            "servicetemplate_id": 56,
            "agent_wizard_option_description": "/"
        },
        {
            "name": "Disk Load sdb",
            "servicetemplate_id": 55,
            "agent_wizard_option_description": "sdb"
        },
        {
            "name": "Device Temperature coretemp",
            "servicetemplate_id": 58,
            "agent_wizard_option_description": "coretemp"
        },
        {
            "name": "Network Stats eth0",
            "servicetemplate_id": 60,
            "agent_wizard_option_description": "eth0"
        },
        {
            "name": "Network Device Status eth0",
            "servicetemplate_id": 61,
            "agent_wizard_option_description": "eth0"
        },
        {
            "name": "Check Process /sbin/init",
            "servicetemplate_id": 62,
            "agent_wizard_option_description": "/sbin/init"
        },
        {
            "name": "Check systemd service running apache2.service",
            "servicetemplate_id": 64,
            "agent_wizard_option_description": "apache2.service"
        }
    ],
    "hostId": 6,
    "tryAutosslInPullMode": false
}
Sample answer
{
    "success": "true",
    "_csrfToken": null
}



  • No labels