InControl 14.00.06 REST API Guide


Table of Contents

1. Introduction
2. Authentication
2.1. Listing Currently Authenticated Users
2.2. Listing Single Authenticated User Information
2.3. Adding a New Authenticated User
2.4. Ending Authentication of a User
3. Server Load Balancing
3.1. Sending the Server Load to cOS Core Using POST
3.2. Writing the Server Software
3.3. Error Messages from a POST Operation
3.4. cOS Core Generated Log Event Messages
3.5. Viewing Server Status
4. Blacklist Control
4.1. Adding a New Blacklist Entry
4.2. Deleting a Blacklist Entry
4.3. Listing Blacklist Entries
5. Neighbor Cache
6. Statistics Value Retrieval
7. Summary Statistics Retrieval
8. Updating Databases
9. About Information

Chapter 1: Introduction

[Note] Note: This document is also available in other formats

A PDF version of this document along with all current and older documentation in PDF format can be found at https://my.clavister.com.

It is also available in a framed HTML version.

The cOS Core software provides a REST API which allows certain aspects of its operation to be controlled by software running on an external computer.

The REST API functions by an external computer sending HTTP or HTTPS messages to the IP address of a cOS Core Ethernet interface over an IP network. cOS Core then processes the message and returns any reply in an HTTP/HTTPS message. Any data sent in messages uses the JSON format.

[Note] Note: JSON data is shown reformatted for readability

The JSON data sent back by cOS Core will be one continuous stream of characters without white space. The JSON output shown in this publication has been reformatted to make it more readable.

Using HTTP POST

In some cases, cOS Core must receive an HTTP POST from the external system using the REST API. For example, when sending server loading data for server load balancing. It should be noted that when using POST, the content-type header must be set to:
		application/x-www-form-urlencoded

Enabling REST API Access in cOS Core

Allowing access by the REST API must be explicitly configured in cOS Core by creating a RemoteManagementREST object. The properties of this object determine what restrictions are placed on REST API access. These properties include the following:

  • Protocol used (HTTP or HTTPS). Encrypting messages with HTTPS is recommended.

  • The interface to accept connections from external clients on. The external computer will send REST API messages to the IP address of this interface.

  • The source IP(s) to accept connections from external clients on.

  • The access level permitted to clients (read only or read/write).

  • The option to require REST API authentication using a basic access authentication schema with username/password credentials.

An Example of Enabling the REST API

Before the REST API can be used, it must be enabled by creating a REST API Management object in the cOS Core configuration and setting the properties of this object to the appropriate values. The example below shows how this is done.

Example 1.1. Enabling the REST API

This example will create a new REST_managment object called my-rest-api. This will allow read/write HTTPS communication only on the if3 interface and only from the network mgmt-net. Credentials will be required for access with a username of my-admin-name and password of my-admin-pass.

Command-Line Interface

Device:/> add RemoteManagement RemoteMgmtREST
			Name=my-rest-api
			Interface=if3
			Network=mgmt-net
			HTTPS=Yes
			AccessLevel=ReadWrite
			BasicAUTH=Yes
			Username=my-admin-name
			Password=my-admin-pass

Web Interface

  • Go to: System > Device > Remote Management
  • Select Add > REST API Management
  • Enter Name: my-rest-api
  • Enable HTTPS
  • Enter Interface: if3
  • Enter Network: mgmt-net
  • Select Access Level to be Read/Write
  • Enable Basic Auth
  • Enter Username: my-admin-name
  • Enter Password: my-admin-pass
  • Click OK

Chapter 2: Authentication

This section describes the usage of the cOS Core REST API with authentication. When the API is used with authentication, an external computer can perform the following management operations on a cOS Core configuration:

  • List currently authenticated users.

  • Retrieve information for a single currently authenticated user.

  • Add a new authenticated user.

  • End authentication of user.

A REST API Authentication Use Case

