Host API allows to access host specific information.

List hosts

URI: https://hub.cfengine.com/api/host

Method: GET

Parameters:

Example response:

{
  "meta": {
    "page": 1,
    "count": 2,
    "total": 2,
    "timestamp": 1437142156
  },
  "data": [
    {
      "id": "SHA=27b88b8a92f1b10b1839ac5b26d022c98d48629bd761c4324d1f1fb0f04f17ba",
      "hostname": "host001",
      "ip": "192.168.33.151",
      "lastreport": "1437141907",
      "firstseen": "1437138906"
    },
    {
      "id": "SHA=4a18877bbb7b79f4dde4b03d3ba05bcd66346124cbcd9373590416a90177fcaa",
      "hostname": "hub",
      "ip": "192.168.33.65",
      "lastreport": "1437141907",
      "firstseen": "1437138666"
    }
  ]
}

Output:

Example usage: Example: Listing Hosts With A Given Context, Example: Looking Up Hosts By Hostname, Example: Looking Up Hosts By IP

Host Details

URI: https://hub.cfengine.com/api/host/:host-id

Method: GET

Example response:

{
  "meta": {
    "page": 1,
    "count": 1,
    "total": 1,
    "timestamp": 1437144171
  },
  "data": [
    {
      "id": "SHA=27b88b8a92f1b10b1839ac5b26d022c98d48629bd",
      "hostname": "host001",
      "ip": "192.168.33.151",
      "lastreport": "1437144007",
      "firstseen": "1437138906"
    }
  ]
}

Output:

Remove host from the hub

URI: https://hub.cfengine.com/api/host/:host-id

Method: DELETE

Remove data about the host from reporting database and stop collecting reports from the host. This should be done when the host is no longer active, activities such as a new bootstrap can cause the host to reappear.

If host is found and scheduled for deletion, status code 202 ACCEPTED is returned. If host is not found, status code 404 NOT FOUND is returned. Other response codes are also possible (access denied, server error, etc.). Only users with the admin role are allowed to delete hosts.

Reporting data associated with the host is immediately purged. This includes SQL tables like agentstatus, hosts, contexts, variables, etc. In order to completely delete the host, a deletion job is scheduled by adding the host to the internal table KeysPendingForDeletion. To see what hosts are pending deletion, run the query SELECT HostKey FROM KeysPendingForDeletion; against the cfsettings database.

After 5-10 minutes (one reporting iteration based on the [hub schedule][cf-hub#hub_schedule]), the main thread of cf-hub will pick up the deletion job. The hostkey is then removed from:

[Depending on the configuration][Masterfiles Policy Framework#trustkeysfrom] of [trustkeysfrom][cf-serverd#trustkeysfrom] for the hub hosts may re-appear and resume being collected from after being deleted.

List monitoring attributes for host

URI: https://hub.cfengine.com/api/host/:host-id/vital

Method: GET

List all available vital attributes monitored by CFEngine on the client.

Note: Collecting monitoring data by default is disabled.

Example response:

{
  "meta": {
    "page": 1,
    "count": 24,
    "total": 24,
    "timestamp": 1437144887
  },
  "data": [
    {
      "id": "mem_free",
      "timestamp": 1437144300,
      "description": "Free system memory",
      "units": "megabytes"
    },
    {
      "id": "mem_total",
      "timestamp": 1437144300,
      "description": "Total system memory",
      "units": "megabytes"
    },
    {
      "id": "loadavg",
      "timestamp": 1437144300,
      "description": "Kernel load average utilization",
      "units": "jobs"
    },
    {
      "id": "diskfree",
      "timestamp": 1437144300,
      "description": "Free disk on / partition",
      "units": "percent"
    }
  ]
}

Output:

Example usage: Example: Listing Available Vital Signs For A Host

Get samples from vital

URI: https://hub.cfengine.com/api/host/:host-id/vital/:vital-id

Method: GET

Parameters:

Example response:

{
  "meta": {
    "page": 1,
    "count": 1,
    "total": 1,
    "timestamp": 1437146605
  },
  "data": [
    {
      "id": "mem_free",
      "description": "Free system memory",
      "units": "megabytes",
      "timestamp": 1437146100,
      "values": [
        [
          1437140700,
          1229.8600
        ],
        [
          1437141000,
          1216.4500
        ],
        [
          1437141300,
          1218.3800
        ]
      ]
    }
  ]
}

Output:

Example usage: Example: Retrieving Vital Sign Data

Get count of bootstrapped hosts by date range

URI: https://hub.cfengine.com/api/host-count

Method: POST

Parameters:

Example request (curl):

curl -k --user admin:admin -X POST https://hub.cfengine.com/api/host-count  -H 'content-type: application/json'   -d '{"period": "month", "from": "2017-11-28", "to" : "2017-12-06"}'

Example response:

HTTP 200 Ok
{
    "period": "month",
    "data": [
        {
            "date": "Nov 2017",
            "count": 0
        },
        {
            "date": "Dec 2017",
            "count": 15
        }
    ]
}

Output: