• API
• /
• Enterprise API reference
• /
• Changes REST API

Changes REST API

Changes API allows to track changes performed by CFEngine agent in the infrastructure.

Count changes performed by agent

URI:https://hub.cfengine.com/api/v2/changes/policy/count

Method: GET

Count changes performed by CFEngine to the infrastructure. Count can be narrowed down to specific groups of hosts, period of time or operation characteristics.

Note: In the environments with extensive policy and large number of clients it is recommended to narrow down the results as much as possible to achieve more precise results and faster response times. This can be done by specifying filtering parameters listed below.

• from(integer)Include changes performed within interval. Startingfrom unix timestamp. If not specified default value is last 24 hours.
• to(integer)Include changes performed within interval. Ending atto unix timestamp. If not specified default value is NOW.
• include(array)Include only nodes that have set specified context (cfengine class). Defaults to include all nodes.
• exclude(array)Exclude only nodes that have set specified context (cfengine class). Defaults to exclude no nodes.
• hostkey(string)Search results for nodes matching specified unique hostkey.
• stackpath(string)Search results matching specified stack path which is execution stack of the promise. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end.
• promisetype(string)Search results matching specified promise type - such ascommands,processes etc. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end.
• promisehandle(string)Search results matching specified promise handle. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end.
• bundlename(string)Search results matching specified bundle name. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end.
• policyfile(string)Search results matching specified path for policy file where promise is defined. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end.
• logmessages(string)Search results matching any of the messages logged for the promise. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end.
• promisees(string)Search results matching any of the promisees specified for promise. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end.

Example response:

{    "count": 49}

Output:

• countTotal count of changes performed by cf-agent that match specified filtering criteria.

Example usage:Example: Count changes

List changes performed by agent

URI:https://hub.cfengine.com/api/v2/changes/policy

Method: GET

List changes performed by CFEngine to the infrastructure. List can be narrowed down to specific groups of hosts, period of time or operation characteristics. In case of checking only for presence of the changes it is recommended to useCount changes performed by agent API.

Note: In the environments with extensive policy and large number of clients it is recommended to narrow down the results as much as possible to achieve more precise results and faster response times. This can be done by specifying filtering parameters listed below.

Parameters:

• from(integer)Include changes performed within interval. Startingfrom unix timestamp. If not specified default value is last 24 hours.
• to(integer)Include changes performed within interval. Ending atto unix timestamp. If not specified default value is NOW.
• include(array)Include only nodes that have set specified context (cfengine class). Defaults to include all nodes.
• exclude(array)Exclude only nodes that have set specified context (cfengine class). Defaults to exclude no nodes.
• hostkey(string)Search results for nodes matching specified unique hostkey.
• stackpath(string)Search results matching specified stack path which is execution stack of the promise. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end.
• promisetype(string)Search results matching specified promise type - such ascommands,processes etc. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end.
• promisehandle(string)Search results matching specified promise handle. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end.
• bundlename(string)Search results matching specified bundle name. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end.
• policyfile(string)Search results matching specified path for policy file where promise is defined. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end.
• logmessages(string)Search results matching any of the messages logged for the promise. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end.
• promisees(string)Search results matching any of the promisees specified for promise. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end.
• sort(string)Sort results by specified direction and attribute. By default sort direction is ascending, to sort as descending add '-' before attribute name. Result can be sorted by all returned fields. If not specified results are not sorted. Examples:sort=bundlename - sort ascending by bundlename,sort=-promisehandle - sort descending by promise handle.
• count(integer)Page size. Default 50 items.
• page(integer)Page number. Default 1st page.

Example response:

{  "data": [    {      "bundlename": "maintain_cfe_hub_process",      "changetime": 1430127161,      "hostkey": "SHA=de6ba9f406a2358e9169fb27e5459687d7107a001bb0abd4dd06485a63c2e50b",      "hostname": "hub",      "logmessages": [        "Unable to make file belong to an unknown user",        "Owner of '/var/log/postgresql.log' was 0, setting to 4294967295",        "Unknown user 'cfpostgres' in promise",        "Unable to make file belong to an unknown user",        "Owner of '/var/log/postgresql.log' was 0, setting to 4294967295"      ],      "policyfile": "/var/cfengine/inputs/update/update_processes.cf",      "promisees": [],      "promisehandle": "cfe_internal_maintain_cfe_hub_process_files_create_postgresql_log",      "promiser": "/var/log/postgresql.log",      "promisetype": "files",      "stackpath": "/default/cfe_internal_update_processes/methods/'TAKING CARE CFE HUB PROCESSES'/default/maintain_cfe_hub_process/files/'/var/log/postgresql.log'[0]"    },    {      "bundlename": "generate_repairs",      "changetime": 1437566606,      "hostkey": "SHA=a5c09762c561f78ee16097c0524e9efc1a2181c910cefae533f9013acd888b9f",      "hostname": "e63dc85f0e3e",      "logmessages": [        "Executing 'no timeout' ... '/bin/echo 123'",        "Completed execution of '/bin/echo 123'"      ],      "policyfile": "/var/cfengine/inputs/promises.cf",      "promisees": [],      "promisehandle": "",      "promiser": "/bin/echo 123",      "promisetype": "commands",      "stackpath": "/default/generate_repairs/commands/'/bin/echo 123'[0]"    }  ],  "total": 382723,  "next": "https://hub.cfengine.com/api/v2/changes/policy/?page=2&count=2",  "previous": null}

Output:

• totalTotal number of results.
• nextLink for fetching next page. Set to NULL if current page is last.
• previousLink for previous page. Set to NULL if the current page if the first.
• data.bundlenameBundle name where the promise is executed.
• data.changetimeTime of performing change by cf-agent to the system. Expressed as UNIT TIMESTAMP.
• data.hostkeyUnique host identifier.
• data.hostnameHost name locally detected on the host, configurable ashostIdentifier option inSettings API and Mission Portal settings UI.
• data.logmessagesList of 5 last messages generated during promise execution. Log messages can be used for tracking specific changes made by CFEngine while repairing or failing promise execution.
• data.policyfilePath to the file where the promise is located in.
• data.promiseesList ofpromisees defined for the promise.
• data.promisehandleA unique id-tag string for referring promise.
• data.promiserObject affected by a promise.
• data.promisetypeType of the promise.
• data.stackpathCall stack of the promise.

Example usage:Example: Show vacuum command executions

Still need help?

Chat

Ask a question on Github

Mailing list