A typical use case for the REST API with authentication is where an external DHCP server is handing out IP addresses to clients on a private WiFi network in a public space such as a train station or airport. The clients might access resources such as the public Internet via a Clavister Next Generation Firewall.

As the DHCP server allocates IP addresses, it therefore needs to add and delete and possibly list the authenticated users in cOS Core. This can be done by using the REST API.

The sections that follow describe how to perform these operations.

2.1. Listing Currently Authenticated Users

To list information about all currently authenticated users, an HTTP GET must be sent to the URI:

/api/oper/userauth

The GET can have only the following optional parameter:

  • num - The maximum number of users to return (default value: 100).

cOS Core will send its reply back in JSON format. Below is an example of a reply to a GET:

{
  "error": false,
  "active_users_count": 2,
  "active_users": [
    {
      "username": "user1",
      "ip": "203.0.113.5",
      "groups": "group1,group2",
      "interface": "wan",
      "agent_type": "Identity Awareness",
      "session_timeout": 60,
      "idle_timeout": 60
    },
    {
      "username": "user2",
      "ip": "203.0.113.7",
      "groups": "group4,group5",
      "interface": "wan",
      "agent_type": "Identity Awareness",
      "session_timeout": 160,
      "idle_timeout": 60
    }
  ]
}

In the above JSON reply, there are 2 users listed with usernames user1 and user2. The user called user1 has an IPv4 address of 203.0113.5 and belongs to the groups group1 and group2. The user called user2 has an IPv4 address of 203.0113.7 and belongs to the groups group4 and group5. Both users have connected to cOS Core through the wan interface.

The agent-type value indicates the origin of the authenticated user. If a user was added to the authenticated list with the REST API then its agent-type value will always be "Identity Awareness".

If there are no authenticated users, the response will be the following:

{
  "error":false,
  "active_users_count":0,"active_users":[]
}
		

2.2. Listing Single Authenticated User Information

To list information about a single currently authenticated user, an HTTP GET is sent to the URI:

/api/oper/userauth

Additional parameters are used to identify the user. The action can have the following parameters:

  • ip - The IPv4 address of the user.

  • interface - The cOS Core interface through which the client connected (optional).

For example, to list a user with the IPv4 address 203.0.113.5 that connected through the wan interface, a GET could be sent to the following URI:

/api/oper/userauth?ip=203.0.113.5&interface=wan

Here, the IP address 203.0.113.5 is the IP address of the user and wan is the cOS Core interface that the user has connected to.

The JSON reply sent by cOS Core will have the following form:

{
  "error": false,
  "active_users": [
    {
      "username": "user1",
      "ip": "203.0.113.5",
      "groups": "group1,group2",
      "interface": "wan",
      "agent_type": "Identity Awareness",
      "session_timeout": 60,
      "idle_timeout": 60
    }
  ]
}

The output is similar in form to the output when a list of all authenticated users is retrieved.

If the specified user cannot be found, a JSON message like the following will be returned:

{
  "error":false,
  "active_users_count":5,
  "active_users":[]
}

Here, the active_users parameter has an empty value. Note also that the active_users_count value is the total number of currently authenticated users.

2.3. Adding a New Authenticated User

To add a new authenticated user, the action received by cOS Core should be an HTTP POST to the path:

/api/oper/userauth

This action can have the following parameters:

  • ip - The IPv4 address of the user.

  • username - The username of the client.

  • interface - The cOS Core interface through which the client connected (optional).

  • session_timeout - The session timeout in seconds for this user.

  • groups - A comma separated list of groups to which this user belongs. This is not optional and if there is no group membership then the parameter must be specified without a value.

For example, send a POST to the following URI:

/api/oper/userauth

The POST body should contain a string in the following form:

ip=192.168.1.10&interface=wan&session_timeout=60
&idle_timeout=30&username=user3&groups=group1,group2

Note that the above POST body has been split into 2 lines to fit this document's page width. These last two lines should be a single continuous line.

