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

1. 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

If no agent has been configured yet, go to Create Agent configuration.


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.

In order to continue with step 5 (Save agent services) and to skip the configuration, "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).


4. Submit agent configuration

If the answer to the query in step 3 says "mode": "pull", select the configuration for the pull mode here.

If the answer to the query in step 3 says "mode": "push", select the configuration for the push mode here.

To migrate the agent between pull and push mode, please follow these instructions: Later change between pull and push mode

Agent in Pull-Mode

Get configuration already saved

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": {
        "id": 3,
        "port": 3333,
        "use_https": 0,
        "insecure": 1,
        "basic_auth": 0,
        "proxy": 1,
        "username": "",
        "password": "",
        "push_noticed": 0
    },
    "_csrfToken": null
}


Update configuration

URL: https://123.123.123.123/agentconfigs/edit/${AgentconfigID}.json?angular=true

Method: POST

Content-Type: application/json

Answer: JSON

Sample request content
{
    "Agentconfig": {
        "id": 5,
        "port": 3333,
        "basic_auth": 0,
        "username": "",
        "password": "",
        "push_noticed": 0
    }
}
Sample answer
{
    "id": 5,
    "_csrfToken": null
}


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

If agent services are to be created, you can continue if there were no serious configuration changes.

Otherwise, step 3 must be carried out again in order to obtain a current checklist of the agent.


Agent im Push-Modus

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


5. 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".

Checks of services that have already been created are filtered out by the server and are therefore not included in the response.

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

Sample request 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