Host API allows to access host specific information.
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
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:
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:
/var/cfengine/state/cf_lastseen.lmdb
)./var/cfengine/ppkeys
).KeysPendingForDeletion
table.[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.
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
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
URI: https://hub.cfengine.com/api/host-count
Method: POST
Parameters:
Emp: 2017-11-28
Emp: 2017-12-28
day, week, month, year
.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:
day, week, month, year
.