The parameter idle_timeout is optional. If this is not specified, the assumed value will be the same as session_timeout. Both idle_timeout and session_timeout have a maximum allowed value of one month.

In the above body, the username of the new authenticated user is specified as user2 with an IP address of 192.168.1.10. This user can only connect to cOS Core via the wan interface and they are a member of the groups called group1 and group2. The client session timeout in seconds can be set as required. Here, it is 60 seconds.

The JSON reply sent by cOS Core will confirm that the user has been added and specify the parameter values used for the user. It will have the following form:

{
  "error": false,
  "user": {
    "username": "user1",
    "ip": "192.168.1.10",
    "groups": "group1, group2",
    "interface": "wan",
    "agent_type": "Identity Awareness",
    "session_timeout": 60,
    "idle_timeout": 60
  }
}

If there is an error, cOS Core will return a message indicating the problem. For example, if the interface name is incorrect, the following JSON message would be sent back to the client:

{
  "error":true,
  "error_code":400,
  "error_message":"Property 'interface': Unknown interface name"
}

2.4. Ending Authentication of a User

In order to delete a user from the list of currently authenticated users, the REST API client must send an HTTP DELETE to the URI /api/oper/userauth. The action can have the following parameters:

  • ip - The IPv4 address of the user.

  • interface - The cOS Core interface through which the client connected (optional).

For example, to remove a user with the IP address 192.168.1.201, send a DELETE command to the URI:

/api/oper/userauth?ip=192.168.1.201

The Content-Type for this should be application/x-www-form-urlencoded.

The following JSON reply will be sent back by cOS Core if the deletion is successful:

{
  "error": false
}

If the user was not found, cOS Core will return the following JSON message:

{
  "error": true,
  "error_code": 404,
  "error_message": "User does not exist"
}

The above message indicates that there is no user with the given IP address (and optionally the given interface) is currently authenticated.

Chapter 3: Server Load Balancing

This section describes the usage of the REST API to control the server load balancing (SLB) feature in cOS Core. When the REST API is used with SLB, the load balanced servers can send back their loading information so cOS Core can allocate connections across the servers appropriately. This means that a new connection can be allocated to the server with the least load.

The need for this feature usually comes from the uneven server distribution that can arise due to "stickiness" with the cOS Core SLB feature. Stickiness can mean that connections from a particular client are always assigned to a particular server, even though SLB has tried to allocate the load evenly.

Having the REST API feature for SLB means that cOS Core can be aware of the actual load experienced by servers so that allocation decisions can be made using more than just the number of connections.

Configuring SLB to make use of the REST API consists of the following steps:

  1. Create custom software which then runs on each of the servers to be balanced. This software uses the REST API to send back load information to cOS Core. The server load is expressed as a single integer percentage between zero and 100.

  2. Enable REST API access by creating the appropriate Remote Management object in the cOS Core configuration. Doing this is described in Chapter 1, Introduction.

  3. Create a cOS CoreServer Load Balancing Rule object which uses Resource-usage as its distribution method. The Server Identifier string property of this rule must be included with the POST messages sent by servers so they can be associated with the rule in conjunction with the server's IP address.

    Doing this is described further in the server load balancing section of the separate cOS Core Administration Guide.

3.1. Sending the Server Load to cOS Core Using POST

To send the current server load to cOS Core, perform an HTTP POST towards the following URI:

/api/oper/slb

The POST message body can contain the following parameters:

  • serverID - A string which is identical to the Server Identifier property of an SLB Rule in the receiving cOS Core configuration. This is mandatory. Along with the serverIP parameter, it associates an SLB Rule with the server.

  • serverIP - The IP address of the sending server. This is mandatory. Along with the serverID parameter, it associates an SLB Rule with the server.

  • maintenance - This can take the values yes or no. It indicates if the server is in service or not and provides a means for the server to temporarily make itself unavailable by using the value yes. A value of no means the server is available and this will make the server available to cOS Core for balancing if it is not already. The parameter can be missing when reporting a load and the online status is not changing.

  • load - This is an integer which represents the current percentage of server load. This parameter can be omitted if the message is changing the maintenance value (either going offline, or coming back online). If it is omitted when the server is going online, cOS Core will assume a load of zero.

