The Complete API

Table of Content

The CFEngine Enterprise API allows HTTP clients to interact with the CFEngine Enterprise Hub. Typically this is also the policy server.

Enterprise API Overview

The Enterprise API is a REST API, but a central part of interacting with the API uses SQL. With the simplicity of REST and the flexibility of SQL, users can craft custom reports about systems of arbitrary scale, mining a wealth of data residing on globally distributed CFEngine Database Servers.

See also the Enterprise API examples and the Enterprise API reference.


Enterprise API examples

See also: Enterprise API reference


SQL query examples

Synchronous Example: Listing hostname and IP for Ubuntu hosts

Request:

code
curl -k --user admin:admin https://test.cfengine.com/api/query -X POST -d '{ "query": "SELECT Hosts.HostName, Hosts.IPAddress FROM Hosts"}'

Response:

code
{
  "data": [
    {
      "header": [
        {
          "columnName": "hostname",
          "columnType": "STRING"
        },
        {
          "columnName": "ipaddress",
          "columnType": "STRING"
        }
      ],
      "query": "select hostname, ipaddress from hosts",
      "queryTimeMs": 152,
      "rowCount": 1001,
      "rows": [
        [
          "ubuntu10-2.stage.cfengine.com",
          "172.20.100.1"
        ],
        [
          "ubuntu10-3.stage.cfengine.com",
          "172.20.100.2"
        ],
        [
          "ubuntu10-4.stage.cfengine.com",
          "172.20.100.3"
        ]
      ],
    }
  ],
  "meta": {
    "count": 1,
    "page": 1,
    "timestamp": 1437051092,
    "total": 1
  }
}
Subscribed query example: Creating a subscribed query

Here we create a new query to count file changes by name and have the result sent to us by email. The schedule field is any CFEngine context expression. The backend polls subscriptions in a loop and checks whether it's time to generate a report and send it out. In the following example, user milton creates a new subscription to a report which he names file-changes-report, which will be sent out every Monday night. His boss will get an email with a link to a PDF version of the report.

Request:

code
curl -k --user admin:admin https://test.cfengine.com/api/user/milton/ subscription/query/file-changes-report -X PUT -d '{"to": "boss@megaco.com", "query": "SELECT FileName, Count(*) FROM FileChangesLog GROUP BY FileName", "schedule": "Monday.Hr23.Min59", "title": "A very important file changes report""description": "Text that will be included in email""outputTypes": [ "pdf" ] }'

Response:

code
204 No Content
Subscribed query example: Listing report subscriptions

Milton can list all his current subscriptions by issuing the following.

Request:

code
curl -k --user admin:admin https://test.cfengine.com/api/user/milton/subscription/query

Response:

code
{
  "meta": {
    "page": 1,
    "count": 1,
    "total": 1,
    "timestamp": 1351003514
  },
  "data": [
    {
      "id": "file-changes-report",
      "to": "boss@megaco.com",
      "query": "SELECT FileName, Count(*) FROM FileChangesLog GROUP BY FileName",
      "title": "A very important file changes report",
      "description": "Text that will be included in email",
      "schedule": "Monday.Hr23.Min59",
      "outputTypes": [
        "pdf"
      ]
    }
  ]
}
Subscribed query example: Removing a report subscription

Request:

code
curl -k --user admin:admin https://test.cfengine.com/api/user/milton/subscription/query/file-changes-report -X DELETE

Response:

code
204 No Content

Checking status

You can get basic info about the API by issuing /api. This status information may also be useful if you contact support, as it gives some basic diagnostics.

Request

code
curl -k --user admin:admin --location https://test.cfengine.com/api/

Response

code
{
  "meta": {
    "page": 1,
    "count": 1,
    "total": 1,
    "timestamp": 1351154889
  },
  "data": [
    {
      "apiName": "CFEngine Enterprise API",
      "apiVersion": "v1",
      "enterpriseVersion": "3.0.0a1.81c0d4c",
      "coreVersion": "3.5.0a1.f3649b2",
      "databaseHostname": "127.0.0.1",
      "databasePort": 27017,
      "authenticated": "internal",
      "license": {
        "expires": 1391036400,
        "installTime": 1329578143,
        "owner": "Stage Environment",
        "granted": 20,
        "licenseUsage": {
          "lastMeasured": 1351122120,
          "samples": 1905,
          "minObservedLevel": 7,
          "maxObservedLevel": 30,
          "meanUsage": 21.9689,
          "meanCumulativeUtilization": 109.8446,
          "usedToday": 7
        }
      }
    }
  ]
}

Managing settings

Settings support two operations, GET (view settings) and POST (update settings). When settings are updated, they are sanity checked individually and as a whole. All or no settings will be updated for a request.

Example: Viewing settings

Request

code
curl --user admin:admin http://test.cfengine.com/api/settings

Response

code
{
  "meta": {
    "page": 1,
    "count": 1,
    "total": 1,
    "timestamp": 1350992335
  },
  "data": [
    {
      "hostIdentifier": "default.sys.fqhost",
      "rbacEnabled": true,
      "ldapEnabled": true,
      "blueHostHorizon": 900
    }
  ]
}
Example: Configuring LDAP

The setting ldapEnabled turns external authentication on or off. LDAP settings are managed by the LDAP API and not this Settings API.

Request

code
curl --user admin:admin http://test.cfengine.com/api/settings -X PATCH -d '{ "ldapEnabled": true }'

Response

code
204 No Content
Example: Changing the log level

The API uses standard Unix syslog to log a number of events. Additionally, log events are sent to stderr, which means they may also end up in your Apache log. Log events are filtered based on the log level in settings. Suppose you wanted to have greater visibility into the processing done at the back-end. The standard log level is error. Changing it to info is done as follows.

NOTE: Change to API log level will only take effect after Apache has re-started.

Request

code
curl --user admin:admin http://test.cfengine.com/api/settings -X PATCH -d '{ "logLevel": "info" }'

Response

code
204 No Content

Managing users and roles

Users and Roles determine who has access to what data from the API. Roles are defined by regular expressions that determine which hosts the user can see, and what policy outcomes are restricted.

Example: Listing users

Request

code
curl --user admin:admin http://test.cfengine.com/api/user

Response

code
{
  "meta": {
    "page": 1,
    "count": 2,
    "total": 2,
    "timestamp": 1350994249
  },
  "data": [
    {
      "id": "calvin",
      "external": true,
      "roles": [
        "Huguenots", "Marketing"
      ]
    },
    {
      "id": "quinester",
      "name": "Willard Van Orman Quine",
      "email": "noreply@@aol.com",
      "external": false,
      "roles": [
        "admin"
      ]
    }
  ]
}
Example: Creating a new user

All users will be created for the internal user table. The API will never attempt to write to an external LDAP server.

Request

code
curl --user admin:admin http://test.cfengine.com/api/user/snookie -X PUT -d
{
  "email": "snookie@mtv.com",
  "roles": [
    "HR"
  ]
}

Response

code
201 Created
}
Example: Updating an existing user

Both internal and external users may be updated. When updating an external users, the API will essentially annotate metadata for the user, it will never write to LDAP. Consequently, passwords may only be updated for internal users. Users may only update their own records, as authenticated by their user credentials.

Request

code
curl --user admin:admin http://test.cfengine.com/api/user/calvin -X POST -d '{ "name": "Calvin" }'

Response

code
204 No Content
Example: Retrieving a user

It is possible to retrieve data on a single user instead of listing everything. The following query is similar to issuing GET /api/user?id=calvin, with the exception that the previous query accepts a regular expression for id.

Request

code
curl --user admin:admin http://test.cfengine.com/api/user/calvin

Response

code
{
  "meta": {
    "page": 1,
    "count": 1,
    "total": 1,
    "timestamp": 1350994249
  },
  "data": [
    {
      "id": "calvin",
      "name": "Calvin",
      "external": true,
      "roles": [
        "Huguenots", "Marketing"
      ]
    },
  ]
}
Example: Adding a user to a role

Adding a user to a role is just an update operation on the user. The full role-set is updated, so if you are only appending a role, you may want to fetch the user data first, append the role and then update. The same approach is used to remove a user from a role.

Request

code
curl --user admin:admin http://test.cfengine.com/api/user/snookie -X POST -d
{
  "roles": [
    "HR", "gcc-contrib"
  ]
}

Response

code
204 No Content
}
Example: Deleting a user

Users can only be deleted from the internal users table.

Request

code
curl --user admin:admin http://test.cfengine.com/api/user/snookie -X DELETE

Response

code
204 No Content

Browsing host information

A resource /api/host is added as an alternative interface for browsing host information. For full flexibility we recommend using SQL reports via /api/query for this. however, currently vital signs (data gathered from cf-monitord) is not part of the SQL reports data model.

Example: Listing hosts with a given context

Request

code
curl --user admin:admin http://test.cfengine.com/api/host?context-include=windows.*

Response

code
{
  "meta": {
    "page": 1,
    "count": 2,
    "total": 2,
    "timestamp": 1350997528
  },
  "data": [
    {
      "id": "1c8fafe478e05eec60fe08d2934415c81a51d2075aac27c9936e19012d625cb8",
      "hostname": "windows2008-2.test.cfengine.com",
      "ip": "172.20.100.43"
    },
    {
      "id": "dddc95486d97e4308f164ddc1fdbbc133825f35254f9cfbd59393a671015ab99",
      "hostname": "windows2003-2.test.cfengine.com",
      "ip": "172.20.100.42"
    }
  ]
}
Example: Looking up hosts by hostname

Contexts, also known as classes, are powerful. You can use them to categorize hosts according to a rich set of tags. For example, each host is automatically tagged with a canonicalized version of its hostname and IP-address. So we could lookup the host with hostname windows2003-2.test.cfengine.com as follows (lines split and indented for presentability).

Request

code
curl --user admin:admin http://test.cfengine.com/api/host?context-include=
   windows2003_2_stage_cfengine_com

Response

code
{
  "meta": {
    "page": 1,
    "count": 1,
    "total": 1,
    "timestamp": 1350997528
  },
  "data": [
    {
      "id": "dddc95486d97e4308f164ddc1fdbbc133825f35254f9cfbd59393a671015ab99",
      "hostname": "windows2003-2.test.cfengine.com",
      "ip": "172.20.100.42"
    }
  ]
}
Example: Looking up hosts by IP

Similarly we can lookup the host with hostname windows2008-2.test.cfengine.com by IP as follows (lines split and indented for presentability).

Request

code
curl --user admin:admin http://test.cfengine.com/api/host?
   context-include=172_20_100_43

Response

code
{
  "meta": {
    "page": 1,
    "count": 1,
    "total": 1,
    "timestamp": 1350997528
  },
  "data": [
    {
      "id": "1c8fafe478e05eec60fe08d2934415c81a51d2075aac27c9936e19012d625cb8",
      "hostname": "windows2008-2.stage.cfengine.com",
      "ip": "172.20.100.43"
    }
  ]
}
Example: Removing host data

If a host has been decommissioned from a Hub, we can explicitly remove data associated with the host from the Hub, by issuing a DELETE request (lines split and indented for presentability).

Request

code
curl --user admin:admin http://test.cfengine.com/api/host/\
SHA=1c8fafe478e05eec60fe08d2934415c81a51d2075aac27c9936e19012d625cb8 -X DELETE

Response

code
204 No Content

See also: Host REST API

Example: Listing available vital signs for a host

Each host record on the Hub has a set of vital signs collected by cf-monitord on the agent. We can view the list of vitals signs from as host as follows (lines split and indented for presentability).

Request

code
curl --user admin:admin http://test.cfengine.com/api/host/\
SHA=4e913e2f5ccf0c572b9573a83c4a992798cee170f5ee3019d489a201bc98a1a/vital

Response

