Table of Contents
- 1. Introduction
- 2. Authentication
- 3. License information
- 4. Server Load Balancing
- 5. Blacklist Control
- 6. Neighbor Cache
- 7. Rules
- 8. Rules Usage
- 9. Host Monitors
- 10. Route Monitors
- 11. High Availability Status
- 12. DHCP Server Leases
- 13. Statistics Value Retrieval
- 14. Summary Statistics Retrieval
- 15. Updating Databases
- 16. About Information
- 17. Hardware Monitoring
![[Note]](images/note.png) |
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: 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-passWeb 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
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.
To list information about all currently authenticated users, an HTTP GET must be sent to the URI:
/api/oper/userauthThe 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":[]
}
To list information about a single currently authenticated user, an HTTP GET is sent to the URI:
/api/oper/userauthAdditional 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=wanHere, 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.
To add a new authenticated user, the action received by cOS Core should be an HTTP POST to the path:
/api/oper/userauthThis 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/userauthThe 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,group2Note 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"
}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.201The 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.
Using the REST API, details of the license and the current status of subscription based licenses (when applicable) in cOS Core can be retrieved. The information is sent back by cOS Core in JSON format and consists of the values that can also be provided by using the cOS Core CLI license command.
The license shows information about registration key, subscription details and status of subscription based licenses (SECaaS).
Sending the Request
To retrieve license information from cOS Core, an HTTP GET should be sent as follows:
/api/oper/license
SECaaS Specific Information
-
Status can have the values "Running normally", "Local lockdown mode", "Demo mode" and "Reduced functionality mode".
-
When Seconds_until_reduced_mode is set to "-1" then the system is running normally, otherwise it will show the number of seconds until the firewall goes into reduced mode.
An Example JSON Reply
Below is an example of a typical JSON reply for an IP rule set with a single entry: {
"error": false,
"license": {
"registration_key": "1234-1234-1234-1234",
"subscription_based": true,
"issued_date": "2023-10-26",
"lastmodified_date": "2023-10-21 22:04:23",
"expiration_date": "2023-12-01",
"techsupport_date": "2023-12-01",
"idp_date": "2023-12-01",
"av_date": "2023-12-01",
"wcf_date": "2023-12-01",
"di_date": "2023-12-01",
"dcc_date": "2023-12-01",
"incenter_date": "2023-12-01",
"iprep_date": "2023-12-01"
},
"secaas": {
"status": "Running normally",
"server_reached": true,
"last_reached": "2023-10-31 11:52:43",
"last_attempt": "2023-10-31 11:52:42",
"last_result": "License is up to date",
"seconds_until_next_attempt": 14384,
"seconds_until_reduced_mode": -1
}
}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:
-
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.
-
Enable REST API access by creating the appropriate Remote Management object in the cOS Core configuration. Doing this is described in Chapter 1, Introduction.
-
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.
To send the current server load to cOS Core, perform an HTTP POST towards the following URI:
/api/oper/slbThe 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: 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=31When 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%.
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.
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.
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.
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.
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.
To add a blacklist entry, the action received by cOS Core should be an HTTP POST to the URI:
/api/oper/blacklistThe 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/blacklistThe POST body should, at minimum, contain a string in the following form:
host=203.0.113.5By 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-allThe 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": "-"
}
}In order to delete a blacklist entry, the REST API client must send an HTTP DELETE to the URI:
/api/oper/blacklistThe 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.5The 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-allThe 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.
To list all blacklist entries, an HTTP GET should be sent to the URI:
/api/oper/blacklistThe 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=RESTAll 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"
}
]
}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_devicesThe 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
}
]
}Using the REST API, information about configured rules in cOS Core can be retrieved. The information is sent back by cOS Core in JSON format and consists of the values that can also be provided by using the cOS Core CLI, see command example under each rule type section below.
Sending the Request
To retrieve configured rule information, an HTTP GET should be sent. The URI values sent, depending on the type of rule, are as follows:-
IP rules
Contains information about IP rules corresponding to the CLI command rules.
/api/oper/iprules -
IP rulesets
Contains information about IP rules within a specified IP ruleset corresponding to the CLI command rules -type=ip -ruleset=<YourRuleset>.
/api/oper/iprules?ruleset=<YourRuleset> -
IDP rules
Contains information about IDP rules corresponding to the CLI command rules -type=IDP.
/api/oper/idprules -
Threshold rules
Contains information about Threshold rules corresponding to the CLI command rules -type=THRESHOLD.
/api/oper/thresholdrules -
Pipe rules
Contains information about Pipe rules (also known as traffic shaping) corresponding to the CLI command rules -type=PIPE.
/api/oper/piperules -
Routing rules
Contains information about Routing rules (Policy Based) corresponding to the CLI command rules -type=ROUTING.
/api/oper/routingrules
|
Note: Regarding IP Rules and IP Policies |
|---|---|
|
In the background, IP policies consist of one or more IP rules, depending on how they are configured. This is why there is no specific GET command for IP policies. There are two important points to consider in this context. 1. Up to three IP rules can be created for a single IP policy, depending on its configuration. However, each of these IP rules will share the same name as the IP policy. 2. Consequently, the index ID output will not correspond with the IP policy index number as displayed in the Web Interface or InControl. |
An Example JSON Reply
Below is an example of a typical JSON reply for an IP rule set with a single entry:{
"error": false,
"rules": [
{
"index": 1,
"name": "LANtoCORE_Ping",
"filter": {
"src_if": "lan",
"src_net": "192.168.1.0/24",
"dst_if": "core",
"dst_net": "192.168.1.1",
"service": {
"name": "main/1_ICMP_CORE",
"details": "ICMP All"
}
},
"action": "Allow"
},
{
"index": 2,
"name": "GotoExtRuleset",
"filter": {
"src_if": "G4",
"src_net": "192.168.10.0/24",
"dst_if": "core",
"dst_net": "192.168.10.1",
"service": {
"name": "http",
"details": "TCP ALL > 80, 443"
}
},
"action": "Goto",
"goto_ruleset": "ExtRuleSet"
},
{
"index": 3,
"name": "LAN1toWAN_DNS",
"filter": {
"src_if": "lan",
"src_net": "192.168.1.0/24",
"dst_if": "wan1",
"dst_net": "0.0.0.0/0",
"service": {
"name": "main/3_DNS_OUT",
"details": "TCP/UDP ALL > 53"
}
},
"action": "NAT"
}
]
}Using the REST API, the usage (amount of hits on a rule) counter of various rules in cOS Core can be retrieved. The information is sent back by cOS Core in JSON format and consists of the values that can also be provided by using the cOS Core CLI rules command.
Sending the Request
To retrieve the rule usage totals since the last system reconfigure, an HTTP GET should be sent. The URI values sent, depending on the type of rule, are as follows:-
IP Rules
For the main rule set:
/api/oper/usage/iprulesFor a specific named IP rule set:
/api/oper/usage/iprules?ruleset=<rule-set-name> -
IDP Rules
/api/oper/usage/idprules -
Threshold Rules
/api/oper/usage/thresholdrules -
Pipe Rules
/api/oper/usage/piperules -
Routing Rules
/api/oper/usage/routingrules
An Example JSON Reply
Below is an example of a typical JSON reply for an IP rule set with a single entry:{
"error":false,
"rules":[
{
"index":1,
"name":"test_log",
"usage":0
}
]
}Using the REST API, a list of the current cOS Core host monitors with their statistics can be retrieved. The information is sent back by cOS Core in JSON format and consists of the values that might also be provided by using the cOS Core CLI hostmon command.
Sending the Request
To retrieve the host monitor information, an HTTP GET should be sent with the following URI:/api/oper/hostmon
The GET has no optional parameters.
An Example JSON Reply
Below is an example of a typical JSON reply:{
"error":false,
"hostmonitors":
[
{
"session":4,
"host":1,
"reachable":true,
"protocol":"ICMP",
"ip":"192.168.1.11",
"local_ip":"0.0.0.0",
"interval":10000,
"sample":10,
"failed":{"current":0,"max_allowed":2},
"latency":{"current":132,"max_allowed":800},
"source_system":"Route"
}
]
}Using the REST API, a list of cOS Core's current route monitors can be retrieved. The information is sent back by cOS Core in JSON format and consists of the values that might also be provided by using the cOS Core CLI routemon command.
Sending the Request
To retrieve the route monitor information, an HTTP GET should be sent with the following URI:/api/oper/routemon
The GET has no optional parameters.
An Example JSON Reply
Below is an example of a typical JSON reply:{
"error":false,
"routes":[
{"flags":
{"error":false,
"routes":[
{
"flags":["M","F","X"],
"interface":"dmz",
"table":"",
"network":"172.16.10.10",
"gateway":"0.0.0.0",
"metric":100,
"monitors":{"arp":"fail"}
}
]
}
}
]
}Using the REST API, the current status of a cOS Core HA cluster can be retrieved. The information is sent back by cOS Core in JSON format and consists of the values that might also be provided by using the cOS Core CLI ha command.
Sending the Request
To retrieve the HA cluster information, an HTTP GET should be sent with the following URI to one of the peers in the cluster:/api/oper/ha
The GET has no optional parameters.
The Information Retrieved
The following information will be retrieved from the responding firewall:-
If the unit is configured to be a peer in an HA cluster.
-
If the peer is currently the active cluster member.
-
How long the peer has been the active cluster member in seconds.
-
If the peer has been configured as the master or the slave unit in the cluster.
-
If the other cluster peer is considered to be alive and functioning.
An Example JSON Reply
Below is an example of a typical JSON reply:{
"error":false,
"enabled":true,
"status":
{
"active":true,
"time":8,
"role":0,
"role_description":"master",
"peer":{"alive":false}
}
}Using the REST API, a list of cOS Core's current DHCP server leases can be retrieved. The information is sent back by cOS Core in JSON format and consists of the values that might also be provided by using the cOS Core CLI dhcp command.
Sending the Request
To the DHCP information, an HTTP GET should be sent with the following URI:/api/oper/dhcpserver
The GET URI can take the optional parameter of a server name. For example:
/api/oper/dhcpserver?name=DHCP_core
Example JSON Replies
Below is an example of a typical JSON reply for a GET with no option showing leases for all servers:{
"error":false,
"active_leases":[
{
"server":"DHCP_LAN",
"interface":"lan",
"client_ip":"192.168.2.100",
"hostname":"VM-WIN10",
"mac_address":"00-50-56-27-53-0A",
"timeout":787
},
{
"server":"DHCP_core",
"interface":"core",
"client_ip":"192.168.1.203",
"hostname":"eth000000000000",
"mac_address":"00-00-00-00-00-00",
"timeout":754
},
{
"server":"DHCP_core",
"interface":"core",
"client_ip":"192.168.1.202",
"hostname":"eth000000000000",
"mac_address":"00-00-00-00-00-00","timeout":754
}
]
}Below is an example of a typical JSON reply with the named single server option used in the URI for a server called DHCP_core:
{
"error":false,
"dhcpserver":{
"server_name":"DHCP_core",
"pool_usage_count":2,
"pool_size":16,
"pool_usage_percent":18
},
"active_leases":[
{
"server":"DHCP_core",
"interface":"core",
"client_ip":"192.168.1.203",
"hostname":"eth000000000000",
"mac_address":"00-00-00-00-00-00",
"timeout":530
},
{
"server":"DHCP_core",
"interface":"core",
"client_ip":"192.168.1.202",
"hostname":"eth000000000000",
"mac_address":"00-00-00-00-00-00",
"timeout":530
}
]
}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 14, 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/statvaluesBelow 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/cpuloadThis 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=extendedThe 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.
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 13, 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/statsThe 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
}Updating of any of the internal databases can be done by performing an HTTP POST towards the following URI:
/api/updatecenterThe 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"
}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/aboutThe 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"
}Using the REST API, a list of all monitored hardware sensors in the firewall can be be retrieved. The reply is sent back by cOS Core in JSON format and consists of the values that can also be provided by using the cOS Core CLI hwm command.
Sending the Hardware Monitoring request
To retrieve the information, an HTTP GET should be sent to the following URI:/api/oper/hwmThe GET has no optional parameters.
The hwm information returned
The following is a list of the values sent back in the JSON reply:-
name - The name given to the hwm object in cOS Core.
-
value - The current value reported by the configured sensor at the time of the query.
-
min_limit - The minimum value configured (if set).
-
max_limit - The max value configured (if set).
-
unit - The unit type. Temperature (C), Voltage (V), Fan speed (RPM) or GPIO (which returns a blank value for this particular field).
An Example JSON Reply
Below is an example of a typical JSON reply: {
"error": false,
"sensors": [
{
"name": "CPU_Temp",
"value": "51.000",
"min_limit": "0.000",
"max_limit": "100.000",
"unit": "C"
},
{
"name": "Voltage_CMOS",
"value": "3.100",
"min_limit": "2.900",
"max_limit": "3.200",
"unit": "V"
},
{
"name": "CPU_Fan",
"value": "7500.000",
"min_limit": "5000.000",
"max_limit": "8500.000",
"unit": "RPM"
}
]
}