[Note] Note: maintenance and/or load must be present

All SLB POST messages must have either maintenance or load present, or both. The message is invalid if neither is present.

Both could be present when a server is both reporting its load and changing its status (such as when it comes online and reports its load).

For example, to send a load value of 31% for a server with an IP address of 192.168.1.10 and an associated SLB rule identifier of serverA, the POST body would contain the following:

serverID=serverA&serverIP=192.168.1.10&maintenance=no&load=31

3.2. Writing the Server Software

When writing the software that uses the REST API, the following should be noted about the way REST API POST messages are handled by cOS Core:

  • cOS Core must receive at least one POST message per minute. If no message has been received for one minute, the server is considered to be unavailable and no connections are allocated to it. The next POST message it sends will make it available again (provided the maintenance is set to no).

  • There is no upper limit how often a server can send a POST message. However, messages sent in excess of one every second will not improve load distribution and will only consume resources on the server and the firewall.

  • It is recommended to only send a POST message when there is a significant change in the server load. A load change equal to or greater than 3% is recommended for a typical deployment.

  • If the load remains stable then a POST message should be sent anyway at least every 15 seconds so that cOS Core continues to view the server as available and has an accurate view of the load.

  • Until it receives at least one POST message from all servers after the last system start, cOS Core will use the round robin algorithm to allocate connections between servers. Once all servers have reported their loading, it will begin to allocate connections to the least loaded server.

  • When the server sends back a load of 100%, connections could still be allocated to it if it has the least "estimated" load of all servers when all have reported 100% loading. When cOS Core allocates connections to servers it adjusts up its estimation of the loading to account for the connections added since the last time the server reported its load. In this way, cOS Core could estimate that a server's load is above 100%.

3.3. Error Messages from a POST Operation

If the POST is accepted, the JSON response sent back by cOS Core will be the following:

{
  "error":false
}

If there is an error, cOS Core will return a message indicating the problem. For example, the following JSON message might be returned to the client:

{
  "error":true,
  "error_code":400,
  "error_message":"Bad Request, malformed"
}

The following is a complete list of POST error messages:

  • malformed - The body has an error in its syntax.
  • no server identifier parameter - The serverID parameter is missing.
  • no server address parameter - The serverIP parameter is missing.
  • missing parameter - Either the load or maintenance parameter is missing.
  • load out of range - The load value is not between 0 and 100.
  • unknown server - No SLB rule matches the serverIP/serverID combination.

3.4. cOS Core Generated Log Event Messages

The following SLB REST API related log event messages are generated by cOS Core:

  • Malformed request sent to the SLB handler in REST API.
  • The specified SLB server identifier and ip not configured.
  • SLB Server <server_ip> is not reporting load.
  • SLB Server <server_ip> is entering maintenance mode.
  • SLB Server <server_ip> is leaving maintenance mode.

In the messages above, the parameter <server_ip> is the actual IP address of the server. These messages are fully described in the separate cOS Core Log Event Reference Guide.

3.5. Viewing Server Status

The load status that servers send back when using the REST API can be viewed in the cOS Core web interface by going to the Server Load Balancing Status page of the interface. An example screenshot of this page with the REST API in operation is shown below.

Web Interface SLB Status Page

Figure 3.1. Web Interface SLB Status Page

If a server did not send a Post message within the last minute, the Errors column in the above screenshot would have shown the value REST for that server.

The Pause button in the Maintenance column of this WebUI display can be used to remove a server from being available for connection distribution. However, the server itself will not be aware when this is done and this is also independent from the API. Any existing connections to a server will not be closed by cOS Core when the pause button is pushed for that server.