code
{
  "meta": {
    "page": 1,
    "count": 4,
    "total": 4,
    "timestamp": 1351001799
  },
  "data": [
    {
      "id": "messages",
      "description": "New log entries (messages)",
      "units": "entries",
      "timestamp": 1351001400
    },
    {
      "id": "mem_swap",
      "description": "Total swap size",
      "units": "megabytes",
      "timestamp": 1351001400
    },
    {
      "id": "mem_freeswap",
      "description": "Free swap size",
      "units": "megabytes",
      "timestamp": 1351001400
    },
    {
      "id": "mem_free",
      "description": "Free system memory",
      "units": "megabytes",
      "timestamp": 1351001400
    },
}
Example: Retrieving vital sign data

Each vital sign has a collected time series of values for up to one week. Here we retrieve the time series for the mem_free vital sign at host 4e913e2f5ccf0c572b9573a83c4a992798cee170f5ee3019d489a201bc98a1a for October 23rd 2012 12:20pm to 12:45pm GMT (lines split and indented for presentability).

Request

code
curl --user admin:admin http://test.cfengine.com/api/host/\
SHA=4e913e2f5ccf0c572b9573a83c4a992798cee170f5ee3019d489a201bc98a1a/vital/\
mem_free?from=1350994800&to=1350996300

Response

code
"meta": {
    "page": 1,
    "count": 1,
    "total": 1,
    "timestamp": 1351002265
  },
  "data": [
    {
      "id": "mem_free",
      "description": "Free system memory",
      "units": "megabytes",
      "timestamp": 1351001700,
      "values": [
        [
          1350994800,
          36.2969
        ],
        [
          1350995100,
          36.2969
        ],
        [
          1350995400,
          36.2969
        ],
        [
          1350995700,
          36.2969
        ],
        [
          1350996000,
          36.1758
        ],
        [
          1350996300,
          36.2969
        ]
      ]
    }
  ]

Tracking changes

Changes REST API allows to track the changes made by cf-agent in the infrastructure.

Example: Count changes

This examples shows how to count changes performed by cf-agent within last 24h hours.

Example is searching for changes that are performed by linux machines within generate_repairs bundle.

Request

code
curl --user admin:admin 'https://test.cfengine.com/api/v2/changes/policy/count?include\[\]=linux&bundlename=generate_repairs'

Response

code
{
  "count": 381
}
Example: Show vacuum command executions

Show all vacuumdb executions within last 24 hours executed on hosts reporting the policy_server or test_cfengine_com class.

Example is searching for changes that are performed by policy_server machines that execute commands promise with command /var/cfengine/bin/vacuumdb% - there is % sign at the end which is a wildcard as vacuumdb is executed with different options across policy.

Request

code
curl --user admin:admin 'https://test.cfengine.com/api/v2/changes/policy?include\[\]='policy_server\|test_cfengine_com'&promisetype=commands&promiser=/var/cfengine/bin/vacuumdb%'

Response

code
{
  "data": [
    {
      "bundlename": "cfe_internal_postgresql_vacuum",
      "changetime": 1437642099,
      "hostkey": "SHA=6ddfd5eaa85ee681ec12ce833fd7206e4d21c76e496be5f8b403ad0ead60a6ce",
      "hostname": "hub.provisioned.1436361289.cfengine.com.com",
      "logmessages": [
        "Executing 'no timeout' ... '/var/cfengine/bin/vacuumdb --analyze --quiet --dbname=cfdb'",
        "Completed execution of '/var/cfengine/bin/vacuumdb --analyze --quiet --dbname=cfdb'"
      ],
      "policyfile": "/var/cfengine/inputs/lib/cfe_internal_hub.cf",
      "promisees": [],
      "promisehandle": "cfe_internal_postgresql_maintenance_commands_run_vacuumdb",
      "promiser": "/var/cfengine/bin/vacuumdb --analyze --quiet --dbname=cfdb",
      "promisetype": "commands",
      "stackpath": "/default/cfe_internal_management/methods/'CFEngine_Internals'/default/cfe_internal_enterprise_main/methods/'hub'/default/cfe_internal_postgresql_vacuum/commands/'/var/cfengine/bin/vacuumdb --analyze --quiet --dbname=cfdb'[0]"
    }
  ],
  "total": 1,
  "next": null,
  "previous": null
}

Enterprise API reference

The Enterprise API is a conventional REST API in the sense that it has a number of URI resources that support one or more GET, PUT, POST, or DELETE operations. While reporting is done using SQL, this query is always wrapped in a JSON request.

See also: Enterprise API examples

Requests

GET requests are one of listing or getting. Listing resources means that a number of results will be returned, but each entry may contain limited information. An example of a listing query is /api/user to list users. Notice that URI components are always non-plural. An exception to this is /api/settings, which returns the singleton resource for settings. Getting a resource specifies an individual resource to return, e.g. /api/user/homer.

PUT request typically create a new resource, e.g. a user.

POST requests typically updates an existing resource. DELETE requests are also supported in some cases.

Note: When updating objects via the REST API the behavior is to overwrite existing objects. Any missing keys are reset to default values. For example if you have custom LDAP settings and want to update the blueHostHorizon you should first query to get the current settings, and then post the complete settings that you desire else the customized LDAP settings will be reset to defaults.

This example shows using JQ to preserve existing setting when updating an individual key value.

code
[root@hub]# curl -s -u admin:admin http://localhost:80/api/settings \
| jq '.data[0] + {"blueHostHorizon": 2222, "logLevel": "warning"}' \
| curl -s -u admin:admin http://localhost:80/api/settings -X POST -d @-

[root@hub]# curl -s -u admin:admin http://localhost:80/api/settings | jq '.data[0]'
{
  "blueHostHorizon": 2222,
  "hostIdentifier": "default.sys.fqhost",
  "ldapEnabled": true,
  "logLevel": "warning",
  "rbacEnabled": true
}
Pagination

Pagination is handled by page and count query parameters to a GET request, e.g. /api/user?page=5&count=30 to get the 5th page of pages with 30 entries each. The default page is 1 and the default count is 50 if these are not specified explicitly.

Responses

Enterprise API responses are always of the following format, consisting of a 'meta' object and a 'data' array.

code
{
  "meta": {
    "page": 1,
    "count": 1,
    "total": 1,
    "timestamp": 1350922925
  },
  "data": [
     ...
  ]
}

page refers to the current page number of the request. count is the number of results in the current page, equaling the length of the data array. total is the number of results in all available pages combined. timestamp is the time the request was processed by the API. The data array is resource dependent, but will always contain objects. Response objects typically do not contain error codes.

If the response is not 200 OK, the appropriate HTTP error code returned along with a (possibly non-JSON) payload.

All timestamps are reported in Unix Time, i.e. seconds since 1970.

Authentication

The API supports both internal and external authentication. The internal users table will always be consulted first, followed by an external source specified in the settings. External sources are OpenLDAP or Active Directory servers configurable through /api/settings.

Authorization

Some resources require that the request user is a member of the admin role. Roles are managed with /api/role. Role Based Access Control (RBAC) is configurable through the settings. Users typically have permission to access their own resources, e.g. their own scheduled reports.


Actions API

Actions API enables you to perform specific actions such a requesting report collection.

Report collection

You can trigger a delta report collection in order to have fresh host data.

URI: https://hub.cfengine.com/api/actions/report_collection

Method: POST

Parameters:

  • hostkey (string) Unique host identifier

Example request (curl):

code
curl -k --user <username>:<password> \
  -X POST \
  https://hub.cfengine.com/api/actions/report_collection \
  -H 'content-type: application/json' \
  -d '{"hostkey": "SHA=f329165d27a4484c626eb888e0ce3b1c6da6317177851fc999c2b1b1c159b4e8"}'

Example response:

code
HTTP 202 Accepted
Trigger agent run

You can trigger an agent run for an individual host.

URI: https://hub.cfengine.com/api/actions/agent_run

Method: POST

Parameters:

  • hostkey (string) Unique host identifier

Example request (curl):

code
curl -k --user <username>:<password> \
  -X POST \
  https://hub.cfengine.com/api/actions/agent_run \
  -H 'content-type: application/json' \
  -d '{"hostkey": "SHA=f329165d27a4484c626eb888e0ce3b1c6da6317177851fc999c2b1b1c159b4e8"}'

Example response:

code
HTTP 202 Accepted

{
    "output": "  notice: Waiting for child processes to finish\n172.28.128.15> cf-serverd executing cfruncommand: /bin/sh -c '
     \"/var/cfengine/bin/cf-agent\" -I -D cf_runagent_initiated -f /var/cfengine/inputs/update.cf  ;
     \"/var/cfengine/bin/cf-agent\" -I -D cf_runagent_initiated\n",
    "exit_code": 0
}

Build API

The Build API enables you to easily manage policy projects and their respective CFEngine Build modules.

Projects API

A project is a set of CFEngine Build modules and custom files/json/policy files.

Create project

URI: https://hub.cfengine.com/api/build/projects

Method: POST

Parameters:

  • repositoryUrl (string) Git repository URL. Project will be synchronized with this repository. Supported protocols: http, https, ssh , git. Required. Git repository URL example: https://github.com/username/repository.git

  • branch (string) Repository branch. Required.

  • name (string) Project name. Required.

  • authenticationType (string) Authentication type that will be used to get access to the repository. Allowed values: password, private_key. Required.

  • username (string) Username for authentication to the repository. Required when authentication type is password.

  • password (string) Password for authentication to the repository. Required when authentication type is password.

  • sshPrivateKey (string) SSH private key for authentication to the repository. Required when authentication type is private_key and sshKeyId is not set.

  • sshKeyId (integer) Generated SSH private key ID by SSH keys API for authentication to the repository. Required when authentication type is private_key and sshPrivateKey is not set.

Note: the SSH key is expected to be in openssh(rfc4716) format as generated by SSH Keys API or a command line like:

code
ssh-keygen -t rsa-sha2-512 -b 4096 -f test -m rfc4716

Example request (curl):

code
curl --user <username>:<password> \
  -X POST \
  https://hub.cfengine.com/api/build/projects \
  -H 'content-type: application/json' \
  -d '
  {
  "repositoryUrl": "https://github.com/username/repository.git",
  "branch": "master",
  "authenticationType": "password",
  "password" : "git_token_or_password",
  "username" : "git_username",
  "name": "Production"
  }'

Successful response example:

code
HTTP 200 Ok
{
    "id": "8"
}

Responses:

HTTP response code Description
200 OK Project successfully created
422 Unprocessable entity Validation error occurred
500 Internal server error Internal server error
Update project

By changing the repository url or branch you will initialize a new project and the current one will be removed from the file system and any un-pushed/un-deployed(terminology in Mission Portal UI) changes will be lost.

URI: https://hub.cfengine.com/api/build/projects/:id

Method: PATCH

Parameters:

  • id (integer) Project's ID. Required.

  • repositoryUrl (string) Git repository URL. Project will be synchronized with this repository. Supported protocols: http, https, ssh , git. Required. Git repository URL example: https://github.com/username/repository.git

  • branch (string) Repository branch.

  • name (string) Project name.

  • authenticationType (string) Authentication type that will be used to get access to the repository. Allowed values: password, private_key.

  • username (string) Username for authentication to the repository. Required when authentication type is password.

  • password (string) Password for authentication to the repository. Required when authentication type is password.

  • sshPrivateKey (string) SSH private key for authentication to the repository. Required when authentication type is private_key and sshKeyId is not set.

  • sshKeyId (integer) Generated SSH private key ID by SSH keys API for authentication to the repository. Required when authentication type is private_key and sshPrivateKey is not set.

Example request (curl):

code
curl --user <username>:<password> \
  -X PATCH \
  https://hub.cfengine.com/api/build/projects/2 \
  -H 'content-type: application/json' \
  -d '
  {
  "branch": "staging",
  }'

Successful response example:

code
HTTP 200 OK
{
    "id": "4"
}

Responses:

HTTP response code Description
204 No content Project successfully updated
404 Not found Project not found
422 Unprocessable entity Validation error occurred
500 Internal server error Internal server error
Get project

URI: https://hub.cfengine.com/api/build/projects/:id

Method: GET

Parameters:

  • id (integer) Project's ID. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/build/projects/2

Successful response example:

code
HTTP 200 OK
{
    "id": 2,
    "repository_url": "https://github.com/username/repository.git",
    "branch": "master",
    "name": "Production",
    "authentication_type": "password",
    "username": "admin",
    "is_empty": false,
    "created_at": "2022-03-17 14:01:56.23852+00",
    "pushed_at": null,
    "ssh_key_id": null,
    "password": "set",
    "ssh_private_key": "not set"
}

Note: The API does not return password or ssh private key, but returns set or not set.

Responses:

HTTP response code Description
200 Ok Successful response
404 Not found Project not found
500 Internal server error Internal server error
Get projects list

URI: https://hub.cfengine.com/api/build/projects

Method: GET

Parameters:

  • skip (integer) Number of results to skip for the processed query. The Mission Portal uses this for pagination. Optional parameter.
  • limit (integer) Limit the number of results in the query. Optional parameter.

Example request (curl):

code
curl --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/build/projects

Successful response example:

code
HTTP 200 OK
{
    "data": [
        {
            "id": 3,
            "repository_url": "https://github.com/build/modules.git",
            "branch": "master",
            "name": null,
            "authentication_type": "password",
            "username": "admin",
            "is_empty": false,
            "created_at": "2022-03-17 13:13:21.107899+00",
            "password": "set",
            "ssh_private_key": "not set"
        },
        {
            "id": 4,
            "repository_url": "https://github.com/build/modules.git",
            "branch": "production",
            "name": null,
            "authentication_type": "password",
            "username": "admin",
            "is_empty": false,
            "created_at": "2022-03-17 13:13:23.333539+00",
            "password": "set",
            "ssh_private_key": "not set"
        }
    ],
    "meta": {
        "count": 2,
        "page": 1,
        "timestamp": 1647596804,
        "total": 2
    }
}

Note: The API does not return password or ssh private key, but returns set or not set.

Responses:

HTTP response code Description
200 Ok Successful response
404 Not found Project not found
500 Internal server error Internal server error
Delete project

URI: https://hub.cfengine.com/api/build/projects/:id

Method: DELETE

Parameters:

  • id (integer) Project's ID. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X DELETE \
  https://hub.cfengine.com/api/build/projects/2

Successful response example:

code
HTTP 204 No content

Responses:

HTTP response code Description
204 No content Project successfully deleted
404 Not found Project not found
500 Internal server error Internal server error
Sync project

URI: https://hub.cfengine.com/build/projects/:id/sync

Method: POST

Parameters:

  • id (integer) Project's ID. Required.
  • action (string) Action. Allowed actions:
    • push - pushes local changes to the upstream repository
    • rebase - rebases local changes from the upstream
    • force-pull - overwrites local project files from upstream repository
    • force-rebase - force rebases local changes from the upstream

Example request (curl):

code
curl --user <username>:<password> \
  -X POST \
  https://hub.cfengine.com/api/build/projects/2 \
  -d '
  {
  "action": "push",
  }'

Successful response example:

code
HTTP 204 No content

Responses:

HTTP response code Description
204 No content Project successfully synced
404 Not found Project not found
500 Internal server error Internal server error
Refresh project

Fetch upstream repository and return the current state.

URI: https://hub.cfengine.com/build/projects/:id/refresh

Method: POST

Parameters:

  • id (integer) Project's ID. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X POST \
  https://hub.cfengine.com/api/build/projects/2/refresh

Successful response example:

code
HTTP 200 OK
{
    "status": "ahead",
    "details": [
        "Refreshed repository for project 4 with 'git fetch'"
    ]
}

Output:

  • status Project's status. Possible values:
    • ok - project is up-to-date
    • behind - there are changes in upstream which are not pulled
    • ahead - there are changes in the local project which are not pushed
    • diverged - there are changes which are not pushed and not pulled at the same time

Responses:

HTTP response code Description
200 Ok Successful response
404 Not found Project not found
500 Internal server error Internal server error
List of CFEngine Build modules added to project

URI: https://hub.cfengine.com/api/build/projects/:id/modules

Method: GET

Parameters:

  • id (integer) Project's ID. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/build/projects/5/modules

Successful response example:

code
HTTP 200 OK
[
    {
        "name": "masterfiles",
        "description": "Official CFEngine Masterfiles Policy Framework (MPF)",
        "tags": [
            "supported",
            "base"
        ],
        "repo": "https://github.com/cfengine/masterfiles",
        "by": "https://github.com/cfengine",
        "version": "3.18.1-1",
        "commit": "b6e9eacc65c797f4c2b4a59056293636c320d0c9",
        "added_by": "cfbs add",
        "steps": [
            "run ./prepare.sh -y",
            "copy ./ ./"
        ],
        "subdirectory": "",
        "isExternal": false,
        "availableVersion": "3.18.2"
    },
    {
        "name": "autorun",
        "version": "1.0.1",
        "description": "Enable autorun functionality",
        "tags": [
            "supported",
            "management"
        ],
        "repo": "https://github.com/cfengine/modules",
        "by": "https://github.com/olehermanse",
        "commit": "c3b7329b240cf7ad062a0a64ee8b607af2cb912a",
        "subdirectory": "management/autorun",
        "added_by": "cfbs add",
        "steps": [
            "json def.json def.json"
        ],
        "isExternal": false,
        "availableVersion": "1.0.1"
    }
]

Responses:

HTTP response code Description
200 Ok Successful response
404 Not found Project not found
500 Internal server error Internal server error
Add CFEngine Build module to project

URI: https://hub.cfengine.com/api/build/projects/:id/modules/:module

Method: POST

Parameters:

  • id (integer) Project's ID. Required.
  • module (string) Module's name. Required.
  • version (string) Module's version. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X POST \
  https://hub.cfengine.com/api/build/projects/1/modules/autorun \
  -H 'content-type: application/json' \
  -d '
  {
  "version": "1.0.1"
  }'

Successful response example:

code
HTTP 201 Created

Responses:

HTTP response code Description
201 Created Module successfully added
404 Not found Project not found
422 Unprocessable entity Validation error occurred
500 Internal server error Internal server error
Delete CFEngine Build module from project

URI: https://hub.cfengine.com/api/build/projects/:id/modules/:module

Method: DELETE

Parameters:

  • id (integer) Project's ID. Required.
  • module (string) Module's name. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X DELETE \
  https://hub.cfengine.com/api/build/projects/1/modules/autorun

Successful response example:

code
HTTP 204 No content

Responses:

HTTP response code Description
204 No content Module successfully deleted from project
404 Not found Project not found
500 Internal server error Internal server error
Update CFEngine Build module version

URI: https://hub.cfengine.com/api/build/projects/:id/modules/:module

Method: PATCH

Parameters:

  • id (integer) Project's ID. Required.
  • module (string) Module's name. Required.
  • version (string) Module's version. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X PATCH \
  https://hub.cfengine.com/api/build/projects/1/modules/autorun \
  -H 'content-type: application/json' \
  -d '
  {
  "version": "1.0.2"
  }'

Successful response example:

code
HTTP No content

Responses:

HTTP response code Description
204 No content Module successfully updated
404 Not found Project not found
422 Unprocessable entity Validation error occurred
500 Internal server error Internal server error
Get list of available CFEngine Build modules

URI: https://hub.cfengine.com/api/build/modules

Method: GET

Parameters:

  • sortColumn (string) Column name on which to sort results. Default value: name. Optional parameter.
  • sortDescending (boolean) Sorting order. Optional parameter. Default value: false. Optional parameter.
  • searchQuery (string) Search query for a full-text search based on modules name and description. Optional parameter.
  • tag (string) Filter modules by tag. Optional parameter.
  • skip (integer) Number of results to skip for the processed query. The Mission Portal uses this for pagination. Optional parameter.
  • limit (integer) Limit the number of results in the query. Optional parameter.

Example request (curl):

code
curl --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/build/modules/?searchQuery=autorun

Successful response example:

code
HTTP 200 OK
{
    "data": [
        {
            "name": "autorun",
            "readme": "<h1 id=\"enable-autorun\">Enable autorun</h1>\n<p>Simple module to enable autorun functionality, using def.json.</p>\n",
            "description": "Enable autorun functionality",
            "version": "1.0.1",
            "author": {
                "url": "https://github.com/olehermanse",
                "name": "Ole Herman Schumacher Elgesem",
                "image": "https://avatars.githubusercontent.com/u/4048546?v=4"
            },
            "updated": "2021-11-03 00:00:00+00",
            "downloads": 1837,
            "repo": "https://github.com/cfengine/modules",
            "documentation": null,
            "website": null,
            "subdirectory": "management/autorun",
            "commit": "c3b7329b240cf7ad062a0a64ee8b607af2cb912a",
            "dependencies": "[]",
            "tags": "[\"supported\", \"management\"]",
            "versions": {
                "1.0.0": {
                    "date": "Oct 26, 2021",
                    "latest": false
                },
                "1.0.1": {
                    "date": "Nov 1, 2021",
                    "latest": true
                }
            },
            "latest": true,
            "ts_vector": "'autorun':1A,3B 'enable':2B 'functionality':4B"
        }
    ],
    "meta": {
        "count": 1,
        "page": 1,
        "timestamp": 1657097484,
        "total": 1
    }
}

Responses:

HTTP response code Description
200 Ok Successful response
500 Internal server error Internal server error
Update list of available CFEngine Build modules

Modules will be received from the official CFEngine Build modules catalogue https://build.cfengine.com

URI: https://hub.cfengine.com/api/build/modules

Method: POST

Example request (curl):

code
curl --user <username>:<password> \
  -X POST \
  https://hub.cfengine.com/api/build/modules

Successful response example:

code
204 No content

Responses:

HTTP response code Description
204 No content Modules list successfully updated
500 Internal server error Internal server error
Get CFEngine build module by name

URI: https://hub.cfengine.com/api/build/modules/:name

Method: GET

Parameters:

  • name (string) Module name. Default value: name. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/build/modules/autorun

Successful response example:

code
HTTP 200 OK
{
    "name": "autorun",
    "readme": "<h1 id=\"enable-autorun\">Enable autorun</h1>\n<p>Simple module to enable autorun functionality, using def.json.</p>\n",
    "description": "Enable autorun functionality",
    "version": "1.0.1",
    "author": {
        "url": "https://github.com/olehermanse",
        "name": "Ole Herman Schumacher Elgesem",
        "image": "https://avatars.githubusercontent.com/u/4048546?v=4"
    },
    "updated": "2021-11-03 00:00:00+00",
    "downloads": 1837,
    "repo": "https://github.com/cfengine/modules",
    "documentation": null,
    "website": null,
    "subdirectory": "management/autorun",
    "commit": "c3b7329b240cf7ad062a0a64ee8b607af2cb912a",
    "dependencies": "[]",
    "tags": "[\"supported\", \"management\"]",
    "versions": {
        "1.0.0": {
            "date": "Oct 26, 2021",
            "latest": false
        },
        "1.0.1": {
            "date": "Nov 1, 2021",
            "latest": true
        }
    },
    "latest": true
}

Responses:

HTTP response code Description
200 Ok Successful response
404 Not found Module not found
500 Internal server error Internal server error
Get specific version of a CFEngine Build module by name

URI: https://hub.cfengine.com/api/build/modules/:name/:version/

Method: GET

Parameters: sortColumn searchQuery tag

  • name (string) Module name. Required.
  • version (string) Module version. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/build/modules/autorun/1.0.0/

Successful response example:

code
HTTP 200 OK
{
    "name": "autorun",
    "readme": "<h1 id=\"enable-autorun\">Enable autorun</h1>\n<p>Simple module to enable autorun functionality, using def.json.</p>\n",
    "description": "Enable autorun functionality",
    "version": "1.0.0",
    "author": {
        "url": "https://github.com/olehermanse",
        "name": "Ole Herman Schumacher Elgesem",
        "image": "https://avatars.githubusercontent.com/u/4048546?v=4"
    },
    "updated": "2021-11-03 00:00:00+00",
    "downloads": 1837,
    "repo": "https://github.com/cfengine/modules",
    "documentation": null,
    "website": null,
    "subdirectory": "management/autorun",
    "commit": "be3bc015f6a19e945bb7a9fa0ed78c97e2cecf61",
    "dependencies": "[]",
    "tags": "[\"supported\", \"management\"]",
    "versions": {
        "1.0.0": {
            "date": "Oct 26, 2021",
            "latest": false
        },
        "1.0.1": {
            "date": "Nov 1, 2021",
            "latest": true
        }
    },
    "latest": false
}

Responses:

HTTP response code Description
200 Ok Successful response
404 Not found Module not found
500 Internal server error Internal server error
Get CFEngine Build module input data

URI: https://hub.cfengine.com/api/build/projects/:id/modules/:name/input

Method: GET

Parameters:

  • id (integer) Project's ID. Required.
  • name (string) Module name. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/build/projects/1/modules/delete-files/input

Successful response example:

code
HTTP 200 OK
{
    "status": "ok",
    "input_spec": [
        {
            "type": "list",
            "label": "Files",
            "while": "Specify another file you want deleted on your hosts?",
            "bundle": "delete_files",
            "subtype": [
                {
                    "key": "path",
                    "type": "string",
                    "label": "Path",
                    "question": "Path to file"
                },
                {
                    "key": "why",
                    "type": "string",
                    "label": "Why",
                    "default": "Unknown",
                    "question": "Why should this file be deleted?"
                }
            ],
            "response": [
                {
                    "path": "/tmp/test",
                    "why": "no tests, please"
                }
            ],
            "variable": "files",
            "namespace": "delete_files"
        }
    ]
}

Output:

  • input_spec (JSON array of objects) Input specification represented as an JSON array of objects. Each object specifies one input entry for the module. To discover more information about these fields, please read Modules with input document.

Responses:

HTTP response code Description
200 Ok Successful response
404 Not found Project or module not found
500 Internal server error Internal server error
Set CFEngine Build module input data

URI: https://hub.cfengine.com/api/build/projects/:id/modules/:name/input

Method: POST

Parameters:

  • id (integer) Project's ID. Required.
  • name (string) Module name. Required.

Request body:

Request body should contain input specification from the Get input data request where each object should have a response property with the data.

response might be: * an JSON array of objects, in case of list input type with string subtypes. An object should be a key-value pair where a key is from input specification and value should be a string. * string, in case of string input type

Example request (curl):

code
curl --user <username>:<password> \
  -X POST \
  https://hub.cfengine.com/api/build/projects/1/modules/delete-files/input \
  --header 'Content-Type: application/json' \
  --data-raw '[
   {
      "type":"list",
      "label":"Files",
      "while":"Specify another file you want deleted on your hosts?",
      "bundle":"delete_files",
      "subtype":[
         {
            "key":"path",
            "type":"string",
            "label":"Path",
            "question":"Path to file"
         },
         {
            "key":"why",
            "type":"string",
            "label":"Why",
            "default":"Unknown",
            "question":"Why should this file be deleted?"
         }
      ],
      "variable":"files",
      "namespace":"delete_files",
      "response":[
         {
            "path":"/etc/test",
            "why":"no tests, please"
         }
      ]
   }
]'

Successful response example:

code
HTTP 200 OK
{
    "status": "ok"
}

Responses:

HTTP response code Description
200 Ok Successful response
404 Not found Project or module not found
500 Internal server error Internal server error

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. Starting from unix timestamp. If not specified default value is last 24 hours.
  • to (integer) Include changes performed within interval. Ending at to 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 as commands, 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:

code
{
    "count": 49
}

Output:

  • count Total 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 use Count 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. Starting from unix timestamp. If not specified default value is last 24 hours.
  • to (integer) Include changes performed within interval. Ending at to 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 as commands, 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:

code
{
  "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:

  • total Total number of results.
  • next Link for fetching next page. Set to NULL if current page is last.
  • previous Link for previous page. Set to NULL if the current page if the first.
  • data.bundlename Bundle name where the promise is executed.
  • data.changetime Time of performing change by cf-agent to the system. Expressed as UNIT TIMESTAMP.
  • data.hostkey Unique host identifier.
  • data.hostname Host name locally detected on the host, configurable as hostIdentifier option in Settings API and Mission Portal settings UI.
  • data.logmessages List 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.policyfile Path to the file where the promise is located in.
  • data.promisees List of promisees defined for the promise.
  • data.promisehandle A unique id-tag string for referring promise.
  • data.promiser Object affected by a promise.
  • data.promisetype Type of the promise.
  • data.stackpath Call stack of the promise.

Example usage: Example: Show vacuum command executions


CMDB API

The configuration management database (CMDB) API enables you to manage classes and variables for specific hosts.

List CMDB

You can see a list of stored host-specific configurations

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

Method: GET

Parameters:

  • fromEpoch (integer) Returns configurations with epoch value greater than set in the filter. Epoch is the sequence number of the latest CMDB change. In every API list request, cmdb_epoch will be present in the meta section, which contains the maximum epoch value among selected items. Optional parameter.
  • fromTime (timestamp) Include changes performed within interval. Format: YYYY-mm-dd HH:MM:SS or YYYY-mm-dd. Optional parameter.
  • toTime (timestamp) Include changes performed within interval. Format: YYYY-mm-dd HH:MM:SS or YYYY-mm-dd. Optional parameter.
  • skip (integer) Number of results to skip for the processed query. The Mission Portal uses this for pagination. Optional parameter.
  • limit (integer) Limit the number of results in the query. Optional parameter.
  • hostContextInclude (array) Includes only results that concern hosts which have all specified CFEngine contexts (class) set. Optional parameter.
  • hostContextExclude (array) Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at least one of the specified contexts set will be excluded from the results. Optional parameter.

Example request (curl):

code
curl -k --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/cmdb?epochFrom=2&hostContextInclude[]=ubuntu

Example response:

code
HTTP 200 Ok
{
    "data": {
        "SHA=fdab725e8fb18aa0ad194477be8a2a1338b4b29f6a8597819af89697e432418f": {
            "classes": {
                "My_class": {},
                "My_class2": {
                    "comment": "comment helps to understand what this class serves for"
                }
            },
            "variables": {
                "HubCMDB:My.hostname": {
                    "value": "host1.cfengine.com",
                    "comment": "comment"
                },
                "Namespace:BundleName.VariableName": {
                    "value": "myvalue"
                }
            }
        }
    },
    "meta": {
        "count": "1",
        "page": 1,
        "timestamp": 1619116399,
        "total": "1",
        "cmdb_epoch": "13"
    }
}
Get host's specific configuration

URI: https://hub.cfengine.com/api/cmdb/:hostkey/:type/:name/

Method: GET

Parameters:

  • hostkey (string) Unique host identifier.

  • type (string) Configuration type. Allowed value: variables, classes

  • name (string) Configuration name. Classes or variables name.

Example request (curl):

code
curl -k --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/cmdb/SHA=f622992fa4525070f47da086041a38733496f03a77880f70b1ce6784c38f79ab/variables/HubCMDB:My.hostname/

Example response:

code
HTTP 200 Ok
{
    "hostkey": "SHA=437d63cdc0b13ad18bb2d9de2490bfabe4edc8aa59f248b5b5b050c77bf4eeef",
    "variables": {
        "default:def.augment_inputs": {
            "tags": [
                "suggestion-004"
            ],
            "value": [],
            "comment": "Add filenames to this list to make the CFEngine agent parse them. Note: Update the bundle sequence to evaluate bundles from these policy files."
        }
    }
}
Get host's configurations

URI: https://hub.cfengine.com/api/cmdb/:hostkey

Method: GET

Parameters:

  • hostkey (string) Unique host identifier.

Example request (curl):

code
curl -k --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/cmdb/SHA=f622992fa4525070f47da086041a38733496f03a77880f70b1ce6784c38f79ab

Example response:

code
HTTP 200 Ok
{
    "hostkey": "SHA=f622992fa4525070f47da086041a38733496f03a77880f70b1ce6784c38f79ab",
    "value": {
        "classes": {
            "My_class": {},
            "My_class2": {
                "comment": ""
            }
        },
        "variables": {
            "HubCMDB:My.hostname": {
                "value": "host1.cfengine.com",
                "comment": "My hostname should be set to this"
            },
            "Namespace:BundleName.VariableName": {
                "value": "myvalue"
            }
        }
    }
}
Create configuration

URI: https://hub.cfengine.com/api/cmdb/:hostkey/:type/:name/

Method: POST

Parameters:

  • hostkey (string) Unique host identifier.

  • type (string) Configuration type. Allowed value: variables, classes

  • name (string) Configuration name. Classes or variables name.

Request body parameters:

  • value (string|array) Variable value, can be array or text. Classes do not support values.

  • comment (string) Variables or classes description. Optional parameter.

  • tags (array) Variables or classes tags. Optional parameter.

Example request (curl):

code
curl -k --user <username>:<password> \
  -X POST \
  https://hub.cfengine.com/api/cmdb/SHA=f622992fa4525070f47da086041a38733496f03a77880f70b1ce6784c38f79ab/variables/Namespace:BundleName.Ports/ \
  -H 'content-type: application/json' \
  -d '
  { "value": ["80", "443"],
    "comment":"Openning ports",
    "tags" : ["ports", "tag"]
  }'

Example response:

code
HTTP 200 Ok
Batch create configurations

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

Method: POST

Parameters:

  • hostkey (string) Unique host identifier.
  • classes (JSON object) The format is a JSON object where the key is class name and value is another JSON object with optionals comment and tags property. Example:

    code
    {
     "classes":{
        "My_class": {},
        "My_class2": {
           "comment":"comment body",
           "tags": ["suggestion-001", "reporting"]
        }
     }
    }
    
  • variables (JSON object) The format is a JSON object where the key is variable name and value is another JSON object with a required value property and optionals comment and tags. Example:

    code
    {
     "variables":{
        "Namespace:BundleName.VariableName":{
           "value":"myvalue"
        },
        "HubCMDB:My.hostname":{
           "value":"host1.cfengine.com",
           "comment":"My hostname should be set to this",
           "tags": ["suggestion-001", "reporting"]
        }
     }
    }
    

Example request (curl):

code
curl -k --user <username>:<password> \
  -X POST \
  https://hub.cfengine.com/api/cmdb \
  -H 'content-type: application/json' \
  -d '{
   "hostkey":"SHA=f622992fa4525070f47da086041a38733496f03a77880f70b1ce6784c38f79ab",
   "classes":{
       "My_class": {},
      "My_class2":{
         "comment":"comment body",
         "tags": ["suggestion-001", "reporting"]
      }
   },
   "variables":{
      "Namespace:BundleName.VariableName":{
         "value":"myvalue"
      },
      "HubCMDB:My.hostname":{
         "value":"host1.cfengine.com",
         "comment":"My hostname should be set to this"
      }
   }
}'

Example response:

code
HTTP 201 Created
Update configuration

URI: https://hub.cfengine.com/api/cmdb/:hostkey/:type/:name/

Method: PATCH

Parameters:

  • hostkey (string) Unique host identifier.

  • type (string) Configuration type. Allowed value: variables, classes

  • name (string) Configuration name. Classes or variables name.

Request body parameters:

  • value (string|array) Variable value, can be array or text. Classes do not support values.

  • comment (string) Variables or classes description. Optional parameter.

  • tags (array) Variables or classes tags. Optional parameter.

  • name (string) New name, in case of renaming. Optional parameter.

Example request (curl):

code
curl -k --user <username>:<password> \
  -X PATCH \
  https://hub.cfengine.com/api/cmdb/SHA=f622992fa4525070f47da086041a38733496f03a77880f70b1ce6784c38f79ab/variables/Namespace:BundleName.Ports/ \
  -H 'content-type: application/json' \
  -d '
  { "value": ["80", "443"],
    "comment":"Openning ports",
    "tags" : ["ports", "tag"]
  }'

Example response:

code
HTTP 200 Ok
Batch update configurations

URI: https://hub.cfengine.com/api/cmdb/:hostkey

Method: PATCH

Parameters:

  • hostkey (string) Unique host identifier.
  • classes (JSON object) The format is a JSON object where the key is class name and value is another JSON object with an optional comment property. Example:

    code
    {
     "classes":{
        "My_class":{
    
        },
        "My_class2":{
           "comment":"comment body"
        }
     }
    }
    

If you need to delete all classes from host you need to set null value:

code
{
    "classes": null
}

If your request body misses classes then the previous value will be preserved.

  • variables (JSON object) The format is a JSON object where the key is variable name and value is another JSON object with a required value property and an optional comment property. Example:

    code
    {
     "variables":{
        "Namespace:BundleName.VariableName":{
           "value":"myvalue"
        },
        "HubCMDB:My.hostname":{
           "value":"host1.cfengine.com",
           "comment":"My hostname should be set to this"
        }
     }
    }
    

If you need to delete all variables from host you need to set null value:

code
{
    "variables": null
}

If your request body misses variables then the previous value will be preserved.

Example request (curl):

code
curl -k --user <username>:<password> \
  -X PATCH \
  https://hub.cfengine.com/api/cmdb/SHA=f622992fa4525070f47da086041a38733496f03a77880f70b1ce6784c38f79ab \
  -H 'content-type: application/json' \
  -d '{
   "classes":{
      "My_class2":{
         "comment" : ""
      },
      "My_class": {}
   },
   "variables":{
      "Namespace:BundleName.VariableName":{
         "value":"myvalue"
      },
      "HubCMDB:My.hostname":{
         "value":"host1.cfengine.com",
         "comment":"My hostname should be set to this"
      }
   }
}'

Example response:

code
HTTP 200 Ok
Delete host's configurations

URI: https://hub.cfengine.com/api/cmdb/:hostkey

Method: DELETE

Parameters:

  • hostkey (string) Unique host identifier.

Example request (curl):

code
curl -k --user <username>:<password> \
  -X DELETE \
  https://hub.cfengine.com/api/cmdb/SHA=f622992fa4525070f47da086041a38733496f03a77880f70b1ce6784c38f79ab

Example response:

code
HTTP 204 No Content
Delete specific configuration

URI: https://hub.cfengine.com/api/cmdb/:hostkey/:type/:name/

Method: DELETE

Parameters:

  • hostkey (string) Unique host identifier.

  • type (string) Configuration type. Allowed value: variables, classes

  • name (string) Configuration name. Classes or variables name.

Example request (curl):

code
curl -k --user <username>:<password> \
  -X DELETE \
  https://hub.cfengine.com/api/cmdb/SHA=f622992fa4525070f47da086041a38733496f03a77880f70b1ce6784c38f79ab/classes/My_class2/

Example response:

code
HTTP 204 No Content

Import & export API

Import & export API provides users the ability to transfer Mission Portal data between hubs.

See also: Export/import Settings UI

Get available items to export

This API call provides a list of items available for export. Please note that the role of the user that authenticates to this API will affect what items are available. For example: the API user must have admin role in order to export settings.

URI: https://hub.example/data_transfer/api/exportItems

Method: GET

Example request (curl):

code
curl -k --user <username>:<password> \
  -X GET \
  https://hub.example/data_transfer/api/exportItems

Example response:

code
HTTP 200 Ok
[
    {
        "id": "categorizations",
        "name": "Host categorizations"
    },
    {
        "id": "dashboards",
        "name": "Dashboards"
    },
    {
        "id": "reports",
        "name": "Reports"
    },
    {
        "id": "settingsScripts",
        "name": "Custom notification scripts"
    },
    {
        "id": "users",
        "name": "Users"
    },
    {
        "id": "settingsRoles",
        "name": "Roles"
    },
    {
        "id": "settingsPreferences",
        "name": "Preferences"
    },
    {
        "id": "settingsAuthentication",
        "name": "LDAP authentication settings"
    },
    {
        "id": "settingsMail",
        "name": "Mail settings"
    },
    {
        "id": "settingsVCS",
        "name": "Version control repository"
    }
]

Output:

  • id Item id. Use this id in export API call.
  • name Name of export item.
Export

URI: https://hub.example/data_transfer/api/export

Method: GET

Parameters:

  • item_id (array) Item id to be exported. List of item ids you can obtain through List of items to export call described below.

  • encryptionKey (string) Encryption key to encrypt sensitive data. Please save this key to be able to import the data.

  • exportOnlyUserItems (string) true - export only user items. false - export whole system data

Example request (curl):

code
curl -k -g --user <username>:<password> \
  -X GET \
  'https://hub.example/index.php/data_transfer/api/export?encryptionKey=key&exportOnlyUserItems=true&items[]=categorizations&items[]=dashboards&items[]=settingsAuthentication&items[]=settingsMail'

Example response:

code
HTTP 200 Ok
{
    "name": "export_12-14-2018_15:19:40.381400.phar",
}

Output:

  • name Name of export file.
  • url Url of export file.
Download export file

URI: https://hub.example/data_transfer/api/download/:file_name:

Method: GET

Parameters:

  • file_name (string) File name to be downloaded.

Example request (curl):

code
curl -k -g --user <username>:<password> \
  -X GET \
  --output /save/file/here/export_12-14-2018_15:19:40.381400.phar \
  'https://hub.example/index.php/data_transfer/api/download/export_12-14-2018_15:19:40.381400.phar'

Example response:

code
HTTP 200 Ok

Raw file contetnt

Output headers:

  • Cache-Control: must-revalidate, post-check=0, pre-check=0
  • Pragma: public
  • Content-Description: File Transfer
  • Content-Disposition: attachment; filename="export_12-14-2018_16:04:46.093500.phar"
  • Content-Length: 337801
  • Content-Type: application/octet-stream
Analyze import file

This API call allows you to see short summary of file content.

URI: https://hub.example/data_transfer/api/analyzeImportFile

Method: POST

Parameters:

  • file (form data file) File to be analyzed.

Example request (curl):

code
curl -k --user <username>:<password> \
-X POST \
-F file=@/path/to/file.phar  \
'https://hub.example/index.php/data_transfer/api/analyzeImportFile'

Example response:

code
HTTP 200 Ok
{
    "categorizations": 3,
    "dashboards": "4, Widgets: 21 , Alerts: 31, Rules: 7",
    "settingsAuthentication": "yes",
    "settingsMail": "yes"
}
Import

URI: https://hub.example/data_transfer/api/import

Method: POST

Parameters:

  • file (form data file) File to be analyzed.
  • encryptionKey (string) Encryption key that was set while export.
  • skipDuplicates (number) Merge conflict strategy: 1 - skip duplicate items. 0 - overwrite duplicate items.

Example request (curl):

code
curl -k --user <username>:<password> \
-X POST \
-F file=@/path/to/file.phar  \
-F encryptionKey=key \
-F skipDuplicates=1 \
'https://hub.example/index.php/data_transfer/api/import'

Example response:

code
HTTP 200 Ok

Import & export compliance report API

This provides users the ability to transfer compliance reports between hubs or create reports from a JSON definition file.

Export

URI: https://hub.example/advancedreports/complianceReport/export?id=:ID

Method: GET

Example request (curl):

code
curl -k --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/advancedreports/complianceReport/export?id=20

Example response:

code
HTTP 200 Ok
{
    "reports": {
        "example-compliance-report": {
            "id": "example-compliance-report",
            "type": "compliance",
            "title": "Example Compliance Report",
            "conditions": [
                "software-updates-available",
                "entire-cfengine-policy"
            ]
        }
    },
    "conditions": {
        "software-updates-available": {
            "id": "software-updates-available",
            "name": "Software updates available",
            "description": "Available software updates to any package.",
            "type": "softwareupdate",
            "condition_for": "failing",
            "rules": {
                "package-name": null,
                "condition": null,
                "architecture": null
            },
            "category": "uncategorized",
            "severity": null,
            "host_filter": null
        },
        "entire-cfengine-policy": {
            "id": "entire-cfengine-policy",
            "name": "Entire CFEngine policy",
            "description": "Promises not kept in the entire policy.",
            "type": "policy",
            "condition_for": "failing",
            "rules": {
                "filter-by": null,
                "value": null,
                "promise-handle": null,
                "promise-status": "NOTKEPT"
            },
            "category": "uncategorized",
            "severity": null,
            "host_filter": null
        }
    }
}
Import

URI: https://hub.example/advancedreports/complianceReport/import

Method: POST

Parameters:

  • data (json) Reports and conditions data to be imported. Data json object should have two nested objects: reports and condtions:

    • reports JSON object where the key is report ID, which will be used to identify if report already exists in the system.
      • id (text) Report ID
      • type (text) Report's type. Should be set to complince
      • title (text) Report's title.
      • conditions (array) Conditions list
    • conditions JSON object where the key is condition ID, which will be used to identify if condition already exists in the system.
      • id (text) Condition ID
      • name (text) Condition name
      • description (text) Condition description
      • condition_for (text) Condition for passing or failing.
      • type (text) Condition type. Possible values: inventory, custom, fileChanged, policy, software
      • rules (json object) JSON object that define rules. Each type has own set of fields:
        • inventory
          • attribute (text) Inventory attribute
          • operator (text) Operator. Possible values: matches, not_match, contains, not_contain, regex_matches, regex_not_match, is_not_reported, is_reported, <, >, <=, >=, =, !=
          • value (text) Value. This field might be skipped in case of is_reported or is_not_reported operators
        • custom
          • sql (text) Custom SQL
        • fileChanged
          • file-name (text) File name
          • condition (text) Condition. Possible values: matches, is
          • time-period (int) Changed within the time period (hours).
        • policy
          • filter-by (text) Filter by: Bundlename, Promisees, Promiser
          • value (text) Filter value
          • promise-handle (text) Promise handle
          • promise-status (text) Promise status: KEPT, NOTKEPT, REPAIRED
        • software
          • package-name (text) Package name
          • condition (text) Condition: matches, is
          • architecture (text) Architecture
      • category (text) Conditions category
      • severity (text) Condition severity. Possible values: low, medium, high
      • host_filter (text) Host filter, should be valid class expression.
  • overwrite (booleans) Set true to overwrite existing reports or conditions that belong to you. Default: false

  • public (booleans) Set true to make report publicly accessible. Default: false

Example request (curl):

code
curl -k --user <username>:<password> \
-X POST https://hub.cfengine.com/advancedreports/complianceReport/import \
--form 'data={
  "reports": {
    "example-report-1": {
      "id": "example-report-1",
      "type": "compliance",
      "title": "Example report #1",
      "conditions": ["os-is-reported", "supported-ubuntu"]
    }
  },
  "conditions": {
    "os-is-reported": {
      "id": "os-is-reported",
      "name": "Operating system is reported",
      "description": "",
      "condition_for": "passing",
      "type": "inventory",
      "rules": [
        {
          "attribute": "OS",
          "operator": "is_reported"
        }
      ],
      "category": "Operating System",
      "severity": "high",
      "host_filter": "linux"
    },
    "supported-ubuntu": {
      "id": "supported-ubuntu",
      "name": "Ubuntu version is supported",
      "description": "Only Ubuntu 18+ are supported",
      "condition_for": "passing",
      "type": "inventory",
      "rules": [
        {
          "attribute": "OS",
          "operator": "matches",
          "value": "Ubuntu"
        }
      ],
      "category": "Operating System",
      "severity": "high",
      "host_filter": "linux"
    }
  }
}' \
--form 'public=true' \
--form 'overwrite=true'

Example response:

code
HTTP 200 OK
{
    "processed-conditions": {
        "os-is-reported": 13,
        "supported-ubuntu": 14
    },
    "processed-reports": {
        "example-report-1": 22
    }
}

Output:

  • processed-conditions List of processed conditions where the key is condition ID from the data JSON and the value is internal ID from the database.
  • processed-reports List of processed reports where the key is condition ID from the data JSON and the value is internal ID from the database.
History
  • Introduced in CFEngine 3.19.0, 3.18.1

Federated reporting configuration API

This API is used for configuring hubs so that a single hub can be used to report on any host connected to participating feeder hubs.

Remote hubs

Federated reporting must be enabled before it is possible to use the remote hubs API, please see the Enable hub for federated reporting section below.

Remote hubs list

URI: https://hub.cfengine.com/api/fr/remote-hub

Method: GET

Example response:

code
HTTP 200 OK
{
    "id-1": {
        "id": 1,
        "hostkey": "SHA=2d67a6840878de...",
        "api_url": "https://172.28.128.5",
        "ui_name": "ubuntu-xenial",
        "role": "feeder",
        "target_state": "on",
        "transport": {
            "mode": "pull_over_rsync",
            "ssh_user": "cfdrop",
            "ssh_host": "172.28.128.5",
            "ssh_pubkey": "",
            "ssh_fingerprint": ""
        }
    },
    "id-2": {
        "id": 2,
        "hostkey": "SHA=wefweg34tgfds...",
        "api_url": "https://172.28.128.6",
        "ui_name": "ubuntu-beaver",
        "role": "feeder",
        "target_state": "on",
        "transport": {
            "mode": "pull_over_rsync",
            "ssh_user": "cfdrop",
            "ssh_host": "superhub",
            "ssh_pubkey": "pubkey cfdrop",
            "ssh_fingerprint": null
        }
    }
}
Get remote hub

URI: https://hub.cfengine.com/api/fr/remote-hub/:remote_hub_id

Method: GET

Parameters:

  • remote_hub_id (number) Remote hub id

Example response:

code
HTTP 200 OK
{
    "id": 1,
    "hostkey": "SHA=2d67a6840878de098abbef1172f103a6febbfb5d00b8ace31ca3d46a9d22930d",
    "api_url": "https://172.28.128.5",
    "ui_name": "ubuntu-xenial",
    "role": "feeder",
    "target_state": "on",
    "transport": {
        "mode": "pull_over_rsync",
        "ssh_user": "cfdrop",
        "ssh_host": "172.28.128.5",
        "ssh_pubkey": "",
        "ssh_fingerprint": ""
    }
}
Add remote hub

URI: https://hub.cfengine.com/api/fr/remote-hub

Method: POST

Parameters:

  • ui_name (string) Remote hub name
  • hostkey (string) Remote hub hostkey
  • role (string) Remote hub role. Allowed values: feeder, superhub
  • target_state (string) Target state of remote hub. Allowed values: on, paused
  • transport (json) Transport data. Emp { "mode": "pull_over_rsync", "ssh_user": "cfdrop", "ssh_host": "172.28.128.5", "ssh_pubkey": "", "ssh_fingerprint": ""}

Example response:

code
HTTP 201 CREATED
Update remote hub

URI: https://hub.cfengine.com/api/fr/remote-hub/:remote_hub_id

Method: PUT

Parameters:

  • remote_hub_id (number) Remote hub id
  • ui_name (string) Remote hub name
  • hostkey (string) Remote hub hostkey
  • role (string) Remote hub role. Allowed values: feeder, superhub
  • target_state (string) Target state of remote hub. Allowed values: on, paused
  • transport (json) Transport data. Emp { "mode": "pull_over_rsync", "ssh_user": "cfdrop", "ssh_host": "172.28.128.5", "ssh_pubkey": "", "ssh_fingerprint": ""}

Example response:

code
HTTP 202 ACCEPTED
Delete remote hub

URI: https://hub.cfengine.com/api/fr/remote-hub/:remote_hub_id

Method: DELETE

Parameters:

  • remote_hub_id (number) Remote hub id

Example response:

code
HTTP 202 ACCEPTED
Enable hub for federated reporting
Enable hub as a superhub

URI: https://hub.cfengine.com/api/fr/setup-hub/superhub

Method: POST

Example response:

code
HTTP 202 ACCEPTED
Enable hub as a feeder

URI: https://hub.cfengine.com/api/fr/setup-hub/feeder

Method: POST

Example response:

code
HTTP 202 ACCEPTED
Hub status

URI: https://hub.cfengine.com/api/fr/hub-status

Method: GET

Example response:

code
{
    "configured": true,
    "role": "feeder",
    "enable_request_sent": true,
    "transport_ssh_public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFpTZhfubmkXONNReTAXA9v2eYo3xQ4GKcsB3J7i5arw root@ubuntu-xenial",
    "ssh_fingerprint": false,
    "target_state": "on"
}
Federation config

Federated reporting must be enabled before generating or removing federation configuration, please see Enable hub for federated reporting section above. Otherwise an error will be thrown and config file will not be created/deleted.

Generate federation config

URI: https://hub.cfengine.com/api/fr/federation-config

Method: POST

Example response:

code
HTTP 202 ACCEPTED
Delete federation config

URI: https://hub.cfengine.com/api/fr/federation-config

Method: DELETE

Example response:

code
HTTP 202 ACCEPTED

File changes API

File changes statistics

URI: https://hub.cfengine.com/api/file-changes/statistics?fromTime=:fromTime&toTime=:toTime

Method: GET

Get file changes statistics by period.

  • fromTime (timestamp) Include changes performed within interval. Format: YYYY-mm-dd HH:MM:SS
  • toTime (timestamp) Include changes performed within interval. Format: YYYY-mm-dd HH:MM:SS

Example request (curl):

code
curl -k --user <username>:<password> \
  -X GET \
  "https://hub.cfengine.com/api/file-changes/statistics?fromTime=2019-07-01%2008:56&toTime=2019-07-08%2023:56"
'

Example response:

code
{
    "data": {
        "DIFF": {
            "20 Sep 2019": 0,
            "21 Sep 2019": 0,
            "22 Sep 2019": 0,
            "23 Sep 2019": 0,
            "24 Sep 2019": 0,
            "25 Sep 2019": 0,
            "26 Sep 2019": 0,
            "27 Sep 2019": 23
        },
        "C": {
            "20 Sep 2019": 0,
            "21 Sep 2019": 0,
            "22 Sep 2019": 0,
            "23 Sep 2019": 0,
            "24 Sep 2019": 0,
            "25 Sep 2019": 0,
            "26 Sep 2019": 0,
            "27 Sep 2019": 33
        },
        "S": {
            "20 Sep 2019": 0,
            "21 Sep 2019": 0,
            "22 Sep 2019": 0,
            "23 Sep 2019": 0,
            "24 Sep 2019": 0,
            "25 Sep 2019": 0,
            "26 Sep 2019": 0,
            "27 Sep 2019": 225
        }
    },
    "labels": {
        "DIFF": "Change in content (with file diff)",
        "C": "Change in content (based on file hash)",
        "S": "Change in file stats"
    },
    "dates": [
        "20 Sep 2019",
        "21 Sep 2019",
        "22 Sep 2019",
        "23 Sep 2019",
        "24 Sep 2019",
        "25 Sep 2019",
        "26 Sep 2019",
        "27 Sep 2019"
    ]
}

Output:

  • DIFF Contains object with statistics of a change in content (with file diff), the object's key is change date and object's value is a number of changed files.
  • C Contains object with statistics of a change in content (based on file hash), the object's key is change date and object's value is a number of changed files.
  • S Contains object with statistics of a change in file stats, the object's key is change date and object's value is a number of changed files.
  • labels Labels of DIFF, C, S change types.
  • dates The array of selected dates.

Health diagnostic API

This API provides access to health diagnostic information.

Get health diagnostic status

URI: https://hub.cfengine.com/api/health-diagnostic/status

Method: GET

Example response:

code
{
    "hostsNeverCollected": 1,
    "hostNotRecentlyCollected": 0,
    "hostsUsingSameIdentity": 0,
    "agentNotRunRecently": 2,
    "lastAgentRunUnsuccessful": 0,
    "totalFailed": 3,
    "total": "50642"
}
List of health diagnostic report categories

URI: https://hub.cfengine.com/api/health-diagnostic/report_ids

Method: GET

Example response:

code
[
    "hostsNeverCollected",
    "notRecentlyCollected",
    "hostsUsingSameIdentity",
    "agentNotRunRecently",
    "lastAgentRunUnsuccessful"
]
Get health diagnostic report data

URI: https://hub.cfengine.com/api/health-diagnostic/report/:report_id

Method: POST

Execute user SQL query. Accepts SQL compatible with PostgreSQL database. Query is a subject to Role Base Access Control and will include data for hosts that issuing user have permissions to access. Read-only SQL is allowed.

API performance depend on the query result size, to achieve fastest results consider narrowing result set at much as possible.

Parameters:

  • report_id (string) Report id. List of report ids you can obtain through List of health diagnostic report categories
  • sortColumn (string) Column name on which to sort results. Optional parameter.
  • sortDescending (boolean) Sorting order. Optional parameter.
  • skip (integer) Number of results to skip for the processed query. The Mission Portal uses this for pagination. Optional parameter.
  • limit (integer) Limit the number of results in the query.
  • hostContextInclude (array) Includes only results that concern hosts which have all specified CFEngine contexts (class) set. Optional parameter.
  • hostContextExclude (array) Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at lest one of the specified contexts set will be excluded from the results. Optional parameter.

CURL Request Example: curl -k --user <username>:<password> -X POST \ https://hub.cfengine.com/api/health-diagnostic/report/agentNotRunRecently \ -H 'Content-Type: application/json' \ -d '{"limit": 50}'

Example response:

code
{
    "data": [
        {
            "header": [
                {
                    "columnName": "key",
                    "columnType": "STRING"
                },
                {
                    "columnName": "Host name",
                    "columnType": "STRING"
                },
                {
                    "columnName": "Last report collected",
                    "columnType": "STRING"
                },
                {
                    "columnName": "Last agent local execution time",
                    "columnType": "STRING"
                }
            ],
            "query": "SELECT h.Hostkey as key,h.hostname as \"Host name\", lastreporttimestamp as \"Last report collected\", agentstatus.lastagentlocalexecutiontimestamp as \"Last agent local execution time\"  \n                            FROM vm_hosts h \n                            LEFT JOIN agentstatus  ON agentstatus.Hostkey = h.Hostkey WHERE h.HostKey IN (SELECT result.hostkey FROM (SELECT agentstatus.HostKey \n                      FROM agentstatus \n                      LEFT JOIN vm_hosts ON vm_hosts.hostkey = agentstatus.hostkey\n                      WHERE  extract(epoch from (lastReportTimeStamp::timestamp - lastagentlocalexecutiontimestamp::timestamp)) > agentexecutioninterval::int  * 1.3) AS result \n                      WHERE hostkey IS NOT NULL  AND HostKey NOT IN (SELECT hostkey FROM hosts_not_reported) AND HostKey NOT IN (SELECT Hosts_view.HostKey \n                      FROM vm_hosts Hosts_view \n                      WHERE Hosts_view.lastreporttimestamp < to_timestamp('1549559891')) AND HostKey NOT IN (SELECT SameHosts.HostKey \n                      FROM (\n                          SELECT remotehostkey as HostKey FROM lastseenhostslogs GROUP BY remotehostkey HAVING COUNT(distinct remotehostip) > 1\n                          ) AS SameHosts))",
            "queryTimeMs": 1408,
            "rowCount": 2,
            "rows": [
                [
                    "SHA=aasdsfdgddswrdfgddfdfgwerdffb86",
                    "SHA=aasdsfdgddswrdfgddfdfgwerdffb86",
                    "2019-02-27 15:16:52.987126+00",
                    "2019-02-27 15:05:56.567979+00"
                ],
                [
                    "SHA=fe7f992547addc96fe167bacd6de37681c188709ce9f01fb995f03124ef2a934",
                    "vagrant-ubuntu-trusty-64",
                    "2019-03-05 10:26:08+00",
                    "2019-03-04 08:38:30+00"
                ]
            ]
        }
    ],
    "meta": {
        "count": 1,
        "page": 1,
        "timestamp": 1551782115,
        "total": 1
    }
}
List of health diagnostic dismissed hosts

URI: https://hub.cfengine.com/api/health-diagnostic/dismiss/:report_id

Method: GET

Parameters

  • report_id (string) Report id. List of report ids you can obtain through List of health diagnostic report categories
  • offset (integer) Number of results to skip for the processed query.
  • limit (integer) Limit the number of results in the query.

CURL Request Example: curl -k --user <username>:<password> -X GET \ https://hub.cfengine.com/api/health-diagnostic/dismiss/notRecentlyCollected?limit=3&offset=0

Example response:

code
{
    "data": [
        {
            "header": [
                {
                    "columnName": "hostkey",
                    "columnType": "STRING"
                },
                {
                    "columnName": "hostname",
                    "columnType": "STRING"
                },
                {
                    "columnName": "ipaddress",
                    "columnType": "STRING"
                },
                {
                    "columnName": "lastreporttimestamp",
                    "columnType": "STRING"
                },
                {
                    "columnName": "firstreporttimestamp",
                    "columnType": "STRING"
                }
            ],
            "query": "SELECT * FROM m_hosts WHERE hostkey IN (SELECT hostkey FROM health_diagnostics_dismissed WHERE report_type = 'notRecentlyCollected' AND username = 'admin')",
            "queryTimeMs": 26,
            "rowCount": 50,
            "rows": [
                [
                    "SHA=aasdsfdgddswrdfgddfdfgdffb8922",
                    "SHA=aasdsfdgddswrdfgddfdfgdffb8922",
                    null,
                    "2019-02-27 10:32:12.813777+00",
                    "2019-02-27 10:32:12.813777+00"
                ],
                [
                    "SHA=aasdsfdgddswrdfgddfdfgdffb8930",
                    "SHA=aasdsfdgddswrdfgddfdfgdffb8930",
                    null,
                    "2019-02-27 10:32:12.813777+00",
                    "2019-02-27 10:32:12.813777+00"
                ],
                [
                    "SHA=aasdsfdgddswrdfgddfdfgdffb8925",
                    "SHA=aasdsfdgddswrdfgddfdfgdffb8925",
                    null,
                    "2019-02-27 10:32:12.813777+00",
                    "2019-02-27 10:32:12.813777+00"
                ]
            ]
        }
    ],
    "meta": {
        "count": 1,
        "page": 1,
        "timestamp": 1553087363,
        "total": 1
    }
}
Dismiss hosts from health diagnostic

URI: https://hub.cfengine.com/api/health-diagnostic/dismiss/:report_id

Method: POST

Parameters

CURL Request Example: curl -k --user admin:admin -X POST \ https://hub.cfengine.com/api/health-diagnostic/dismiss/notRecentlyCollected \ -H 'Content-Type: application/json' \ -d '{"hosts": ["SHA=aasdsfdgddswrdfgddfdfgwerdffb86", "SHA=fe7f992547addc96fe167bacd6de37681c188709ce9f01fb995f03124ef2a934"]}'

Example response:

code
HTTP 201 CREATED
Remove hosts from dismissed list

URI: https://hub.cfengine.com/api/health-diagnostic/dismiss/:report_id

Method: DELETE

Parameters

CURL Request Example: curl -k --user admin:admin -X POST \ https://hub.cfengine.com/api/health-diagnostic/dismiss/notRecentlyCollected \ -H 'Content-Type: application/json' \ -d '{"hosts": ["SHA=aasdsfdgddswrdfgddfdfgwerdffb86", "SHA=fe7f992547addc96fe167bacd6de37681c188709ce9f01fb995f03124ef2a934"]}'

Example response:

code
HTTP 202 ACCEPTED

Host REST API

Host API allows to access host specific information.

List hosts

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

Method: GET

Parameters:

  • context-include (comma delimited string of regular expression strings) Includes hosts having context matching the expression.
  • context-exclude (comma delimited string of regular expression strings) Excludes hosts having context matching the expression.
  • page (integer) Number of the page with results. By default 1.
  • count (integer) Size of the page. By default 50 results.

Example response:

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

Output:

  • id Unique host identifier.
  • hostname Host name. Can be reconfigured globally to represent variable set in the policy using hostIdentifier setting.
  • ip IP address of the host. If host have multiple network interfaces, IP belongs to the interface that is used to communicate with policy server.
  • lastreport Time of receiving last report from the client, successfully. Represented as UNIX TIMESTAMP.
  • firstseen Time of receiving the first status report from the client. It is equivalent to the time when the client have been bootstrapped to the server for the first time. Represented as UNIX TIMESTAMP.

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:

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

Output:

  • id Unique host identifier.
  • hostname Host name. Can be reconfigured globally to represent variable set in the policy using hostIdentifier setting.
  • ip IP address of the host. If host have multiple network interfaces, IP belongs to the interface that is used to communicate with policy server.
  • lastreport Time of receiving last report from the client, successfully. Represented as UNIX TIMESTAMP.
  • firstseen Time of receiving the first status report from the client. It is equivalent to the time when the client have been bootstrapped to the server for the first time. Represented as UNIX TIMESTAMP.
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.

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), the main thread of cf-hub will pick up the deletion job. The hostkey is then removed from:

  • "Last seen" database, which contains network connection info (/var/cfengine/state/cf_lastseen.lmdb).
  • Public key directory, containing cryptographic keys exchaned during bootstrap (/var/cfengine/ppkeys).
  • The previously mentioned KeysPendingForDeletion table.

Note: There is a record of the host retained that includes the time when the host was deleted and this record also prevents further collection from this host identity.

See also: Example removing host data

Hosts list grouped by hard classes

URI: https://hub.cfengine.com/api/hosts/by-class

Method: GET

Parameters:

  • context-include (comma delimited string of regular expression strings)
  • format (string) Output format. Default value is json. Allowed values: json, yaml.
  • withInventory (boolean) Include inventory data to the API response. Default value is false. Allowed values: true, false
  • inventoryFile (boolean) Make hosts' children values objects which aligns with Ansible inventory that is sourced from a file (so this format is appropriate for caching responses), by default when inventoryFile is false, the output format aligns with Ansible inventory sourced from a script. Default value is false. Allowed values: true, false

CURL unfiltered request example

code
curl -k --user admin:admin -X GET https://hub.example.com/api/hosts/by-class

Example response:

code
{
    "10_0_2_15": {
            "hosts": [
                "ubuntu-xenial"
            ]
    },
    "127_0_0_1": {
            "hosts": [
                "ubuntu-xenial"
            ]
    },
    "ubuntu_16": {
            "hosts": [
                "ubuntu-xenial"
            ]
    }
}

inventoryFile=true

code
curl -k --user admin:admin -X GET https://hub.example.com/api/hosts/by-class?inventoryFile=true

Example response:

code
{
    "10_0_2_15": {
            "hosts": [
                "ubuntu-xenial": {}
            ]
    },
    "127_0_0_1": {
            "hosts": [
                "ubuntu-xenial": {}
            ]
    },
    "ubuntu_16": {
            "hosts": [
                "ubuntu-xenial": {}
            ]
    }
}

CURL request with inventory data example

code
curl -k --user admin:admin -X GET https://hub.example.com/api/hosts/by-class?withInventory=true

Example response:

code
{
    "_meta": {
        "hostvars": {
            "ubuntu-xenial": {
                "CFEngine Inventory": {
                    "OS": "Ubuntu 16.04.6 LTS",
                    "OS type": "linux",
                    "Timezone": "UTC"
                }
            }
        }
    },
    "10_0_2_15": {
            "hosts": [
                "ubuntu-xenial"
            ]
    },
    "127_0_0_1": {
            "hosts": [
                "ubuntu-xenial"
            ]
    },
    "ubuntu_16": {
            "hosts": [
                "ubuntu-xenial"
            ]
    }
}
Get deleted hosts list

URI: https://hub.cfengine.com/api/hosts/deleted

Method: GET

Parameters:

  • skip (integer) Number of results to skip for the processed query. Optional parameter.
  • limit (integer) Limit the number of results in the query. No limit when parameter is not set. Optional parameter.

Example request (curl): curl -k --user admin:admin -X GET https://hub.example.com/api/hosts/deleted Example response:

code
HTTP 200 Ok
{
    "data": [
        {
            "hostkey": "SHA=2123f85b38189008ae12be159fb961584dda1249c94efed43fec2c70f233975d",
            "iscallcollected": false,
            "lastreporttimestamp": "2017-02-17 18:00:17+00",
            "firstreporttimestamp": "2017-01-09 17:35:35.427063+00",
            "hostkeycollisions": 0,
            "deleted": "2021-08-19 09:20:02.752463+00",
            "ipaddress": "10.0.2.15"
        }
    ],
    "meta": {
        "total": 1,
        "page": 1,
        "count": 1,
        "timestamp": 1629365174
    }
}
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:

code
{
  "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:

  • id Unique vital identifier.
  • timestamp Last measurement time. Represented as UNIX TIMESTAMP.
  • description Vital short description.
  • units Units for the samples.

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:

  • from (integer) Timestamp marking the start of the interval for which to fetch data. Data is only available going back one week.
  • to (integer) End of data interval to be fetched.

Example response:

code
{
  "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:

  • id ID of vital sign.
  • description Description of vital sign.
  • units Measurement unit of vital sign.
  • timestamp Timestamp of the last received data point.
  • values Vital sign data. (array of [ t, y ], where t is the sample timestamp)

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:

  • from (string) Timestamp marking the start of the interval for which to fetch data. Emp: 2017-11-28
  • to (string) End of data interval to be fetched. Emp: 2017-12-28
  • period (string) Group data by period. Allowed values: 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:

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

Output:

  • period Period of grouping the data. Allowed values: day, week, month, year.
  • date The date of statistic.
  • count The bootstrapped hosts to the hub count.
History
  • inventoryFile=true parameter added in CFEngine 3.19.0, 3.18.1

Inventory API

Inventory API allows to access inventory reports and attributes dictionary.

Inventory reports

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

Method: POST

Parameters:

  • select (array) Fields for selecting. Required parameter.

    List of fields name you can obtain through List of inventory attributes call described below. Extra attributes are hostkey for selecting host key and resultCount for selecting rows count.

  • filter (json object) Optionally filter data. You can use array values for multiple filter, the logic will be AND. Format is

    code
    {
      "Attribute name":{
        "operator":["value","value1"],
        "operator2":"value2",
        "operator4":"value2"
      }
    }
    

    Operators:

    For filtering you can use the operators below:

    Operator
    <
    >
    =
    !=
    <=
    >=
    matches
    not_match
    contains
    not_contain
    regex_matches
    regex_not_match
    is_reported
    is_not_reported
  • sort (string) Field name for sorting with "-" for DESC order. Optional parameter.

  • start (integer) Number of results to start from. Optional parameter.

  • limit (integer) Limit the number of results in the query. Default value is 1000, max value is 10000.

  • hostContextExclude (array) Includes only results that concern hosts which have all specified CFEngine contexts (class) set. Optional parameter.

  • hostContextInclude (array) Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at least one of the specified contexts set will be excluded from the results. Optional parameter.

code
curl -k --user <username>:<password> \
  -X POST \
  https://hub.cfengine.com/api/inventory \
  -H 'content-type: application/json' \
  -d '{
        "sort":"Host name",
        "filter":{
           "Host name":{
              "matches":["value1","value"],
              "not_contain":"value2"
           }
        },
        "select":[
           "Host name",
           "OS type",
           "IPv4 addresses",
           "CFEngine version",
           "Ports listening"
        ],
        "hostContextExclude":[
           "policy_server"
        ]
      }
'

Example Request Body:

code
{
   "sort":"Host name",
   "filter":{
      "Host name":{
         "matches":"value1",
         "=":"value2"
      }
   },
   "select":[
      "Host name",
      "OS type",
      "IPv4 addresses",
      "CFEngine version",
      "Ports listening"
   ],
   "hostContextExclude":[
      "policy_server"
   ]
}

Example response:

code
{
  "data": [
    {
      "header": [
        {
          "columnName": "Host name",
          "columnType": "STRING"
        },
        {
          "columnName": "OS type",
          "columnType": "STRING"
        },
        {
          "columnName": "IPv4 addresses",
          "columnType": "STRING"
        },
        {
          "columnName": "CFEngine version",
          "columnType": "STRING"
        },
        {
          "columnName": "Ports listening",
          "columnType": "STRING"
        }
      ],
      "queryTimeMs": 30,
      "rowCount": 2,
      "rows": [
        [
          "host1.cfengine.com",
          "linux",
          "128.30.23.33",
          "3.10.0",
          "22, 25, 80, 443, 5308, 9000"
        ],
        [
          "host2.cfengine.com",
          "linux",
          "184.45.1.75",
          "3.10.0",
          null
        ]
      ]
    }
  ],
  "meta": {
    "count": 1,
    "page": 1,
    "timestamp": 1496222472,
    "total": 1
  }
}
List of inventory attributes

URI: https://hub.cfengine.com/api/inventory/attributes-dictionary

Method: GET

Shows list of all inventory attributes available in the system.

See more details: * Custom inventory

CURL request example curl -k --user admin:admin -X GET https://hub.cfengine.com/api/inventory/attributes-dictionary

Example response:

code
[
  {
    "id": 2,
    "attribute_name": "BIOS vendor",
    "category": "Hardware",
    "readonly": 1,
    "type": "string",
    "convert_function": null,
    "keyname": "default.cfe_autorun_inventory_dmidecode.dmi[bios-vendor]"
  },
  {
    "id": 3,
    "attribute_name": "BIOS version",
    "category": "Hardware",
    "readonly": 1,
    "type": "string",
    "convert_function": null,
    "keyname": "default.cfe_autorun_inventory_dmidecode.dmi[bios-version]"
  }
]
Edit inventory attribute

URI: https://hub.cfengine.com/api/inventory/attributes-dictionary/:id

Method: PATCH

Set inventory attribute type (int/string..). This is needed for applying filtering in correct format. Only readonly - 0 attribute can be edited

Parameters:

  • id (integer) Attribute Id
  • category (string) Category of attribute
  • type (string) Attribute's type. Allowed values: int, real, slist, string
  • convert_function (string) Convert Function. Emp.: cf_clearSlist - to transform string like {"1", "2"} to 1, 2

CURL request example curl -k --user admin:admin -X PATCH https://hub.cfengine.com/api/inventory/attributes-dictionary/260 -H 'content-type: application/json' -d '{ "category":"Hardware", "type": "int" }'

Example Request Body:

code
{
 "category":"Hardware",
 "type": "int"
}

Example response:

code
{
  "id": 1,
  "attribute_name": "Architecture",
  "category": "Hardware",
  "readonly": 0,
  "type": "slist",
  "convert_function": "cf_clearSlist"
}

LDAP authentication API

LDAP authentication API allows to check ldap user credentials and change LDAP settings.

Login

URI: https://hub.cfengine.com/ldap/login

Method: POST

Parameters:

  • username (string) Username from LDAP
  • password (string) User password

Example response:

code
HTTP 200 Ok
{
    "success": true,
    "message": "You are successfully authenticated"
}
Get settings

URI: https://hub.cfengine.com/ldap/settings

Method: GET

Headers:

  • Authorization: api_token (string) Set token to access api. To get the token please look at - /var/cfengine/httpd/htdocs/ldap/config/settings.php

Example response:

code
HTTP 200 Ok
{
    "success": true,
    "data": {
        "domain_controller": "local.loc",
        "base_dn": "DC=local,DC=loc",
        "login_attribute": "cn",
        "port": 365,
        "use_ssl": false,
        "use_tls": false,
        "timeout": 5,
        "admin_username": "cn=admin,DC=local,DC=loc",
        "admin_password": "Password is set"
    }
}

Output:

  • domain_controller The domain controllers option is server name located on your network that serve Active Directory.
  • base_dn The base distinguished name is the base distinguished name you'd like to perform operations on. An example base DN would be DC=corp,DC=acme,DC=org.
  • login_attribute Login attribute like cn or uid
  • group_attribute Group attribute (e.g. memberOf in Active Directory). Required for LDAP roles syncing with internal roles.
  • port The port option is used for authenticating and binding to your AD server. The default ports are already used for non SSL and SSL connections (389 and 636).
  • use_ssl Use ssl for connection
  • use_tls Use tls for connection
  • timeout The timeout option allows you to configure the amount of seconds to wait until your application receives a response from your LDAP server.
  • admin_username LDAP admin distinguished name. Emp.: cn=admin,dc=jumpcloud,dc=com
  • admin_password LDAP admin password.
Update settings

URI: https://hub.cfengine.com/ldap/settings

Method: PATCH

Note that the PATCH HTTP method only requires partial JSON for an update. Such as {"port":3269} instead of the entire set of parameters.

Headers:

  • Authorization: api_token (string) Set token to access api. To get the token please look at - /var/cfengine/httpd/htdocs/ldap/config/settings.php

  • Content-Type: application/json (string) Content-Type must be application/json for the API to parse JSON provided.

Parameters:

  • domain_controller (string) The domain controllers option is server name located on your network that serve Active Directory.
  • base_dn (string) The base distinguished name is the base distinguished name you'd like to perform operations on. An example base DN would be DC=corp,DC=acme,DC=org.
  • login_attribute (string) Login attribute like cn or uid
  • port (integer) The port option is used for authenticating and binding to your AD server. The default ports are already used for non SSL and SSL connections (389 and 636). Optional parameter.
  • use_ssl (boolean) Use ssl for connection. Optional parameter.
  • use_tls (boolean) Use tls for connection. Optional parameter.
  • timeout (integer) The timeout option allows you to configure the amount of seconds to wait until your application receives a response from your LDAP server. Optional parameter.
  • admin_username LDAP admin distinguished name. Emp.: cn=admin,dc=jumpcloud,dc=com
  • admin_password LDAP admin password.

Example response:

code
HTTP 200 Ok
{
    "success": true,
    "message": "Settings successfully saved."
}

Query REST API

In case of a need for full flexibility, Query API allow users to execute SQL queries on CFEngine Database.

Database schema available can be found here.

Execute SQL query

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

Method: POST

Execute user SQL query. Accepts SQL compatible with PostgreSQL database. Query is a subject to Role Base Access Control and will include data for hosts that issuing user have permissions to access. Read-only SQL is allowed.

API performance depend on the query result size, to achieve fastest results consider narrowing result set at much as possible.

Parameters:

  • query (string) SQL query string.
  • sortColumn (string) Column name on which to sort results. Optional parameter.
  • sortDescending (boolean) Sorting order. Optional parameter.
  • skip (integer) Number of results to skip for the processed query. The Mission Portal uses this for pagination. Optional parameter.
  • limit (integer) Limit the number of results in the query.
  • hostContextInclude (array) Includes only results that concern hosts which have all specified CFEngine contexts (class) set. Optional parameter.
  • hostContextExclude (array) Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at lest one of the specified contexts set will be excluded from the results. Optional parameter.

Example Request Body:

code
{
  "query": "select hostname, ipaddress from hosts",
  "limit": 2,
  "hostContextExclude": ["policy_server"]
}

Example response:

code
{
  "data": [
    {
      "header": [
        {
          "columnName": "hostname",
          "columnType": "STRING"
        },
        {
          "columnName": "ipaddress",
          "columnType": "STRING"
        }
      ],
      "query": "select hostname, ipaddress from hosts",
      "queryTimeMs": 152,
      "rowCount": 1001,
      "rows": [
        [
          "ab84e58e4287",
          "172.17.16.251"
        ],
        [
          "293b3c9647fb",
          "172.17.16.6"
        ]
      ]
    }
  ],
  "meta": {
    "count": 1,
    "page": 1,
    "timestamp": 1437051092,
    "total": 1
  }
}

Example usage: Synchronous Example: Listing hostname and IP for Ubuntu hosts

Schedule SQL query as long running job

URI: https://hub.cfengine.com/api/query/async

Method: POST

Execute user SQL query as a async job. Result is available as file to download within specified format after job is finished.

Accepts SQL compatible with PostgreSQL database. Query is a subject to Role Base Access Control and will include data for hosts that issuing user have permissions to access. Read-only SQL is allowed.

Returns JOB ID which can be used to check query status and get query results.

API returns entire query result. Make sure that result size is sensible.

Parameters:

  • query (string) SQL query string.
  • outputType (string) Supported types: 'csv' (default). Optional parameter.
  • hostContextInclude (array) Includes only results that concern hosts which have all specified CFEngine contexts (class) set. Optional parameter.
  • hostContextExclude (array) Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at lest one of the specified contexts set will be excluded from the results. Optional parameter.

Example Request Body:

code
{
  "query": "select hostname, ipaddress from hosts",
  "outputType": "csv",
  "hostContextExclude": "policy_server"
}

Example response:

code
{
  "data": [
    {
      "id": "7b7de87ade18f337d62df26881ff39b1",
      "query": "select hostname, ipaddress from hosts limit 10"
    }
  ],
  "meta": {
    "count": 1,
    "page": 1,
    "timestamp": 1437054235,
    "total": 1
  }
}

Value of ID field is a unique job identifier that can be used to check job status and retrieve query results.

Check async query status

URI: https://hub.cfengine.com/api/query/async/:id

Method: GET

Check the status of async scheduled job. When the query is finished it will return a URI to file available to download as a href field in the response.

Example response:

code
{
  "data": [
    {
      "href": "https://hub.cfengine.com/api/static/7b7de87ade18f337d62df26881ff39b1.csv",
      "id": "7b7de87ade18f337d62df26881ff39b1",
      "percentageComplete": 100
    }
  ],
  "meta": {
    "count": 1,
    "page": 1,
    "timestamp": 1437054427,
    "total": 1
  }
}
Cancel async query

URI: https://hub.cfengine.com/api/query/async/:id

Method: DELETE


SQL schema

CFEngine Enterprise uses multiple databases.

  • cfdb - Database containing information that hosts report.
  • cfsettings - Database containing settings used by Mission Portal APIs, no reported data.
  • cfmp - Database containing Mission Portal related settings not processed by API.

cfdb

CFEngine allows standardized SQL SELECT queries to be used with REST API. Queries can be used with following database schema.

code
curl -k --user admin:admin https://hub.cfengine.com/api/query -X POST -d "{ \"query\": \"SELECT Hosts.HostName, Hosts.IPAddress FROM Hosts WHERE hostname = 'hub'\"}"
Table: AgentStatus

Agent status contains information about last cf-agent execution.

Columns:

  • HostKey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • AgentExecutionInterval (integer) Estimated interval in which cf-agent is being executed, as cf-agent execution interval is expressed in CFEngine context expressions (Min00_05 etc.) it can be not regular, this interval is discovered by analyzing last few cf-agent execution timestamps. Expressed in seconds.

  • LastAgentLocalExecutionTimeStamp (timestamp) Timestamp of last cf-agent execution on the host.

  • LastAgentExecutionStatus (OK/FAIL) cf-agent execution status. In case cf-agent will not execute within 3x AgentExecutionInterval from last execution, status will be set to FAIL. Failure may indicate cf-execd issues, or cf-agent crashes.

Example query:

code
SELECT hostkey,
       agentexecutioninterval,
       lastagentlocalexecutiontimestamp,
       lastagentexecutionstatus
FROM   agentstatus;

Output:

code
-[ RECORD 1 ]--------------------|-----------------------
hostkey                          | SHA=3b94d...
agentexecutioninterval           | 277
lastagentlocalexecutiontimestamp | 2015-03-11 12:37:39+00
lastagentexecutionstatus         | OK
-[ RECORD 2 ]--------------------|-----------------------
hostkey                          | SHA=a4dd5...
agentexecutioninterval           | 275
lastagentlocalexecutiontimestamp | 2015-03-11 12:36:36+00
lastagentexecutionstatus         | OK
-[ RECORD 3 ]--------------------|-----------------------
hostkey                          | SHA=2aab8...
agentexecutioninterval           | 284
lastagentlocalexecutiontimestamp | 2015-03-11 12:36:51+00
lastagentexecutionstatus         | OK
Table: BenchmarksLog

Data from internal cf-agent monitoring as also measurements promises.

Columns:

  • HostKey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • EventName (text) Name of measured event.

  • StandardDeviation (numeric) Dispersion of a set of data from its mean.

  • AverageValue (numeric) Average value.

  • LastValue (numeric) Last measured value.

  • CheckTimeStamp (timestamp) Measurement time.

Example query:

code
SELECT hostkey,
       eventname,
       standarddeviation,
       averagevalue,
       lastvalue,
       checktimestamp
FROM   benchmarkslog;

Output:

code
-[ RECORD 1 ]-----|--------------------------------------------------------
hostkey           | SHA=3b94d...
eventname         | CFEngine Execution ('/var/cfengine/inputs/promises.cf')
standarddeviation | 7.659365
averagevalue      | 3.569665
lastvalue         | 1.170841
checktimestamp    | 2015-03-10 14:08:12+00
-[ RECORD 2 ]---=-|--------------------------------------------------------
hostkey           | SHA=3b94d...
eventname         | CFEngine Execution ('/var/cfengine/inputs/update.cf')
standarddeviation | 0.131094
averagevalue      | 0.422757
lastvalue         | 0.370686
checktimestamp    | 2015-03-10 14:08:11+00
-[ RECORD 3 ]-----|--------------------------------------------------------
hostkey           | SHA=3b94d...
eventname         | DBReportCollectAll
standarddeviation | 0.041025
averagevalue      | 1.001964
lastvalue         | 1.002346
checktimestamp    | 2015-03-10 14:05:20+00
Table: Contexts

CFEngine contexts present on hosts at their last reported cf-agent execution.

Columns:

  • HostKey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • ContextName (text) CFEngine context set by cf-agent.

  • MetaTags (text[]) List of meta tags set for the context.

  • ChangeTimeStamp (timestamp) Timestamp since when context is set in its current form. Note: If any of the context attributes change, the timestamp will be updated.

Example query:

code
SELECT hostkey,
       contextname,
       metatags,
       changetimestamp
FROM   contexts;

Output:

code
-[ RECORD 1 ]---|-------------------------------------------------------
hostkey         | SHA=a4dd5...
contextname     | enterprise_3_6_5
metatags        | {inventory,attribute_name=none,source=agent,hardclass}
changetimestamp | 2015-03-11 09:50:11+00
-[ RECORD 2 ]---|-------------------------------------------------------
hostkey         | SHA=a4dd5...
contextname     | production
metatags        | {report,"Production environment"}
changetimestamp | 2015-03-11 09:50:11+00
-[ RECORD 3 ]---|-------------------------------------------------------
hostkey         | SHA=a4dd5...
contextname     | enterprise_edition
metatags        | {inventory,attribute_name=none,source=agent,hardclass}
changetimestamp | 2015-03-11 09:50:11+00
Table: ContextsLog

CFEngine contexts set on hosts by CFEngine over period of time.

Columns:

  • HostKey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • ChangeTimeStamp (timestamp) Timestamp since when context is set in its current form. Note: The statement if true till present time or newer entry claims otherwise.

  • ChangeOperation (ADD,CHANGE,REMOVE,UNTRACKED) CFEngine uses incremental diffs to report it's state. ChangeOperation is a diff state describing current entry.

    • ADD - stands for introducing a new entry which did not exist before. In this case, new CFEngine context have been introduced.
    • CHANGE - stands for changing value or attribute such as MetaTags have changed.
    • REMOVE - Context have not been set.
    • UNTRACKED - CFEngine provides a mechanism for filtering unwanted data from being reported. UNTRACKED marker states that information about this context is being filtered and will not report any future information about it.
  • ContextName (text) CFEngine context set by cf-agent.

  • MetaTags (text[]) List of meta tags set for the context.

Example query:

code
SELECT hostkey,
       changetimestamp,
       changeoperation,
       contextname,
       metatags
FROM   contextslog;

Output:

code
-[ RECORD 1 ]---|-------------------------------------------------------
hostkey         | SHA=a4dd5...
changetimestamp | 2015-03-10 13:40:20+00
changeoperation | ADD
contextname     | debian
metatags        | {inventory,attribute_name=none,source=agent,hardclass}
-[ RECORD 2 ]---|-------------------------------------------------------
hostkey         | SHA=a4dd5...
changetimestamp | 2015-03-10 14:40:20+00
changeoperation | ADD
contextname     | ipv4_192_168
metatags        | {inventory,attribute_name=none,source=agent,hardclass}
-[ RECORD 3 ]---|-------------------------------------------------------
hostkey         | SHA=a4dd5...
changetimestamp | 2015-03-10 15:40:20+00
changeoperation | ADD
contextname     | nova_3_6_5
metatags        | {inventory,attribute_name=none,source=agent,hardclass}
Table: FileChangesLog

Log of changes detected to files that are set to be monitored by cf-agent.

Columns:

  • HostKey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • PromiseHandle (text) A Uniqueue id-tag string for referring promise.

  • FileName (text) Name of the file that have changed.

  • ChangeTimeStamp (timestamp) Timestamp when CFEngine have detected the change to the file.

  • ChangeType (text) Type of change detected on the monitored file.

    • DIFF - change in content (with file diff)
    • S - change in file stats
    • C - change in content (based on file hash)
  • ChangeDetails (text[]) Information about changes detected to the file. Such as file stats information, file diff etc.

Example query:

code
SELECT hostkey,
       promisehandle,
       filename,
       changetimestamp,
       changetype,
       changedetails
FROM   filechangeslog;

Output:

code
-[ RECORD 1 ]---|------------------------------------------------------------
hostkey         | SHA=3b94d...
promisehandle   | my_test_promise
filename        | /tmp/app.conf
changetimestamp | 2015-03-13 13:16:10+00
changetype      | C
changedetails   | {"Content changed"}
-[ RECORD 2 ]---|------------------------------------------------------------
hostkey         | SHA=3b94d...
promisehandle   | my_test_promise
filename        | /tmp/app.conf
changetimestamp | 2015-03-13 13:16:10+00
changetype      | DIFF
changedetails   | {"-,1,loglevel = info","+,1,loglevel = debug"}
-[ RECORD 3 ]---|------------------------------------------------------------
hostkey         | SHA=3b94d...
promisehandle   | my_test_promise
filename        | /tmp/app.conf
changetimestamp | 2015-03-09 11:46:36+00
changetype      | S
changedetails   | {"Modified time: Mon Mar 9 11:37:50 -> Mon Mar 9 11:42:27"}
Table: Hosts

Hosts table contains basic information about hosts managed by CFEngine.

Columns:

  • HostKey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • HostName (text) Host name locally detected on the host, configurable as hostIdentifier option in Settings API and Mission Portal settings UI.

  • IPAddress (text) IP address of the host derived from the lastseen database (this is expected to be the IP address from which connections come from, beware NAT will cause multiple hosts to appear to have the same IP address).

  • LastReportTimeStamp (timestamp) Timestamp of the most recent successful report collection.

  • FirstReportTimeStamp (timestamp) Timestamp when the host reported to the hub for the first time, which indicate when the host was bootstrapped to the hub.

Example query:

code
SELECT hostkey,
       hostname,
       ipaddress,
       lastreporttimestamp,
       firstreporttimestamp
FROM   hosts;

Output:

code
-[ RECORD 1 ]--------|-----------------------
hostkey              | SHA=a4dd...
hostname             | host001
ipaddress            | 192.168.56.151
lastreporttimestamp  | 2015-03-10 14:20:20+00
firstreporttimestamp | 2015-03-10 13:40:20+00
-[ RECORD 2 ]--------|-----------------------
hostkey              | SHA=3b94...
hostname             | hub
ipaddress            | 192.168.56.65
lastreporttimestamp  | 2015-03-10 14:20:20+00
firstreporttimestamp | 2015-03-10 13:34:20+00
-[ RECORD 3 ]--------|-----------------------
hostkey              | SHA=2aab...
hostname             | host002
ipaddress            | 192.168.56.152
lastreporttimestamp  | 2015-03-10 14:20:20+00
firstreporttimestamp | 2015-03-10 13:40:20+00
Table: Hosts_not_reported

Hosts_not_reported table contains information about not reported hosts.

Columns:

  • HostKey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • iscallcollected (boolean) Is host call collected

  • LastReportTimeStamp (timestamp) Timestamp of the most recent successful report collection.

  • FirstReportTimeStamp (timestamp) Timestamp when the host reported to the hub for the first time, which indicate when the host was bootstrapped to the hub.

Example query:

code
SELECT hostkey,
       iscallcollected,
       lastreporttimestamp,
       firstreporttimestamp
FROM   hosts;

Output:

code
-[ RECORD 1 ]--------|-----------------------
hostkey              | SHA=a4dd...
iscallcollected      | t
lastreporttimestamp  | 2015-03-10 14:20:20+00
firstreporttimestamp | 2015-03-10 13:40:20+00
-[ RECORD 2 ]--------|-----------------------
hostkey              | SHA=3b94...
iscallcollected      | f
lastreporttimestamp  | 2015-03-10 14:20:20+00
firstreporttimestamp | 2015-03-10 13:34:20+00
-[ RECORD 3 ]--------|-----------------------
hostkey              | SHA=2aab...
iscallcollected      | f
lastreporttimestamp  | 2015-03-10 14:20:20+00
firstreporttimestamp | 2015-03-10 13:40:20+00
Table: HubConnectionErrors

Networking errors encountered by cf-hub during its operation.

Columns:

  • HostKey (text) Unique identifier of the host that cf-hub was connecting to.

  • CheckTimeStamp (timestamp) Timestamp when the error occurred.

  • Message (text) Error type / message.

  • QueryType (text) Type of query that was intended to be sent by hub during failed connection attempt.

Example query:

code
SELECT hostkey,
       checktimestamp,
       message,
       querytype,
FROM   hubconnectionErrors;

Output:

code
-[ RECORD 1 ]--|--------------------------
hostkey        | SHA=3b94d...
checktimestamp | 2015-03-13 13:16:10+00
message        | ServerNoReply
querytype      | delta
-[ RECORD 2 ]--|--------------------------
hostkey        | SHA=3b94d...
checktimestamp | 2015-03-13 14:16:10+00
message        | InvalidData
querytype      | rebase
-[ RECORD 3 ]--|--------------------------
hostkey        | SHA=3b94d...
checktimestamp | 2015-03-13 15:16:10+00
message        | ServerAuthenticationError
querytype      | delta
Table: Inventory

Inventory data

Columns:

  • HostKey (text) Unique identifier of the host.

  • keyname (text) Name of the key.

  • type (text) Type of the variable. List of supported variable types.

  • metatags (text[]) List of meta tags set for the variable.

  • value (text) Variable value serialized to string. * List types such as: slist, ilist, rlist are serialized with CFEngine list format: {'value','value'}. * Data type is serialized as JSON string.

Example query:

code
SELECT hostkey,
       keyname,
       type,
       metatags,
       value
FROM   Inventory;

Output:

code
-[ RECORD 1 ]--|--------------------------
hostkey        | SHA=3b94d...
keyname        | default.sys.fqhost
type           | string
metatags       | {inventory,source=agent,"attribute_name=Host name"}
value          | host name
-[ RECORD 2 ]--|--------------------------
hostkey        | SHA=3b94d...
keyname        | default.sys.uptime
type           | int
metatags       | {inventory,source=agent,"attribute_name=Uptime minutes"}
value          | 4543
Table: Inventory_new

Inventory data grouped by host

Columns:

  • HostKey (text) Unique identifier of the host.

  • values (jsonb) Inventory values presented in JSON format

Example query:

code
SELECT hostkey,
       values
FROM   Inventory_new;

Output:

code
-[ RECORD 1 ]--|--------------------------
hostkey        | SHA=3b94d...
values         | {"OS": "ubuntu", "OS type": "linux", "CPU model": "CPU model A10", "Host name": "SHA=aa11bb1", "OS kernel": "14.4.0-53-generic", "Interfaces": "pop, imap", "BIOS vendor": "BIOS vendor", "CFEngine ID": "SHA=aa11bb1", "CPU sockets": "229", "New OS type": "linux", "Architecture": "x86_64"}
-[ RECORD 2 ]--|--------------------------
hostkey        | SHA=5rt43...
values         | {"OS": "ubuntu", "OS type": "linux", "CPU model": "CPU model A10", "Host name": "SHA=aa11bb1", "OS kernel": "14.4.0-53-generic", "Interfaces": "pop, imap", "BIOS vendor": "BIOS vendor", "CFEngine ID": "SHA=aa11bb1", "CPU sockets": "229", "New OS type": "linux", "Architecture": "x86_64"}
Table: LastSeenHosts

Information about communication between CFEngine clients. Effectively a snapshot of each hosts lastseen database (cf_lastseen.lmdb, cf-key -s) at the time of their last reported cf-agent execution.

Columns:

  • HostKey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • LastSeenDirection (INCOMING/OUTGOING) Direction within which the connection was established.

    • INCOMING - host received incoming connection.
    • OUTGOING - host opened connection to remote host.
  • RemoteHostKey (text) HostKey of the remote host.

  • RemoteHostIP (text) IP address of the remote host.

  • LastSeenTimeStamp (timestamp) Time when the connection was established.

  • LastSeenInterval (real) Average time period (seconds) between connections for the given LastSeenDirection with the host.

Example query:

code
SELECT hostkey,
       lastseendirection,
       remotehostkey,
       remotehostip,
       lastseentimestamp,
       lastseeninterval
FROM   lastseenhosts;

Output:

code
-[ RECORD 1 ]-----|-----------------------
hostkey           | SHA=3b94d...
lastseendirection | OUTGOING
remotehostkey     | SHA=2aab8...
remotehostip      | 192.168.56.152
lastseentimestamp | 2015-03-13 12:20:45+00
lastseeninterval  | 299
-[ RECORD 2 ]-----|------------------------
hostkey           | SHA=3b94d...
lastseendirection | INCOMING
remotehostkey     | SHA=a4dd5...
remotehostip      | 192.168.56.151
lastseentimestamp | 2015-03-13 12:22:06+00
lastseeninterval  | 298
-[ RECORD 3 ]-----|------------------------
hostkey           | SHA=2aab8...
lastseendirection | INCOMING
remotehostkey     | SHA=3b94d...
remotehostip      | 192.168.56.65
lastseentimestamp | 2015-03-13 12:20:45+00
lastseeninterval  | 299
Table: LastSeenHostsLogs

History of LastSeenHosts table

Columns:

  • HostKey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • LastSeenDirection (INCOMING/OUTGOING) Direction within which the connection was established.

    • INCOMING - host received incoming connection.
    • OUTGOING - host opened connection to remote host.
  • RemoteHostKey (text) HostKey of the remote host.

  • RemoteHostIP (text) IP address of the remote host.

  • LastSeenTimeStamp (timestamp) Time when the connection was established.

  • LastSeenInterval (real) Average time period (seconds) between connections for the given LastSeenDirection with the host.

Example query:

code
SELECT hostkey,
       lastseendirection,
       remotehostkey,
       remotehostip,
       lastseentimestamp,
       lastseeninterval
FROM   LastSeenHostsLogs;

Output:

code
-[ RECORD 1 ]-----|-----------------------
hostkey           | SHA=3b94d...
lastseendirection | OUTGOING
remotehostkey     | SHA=2aab8...
remotehostip      | 192.168.56.152
lastseentimestamp | 2015-03-13 12:20:45+00
lastseeninterval  | 299
-[ RECORD 2 ]-----|------------------------
hostkey           | SHA=3b94d...
lastseendirection | INCOMING
remotehostkey     | SHA=a4dd5...
remotehostip      | 192.168.56.151
lastseentimestamp | 2015-03-13 12:22:06+00
lastseeninterval  | 298
-[ RECORD 3 ]-----|------------------------
hostkey           | SHA=2aab8...
lastseendirection | INCOMING
remotehostkey     | SHA=3b94d...
remotehostip      | 192.168.56.65
lastseentimestamp | 2015-03-13 12:20:45+00
lastseeninterval  | 299
Table: MonitoringHg

Stores 1 record for each observable per host.

Columns:

  • host (text) Unique host identifier. Referred to in other tables as HostKey to connect data concerning same hosts.

  • id (text) Name of monitored metric. The handle of the measurement promise.

  • ar1 (real) Average across 66 observations.

Table: MonitoringMgMeta

Stores 1 record for each observable per host.

Columns:

  • id (integer) Unique identifier for host observable.

  • hostkey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • observable (text) Name of monitored metric. The handle of the measurement promise.

  • global (boolean)

  • expected_min (real) Minimum expected value.

  • expected_max (real) Maximum expected value.

  • unit (text) Unit of measurement.

  • description (text) Description of unit of measurement.

  • updatedtimestamp (timestamp with time zone) Time when measurement sampled.

  • lastupdatedsample (integer) Value of most recently collected measurement.

Table: MonitoringYrMeta

Stores 1 record for each observable per host.

Columns:

  • id (integer) Unique identifier for host observable.

  • hostkey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • observable (text) Name of monitored metric. The handle of the measurement promise.

  • global (boolean)

  • expected_min (real) Minimum expected value.

  • expected_max (real) Maximum expected value.

  • unit (text) Unit of measurement.

  • description (text) Description of unit of measurement.

  • lastupdatedsample (integer) Value of most recently collected measurement.

Table: PromiseExecutions

Promises executed on hosts during their last reported cf-agent run.

Columns:

  • HostKey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • PolicyFile (text) Path to the file where the promise is located in.

  • ReleaseId (text) Unique identifier of masterfiles version that is executed on the host.

  • PromiseHash (text) Unique identifier of a promise. It is a hash of all promise attributes and their values.

  • NameSpace (text) Namespace within which the promise is executed. If no namespace is set then it is set as: default.

  • BundleName (text) Bundle name where the promise is executed.

  • PromiseType (text) Type of the promise.

  • Promiser (text) Object affected by a promise.

  • StackPath (text) Call stack of the promise.

  • PromiseHandle (text) A unique id-tag string for referring promise.

  • PromiseOutcome (KEPT/NOTKEPT/REPAIRED) Promise execution result.

    • KEPT - System has been found in the state as desired by the promise. CFEngine did not have to do any action to correct the state.
    • REPAIRED - State of the system differed from the desired state. CFEngine took successful action to correct it according to promise specification.
    • NOTKEPT - CFEngine has failed to converge the system according to the promise specification.
  • LogMessages (text[]) List of 5 last messages generated during promise execution. If the promise is KEPT the messages are not reported. Log messages can be used for tracking specific changes made by CFEngine while repairing or failing promise execution.

  • Promisees (text[]) List of promisees defined for the promise.

  • ChangeTimeStamp (timestamp) Timestamp since when the promise is continuously executed by cf-agent in its current configuration and provides the same output. Note: If any of the promise dynamic attributes change, like promise outcome, log messages or the new policy version will be rolled out. This timestamp will be changed.

Example query:

code
SELECT hostkey,
       policyfile,
       releaseid,
       promisehash,
       namespace,
       bundlename,
       promisetype,
       promiser,
       stackpath,
       promisehandle,
       promiseoutcome,
       logmessages,
       promisees,
       changetimestamp
FROM   softwareupdates;

Output:

code
-[ RECORD 1 ]---|---------------------------------------------------------
hostkey         | SHA=a4dd5...
policyfile      | /var/cfengine/inputs/inventory/any.cf
releaseid       | 05c0cc909d6709d816521d6cedbc4508894cc497
promisehash     | fd6d5e40b734e35d9e8b2ed071dfe390f23148053adaae3dbb936...
namespace       | default
bundlename      | inventory_autorun
promisetype     | methods
promiser        | mtab
stackpath       | /default/inventory_autorun/methods/'mtab'[0]
promisehandle   | cfe_internal_autorun_inventory_mtab
promiseoutcome  | KEPT
logmessages     | {}
promisees       | {}
changetimestamp | 2015-03-12 10:20:18+00
-[ RECORD 2 ]---|---------------------------------------------------------
hostkey         | SHA=a4dd5...
policyfile      | /var/cfengine/inputs/promises.cf
releaseid       | 05c0cc909d6709d816521d6cedbc4508894cc497
promisehash     | 925b04453ef86ff2e43228a5ca5d56dc4d69ddf12378d6fdba28b...
namespace       | default
bundlename      | service_catalogue
promisetype     | methods
promiser        | security
stackpath       | /default/service_catalogue/methods/'security'[0]
promisehandle   | service_catalogue_change_management
promiseoutcome  | KEPT
logmessages     | {}
promisees       | {goal_infosec,goal_compliance}
changetimestamp | 2015-03-12 10:20:18+00
-[ RECORD 3 ]---|---------------------------------------------------------
hostkey         | SHA=3b94d...
policyfile      | /var/cfengine/inputs/lib/3.6/bundles.cf
releaseid       | 05c0cc909d6709d816521d6cedbc4508894cc497
promisehash     | 47f64d43f21bc6162b4f21bf385e715535617eebc649b259ebaca...
namespace       | default
bundlename      | logrotate
promisetype     | files
promiser        | /var/cfengine/cf3.hub.runlog
stackpath       | /default/cfe_internal_management/files/'any'/default/...
promisehandle   |
promiseoutcome  | REPAIRED
logmessages     | {"Rotating files '/var/cfengine/cf3.hub.runlog'"}
promisees       | {}
changetimestamp | 2015-03-12 14:52:36+00
Table: PromiseExecutionsLog

This table was deprecated in 3.7.0. It is no longer used.

Promise status / outcome changes over period of time.

Columns:

  • HostKey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • ChangeTimeStamp (timestamp) Timestamp when the promise state or outcome changed. Note: The statement if true till present time or newer entry claims otherwise.

  • ChangeOperation (ADD,CHANGE,REMOVE,UNTRACKED) CFEngine uses incremental diffs to report it's state. ChangeOperation is a diff state describing current entry.

    • ADD - stands for introducing a new entry which did not exist at last execution. In this case, new promise executed, or the promise was not executed at previous cf-agent run.
    • CHANGE - stands for changing value or attribute such as PromiseOutcome, LogMessages or ReleaseId in case of new policy rollout.
    • REMOVE - Promise was not executed last time, but it was executed previously. This is a common report for promises that have been removed from policy at some point, or they are executed only periodically (like once a hour, day etc.).
    • UNTRACKED - CFEngine provides a mechanism for filtering unwanted data from being reported. UNTRACKED marker states that information is being filtered and will not report any future information about it.
  • PolicyFile (text) Path to the file where the promise is located in.

  • ReleaseId (text) Unique identifier of masterfiles version that is executed in the host.

  • PromiseHash (text) Unique identifier of a promise. It is a hash of all promise attributes and their values.

  • NameSpace (text) Namespace within which the promise is executed. If no namespace is set then it is set as: default.

  • BundleName (text) Bundle name where the promise is executed.

  • PromiseType (text) Type of the promise.

  • Promiser (text) Object affected by a promise.

  • StackPath (text) Call stack of the promise.

  • PromiseHandle (text) A unique id-tag string for referring promise.

  • PromiseOutcome (KEPT/NOTKEPT/REPAIRED) Promise execution result.

    • KEPT - System has been found in the state as desired by the promise. CFEngine did not have to do any action to correct the state.
    • REPAIRED - State of the system differed from the desired state. CFEngine took successful action to correct it according to promise specification.
    • NOTKEPT - CFEngine has failed to converge the system according to the promise specification.
  • LogMessages (text[]) List of 5 last messages generated during promise execution. If the promise is KEPT the messages are not reported. Log messages can be used for tracking specific changes made by CFEngine while repairing or failing promise execution.

  • Promisees (text[]) List of promisees defined for the promise.

Example query:

code
SELECT hostkey,
       changetimestamp,
       changeoperation,
       policyfile,
       releaseid,
       promisehash,
       namespace,
       bundlename,
       promisetype,
       promiser,
       stackpath,
       promisehandle,
       promiseoutcome,
       logmessages,
       promisees
FROM   promiseexecutionslog;

Output:

code
-[ RECORD 1 ]---|--------------------------------------------------
hostkey         | SHA=a4dd5...
changetimestamp | 2015-03-11 09:50:11+00
changeoperation | ADD
policyfile      | /var/cfengine/inputs/sketches/meta/api-runfile.cf
releaseid       | 05c0cc909d6709d816521d6cedbc4508894cc497
promisehash     | 48bc...
namespace       | default
bundlename      | cfsketch_run
promisetype     | methods
promiser        | cfsketch_g
stackpath       | /default/cfsketch_run/methods/'cfsketch_g'[0]
promisehandle   |
promiseoutcome  | KEPT
logmessages     | {}
promisees       | {}
-[ RECORD 2 ]---|--------------------------------------------------
hostkey         | SHA=3b94d...
changetimestamp | 2015-03-17 08:55:38+00
changeoperation | ADD
policyfile      | /var/cfengine/inputs/inventory/any.cf
releaseid       | 05c0cc909d6709d816521d6cedbc4508894cc497
promisehash     | 6eef8...
namespace       | default
bundlename      | inventory_autorun
promisetype     | methods
promiser        | disk
stackpath       | /default/inventory_autorun/methods/'disk'[0]
promisehandle   | cfe_internal_autorun_disk
promiseoutcome  | KEPT
logmessages     | {}
promisees       | {}
-[ RECORD 3 ]---|--------------------------------------------------
hostkey         | SHA=3b94d...
changetimestamp | 2015-03-10 13:43:28+00
changeoperation | CHANGE
policyfile      | /var/cfengine/inputs/inventory/any.cf
releaseid       | 05c0cc909d6709d816521d6cedbc4508894cc497
promisehash     | fd6d5...
namespace       | default
bundlename      | inventory_autorun
promisetype     | methods
promiser        | mtab
stackpath       | /default/inventory_autorun/methods/'mtab'[0]
promisehandle   | cfe_internal_autorun_inventory_mtab
promiseoutcome  | KEPT
logmessages     | {}
promisees       | {}
Table: PromiseLog

History of promises executed on hosts.

Columns:

  • id (integer)

  • HostKey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • ChangeTimeStamp (timestamp) The GMT time on the host when this state was first perceived.

    Note causes of change:

    • A change in the promise signature/hash for example, altering the promise handle, promisees, or moving the promise to a different bundle
    • A change in the policy releaseId (cf_promises_release_id)
    • A change in promise outcome
  • PolicyFile (text) Path to the file where the promise is located in.

  • ReleaseId (text) Unique identifier of masterfiles version that is executed on the host.

  • PromiseHash (text) Unique identifier of a promise. It is a hash of all promise attributes and their values.

  • NameSpace (text) Namespace within which the promise is executed. If no namespace is set then it is set as: default.

  • BundleName (text) Bundle name where the promise is executed.

  • PromiseType (text) Type of the promise.

  • Promiser (text) Object affected by a promise.

  • StackPath (text) Call stack of the promise.

  • PromiseHandle (text) A unique id-tag string for referring promise.

  • PromiseOutcome (KEPT/NOTKEPT/REPAIRED) Promise execution result.

    • KEPT - System has been found in the state as desired by the promise. CFEngine did not have to do any action to correct the state.
    • REPAIRED - State of the system differed from the desired state. CFEngine took successful action to correct it according to promise specification.
    • NOTKEPT - CFEngine has failed to converge the system according to the promise specification.
  • LogMessages (text[]) List of 5 last messages generated during promise execution. If the promise is KEPT the messages are not reported. Log messages can be used for tracking specific changes made by CFEngine while repairing or failing promise execution.

  • Promisees (text[]) List of promisees defined for the promise.

Example query:

code
SELECT hostkey,
       policyfile,
       releaseid,
       promisehash,
       namespace,
       bundlename,
       promisetype,
       promiser,
       stackpath,
       promisehandle,
       promiseoutcome,
       logmessages,
       promisees,
       changetimestamp
FROM   promiselog;

Output:

code
-[ RECORD 1 ]---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
hostkey         | SHA=70138d580b9fd292ff856746df2fe7f9ded29db9ffca0c4d83acbbb97cde4d42
policyfile      | /var/cfengine/inputs/lib/bundles.cf
releaseid       | f90866033a826aa05cf10fdc8d34a532a9cd465b
promisehash     | 04659a0501f471eb1794cead6cd7a3291b78dcb195063821a7dcb4dbe7f7f804
namespace       | default
bundlename      | prunedir
promisetype     | files
promiser        | /var/cfengine/outputs
stackpath       | /default/cfe_internal_management/methods/'CFEngine_Internals'/default/cfe_internal_core_main/methods/'any'/default/cfe_internal_log_rotation/methods/'Prune old log files'/default/prunedir/files/'/var/cfengine/output
s'[1]
promisehandle   |
promiseoutcome  | REPAIRED
logmessages     | {"Deleted file '/var/cfengine/outputs/cf_demohub_a10042_cfengine_com__1535846669_Sun_Sep__2_00_04_29_2018_0x7f4da3549700'"}
promisees       | {}
changetimestamp | 2018-10-02 00:04:52+00
Table: Software

Software packages installed (according to local package manager) on the hosts. More information about CFEngine and package management can be found here.

Columns:

  • HostKey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • SoftwareName (text) Name of installed software package.

  • SoftwareVersion (text) Software package version.

  • SoftwareArchitecture (text) Architecture.

  • ChangeTimeStamp (timestamp) Timestamp when the package was discovered / installed on the host.

Example query:

code
SELECT hostkey,
       softwarename,
       softwareversion,
       softwarearchitecture,
       changetimestamp
FROM   software;

Output:

code
-[ RECORD 1 ]--------|-----------------------
hostkey              | SHA=a4dd5...
softwarename         | libgssapi-krb5-2
softwareversion      | 1.12+dfsg-2ubuntu4.2
softwarearchitecture | default
changetimestamp      | 2015-03-12 10:20:18+00
-[ RECORD 2 ]--------|-----------------------
hostkey              | SHA=a4dd5...
softwarename         | whiptail
softwareversion      | 0.52.15-2ubuntu5
softwarearchitecture | default
changetimestamp      | 2015-03-12 10:20:18+00
-[ RECORD 3 ]--------|-----------------------
hostkey              | SHA=a4dd5...
softwarename         | libruby1.9.1
softwareversion      | 1.9.3.484-2ubuntu1.2
softwarearchitecture | default
changetimestamp      | 2015-03-12 10:20:18+00
Table: SoftwareUpdates

Patches available for installed packages on the hosts (as reported by local package manager). The most up to date patch will be listed.

Columns:

  • HostKey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • PatchName (text) Name of the software.

  • PatchVersion (text) Patch version.

  • PatchArchitecture (text) Architecture of the patch.

  • PatchReportType (INSTALLED/AVAILABLE) Patch status (INSTALLED status is specific only to SUSE Linux).

  • ChangeTimeStamp (timestamp) Timestamp when the new patch / version was discovered as available on the host.

Example query:

code
SELECT hostkey,
       patchname,
       patchversion,
       patcharchitecture,
       patchreporttype,
       changetimestamp
FROM   softwareupdates;

Output:

code
-[ RECORD 1 ]-----|------------------------
hostkey           | SHA=a4dd5...
patchname         | libelf1
patchversion      | 0.158-0ubuntu5.2
patcharchitecture | default
patchreporttype   | AVAILABLE
changetimestamp   | 2015-03-12 10:20:18+00
-[ RECORD 2 ]-----|------------------------
hostkey           | SHA=a4dd5...
patchname         | libisccfg90
patchversion      | 1:9.9.5.dfsg-3ubuntu0.2
patcharchitecture | default
patchreporttype   | AVAILABLE
changetimestamp   | 2015-03-12 10:20:18+00
-[ RECORD 3 ]-----|------------------------
hostkey           | SHA=a4dd5...
patchname         | libc6-dev
patchversion      | 2.19-0ubuntu6.6
patcharchitecture | default
patchreporttype   | AVAILABLE
changetimestamp   | 2015-03-12 10:20:18+00
Table: SoftwareLog

Software packages installed / deleted over period of time. More information about CFEngine and package management can be found here.

Columns:

  • HostKey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • ChangeTimeStamp (timestamp) Timestamp when the package state was discovered on the host. Note: The statement if true till present time or newer entry claims otherwise.

  • ChangeOperation (ADD,REMOVE) CFEngine uses incremental diffs to report it's state. ChangeOperation is a diff state describing current entry.

    • ADD - New package have been detected / installed. Package upgrate is considered as installing a new package with a different version.
    • REMOVE - Package have been detected to be removed / uninstalled. During upgrate older version of the package is removed and reported as so.
  • SoftwareName (text) Name of installed software package.

  • SoftwareVersion (text) Software package version.

  • SoftwareArchitecture (text) Architecture.

Example query:

code
SELECT hostkey,
       changetimestamp,
       changeoperation,
       softwarename,
       softwareversion,
       softwarearchitecture
FROM   softwarelog;

Output:

code
-[ RECORD 1 ]--------|-----------------------
hostkey              | SHA=3b94d...
changetimestamp      | 2015-03-10 13:38:14+00
changeoperation      | ADD
softwarename         | libgssapi-krb5-2
softwareversion      | 1.12+dfsg-2ubuntu4.2
softwarearchitecture | default
-[ RECORD 2 ]--------|-----------------------
hostkey              | SHA=3b94d...
changetimestamp      | 2015-03-10 13:38:14+00
changeoperation      | ADD
softwarename         | whiptail
softwareversion      | 0.52.15-2ubuntu5
softwarearchitecture | default
-[ RECORD 3 ]--------|-----------------------
hostkey              | SHA=3b94d...
changetimestamp      | 2015-03-10 13:38:14+00
changeoperation      | ADD
softwarename         | libruby1.9.1
softwareversion      | 1.9.3.484-2ubuntu1.2
softwarearchitecture | default
Table: SoftwareUpdatesLog

This table was deprecated in 3.7.0. It is no longer used.

Patches available for installed packages on the hosts (as reported by local package manager) over period of time.

Columns:

  • HostKey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • ChangeTimeStamp (timestamp) Timestamp when the patch state was discovered on the host. Note: The statement if true till present time or newer entry claims otherwise.

  • ChangeOperation (ADD,REMOVE) CFEngine uses incremental diffs to report it's state. ChangeOperation is a diff state describing current entry.

    • ADD - New patch have been detected. This is a common in case of release of new patch version or new package was installed that have an upgrate available.
    • REMOVE - Patch is not longer available. Patch may be replaced with newer version, or installed package have been upgrated. Note: CFEngine reports only the most up to date version available.
  • PatchName (text) Name of the software.

  • PatchVersion (text) Patch version.

  • PatchArchitecture (text) Architecture of the patch.

  • PatchReportType (INSTALLED/AVAILABLE) Patch status (INSTALLED status is specific only to SUSE Linux).

Example query:

code
SELECT hostkey,
       changetimestamp,
       changeoperation,
       patchname,
       patchversion,
       patcharchitecture,
       patchreporttype
FROM   softwareupdateslog;

Output:

code
-[ RECORD 1 ]-----|------------------------
hostkey           | SHA=3b94d...
changetimestamp   | 2015-03-10 13:38:14+00
changeoperation   | ADD
patchname         | libelf1
patchversion      | 0.158-0ubuntu5.2
patcharchitecture | default
patchreporttype   | AVAILABLE
-[ RECORD 2 ]-----|------------------------
hostkey           | SHA=3b94d...
changetimestamp   | 2015-03-10 13:38:14+00
changeoperation   | ADD
patchname         | libisccfg90
patchversion      | 1:9.9.5.dfsg-3ubuntu0.2
patcharchitecture | default
patchreporttype   | AVAILABLE
-[ RECORD 3 ]-----|------------------------
hostkey           | SHA=3b94d...
changetimestamp   | 2015-03-10 13:38:14+00
changeoperation   | ADD
patchname         | libc6-dev
patchversion      | 2.19-0ubuntu6.6
patcharchitecture | default
patchreporttype   | AVAILABLE
Table: Status

Statuses of report collection. cf-hub records all collection attempts and whether they are FAILEDC or CONSUMED. CONSUMED means next one will be delta. FAILEDC means next one will be REBASE.

Columns:

  • host (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • ts (timestamp) Timestamp of last data provided by client during report collection. This is used by delta queries to request a start time.

  • status (FAILEDC,CONSUMED) CFEngine uses incremental diffs to report it's state. ChangeOperation is a diff state describing current entry.

    • FAILEDC - New patch have been detected. This is a common in case of release of new patch version or new package was installed that have an upgrate available.
    • CONSUMED - Patch is not longer available. Patch may be replaced with newer version, or installed package have been upgrated. Note: CFEngine reports only the most up to date version available.
  • lstatus (text) Deprecated

  • type (text) Deprecated

  • who (integer) Deprecated

  • whr integer Deprecated

Example query:

code
SELECT hostkey,
       changetimestamp,
       changeoperation,
       patchname,
       patchversion,
       patcharchitecture,
       patchreporttype
FROM   softwareupdateslog;

Output:

code
-[ RECORD 1 ]-----|------------------------
hostkey           | SHA=3b94d...
changetimestamp   | 2015-03-10 13:38:14+00
changeoperation   | ADD
patchname         | libelf1
patchversion      | 0.158-0ubuntu5.2
patcharchitecture | default
patchreporttype   | AVAILABLE
-[ RECORD 2 ]-----|------------------------
hostkey           | SHA=3b94d...
changetimestamp   | 2015-03-10 13:38:14+00
changeoperation   | ADD
patchname         | libisccfg90
patchversion      | 1:9.9.5.dfsg-3ubuntu0.2
patcharchitecture | default
patchreporttype   | AVAILABLE
-[ RECORD 3 ]-----|------------------------
hostkey           | SHA=3b94d...
changetimestamp   | 2015-03-10 13:38:14+00
changeoperation   | ADD
patchname         | libc6-dev
patchversion      | 2.19-0ubuntu6.6
patcharchitecture | default
patchreporttype   | AVAILABLE
Table: Variables

Variables and their values set on hosts at their last reported cf-agent execution.

Columns:

  • HostKey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • NameSpace (text) Namespace within which the variable is set. If no namespace is set then it is set as: default.

  • Bundle (text) Bundle name where the variable is set.

  • VariableName (text) Name of the variable.

  • VariableValue (text) Variable value serialized to string.

    • List types such as: slist, ilist, rlist are serialized with CFEngine list format: {'value','value'}.
    • Data type is serialized as JSON string.
  • VariableType (text) Type of the variable. List of supported variable types.

  • MetaTags (text[]) List of meta tags set for the variable.

  • ChangeTimeStamp (timestamp) Timestamp since when variable is set in its current form. Note: If any of variable attributes change such as its VariableValue or Bundle, the timestamp will be updated.

Example query:

code
SELECT hostkey,
       namespace,
       bundle,
       variablename,
       variablevalue,
       variabletype,
       metatags,
       changetimestamp
FROM   variables;

Output:

code
-[ RECORD 1 ]---|-------------------------------------------------------------
hostkey         | SHA=a4dd5...
namespace       | default
bundle          | cfe_autorun_inventory_memory
variablename    | total
variablevalue   | 490.00
variabletype    | string
metatags        | {source=promise,inventory,"attribute_name=Memory size (MB)"}
changetimestamp | 2015-03-11 09:51:41+00
-[ RECORD 2 ]---|-------------------------------------------------------------
hostkey         | SHA=a4dd5...
namespace       | default
bundle          | cfe_autorun_inventory_listening_ports
variablename    | ports
variablevalue   | {'22','111','5308','38854','50241'}
variabletype    | slist
metatags        | {source=promise,inventory,"attribute_name=Ports listening"}
changetimestamp | 2015-03-11 09:51:41+00
-[ RECORD 3 ]---|-------------------------------------------------------------
hostkey         | SHA=a4dd5...
namespace       | default
bundle          | cfe_autorun_inventory_memory
variablename    | free
variablevalue   | 69.66
variabletype    | string
metatags        | {source=promise,report}
changetimestamp | 2015-03-11 14:27:12+00
Table: Variables_dictionary

Inventory attributes, these data are using in List of inventory attributes API

Columns:

  • Id (integer) Auto incremental ID
  • Attribute_name (text) Attribute name
  • Category (text) (Hardware,Software,Network, Security, User defined) Attribute category
  • Readonly (integer) (0,1) Is attribute readonly
  • Type (text) Type of the attribute. List of supported variable types.
  • convert_function (text) Convert function. Emp.: cf_clearSlist - to transform string like {"1", "2"} to 1, 2
  • keyname (text) Key name
  • Enabled (integer) (0,1) Is attribute enabled for the API

Example query:

code
SELECT attribute_name,
       category,
       readonly,
       type,
       convert_function,
       enabled
FROM   variables_dictionary;

Output:

code
-[ RECORD 1 ]---|-----------------------------------------------------
attribute_name  | Architecture
category        | Software
readonly        | 1
type            | string
convert_function|
enabled         | 1
-[ RECORD 2 ]---|-----------------------------------------------------
attribute_name  | IPv4 addresses
category        | Network
readonly        | 1
type            | slist
convert_function| cf_clearSlist
enabled         | 1
Table: VariablesLog

CFEngine variables set on hosts by CFEngine over period of time.

Columns:

  • HostKey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • ChangeTimeStamp (timestamp) Timestamp since when variable is set in its current form. Note: The statement if true till present time or newer entry claims otherwise.

  • ChangeOperation (ADD,CHANGE,REMOVE,UNTRACKED) CFEngine uses incremental diffs to report it's state. ChangeOperation is a diff state describing current entry.

    • ADD - stands for introducing a new entry which did not exist before. In this case, new CFEngine variable have been introduced.
    • CHANGE - stands for changing value or attribute such as VariableValue or MetaTags have changed.
    • REMOVE - Variable have not been set.
    • UNTRACKED - CFEngine provides a mechanism for filtering unwanted data from being reported. UNTRACKED marker states that information is being filtered and will not report any future information about it.
  • NameSpace (text) Namespace within which the variable is set. If no namespace is set then it is set as: default.

  • Bundle (text) Bundle name where the variable is set.

  • VariableName (text) Name of the variable.

  • VariableValue (text) Variable value serialized to string.

    • List types such as: slist, ilist, rlist are serialized with CFEngine list format: {'value','value'}.
    • Data type is serialized as JSON string.
  • VariableType (text) Type of the variable. List of supported variable types.

  • MetaTags (text[]) List of meta tags set for the variable.

Example query:

code
SELECT hostkey,
       changetimestamp,
       changeoperation,
       namespace,
       bundle,
       variablename,
       variablevalue,
       variabletype,
       metatags
FROM   variableslog;

Output:

code
-[ RECORD 1 ]---|-----------------------------------------------------
hostkey         | SHA=2aab8...
changetimestamp | 2015-03-10 13:43:00+00
changeoperation | CHANGE
namespace       | default
bundle          | mon
variablename    | av_cpu
variablevalue   | 0.06
variabletype    | string
metatags        | {monitoring,source=environment}
-[ RECORD 2 ]---|-----------------------------------------------------
hostkey         | SHA=2aab8...
changetimestamp | 2015-03-10 13:40:20+00
changeoperation | ADD
namespace       | default
bundle          | sys
variablename    | arch
variablevalue   | x86_64
variabletype    | string
metatags        | {inventory,source=agent,attribute_name=Architecture}
-[ RECORD 3 ]---|-----------------------------------------------------
hostkey         | SHA=2aab8...
changetimestamp | 2015-03-10 13:43:00+00
changeoperation | CHANGE
namespace       | default
bundle          | mon
variablename    | av_diskfree
variablevalue   | 67.01
variabletype    | string
metatags        | {monitoring,source=environment}
Table: v_hosts

V_hosts table contains information about hosts.

Columns:

  • HostKey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • iscallcollected (boolean) Is host call collected

  • LastReportTimeStamp (timestamp) Timestamp of the most recent successful report collection.

  • FirstReportTimeStamp (timestamp) Timestamp when the host reported to the hub for the first time, which indicate when the host was bootstrapped to the hub.

Example query:

code
SELECT hostkey,
       iscallcollected,
       lastreporttimestamp,
       firstreporttimestamp
FROM   hosts;

Output:

code
-[ RECORD 1 ]--------|-----------------------
hostkey              | SHA=a4dd...
iscallcollected      | t
lastreporttimestamp  | 2015-03-10 14:20:20+00
firstreporttimestamp | 2015-03-10 13:40:20+00
-[ RECORD 2 ]--------|-----------------------
hostkey              | SHA=3b94...
iscallcollected      | f
lastreporttimestamp  | 2015-03-10 14:20:20+00
firstreporttimestamp | 2015-03-10 13:34:20+00
-[ RECORD 3 ]--------|-----------------------
hostkey              | SHA=2aab...
iscallcollected      | f
lastreporttimestamp  | 2015-03-10 14:20:20+00
firstreporttimestamp | 2015-03-10 13:40:20+00
Table: vm_hosts

vm_hosts table contains basic information about hosts managed by CFEngine. In this table data are cached what gives a better query performance

Columns:

  • HostKey (text) Unique host identifier. All tables can be joined by HostKey to connect data concerning same hosts.

  • HostName (text) Host name locally detected on the host, configurable as hostIdentifier option in Settings API and Mission Portal settings UI.

  • IPAddress (text) IP address of the host derived from the lastseen database (this is expected to be the IP address from which connections come from, beware NAT will cause multiple hosts to appear to have the same IP address).

  • LastReportTimeStamp (timestamp) Timestamp of the most recent successful report collection.

  • FirstReportTimeStamp (timestamp) Timestamp when the host reported to the hub for the first time, which indicate when the host was bootstrapped to the hub.

Example query:

code
SELECT hostkey,
       hostname,
       ipaddress,
       lastreporttimestamp,
       firstreporttimestamp
FROM   hosts;

Output:

code
-[ RECORD 1 ]--------|-----------------------
hostkey              | SHA=a4dd...
hostname             | host001
ipaddress            | 192.168.56.151
lastreporttimestamp  | 2015-03-10 14:20:20+00
firstreporttimestamp | 2015-03-10 13:40:20+00
-[ RECORD 2 ]--------|-----------------------
hostkey              | SHA=3b94...
hostname             | hub
ipaddress            | 192.168.56.65
lastreporttimestamp  | 2015-03-10 14:20:20+00
firstreporttimestamp | 2015-03-10 13:34:20+00
-[ RECORD 3 ]--------|-----------------------
hostkey              | SHA=2aab...
hostname             | host002
ipaddress            | 192.168.56.152
lastreporttimestamp  | 2015-03-10 14:20:20+00
firstreporttimestamp | 2015-03-10 13:40:20+00

cfmp

This database contains Mission Portal related settings not processed by the API.

Table: app

Information about Mission Portal applications.

Columns:

  • displayindex (integer) The display order of the app in the Mission Portal menu.
  • filepath (text) The path of the app module in the application directory.
  • hascontroller (integer) The flag that indicates whether the app has a controller file or not.
  • icon (character varying(50)) The name of the app icon file in the images directory.
  • meta (json) The JSON object that stores the app metadata, such as name, description, license, etc.
  • showappslist (integer) The flag that indicates whether the app is visible in the Mission Portal menu or not.
  • state (integer) The state of the app, such as 1 or 0.
  • url (text) The URL of the app in the Mission Portal.
  • id (character varying(100)) The unique identifier of the app, used as the primary key.
  • rbac_id (character varying(50)) The identifier of the RBAC permission that the app requires, may be null.
Table: astrolabeprofile

Information about Host trees such as who it was created by, who it is shared with and the definition of the host tree.

Columns:

  • id (integer) The unique identifier of the profile, generated from a sequence.
  • username (character varying(50)) The username of the user who created or owns the profile.
  • profileid (character varying(50)) The name of the profile, such as OS, Services, etc.
  • defaulttree (boolean) The flag that indicates whether the profile is the default one for the user or not.
  • globaltree (boolean) The flag that indicates whether the profile is a global one for all users or not.
  • sharedpermission (character varying(50)[]) The array of usernames that the profile is shared with, may be empty.
  • sharedby (character varying(50)[]) The array of usernames that shared the profile with the user, may be empty.
  • data (json) The JSON object that stores the profile data, such as label, classRegex, children, etc.
Table: ci_sessions

Information about current sessions.

Columns:

  • id (character varying(128)) The unique identifier of the session, used as the primary key.
  • ip_address (character varying(45)) The IP address of the user who initiated the session.
  • timestamp (bigint) The UNIX timestamp of the last activity of the session.
  • data (text) The text data of the session, encoded in base64.
Table: compliance_score

Compliance reports score.

Columns:

  • report_id (integer) The id of the compliance report that the user has generated.
  • username (text) The name of the user who has generated the compliance report.
  • score (integer) The percentage of compliance checks that the user has passed.
  • update_ts (timestamp with time zone) The timestamp of the last update of the compliance report.
  • fail_checks (integer) The number of compliance checks that the user has failed.
  • total (integer) The total number of compliance checks that the user has performed.
Table: customization

Stores Mission Portal UI customization config.

Columns:

  • key (character varying) The name of the customization option such as logo_on_login, login_text, header_color, etc.
  • value (text) The value of the customization option.
Table: dashboard_alerts

User dashboards alerts status.

Columns:

  • id (integer) The primary key of the dashboard alerts table.
  • ruleid (integer) The id of the rule that triggered the alert.
  • failhosts (integer) The number of hosts that failed the rule.
  • lastcheck (integer) The timestamp of the last check of the rule.
  • lasteventtime (integer) The timestamp of the last event that caused the alert status to change.
  • laststatuschange (integer) The timestamp of the last change of the alert status.
  • servertime (integer) The timestamp of the server time when the alert was generated.
  • pause (integer) The timestamp indicating when the alert was paused.
  • paused (integer) A flag indicating whether the alert was paused by the user or not.
  • name (character varying(500)) The name of the alert.
  • severity (character varying(10)) The severity level of the alert, such as high, medium, or low.
  • site_url (text) The URL of the Mission Portal host where the alert is displayed.
  • status (character varying(32)) The status of the alert, such as success, fail, or warning.
  • totalhosts (integer) The total number of hosts that are affected by the rule.
  • username (character varying(50)) The name of the user who created the alert.
  • widgetname (character varying(100)) The name of the widget that shows the alert.
  • emailtonotify (character varying(100)) The email address of the user who will be notified of the alert.
  • reminder (integer) The frequency of the reminder email for the alert.
  • widgetid (integer) The id of the widget that shows the alert.
  • hostcontextsprofileid (character varying(20)) The id of the host contexts profile that defines the scope of the alert.
  • hostcontexts (json) A JSON object containing the host contexts that define the scope of the alert.
  • hostcontextspath (text) The path of the host contexts that define the scope of the alert.
  • excludedhosts (json) A JSON object describing hosts that should be excluded from checking the alert.
Table: dashboard_alerts_script

Association of script with dashboard alert.

Columns:

  • alert_id (integer) The id of the dashboard alert that is associated with a script.
  • script_id (integer) The id of the script that is associated with a dashboard alert.
Table: dashboard_dashboards

User dashboards and configuration.

Columns:

  • id (integer) The primary key of the dashboard table.
  • name (character varying(200)) The name of the dashboard.
  • username (character varying(20)) The name of the user who owns the dashboard.
  • public (integer) A flag indicating whether the dashboard is public or private.
  • widgets (character varying(200)) A comma separated list of widget ids that are displayed on the dashboard.
  • sharedwith (jsonb) A JSON object containing the roles, users, and sharedWithAll flag that determine the sharing settings of the dashboard.
Table: dashboard_rules

User-defined dashboard alert rules.

Columns:

  • id (integer) Unique identifier for the dashboard rule.
  • name (text) Name of the dashboard rule.
  • description (text) Description of the dashboard rule.
  • type (character varying(20)) Type of the dashboard rule (e.g., policy, softwareupdate, inventory).
  • username (character varying(20)) Username of the user who created the dashboard rule.
  • policyconditions (json) Dashboard rule conditions for checks based on promise outcomes such as KEPT, NOT_KEPT, and REPAIRED. (JSON object)
  • inventoryconditions (json) JSON object of conditions for inventory-based dashboard rules.
  • softwareupdateconditions (json) JSON object of conditions for software update-based dashboard rules.
  • category (text) Category assigned to the dashboard rule.
  • severity (text) Severity level assigned to the dashboard rule such as low, medium, high.
  • hostcontexts (json) JSON object describing the set of hosts the limiting the hosts that should be considered when checking the rule. If not set the condition is checked for against all hosts the user has access to based on RBAC and host reported data.
  • conditionmustbemet (boolean) Flag indicating whether conditions must be met for the dashboard rule.
  • customconditions (json) Custom dashboard conditions (for widgets), which use SQL queries returning hostkeys of affected hosts (JSON object).
  • filechangedconditions (json) File changed conditions for the dashboard rule.
  • export_id (text) Identifier for exporting dashboard rules.
Table: dashboard_scripts

Table containing scripts available for association with alerts.

Columns:

  • id (integer) Unique identifier for the script entry.
  • name (text) Name of the script.
  • description (text) Description of the script.
  • script_name (text) Name of the actual script file.
  • type (text) Type of the script. (not used)
Table: dashboard_widgets

User configurations for dashboard widgets.

Columns:

  • id (integer) Unique identifier for the dashboard widget.
  • name (character varying(500)) Name of the dashboard widget.
  • type (character varying(20)) Type of the dashboard widget (e.g., inventory, alerts, hostCount).
  • username (character varying(50)) Username of the user who configured the dashboard widget.
  • ordering (integer) Ordering of the dashboard widget in the dashboard.
  • dashboardid (integer) Identifier for the associated dashboard.
  • payload (jsonb) JSON payload containing additional configuration for the dashboard widget. ###### Table: eventslog

Event logs.

Columns:

  • id (integer) Unique identifier for the event log entry.
  • username (character varying(100)) Username associated with the event log entry.
  • item_id (character varying(100)) Identifier associated with the item triggering the event (e.g., alert id).
  • item_type (character varying) Type of the item triggering the event (e.g., host, alerts).
  • item_name (character varying(500)) Name of the item triggering the event.
  • tags (character varying(500)[]) Tags associated with the event log entry.
  • time (timestamp without time zone) Timestamp when the event occurred.
  • severity (character varying(20)) Severity level of the event such as low, medium, high. Not all events specify a severity.
  • message (text) Detailed message describing the event.
  • status (character varying(10)) Status of the event (e.g., triggered, cleared).
Table: favourite_reports

Table associating favorited reports with users.

Columns:

  • report_id (bigint) Identifier of the favorite report.
  • username (text) Username of the user who marked the report as a favorite.
  • created_at (timestamp with time zone) Timestamp indicating when the report was marked as a favorite.
Table: mail_settings

Global email settings.

Columns:

  • key (character varying) Key representing a specific email setting.
  • value (text) Value associated with the email setting key.
Table: pinned_items

Pinned inventory, class, or variable items.

Columns:

  • id (bigint) Unique identifier for the pinned item.
  • username (text) Username of the user who pinned the item.
  • type (pinned_type) Type of the pinned item (e.g., inventory, class, variable).
  • name (text) Name of the pinned item.
  • created_at (timestamp with time zone) Timestamp indicating when the item was pinned.
Table: report

Information about saved reports.

Columns:

  • id (integer) The primary key of the report table.
  • username (character varying(50)) The name of the user who saved the report.
  • url (character varying(500)) The URL of the report.
  • reporttype (character varying(50)) The type of the report, such as compliance, inventory, or software update.
  • reportcategory (character varying(50)) The category of the report, such as security, performance, or other.
  • type (character varying(50)) The format of the report, such as pdf or csv.
  • readonly (integer) A flag indicating whether the report is read-only or editable.
  • is_public (integer) A flag indicating whether the report is public or private.
  • can_subscribe (integer) A flag indicating whether the report can be subscribed to or not.
  • is_subscribed (integer) A flag indicating whether the user is subscribed to the report or not.
  • label (character varying(500)) The label of the report.
  • date (timestamp without time zone) The date of the report.
  • params (text) The parameters of the report.
  • sharedpermission (character varying(50)[]) A list of permissions that the report has been shared with.
  • sharedby (character varying(50)[]) A list of users who have shared the report.
  • advancedreportsdata (json) A JSON object containing the advanced reports data.
  • export_id (text) The export id of the report, used for importing and exporting reports.
  • meta_data (jsonb) A JSON object containing the meta data of the report.
Table: report_schedule

Information about scheduled reports.

Columns:

  • id (character varying(500)) The unique identifier for the scheduled report.
  • reportid (integer) The foreign key referencing the associated report.
  • userid (character varying(50)) The user ID associated with the scheduled report.
  • title (character varying(500)) The title of the scheduled report.
  • description (character varying(500)) The description of the scheduled report.
  • emailfrom (character varying(500)) The email address from which the report is sent.
  • emailto (character varying(500)) The email address to which the report is sent.
  • enabled (integer) Flag indicating whether the scheduled report is enabled.
  • query (text) The SQL query that defines the report for the scheduled task.
  • outputtypes (character varying(50)[]) Array of output types for the scheduled report.
  • schedule* (character varying(500)) The schedule for running the report.
  • schedulehumanreadabletime (character varying(500)) Human-readable representation of the schedule time.
  • schedulename (character varying(500)) The name associated with the schedule.
  • site_url (text) The URL associated with the scheduled report.
  • hostcontextsprofileid (character varying(20)) The profile ID associated with the host contexts.
  • hostcontextspath (text) The path associated with the host contexts.
  • hostcontexts (json) JSON data representing the subset of hosts that the report should be filtered for. If not defined the scheduled report includes all hosts the userid is allowed to see based on RBAC and data reported by the host.
  • scheduledata (json) JSON data containing details about the schedule.
  • excludedhosts (json) JSON data representing excluded hosts for the scheduled report.
  • skipmailing (boolean) Flag indicating whether mailing is skipped for the scheduled report.
Table: users

User preferences and information about Mission Portal behavior.

Columns:

  • id (integer) The primary key of the user table.
  • username (character varying(50)) The unique name of the user.
  • source (character varying(20)) The source of the user account, such as internal or external (e.g. LDAP, Active Directory).
  • last_login (timestamp without time zone) The timestamp of the last login of the user.
  • remember_code (character varying(50)) The code used to remember the user login session.
  • dashboard (integer) The id of the default dashboard for the user.
  • seen_tour (smallint) A flag indicating whether the user has seen the tour of the Mission Portal.
  • seen_wizard (smallint) A flag indicating whether the user has seen the wizard of the Mission Portal.
  • never_ask_timezone_change (smallint) A flag indicating whether the user wants to be asked about changing the timezone.
  • use_browser_time (smallint) A flag indicating whether the user wants to use the browser time or the server time.
  • dark_mode (smallint) A flag indicating whether the user prefers the dark mode or the light mode.
  • pinned_items_version (smallint) This is used to add default pinned items which are added after this version.
  • additional_data (jsonb) A JSON object containing additional data about the user preferences and behavior.
Table: variables_dictionary

Information about reported inventory attributes.

Columns:

  • id (integer) The unique identifier for the variable in the dictionary.
  • attribute_name (character varying(200)) The name of the attribute represented by the variable.
  • category (character varying(200)) The category to which the attribute belongs.
  • readonly (integer) Flag indicating whether the attribute is read-only.
  • type (character varying(200)) The data type of the attribute such as string, slist, int, real.
  • convert_function (character varying(200)) The conversion function applied to the attribute such as cf_clearslist (if any).

cfsettings

Settings used by Mission Portal APIs, no reported data.

Table: build_modules

Information about build modules available from the index (build.cfengine.com).

Columns:

  • name (text) The name of the build module.
  • readme (text) The readme file content of the build module in HTML.
  • description (text) The description of the build module.
  • version (text) The version of the build module.
  • author (jsonb) The author information of the build module as a JSON object with keys such as url, name, image.
  • updated (timestamp with time zone) The last updated time of the build module.
  • downloads (integer) The number of downloads of the build module.
  • repo (text) The repository URL of the build module.
  • documentation (text) The documentation URL of the build module.
  • website (text) The website URL of the build module.
  • subdirectory (text) The subdirectory of the build module in the repository.
  • commit (text) The commit hash of the build module.
  • dependencies (jsonb) The dependencies of the build module as a JSON object.
  • tags (jsonb) The tags of the build module as a JSON object.
  • versions (jsonb) The available versions of the build module as a JSON object.
  • latest (boolean) A flag indicating whether the build module is the latest version.
  • ts_vector (tsvector)* Generated ts_vector column based on id and description.
Table: build_projects

Build application projects.

Columns:

  • id (bigint) The unique identifier of the build project, generated from a sequence.
  • repository_url (text) The URL of the git repository that contains the build project.
  • branch (text) The branch of the git repository that the build project uses.
  • name (text) The name of the build project, derived from the repository URL and branch.
  • authentication_type (authentication_types) The type of authentication that the build project uses to access the git repository. Must match authentication_types such as password or private_key.
  • username (text) The username that the build project uses to access the git repository, if applicable.
  • password (text) The password that the build project uses to access the git repository, if applicable.
  • ssh_private_key (text) This field is not used. Ref ENT-11330.
  • ssh_key_id (integer) The foreign key that references the ssh_keys table, if applicable.
  • created_at (timestamp with time zone) The timestamp of when the build project was created.
  • pushed_at (timestamp with time zone) The timestamp of when the build project was last pushed to the git repository.
  • is_local (boolean) The flag that indicates whether the build project is local or remote.
  • is_deployed_locally (boolean) The flag that indicates whether the build project is deployed locally or not.
  • action (text) The action that the build project performs, such as push, pushAndDeploy, localDeploy.
Table: cfbs_requests

cfbs requests and responses handled by cf-reactor.

Columns:

  • id (bigint) The unique identifier of the cfbs request, generated from a sequence.
  • request_name (text) The name of the cfbs request, such as init_project, local_deploy, etc.
  • arguments (jsonb) The JSONB object that stores the arguments of the cfbs request, such as git, project_id, etc.
  • created_at (timestamp with time zone) The timestamp of when the cfbs request was created.
  • finished_at (timestamp with time zone) The timestamp of when the cfbs request was finished, may be null if the request is still in progress.
  • response (jsonb) The JSONB object that stores the response of the cfbs request, such as status, details, etc.
Table: external_roles_map

Map of external directory group to Mission Portal RBAC role for automatic association of directory users to Mission Portal roles.

Columns:

  • external_role (text) The name of the external directory (LDAP/Active Directory) group.
  • internal_role (text) The name of the internal Mission Portal role, such as admin, auditor, or guest.
  • changetimestamp (timestamp with time zone) The timestamp of when the mapping was last changed.
Table: federated_reporting_settings

Federated reporting settings when enabled.

Columns:

  • key (character varying) The name of the federated reporting setting, such as enable_as, enable_request_sent, or target_state.
  • value (text) The value of the federated reporting setting, such as superhub, 1, or on.
Table: inventory_aliases

Inventory attributes aliases.

Columns:

  • inventory_attribute (text) The name of the inventory attribute, such as Kernel, Kernel Release, etc.
  • alias (text) The alias of the inventory attribute, such as os type, os kernel, etc.
Table: keyspendingfordeletion

Keys of deleted hosts yet to be deleted.

Columns:

  • hostkey (text) The key of the host that was deleted from the database but not yet from the ppkeys directory.
Table: licenseinfo

Information about the currently installed license.

Columns:

  • expiretimestamp (timestamp with time zone) The timestamp of when the license expires.
  • installtimestamp (timestamp with time zone) The timestamp of when the license was installed.
  • organization (text) The name of the organization that owns the license.
  • licensetype (text) The type of the license such as Enterprise.
  • licensecount (integer) The number of hosts that the license covers.
Table: oauth_access_tokens

OAuth access tokens and expiration.

Columns:

  • access_token (character varying(40)) The access token that grants access to the OAuth client.
  • client_id (character varying(80)) The client identifier of the OAuth client that obtained the access token.
  • user_id (character varying(255)) The user identifier of the user that authorized the access token.
  • expires (timestamp without time zone) The timestamp of when the access token expires.
  • scope (character varying(2000)) The scope of access that the access token grants.
Table: oauth_authorization_codes

OAuth authorizations.

Columns:

  • authorization_code (character varying(40)) The authorization code that grants access to the OAuth client.
  • client_id (character varying(80)) The client identifier of the OAuth client that requested the authorization code.
  • user_id (character varying(255)) The user identifier of the user that authorized the OAuth client.
  • redirect_uri (character varying(2000)) The URI that the OAuth client will redirect to after obtaining the authorization code.
  • expires (timestamp without time zone) The timestamp of when the authorization code expires.
  • scope (character varying(2000)) The scope of access that the authorization code grants.
Table: oauth_clients

OAuth clients.

Columns:

  • client_id (character varying(80)) The unique identifier of the OAuth client.
  • client_secret (character varying(80)) The secret key of the OAuth client.
  • redirect_uri (character varying(2000)) The URI that the OAuth client will redirect to after authorization.
  • grant_types (character varying(80)) The grant types that the OAuth client supports, such as authorization_code, password, etc.
  • scope (character varying(100)) The scope of access that the OAuth client requests, such as read, write, etc.
  • user_id (character varying(80)) The user identifier that the OAuth client is associated with.
Table: oauth_jwt

OAuth JSON Web Tokens.

Columns:

  • client_id (character varying(80)) The client identifier of the OAuth client that uses JSON Web Tokens.
  • subject (character varying(80)) The subject of the JSON Web Token, usually the user identifier.
  • public_key (character varying(2000)) The public key of the OAuth client that verifies the JSON Web Token signature.
Table: oauth_refresh_tokens

OAuth token expiration.

Columns:

  • refresh_token (character varying(40)) The refresh token that can be used to obtain a new access token.
  • client_id (character varying(80)) The client identifier of the OAuth client that obtained the refresh token.
  • user_id (character varying(255)) The user identifier of the user that authorized the OAuth client.
  • expires (timestamp without time zone) The timestamp of when the refresh token expires.
  • scope (character varying(2000)) The scope of access that the refresh token grants.
Table: oauth_scopes

OAuth scopes.

Columns:

  • scope (text) The name of the OAuth scope, such as read, write, etc.
  • is_default (boolean) The flag that indicates whether the OAuth scope is the default scope for new clients.
Table: rbac_permissions

RBAC permissions.

Columns:

  • alias (character varying(100)) The unique alias of the RBAC permission, used as the primary key.
  • group (character varying(50)) The group that the RBAC permission belongs to, such as Inventory API, Changes API, Events API, Hosts, etc.
  • name (character varying(100)) The name of the RBAC permission, such as Get inventory report, Get event list, etc.
  • description (character varying(200)) The description of the RBAC permission, explaining what it does and why it is needed.
  • application (character varying(50)) The application that the RBAC permission applies to, such as API, Mission Portal, etc.
  • allowed_by_default (boolean) The flag that indicates whether the RBAC permission is allowed by default for new roles, defaults to false.
Table: rbac_role_permission

This table associates roles to permissions in a 1-to-many relationship.

Columns:

  • role_id (character varying) The name of the role that has the permission.
  • permission_alias (character varying) The alias of the permission that the role has.
Table: remote_hubs

Information about federated reporting feeder hubs when federated reporting has been enabled.

Columns:

  • id (bigint) The unique identifier of the remote hub, generated from a sequence.
  • hostkey (text) The host key of the remote hub.
  • ui_name (character varying(70)) The user-friendly name of the remote hub, must be unique among all remote hubs.
  • api_url (text) The URL of the remote hub API, used for communication and data transfer.
  • target_state (character varying(20)) The desired state of the remote hub such as on, paused.
  • transport (json) The JSON object that stores the transport settings of the remote hub with keys such as mode, ssh_user, ssh_host, ssh_pubkey.
  • role (character varying(50)) The role of the remote hub, such as feeder or superhub.
Table: roles

Role definitions that manage host visibility.

Columns:

  • name (text) The name of the role, must be unique and not null.
  • description (text) The description of the role.
  • include_rx (text) The regular expression that matches classes reported by the host governing what the role can see.
  • exclude_rx (text) The regular expression that matches classes reported by the host governing what the role cannot see.
  • changetimestamp (timestamp with time zone) The timestamp of when the role was last change.
  • is_default (boolean) The boolean flag that indicates whether the role is the default role for new users, defaults to false.
Table: scheduledreports

Users scheduled reports.

Columns:

  • username (text) The username of the user who scheduled the report.
  • query (text) The SQL query that defines the report.
  • query_id (text) The unique identifier of the query.
  • run_classes (text) A CFEngine class expression (without ::) such as (January|February|March|April|May|June|July|August|September|October|November|December).GMT_Hr22.Min50_55 describing when the report should be run.
  • last_executed (text) The timestamp of when the report was last executed.
  • email (text) The email address of the user who scheduled the report.
  • email_title (text) The title of the email that contains the report.
  • email_description (text) The description which is present in the email providing the report.
  • host_include (text[]) The array of hosts that the report should include.
  • host_exclude (text[]) The array of hosts that the report should exclude (overriding inclusions).
  • already_run (boolean) The boolean flag that indicates whether the report has already run or not.
  • enabled (boolean) The boolean flag that indicates whether the report is enabled or not.
  • output (text[]) The array of output formats (csv, pdf) that the report should generate.
  • excludedhosts (json) The JSON object that stores the hosts that are excluded from the report.
Table: settings

User settings and preferences for RBAC, host not reporting threshold, collision threshold (duplicate host indicator), and Enterprise API log level. Populated when non-default settings are saved.

Columns:

  • key (text) The Key of the setting.
  • value (json) The value of the setting.
Table: ssh_keys

Generated ssh keys.

Columns:

  • id (bigint) The unique identifier of the ssh key, generated from a sequence.
  • public_key (text) The public key of the ssh key, used for authentication and encryption.
  • private_key (text) The private key of the ssh key, used for decryption and signing.
  • generated_at (timestamp with time zone) The timestamp of when the ssh key was generated, defaults to the current time.
  • generated_by (text) The username of the user who generated the ssh key.
Table: users

User settings (name, email, password, timezone, provenance) and roles associated with the user.

Columns:

  • username (text) The username of the user.
  • password (text) The hashed password of the user.
  • salt (text) The salt used to hash the password of the user.
  • name (text) The name of the user.
  • email (text) The email address of the user.
  • external (boolean) The boolean flag that indicates whether the user is an external user or not, defaults to false.
  • active (boolean) The boolean flag that indicates whether the user is active or not, defaults to false.
  • roles (text[]) The array of roles that the user has, defaults to an empty array.
  • time_zone (text) The timestamp of when the user settings were last changed.
  • changetimestamp (timestamp with time zone) The time zone of the user, defaults to Etc/GMT+0.

SSH keys API

The SSH keys API enables you to generate a key pair that can be used for authorization.

SSH keys API
Generate SSH key

Generates a key with 4096 bits, sha2-512 digest and in rfc4716 (default openssh) format.

URI: https://hub.cfengine.com/api/ssh-key

Method: POST

Example request (curl):

code
curl --user <username>:<password> \
  -X POST \
  https://hub.cfengine.com/api/ssh-key

Successful response example:

code
HTTP 200 Ok
{
    "id": 2,
    "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQC8M3W9juaAvGVqL7j37iukojCAAqwL2KkArlOMJhmEc5xrEs3/v8pz4/tu2sTdCyVjML3PUZUeUZq8dorSUDn1b7co1LpQsAt5z3AF1yLPGtfivEUsBD96G6fCHTsayHZM8yojjHN2gydDDmlvoTntdH3BcOLA2Pw5iUCQrPpXX23DdqOJENDLn67w6H8dqxbObZlt0niJbGwmNNz16lCii0Lf9SYS8SPPsbPprU1zmNKxEzd32PFl1k0544RMdXGWOpt79batVDGrQVooH5ESm08ODFgdSOD6wPMTQ5+VUC7SCLstODEia9f9/ZajFn14rDzC5ICZT/GNrtqWiHjr5TCwsr+V/EfwlEGYl6eRJ5K3MWIZqFXPpLCllZZYw90dA0VW74O7gL6uWWXQQDeRdBvwuJkBSvH+S4UB+VF+f+c55pH37tGf+WLHUc+m26qOrPJUnxTvHWcH09EUh1nELiHs1OZPwc7CF3ijRKIo3Xm3R45YFXREbfOJFb2XYuxBp0OSRAcqy2aVdST1hlt+NZuhtMKLKT30YkwYgkpl52Y0LpReUaG7ENQxvA5/6Js8vTQPjiTLbOw4L8/nDANCtAavytX3BvTJGbJU0VsErJ50I13xIake/owJzKbfxxLJhBNpllZY8IhSquIyl9S851eB743Bbiufpngk8fEPzw== generated-by-cfengine-ssh-api"
}

Responses:

HTTP response code Description
200 OK SSH key successfully created
500 Internal server error Internal server error
Get SSH keys list

URI: https://hub.cfengine.com/api/ssh-key

Method: GET

Example request (curl):

code
curl --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/ssh-key

Successful response example:

code
HTTP 200 OK
[
    {
        "id": 2,
        "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQC8M3W9juaAvGVqL7j37iukojCAAqwL2KkArlOMJhmEc5xrEs3/v8pz4/tu2sTdCyVjML3PUZUeUZq8dorSUDn1b7co1LpQsAt5z3AF1yLPGtfivEUsBD96G6fCHTsayHZM8yojjHN2gydDDmlvoTntdH3BcOLA2Pw5iUCQrPpXX23DdqOJENDLn67w6H8dqxbObZlt0niJbGwmNNz16lCii0Lf9SYS8SPPsbPprU1zmNKxEzd32PFl1k0544RMdXGWOpt79batVDGrQVooH5ESm08ODFgdSOD6wPMTQ5+VUC7SCLstODEia9f9/ZajFn14rDzC5ICZT/GNrtqWiHjr5TCwsr+V/EfwlEGYl6eRJ5K3MWIZqFXPpLCllZZYw90dA0VW74O7gL6uWWXQQDeRdBvwuJkBSvH+S4UB+VF+f+c55pH37tGf+WLHUc+m26qOrPJUnxTvHWcH09EUh1nELiHs1OZPwc7CF3ijRKIo3Xm3R45YFXREbfOJFb2XYuxBp0OSRAcqy2aVdST1hlt+NZuhtMKLKT30YkwYgkpl52Y0LpReUaG7ENQxvA5/6Js8vTQPjiTLbOw4L8/nDANCtAavytX3BvTJGbJU0VsErJ50I13xIake/owJzKbfxxLJhBNpllZY8IhSquIyl9S851eB743Bbiufpngk8fEPzw== generated-by-cfengine-ssh-api",
        "generated_by": "admin",
        "generated_at": "2022-07-06 09:03:31.559311+00"
    },
    {
        "id": 3,
        "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQCkm7yAi4Np5TBl4GGmZ3FDUW3QT/1/1EMimBfzNl8wHggLnImeENwvd/tBmtrt3fbz8IVVnpytspbMlqrejQdhiCORMvNNVmV3q7pdWDgeHccVDiugl16+OS7VvNnU7YzbWcSjcS1KXqGS3p/PWEDgejLRre8Jju9v43DD76A2A6InYuCdQt4cpRoqPhsZiro65UIrUb5VzaKfQlS7vD7wBtrsXmDO0L3YFw4lQMCqISnDNLhG57qtT8kjFXsuKnCTsMnt1QtTqUSuYPFiTdPTjVuAGVNtiRoM7BU3jmxcOs0Y+pwIb3TyO3cK+gbY3+gSsHVLsEfgY9fljtV3iWu+EJMEASCTHgrh4OU3homeT+msS7zpE19covoC8+Qg0Z5dGlWEfgoQ2Y87PqjZZ9j+3KmHJcXvdYfdpXD3UHbwyM1Gfzl6IMK7QqQoyS0QXNM/3GLdiZf5Orf4ZbHRdkBEY/tZlEZSMLA6NVtU2eck6FEOime6/+2lS1Ai9ofgGglq0P5eT5k/eFrhFWy05yvKc1pVe9jjk4wdhHzJ28ffdkgNumDMlrbTKgPaxwIKWTOgMunnHWJZJqm1oJPeLT7OgQN3B1eabxfT/XRo0TA2QCRLR1fNYEzkK/RFQifoWK7tc+k5mshPs6I7ZIAQ7KXS/otccj+5mWjspJoHHAbYgw== generated-by-cfengine-ssh-api",
        "generated_by": "admin",
        "generated_at": "2022-07-06 09:04:53.476701+00"
    }
]

Responses:

HTTP response code Description
200 Ok Successful response
500 Internal server error Internal server error
Get SSH key

URI: https://hub.cfengine.com/api/ssh-key/:id

Method: GET

Parameters:

  • id (integer) SSH key ID. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/ssh-key/2

Successful response example:

code
HTTP 200 OK
{
    "id": 2,
    "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQC8M3W9juaAvGVqL7j37iukojCAAqwL2KkArlOMJhmEc5xrEs3/v8pz4/tu2sTdCyVjML3PUZUeUZq8dorSUDn1b7co1LpQsAt5z3AF1yLPGtfivEUsBD96G6fCHTsayHZM8yojjHN2gydDDmlvoTntdH3BcOLA2Pw5iUCQrPpXX23DdqOJENDLn67w6H8dqxbObZlt0niJbGwmNNz16lCii0Lf9SYS8SPPsbPprU1zmNKxEzd32PFl1k0544RMdXGWOpt79batVDGrQVooH5ESm08ODFgdSOD6wPMTQ5+VUC7SCLstODEia9f9/ZajFn14rDzC5ICZT/GNrtqWiHjr5TCwsr+V/EfwlEGYl6eRJ5K3MWIZqFXPpLCllZZYw90dA0VW74O7gL6uWWXQQDeRdBvwuJkBSvH+S4UB+VF+f+c55pH37tGf+WLHUc+m26qOrPJUnxTvHWcH09EUh1nELiHs1OZPwc7CF3ijRKIo3Xm3R45YFXREbfOJFb2XYuxBp0OSRAcqy2aVdST1hlt+NZuhtMKLKT30YkwYgkpl52Y0LpReUaG7ENQxvA5/6Js8vTQPjiTLbOw4L8/nDANCtAavytX3BvTJGbJU0VsErJ50I13xIake/owJzKbfxxLJhBNpllZY8IhSquIyl9S851eB743Bbiufpngk8fEPzw== generated-by-cfengine-ssh-api",
    "generated_by": "admin",
    "generated_at": "2022-07-06 09:03:31.559311+00"
}

Responses:

HTTP response code Description
200 Ok Successful response
404 Not found SSH key not found
500 Internal server error Internal server error
Delete SSH key

URI: https://hub.cfengine.com/api/ssh-key/:id

Method: DELETE

Parameters:

  • id (integer) SSH key ID. Required.

Example request (curl):

code
curl --user <username>:<password> \
  -X DELETE \
  https://hub.cfengine.com/api/ssh-key/2

Successful response example:

code
HTTP 204 No content

Responses:

HTTP response code Description
204 No content SSH key successfully deleted
404 Not found SSH key not found
500 Internal server error Internal server error

Status and settings REST API

REST API for managing settings, checking hub status.

Get server status

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

Method: GET

Example response:

code
{
  "meta": {
    "page": 1,
    "count": 1,
    "total": 1,
    "timestamp": 1437396760
  },
  "data": [
    {
      "apiName": "CFEngine Enterprise API",
      "apiVersion": "v1",
      "enterpriseVersion": "3.6.4",
      "uiVersion": "ed2766c",
      "coreVersion": "3.6.5",
      "authenticated": "internal",
      "userId": "admin",
      "license": {
        "expires": "2222-12-25 00:00:00+00",
        "owner": "FREE ENTERPRISE - http://cfengine.com/terms for terms",
        "licenseType": "Enterprise Free",
        "granted": 25
      }
    }
  ]
}

Output:

  • apiName Human-friendly API name.
  • apiVersion API version string.
  • enterpriseVersion Version of the CFEngine Enterprise build.
  • uiVersion The internal build number of the Enterprise UI.
  • coreVersion The version of CFEngine Core (Community) the Enterprise version was built against.
  • authenticated ("internal", "external") Whether the request was authenticated using the internal users table or an external source.
  • license.expires Time when the license expires.
  • license.owner The name of the license owner.
  • license.granted Host number capacity granted by the license.
  • license.licenseType License description.

Example usage: Checking status

Get settings

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

Method: GET

Check all settings of Mission Portal and REST API. API call allowed only for administrator.

Example response:

code
{
  "meta": {
    "page": 1,
    "count": 1,
    "total": 1,
    "timestamp": 1350992335
  },
  "data": [
    {
      "hostIdentifier": "default.sys.fqhost",
      "rbacEnabled": true,
      "logLevel": "error",
      "ldapEnabled": true,
      "blueHostHorizon": 900,
      "sameHostsNumberOfRuns": 3
    }
  ]
}

Output:

  • rbacEnabled (boolean) Whether RBAC is applied to requests.
  • hostIdentifier (string) The identfying string for hosts, such as name or IP.
  • ldapEnabled (boolean) Whether external authentication is activated.
  • logLevel ("emergency", "alert", "critical", "error", "warning", "notice", "info", "debug") Syslog filter specifying the severity level at which messages produced by the API should be emitted to syslog and apache.log. (default: error).
  • sameHostsNumberOfRuns (integer) Number of samples used to identify a duplicate identity. Default value is 3.

Example usage: Example: Viewing settings

Update settings

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

Method: POST

Update settings for Mission Portal and API's. API call allowed only for administrator.

Fields:

  • rbacEnabled (boolean) Whether RBAC is applied to requests.
  • hostIdentifier (string) The identfying string for hosts, such as name or IP.
  • ldapEnabled (boolean) Whether external authentication is activated.
  • logLevel ("emergency", "alert", "critical", "error", "warning", "notice", "info", "debug") Syslog filter specifying the severity level at which messages produced by the API should be emitted to syslog and apache.log. (default: error).
  • blueHostHorizon (900) Threshold in minutes that hosts are unreachable before they are considered a health issue.
  • sameHostsNumberOfRuns (integer) Number of samples used to identify a duplicate identity. Default value is 3.

Example Request Body:

code
{
  "hostIdentifier": "default.sys.fqhost",
  "rbacEnabled": false,
  "logLevel": "error",
  "ldapEnabled": true,
  "blueHostHorizon": 900,
  "sameHostsNumberOfRuns": 5
}

Example usage: Example: Configuring LDAP, Example: Changing the log level


Users and access-control REST API

This REST API allows to manage users allowed to use Mission Portal as also Role Based Access Control settings.

List users

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

Method: GET

List all users. API call allowed only for administrator.

Parameters:

  • id (regex string) Regular expression for filtering usernames.
  • external ('true', 'false') Returns only internal users (false) or only external (true), or all if not specified.

Example response:

code
{
  "meta": {
    "page": 1,
    "count": 3,
    "total": 3,
    "timestamp": 1437383957
  },
  "data": [
    {
      "id": "CFE_ROBOT",
      "email": "admin@organisation.com",
      "roles": [
        "admin",
        "cf_remoteagent"
      ],
      "external": false
    },
    {
      "id": "admin",
      "name": "admin",
      "email": "admin@organisation.com",
      "roles": [
        "admin",
        "cf_remoteagent"
      ],
      "external": false
    },
    {
      "id": "user_1",
      "email": "user_1@example.com",
      "roles": [
        "linux_team"
      ],
      "external": false
    }
  ]
}

Output:

  • id User name.
  • email Email address.
  • roles List of assigned RBAC roles.
  • external Is user from external source (LDAP/AD).

Example usage: Example: Listing users

Get user data

URI: https://hub.cfengine.com/api/user/:username

Method: GET

Get info for a specified user. API call allowed only for administrator.

Example response:

code
{
  "meta": {
    "page": 1,
    "count": 1,
    "total": 1,
    "timestamp": 1437385581
  },
  "data": [
    {
      "id": "user_1",
      "name": "",
      "email": "user_1@example.com",
      "roles": [
        "linux_team"
      ],
      "external": false,
      "time_zone": "Europe/Oslo"
    }
  ]
}

Output:

  • id User name.
  • email Email address.
  • roles List of assigned RBAC roles.
  • external Is user from external source (LDAP/AD).
  • time_zone Time zone

Example usage: Example: Retrieving a user

Create new user

URI: https://hub.cfengine.com/api/user/:username

Method: PUT

Parameters:

  • username (string) User name
  • password (string) User password
  • email (string) User email
  • roles (array) User roles, emp: ["admin", "test"]
  • time_zone (string) Time zone

Create a new user. API call allowed only for administrator.

Example Request Body:

code
{
  "email": "user_1@example.com",
  "roles": [
    "linux_team"
  ]
}

Example usage: Example: Creating a new user

Update user

URI: https://hub.cfengine.com/api/user/:username

Method: POST

Update user information. API call allowed only for administrator.

Parameters:

  • username (string) User name
  • password (string) User password
  • email (string) User email
  • roles (array) User roles, emp: ["admin", "test"]
  • time_zone (string) Time zone

Example Request Body:

code
{
  "email": "user_1@example.com",
  "roles": [
    "linux_team"
  ]
}

Example usage: Example: Updating an existing user, Example: Adding a user to a role

Delete user

URI: https://hub.cfengine.com/api/user/:username

Method: DELETE

Remove internal user. API call allowed only for administrator.

Example usage: Example: Deleting a user

List RBAC roles

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

Method: GET

List defined roles for Role Based Access Control. API call allowed only for administrator.

Example response:

code
{
  "meta": {
    "page": 1,
    "count": 3,
    "total": 3,
    "timestamp": 1437391879
  },
  "data": [
    {
      "id": "admin",
      "description": "Admin role"
    },
    {
      "id": "cf_remoteagent",
      "description": "Allow execution of cf-runagent"
    },
    {
      "id": "linux_team",
      "description": "Linux team is responsible for all linux test servers.",
      "includeContext": "linux,test_env",
      "excludeContext": "dev_env|production_env"
    }
  ]
}

Output:

  • id Unique role name.
  • description Role description.
  • includeContext Permit access to hosts that have class set.
  • excludeContext Permit access to hosts that have class not set.
Get RBAC role

URI: https://hub.cfengine.com/api/role/:role_id

Method: GET

Get role definition. API call allowed only for administrator.

Example response:

code
{
  "meta": {
    "page": 1,
    "count": 1,
    "total": 1,
    "timestamp": 1437392992
  },
  "data": [
    {
      "id": "linux_team",
      "description": "Linux team is responsible for all linux servers.",
      "includeContext": "linux"
    }
  ]
}

Output:

  • id Unique role name.
  • description Role description.
  • includeContext Permit access to hosts that have class set.
  • excludeContext Permit access to hosts that have class not set.
Create RBAC role

URI: https://hub.cfengine.com/api/role/:role_id

Method: PUT

Create a new role definition. API call allowed only for administrator.

Fields:

  • description Role description.
  • includeContext Permit access to hosts that have class set.
  • excludeContext Permit access to hosts that have class not set.

Example Request Body:

code
{
  "description": "Linux team is responsible for all linux servers.",
  "includeContext": "linux",
  "excludeContext": "product_a"
}
Update RBAC role

URI: https://hub.cfengine.com/api/role/:role_id

Method: POST

Update role definition. API call allowed only for administrator.

Fields:

  • description Role description.
  • includeContext Permit access to hosts that have class set.
  • excludeContext Permit access to hosts that have class not set

Example Request Body:

code
{
  "description": "Linux team is responsible for all linux servers.",
  "includeContext": "linux",
  "excludeContext": "product_a"
}
Delete RBAC role

URI: https://hub.cfengine.com/api/role/:role_id

Method: DELETE

Remove role definition. API call allowed only for administrator.


VCS settings API

VCS API for managing version control repository settings.

Get VCS settings

URI: https://hub.cfengine.com/api/vcs/settings

Method: GET

Example request (curl):

code
curl -k --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/vcs/settings
'

Example response:

code
{
    "meta": {
        "page": 1,
        "count": 10,
        "total": 1,
        "timestamp": 1535717855
    },
    "data": {
        "GIT_URL": "https://github.com/cfengine/masterfiles.git",
        "GIT_REFSPEC": "master",
        "GIT_USERNAME": "username",
        "GIT_PASSWORD": "passwordOrToken",
        "GIT_WORKING_BRANCH": "CF_WORKING_BRANCH",
        "PKEY": "/opt/cfengine/userworkdir/admin/.ssh/id_rsa.pvt",
        "SCRIPT_DIR": "/var/cfengine/httpd/htdocs/api/dc-scripts",
        "VCS_TYPE": "GIT"
    }
}
Change VCS settings

URI: https://hub.cfengine.com/api/vcs/settings

Method: POST

Parameters:

  • vscType (string) VCS type. Allowed values: GIT, GIT_CFBS. Default value: GIT
  • gitServer (string) Git repository URL Emp: https://github.com/cfengine/masterfiles.git. Required parameter.
  • gitRefspec (string) The Git refspec to checkout. It can be a branch name, a tag name, a commit hash or a partial hash. Required parameter.
  • gitUsername (string) Git username for authentication, not needed for public repositories.
  • gitPassword (string) Git password or token for authentication, not needed for public repositories.
  • gitPrivateKey (string) Git private key raw content for authentication.

Example request (curl):

code
curl -k --user <username>:<password> \
  -X POST \
  https://hub.cfengine.com/api/vcs/settings \
  -H 'content-type: application/json' \
  -d '{
        "gitServer":"https://github.com/cfengine/masterfiles.git",
        "gitRefspec":"master",
        "gitUsername":"gituser",
        "gitPassword":"passwordOrToken",
        "gitPrivateKey" "Private key raw content"
      }
'

Example response:

code
{
    "gitServer": "https://github.com/cfengine/masterfiles.git",
    "gitRefspec": "master",
    "gitUsername": "gituser",
    "gitPassword": "passwordOrToken",
    "gitPrivateKey": "/opt/cfengine/userworkdir/admin/.ssh/id_rsa.pvt"
}
History
  • vscType parameter added in 3.19.0, 3.18.1

Web RBAC API

Web RBAC API for managing role based access control settings.

Get all permissions list

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

Method: GET

Example request (curl):

code
curl -k --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/rbac

Example response:

code
[
    {
        "alias": "Inventory.post",
        "group": "Inventory API",
        "name": "Get inventory report",
        "description": "",
        "application": "API",
        "allowed_by_default": true
    },
    {
        "alias": "VariablesDictionary.get",
        "group": "Inventory API",
        "name": "Get inventory attributes",
        "description": "",
        "application": "API",
        "allowed_by_default": true
    },
    {
        "alias": "variablesDictionaryUpdate.post",
        "group": "Inventory API",
        "name": "Update inventory attributes",
        "description": "",
        "application": "API",
        "allowed_by_default": true
    }
]

Output:

  • alias (string) Alias (ID) of a permission
  • group (string) Group of a permission.
  • name (string) Name of a permission.
  • description (string) Description of a permission.
  • application (string) Application of a permission. Allowed values: API, Mission portal
  • allowed_by_default (boolean) Permission allowed by default. New role will be able to perform allowed by default actions.
Get current user permissions

URI: https://hub.cfengine.com/api/rbac/user-permissions

Method: GET

Example request (curl):

code
curl -k --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/rbac/user-permissions

Example response: [ { "alias": "Inventory.post", "group": "Inventory API", "name": "Get inventory report", "description": "", "application": "API", "allowed_by_default": true }, { "alias": "VariablesDictionary.get", "group": "Inventory API", "name": "Get inventory attributes", "description": "", "application": "API", "allowed_by_default": true }, { "alias": "variablesDictionaryUpdate.post", "group": "Inventory API", "name": "Update inventory attributes", "description": "", "application": "API", "allowed_by_default": true } ]

Get role permissions

URI: https://hub.cfengine.com/api/role/:role_name/permissions

Method: GET

Parameters:

  • role_name (string) Role name

Example request (curl):

code
curl -k --user <username>:<password> \
  -X GET \
  https://hub.cfengine.com/api/role/admin/permissions

Example response:

code
[
    {
        "alias": "Inventory.post",
        "group": "Inventory API",
        "name": "Get inventory report",
        "description": "",
        "application": "API",
        "allowed_by_default": true
    },
    {
        "alias": "VariablesDictionary.get",
        "group": "Inventory API",
        "name": "Get inventory attributes",
        "description": "",
        "application": "API",
        "allowed_by_default": true
    },
    {
        "alias": "variablesDictionaryUpdate.post",
        "group": "Inventory API",
        "name": "Update inventory attributes",
        "description": "",
        "application": "API",
        "allowed_by_default": true
    }
]
Add permissions to role

URI: https://hub.cfengine.com/api/role/:role_name/permissions

Method: POST

Assign new permission to role. Permissions will be added to existing permission list.

Parameters:

  • role_name (string) Role name

  • alias (array) Array of permission aliases Emp: ["Inventory.post", "VariablesDictionary.get"]. Required parameter.

Example request (curl):

code
curl -k --user <username>:<password> \
  -X POST \
  https://hub.cfengine.com/api/role/role_name/permissions \
  -H 'content-type: application/json' \
  -d '["Inventory.post", "VariablesDictionary.get"]'

Example response:

code
HTTP 201 Created
Rewrite role's permissions

URI: https://hub.cfengine.com/api/role/:role_name/permissions

Method: PUT

Assign permission to role. New permissions replace existing.

Parameters:

  • role_name (string) Role name

  • alias (array) Array of permission aliases Emp: ["Inventory.post", "VariablesDictionary.get"]. Required parameter.

Example request (curl):

code
curl -k --user <username>:<password> \
  -X PUT \
  https://hub.cfengine.com/api/role/role_name/permissions \
  -H 'content-type: application/json' \
  -d '["Inventory.post", "VariablesDictionary.get"]'

Example response:

code
HTTP 201 Created
Revoke permissions from role

URI: https://hub.cfengine.com/api/role/:role_name/permissions

Method: DELETE

Parameters:

  • role_name (string) Role name

  • alias (array) Array of permission aliases Emp: ["Inventory.post", "VariablesDictionary.get"]. Required parameter.

Example request (curl):

code
curl -k --user <username>:<password> \
  -X DELETE \
  https://hub.cfengine.com/api/role/role_name/permissions \
  -H 'content-type: application/json' \
  -d '["Inventory.post", "VariablesDictionary.get"]'

Example response:

code
HTTP 204 No Content