However, note that new connections could still be allocated to a paused server in order to to comply with the requirement for SLB stickiness, if stickiness is enabled. Stickiness is explained further in the SLB section of the separate cOS Core Administration Guide.

Chapter 4: Blacklist Control

This section describes the usage of the cOS Core REST API to change and list the contents of a configuration's blacklist. This section will not describe how the blacklist feature itself functions but only how the REST API is used to interact with it. A full description of the blacklist can be found in the separate cOS Core Administration Guide in the section titled Blacklisting Hosts and Networks.

The REST API allows an external computer to perform the following management operations on a cOS Core configuration:

  • Add a new entry to the blacklist to block a single source IPv4 address (and optional service).

  • Delete a blacklist entry previously added by the REST API.

  • List all entries in the blacklist or entries of a specific alert type.

Note that the API can only delete blacklist entries that were first added by the API. Entries created by configured cOS Core features, such as IDP and threshold rules, cannot be altered by the API.

However, when retrieving a list of blacklist entries using the API, all entries are returned, including those not added by the API. It is possible when retrieving a list of entries to use a filter so that only the entries of a certain type are retrieved and doing this is described later in this section.

The typical use case for adding and deleting blacklist entries is when a separate network component identifies an IP address as the source of a threat and needs to have a Clavister Next Generation Firewall drop connections initiated by that address.

Visibility of REST API Changes for the cOS Core Administrator

Any changes made to the blacklist using the REST API are visible to the administrator when the blacklist is listed in a management interface such as the Web Interface (WebUI) or CLI.

In addition, a cOS Core user with administrator privileges has the ability to delete blacklist entries that were added using the REST API. However, the API cannot delete entries not created through the API.

4.1. Adding a New Blacklist Entry

To add a blacklist entry, the action received by cOS Core should be an HTTP POST to the URI:

/api/oper/blacklist

The action can have the following parameters:

  • host - The single source IPv4 address to be blacklisted. (Required.) This must be a single IP address, not a range or network.

  • service - The service associated with the entry. The value specified should be the name of a Service object defined in the cOS Core configuration. A "400 Bad Request" message is returned if it is not a valid service name. (Optional with an default value of all_services.)

  • ttl - The time-to-live in the blacklist in seconds. (Optional with a default value of 300 seconds.)

  • rule_name - The rule name associated with the entry. This arbitrary text data which can be used to store some value meaningful to the API client. It has no meaning for cOS Core but will be stored in the blacklist and appear in a listing of entries. (Optional with an empty default value.)

  • close_established - Close any established connections that originate from this IP address. (Optional.) If specified, this must have a value of yes or no. If not specified, the default value is no.

  • description - A textual description for the entry. (Optional with an empty default value.)

For example, to blacklist the IPv4 address 203.0.113.5, send a POST to the following URI:

/api/oper/blacklist

The POST body should, at minimum, contain a string in the following form:

host=203.0.113.5

By default, this adds a blacklist entry with the service set to all_services. If, for example, the blacklist entry is only to apply to HTTP and HTTPS traffic then the http-all service would be specified as an additional parameters in the POST body:

host=203.0.113.5&service=http-all

The JSON reply sent by cOS Core will confirm that the entry has been added and specify all the parameter values used. It will have the following form:

{
  "error": false,
  "blacklist_entry": {
    "host": "203.0.113.5",
    "service": "http-all",
    "ttl": "300",
    "rule_name": "-",
    "description": "-"
  }
}

4.2. Deleting a Blacklist Entry

In order to delete a blacklist entry, the REST API client must send an HTTP DELETE to the URI:

/api/oper/blacklist

The action can have the following parameters:

  • host - The host IP address to blacklist. (Required.)

  • service - The service associated with the entry. (Optional with a default value of all_services.)

As mentioned previously, a DELETE operation can only remove a blacklist entry that was previously added by the REST API. It cannot remove an entry that was added by a cOS Core feature such as IDP or threshold rules.

For example, to remove any entry with the IP address 203.0.113.5, send an HTTP DELETE to the URI:

/api/oper/blacklist?host=203.0.113.5

The Content-Type for this should be application/x-www-form-urlencoded.

The service parameter can be added to delete a previously added blacklist entry with a specific service. For example, to delete the entry with the IPv4 address 203.0.113.7 and service http-all. send a DELETE command to the following URI:

/api/oper/blacklist?host=203.0.113.5&service=http-all

The following JSON reply will be sent back by cOS Core if the deletion is successful:

{
  "error": false
}

Note that every blacklist entry has a service associated with it and the delete operation will only delete an entry that has an exact match with the specified combination of IP address and service. If the service parameter is specified as all_services (the default) then this would not delete an entry that has a service of http-all.

4.3. Listing Blacklist Entries

To list all blacklist entries, an HTTP GET should be sent to the URI:

/api/oper/blacklist

The GET has only a single optional parameter with is alert_type. The alert_type restricts the listed entries to a particular source. All blacklist entries added using the REST API will have an alert_type value of "REST". If the alert_type parameter is not specified then all entries will be retrieved.

For example, to retrieve all entries created by the REST API then the alert-type filter should be set to the value "REST":

/api/oper/blacklist?alert_type=REST

All the possible values for the parameter alert_type can be found under the -alerttype option in the section for the command blacklist in the separate cOS Core CLI Reference Guide. It should be noted that the value "ALL" is not a valid alert_type with the REST API but this is the default if the alert_type parameter is not specified.

cOS Core will send back its reply to a GET in JSON format. Below is an example of a typical reply:

{
  "error": false,
  "blacklist_count": 2,
  "blacklist_hosts": [
    {
      "host": "203.0.113.5",
      "service": "",
      "ttl": "300",
      "alert_type": "REST",
      "rule_name": "-",
      "description": "api added"
    },
    {
      "host": "203.0.113.7",
      "service": "http-all",
      "ttl": "100",
      "alert_type": "REST",
      "rule_name": "-",
      "description": "api added"
    }
  ]
}

Chapter 5: Neighbor Cache

Using the REST API, a summary of the devices directly connected to the firewall can be retrieved. This has similarities with a listing of the ARP cache but provides extra information about each device. The device information is sent back by cOS Core in JSON format. This same information can also be retrieved by using the neighborcache CLI command with various command options.

Sending the Neighbor Cache Request

To retrieve the neighbor cache information, an HTTP GET should be sent to the following URI:

/api/oper/neighbor_devices

The GET has no optional parameters.

The Statistics Retrieved

The following is a list of the possible values sent back in the JSON reply:

  • interface - The name of the interface on which the external device is found.

  • ethernet_address - The MAC address object of the external device.

  • ethernet_object - Configuration object matching the MAC address (optional).

  • ethernet_vendor - The vendor name matching the MAC address (optional).

  • ipv4 - The IPv4 address for this device (optional).

  • ipv6 - The IPv6 address for this device (optional).

  • authenticated_user - The authenticated username for this IP address (optional).

  • hostname - DHCP hostname (optional).

  • status - Current status of the entry.

  • last_seen - Number of seconds since last seen (optional). This value will appear only if the status is Inactive.

When one of the above values is indicated as optional, this indicates that the value will not be present if it is either unavailable or not relevant.

The ethernet_object is the name of the first EthernetAddress object found in the cOS Core address book that has a MAC address matching the MAC address of the external device. If no such object is found then the value will not be included in the JSON reply. The EthernetAddress object will have to be first created manually by the administrator with the relevant MAC address.

The hostname value may be included in the JSON reply if the external device was allocated its IP address by cOS Core acting as a DHCP server. The hostname will be the name sent by the external device in its DHCP request for an IP address. If it did not send a name in the request the hostname value will not be included.

An Example JSON Reply

Below is an example of a typical JSON reply:

{
  "error": false,
  "devices": [
    {
      "interface": "wan",
      "ethernet_address": "00-50-8B-D9-16-5E",
      "ethernet_vendor": "Clavister",
      "ipv4": "203.0.113.6",
      "status": "Active"
    },
    {
      "interface": "dmz",
      "ethernet_address": "F8-B2-53-CF-2B-CD",
      "ethernet_object": "my-pc",
      "ethernet_vendor": "Example Corp.",
      "ipv4": "10.6.19.1",
      "status": "Inactive",
      "last_seen": 2
    }
  ]
}

Chapter 6: Statistics Value Retrieval

This feature of the REST API is to designed to provide retrieval of all or a selected set of the available cOS Core statistical values in real time. This is similar to the capabilities that an SNMP client might provide. The information is sent back by cOS Core in JSON format.

This feature has some overlap with the retrieval described in Chapter 7, Summary Statistics Retrieval but differs in that it can provide all of the several hundred available statistics or a given subset of them.

Retrieving All Available Statistics

To retrieve all of the available statistical values, an HTTP GET should be sent to the following URI with no parameters:

/api/oper/statvalues

Below is an example of the beginning of a typical JSON reply to a GET with no parameters:

{
  "error": false,
  "values": {
    "core/uptime": 157345,
    "core/cpuload": "2.00",
    "core/fwdbps": 0,
    "core/fwdpps": 0,
    "core/bufusage": "45.00",
    "core/conns": 0,
    "core/timers": 64,
    "core/connrate/conn_opened": 0,
           "
           "
           "
  }
}

Adding a Filter

The complete statistics list consists of many hundreds of values and often only a subset of these may be required. To achieve this, the GET can have an optional filter added which requests a single statistic or a comma separated list of statistics. For example:

/api/oper/statvalues?filter=core/uptime,core/cpuload

This would give a truncated version of the previous output:

{
  "error": false,
  "values": {
    "core/uptime": 157345,
    "core/cpuload": "2.00"
  }
}

Showing Extended Details

The GET can return extended information about all or selected statistics by adding the show=extended option. For example:

/api/oper/statvalues?filter=core/uptime,core/cpuload&show=extended

The following example illustrates the extended JSON reply that will be received:

{
  "error": false,
  "values": {
    "core/uptime": {
      "unit": "seconds",
      "description": "Uptime",
      "value": 94
     },
     "core/cpuload": {
       "unit": "%",
       "description": "CPU",
       "value": "5.00"
     }
  }
}

Statistics Filter Names

It should be noted that statistic names fall into one of two categories:

  • Statistic names that are not configuration dependent

    These are the statistics that are available from all cOS Core configurations and do not change across the underlying computing platform. Some examples related to the rate that connections are opened and closed are listed below:

    core/connrate/conn_opened
    core/connrate/conn_closed
    core/connrate/conn_replaced
  • Statistic names that are configuration dependent

    These are the statistics that depend on the cOS Core configuration or the underlying computing platform. For example, if a particular configuration has an If1 Ethernet interface, the following names will be valid for retrieval of the statistics related to that interface:

    ifaces/If1/recvpps
    ifaces/If1/sentpps
    ifaces/If1/totpps
    ifaces/If1/recvbps
    ifaces/If1/sentbps
    ifaces/If1/totbps
    ifaces/If1/drops
    ifaces/If1/errin
    ifaces/If1/sendfails
    ifaces/If1/fragsin
    ifaces/If1/fragreassok
    ifaces/If1/fragreassfail

The names of the statistics used for the GET filter have some similarity with the names used in the cOS Core SNMP MIB file. However, not all statistics in the MIB file can be retrieved using the REST API. Conversely, there are some statistics that can be retrieved by the REST API but which cannot be retrieved using SNMP.

Chapter 7: Summary Statistics Retrieval

Using the REST API, the current values of a range of key cOS Core operational parameters can be retrieved which summarize the current state of the firewall. The information is sent back by cOS Core in JSON format and consists of the values normally provided by the cOS Core CLI stats command plus some additional information.

Note that if more detailed individual statistics are required then the retrieval method described in Chapter 6, Statistics Value Retrieval should be used.

Sending the Statistics Summary Request

To retrieve a summary of key statistical values, an HTTP GET should be sent to the following URI:

/api/stats

The GET has no optional parameters.

The Summary Statistics Retrieved

The following is a list of the statistical values sent back in the JSON reply:

  • System uptime since the last restart.
  • Time of last system event such as a version updgrade.
  • Current CPU load as a percentage.
  • Memory installed, free and maximum free (bytes).
  • Number of allocated and active connections.
  • Current packet fragments that are allocated, lingering and active.
  • Buffer sizes that are allocated, free and total allocation (bytes).
  • Packet fragment buffer size allocated and total allocation (bytes).
  • Number of cores used for polling.
  • If the unit is under InControl management.

An Example JSON Reply

Below is an example of a typical JSON reply:

{
  "error": false,
  "uptime": {
     "seconds_total": 191,
     "days": 0,
     "hours": 0,
     "minutes": 3,
     "seconds": 11
  },
  "last_event": "2018-02-06 18:23:49: Firmware upgrade
            request from WebUI by admin (192.168.1.11).",
  "cpu_load": 14,
  "memory": {
    "installed": 2137166035,
    "free": 1807419356,
    "largest_free": 1696489544
  },
  "connections": {
  "allocated": 256000,
  "active": 7
  },
  "fragments": {
    "allocated": 1024,
    "active": 0,
    "lingering": 0
  },
  "buffers": {
    "allocated": 24617,
    "free": 23590,
    "memory": 33058800,
    "out_of_buffers": 0
  },
  "fragbufs": {
    "allocated": 32,
    "memory": 322048
  },
  "active_poll_cores": 1,
  "incontrol_status": "Not Configured
}

Chapter 8: Updating Databases

Updating of any of the internal databases can be done by performing an HTTP POST towards the following URI:

/api/updatecenter

The POST body can contain only one of the following options:

  • To force an update of the IDP database:

     update=idp
  • To force an update of the antivirus database:

     update=antivirus
  • To force an update of the IP reputation database:

     update=ipreputation

If the POST is accepted, the JSON response sent back by cOS Core will be the following:

{
  "error":false
}

If there is an error, cOS Core will return a message indicating the problem. For example, the following JSON message might be returned to the client:

{
  "error":true,
  "error_code":400,
  "error_message":"Bad Request, malformed"
}

Chapter 9: About Information

Using the REST API, a program running on an external computer is able to retrieve the version of cOS Core that is currently running, as well as information about the underlying computing platform. The reply is sent back by cOS Core in JSON format.

Sending the About Request

To retrieve the information, an HTTP GET should be sent to the following URI:

/api/about

The GET has no optional parameters.

The About Information Returned

The following is a list of the values sent back in the JSON reply:

  • error - This is false if the request was successful.

  • version - The full version number of the cOS Core software.

  • version_numbers - The version number broken down into its parts.

  • buildtype - This usually has the value Release unless the version a technical preview.

  • vendor- The system vendor. This will usually be Clavister.

  • product - The name of the system software. This will usually be cOS Core.

  • model - The platform on which the software is running.

  • device_name - The name that has been assigned to the device.

    The default name will be Device if it has not been previously changed.

An Example JSON Reply

Below is an example of a typical JSON reply:

{
  "error": false,
  "version": "12.00.12.03-12345",
  "version_numbers": [
     12,
     0,
     12,
     3,
     12345
  ],
  "buildtype": "Release",
  "vendor": "Clavister",
  "product": "cOS Core",
  "model": "E10",
  "device_name": "MyDevice"
}