EXWui REST API Documentation

Base URL: /rest, Version: 2.2.5 (rev.: 1-WpQuYw)

Description of the public REST API interfaces of the Cubro Packetmaster devices.

Some notes:

Path

An URL as used by REST is made up of the scheme (e.g. "http"), the host (e.g. "192.168.0.200"), the base path (here "/rest") and the specific path (e.g. "/rules/all"), this results in e.g. http://192.168.0.200/rest/rules/all.

Dynamic Parameters

In this document, parameters/Keys written in all-caps and in parentheses (e.g. '(EXAMPLE)') are placeholders for keys with dynamic names. Three dots after it '...' additionally indicate that multiple such fields are expected.

Parameter Casing

Most parameters are in snake case (e.g. "snake_case") but some can also be addressed using camel case (camelCase) or lower case (lowercase).

JSON parameter format

All function using the default HTTP parameter format also support JSON as an input format format if the content type of the request is "application/json". x=1 is equivalent to {"x":1}, x[]=1&x[]=2 to {"x":[1,2]}, and x[a]=1 to {"x":{"a":1}}.

Authentication and Access Checks

If UAC (user authentication and access control) is activated the REST interface can only be used if authenticated through an existing web UI user account. Authentication is possible through either HTTP basic authentication or by setting the parameters 'username' and 'password'. Note that the console and web/REST users are totally seperate. The default web/REST user account has the username 'admin' and password 'cubro' (both without quotes).

An user account has a certain access level and REST methods might have minimum level required. Three user level exist: READ (1), WRITE (7) and SUPER (31); in the brackets are the numeric representations. Every level encompasses the levels below it. A user is at least level 1 (READ).

Types

Sometimes, multiple types are possible for a parameter or returned in a response, the type mentioned here always represents the most likely type used, e.g. a numeric value for throughputs even if it can be 'n/a' in case the port does yet not exist for long enough.

Errors

Errors are normally returned using an error object with an 'error' field but in some cases it is possible that it is actually simply in the 'result' field of an result object. This is normally only the case if the error is not likely to be dire for the user.

HTTP Methods

Instead of using the HTTP methods PUT/DELETE there is the possibility of using POST together with the HTTP header X-HTTP-Method-Override:<METHOD> (where <METHOD> stands for the PUT/DELETE to represent) instead.

Default response content-types: application/json
Schemes: http

Summary

PathOperationDescription
/appsDELETE

Stops a running app

GET

Returns all apps

POST

Starts an app

PUT

Modifies the parameters of an app instance

/apps/actionPOST

Calls a custom app action

/apps/runningGET

Returns all app instances

/device/controllerDELETE

Deletes the given controller.

GET

Returns the configured controller

POST

Adds the given controller.

/device/customidentGET

Returns the device label and notes

POST

Sets the device label and device notes

/device/dpidGET

Returns the device Openflow Datapath ID

/device/environmentGET

Returns environment information

/device/generationGET

Returns the generation

/device/grouphashGET

Returns a map of all supported group select hash keys and their states

POST

Sets whether certain group select hash keys should be used or not

/device/httpsPOST

Sets the HTTPS setting

/device/idledGET

Gets the device ID LED status

POST

Sets the device ID LED

/device/imageversionGET

Returns the version of the active image

/device/ipconfigGET

Returns the IP config

POST

Sets the IP config

/device/loadaverageGET

Returns load information

/device/memoryusageGET

Returns memory usage

/device/modelGET

Returns the device model

/device/nameGET

Returns the device label

POST

Sets the device label

/device/nameresolutionGET

Sets name resolution settings

POST

Sets the name resolution settings.

/device/permanentrulesmodeGET

Returns state of permanent mode

POST

Sets the permanent mode

/device/rebootPOST

Device reboot

/device/restartwebserverPOST

Restarts the webserver without a reboot.

/device/rulestoragemodeGET

Returns the rule storage mode setting

POST

Sets the rule storage mode

/device/serialnoGET

Returns the serial number

/device/serverrevisionGET

Returns the revision

/device/setlicensePOST

Adds a license for this device

/device/telnetGET

Gets the device ID LED status

POST

Gets the device ID LED status

/flownumbersGET

Returns the maximum and currently used amount of TCAM flows

/groupsDELETE

Deletes a group

POST

Adds a group

PUT

Modifies a group

/groups/allDELETE

Deletes all active groups

GET

Returns all currently active groups on the device

/ports/configGET

Returns port configurations

POST

Configures a port

/ports/infoGET

Returns status of the ports

/ports/sfpstatusGET

Returns information about the SFPs

/ports/statsGET

Returns the counters of all ports

/rulesDELETE

Deletes a rule

POST

Adds a rule

PUT

Modifies a rule

/rules/allDELETE

Deletes all rules

GET

Returns all rules

/rules/countersDELETE

Resets all rule counters

/savepointsGET

Returns all rule and port save-points

/savepoints/activeportsavepointPUT

Activates a port save-point

/savepoints/activerulesavepointPUT

Activates a rule save-point

/savepoints/defaultrulesavepointPUT

Sets a rule save-point to be loaded on boot

/savepoints/exportGET

Returns selected rule and port save-points

/savepoints/modportsavepointPOST

Modifies an existing port save-point

/savepoints/modrulesavepointPOST

Modifies an existing rule save-point

/savepoints/portsavepointDELETE

Deletes a port save-point

POST

Creates a new port save-point from current port settings

/savepoints/quicksaverulesPUT

From current rules/groups creates a 'Quicksave' rule save-point set to load on boot

/savepoints/rulesavepointDELETE

Deletes a rule save-point

POST

Creates a new rule save-point from current rules/groups

/usersDELETE

Deletes an user

GET

Returns all users

POST

Adds an user

PUT

Modifies an user

/users/radiusGET

Gets the RADIUS config

POST

Sets the RADIUS config

/users/uacGET

Returns the UAC state

POST

Sets the UAC state

/weblogDELETE

Deletes the logs

GET

Returns the logs

Security

Read_Rights_Required

Type: basic
Description:

Read-only access to everything. Any user has at least this rights level.

Numeric level: 1

Write_Rights_Required

Type: basic
Description:

Can add/​change/​remove rules/​groups/apps, add/​change/​remove rule save-points and set them as load-on-boot, reset counters, and change group hashing methods used.

Numeric level: 7

Super_Rights_Required

Type: basic
Description:

Can do everything, therefore has the ability to e.g. change port settings, add/​change/​remove port save-points, import save-points, upgrade/​reboot device, change IP/​label/​description, add/​change/​remove users, enable/​disable user access checks and change any setting/​mode like the special protocol transparency settings.

Numeric level: 31

Paths

Stops a running app

DELETE /apps

Stops an app instance. User level has to be higher or equal to WRITE.

pid

PID of the app instance to be killed.

queryinteger

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Write_Rights_Required
Returns all apps

GET /apps

Returns a list of all available apps

Uses default content-types: application/json

200 OK

Map with apps with the keys being the app names. (APPNAME) is a placeholder for the unique name of the app.

(APPNAME): App
default

Error state.

Starts an app

POST /apps

Starts an available app, creating a new instance. User level has to be higher or equal to WRITE.

name

Name of the app to start an instance of.

querystring
user_description

Custom description for the new instance of the app.

querystring
(PARAM)...

(PARAM) is a placeholder for any app-specific parameter.

querystring

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Write_Rights_Required
Modifies the parameters of an app instance

PUT /apps

Modifies the parameters of an already running app. User level has to be higher or equal to WRITE.

pid

PID of the app instance.

queryinteger
user_description

Custom description for the new instance of the app.

querystring
(PARAM)...

App parameter to change. (PARAM) is a placeholder for any app-specific parameter.

querystring

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Write_Rights_Required
Calls a custom app action

POST /apps/action

Calls a custom app action. An user level as required by the app might be necessary.

pid

PID of the app instance

queryinteger
action_name

Name of the action to be called.

querystring

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Returns all app instances

GET /apps/running

Returns all running apps (app instances)

Uses default content-types: application/json

200 OK

Map with app instances with the keys being the PIDs. (PID) is a placeholder for the unique ID of an app instance.

(PID): App
default

Error state.

Deletes the given controller.

DELETE /device/controller

Deletes the given controller. User level has to be higher or equal to SUPER.

connection

Connection type of the controller. Either "tcp" or "ssl"

querystring
ip

IP address of the controller.

querystring
port

TCP port of the controller.

querystring

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Super_Rights_Required
Returns the configured controller

GET /device/controller

Returns the configured controller details

Uses default content-types: application/json

200 OK

Configured controller details

connection: string

tcp or ssl

ip: string
port: integer
role: string
status: string
default

Error state.

Adds the given controller.

POST /device/controller

Adds the given controller. User level has to be higher or equal to SUPER.

connection

Connection type of the controller. Either "tcp" or "ssl"

querystring
ip

IP address of the controller.

querystring
port

TCP port of the controller.

querystring

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Super_Rights_Required
Returns the device label and notes

GET /device/customident

Returns the web UI device label and notes.

Uses default content-types: application/json

200 OK

Device label and notes.

name: string

Device label.

notes: string

Device notes.

default

Error state.

Sets the device label and device notes

POST /device/customident

Sets the device label and device notes used in the web UI.

User level has to be higher or equal to SUPER.

name

New device label.

querystring
notes

New device notes.

querystring

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Super_Rights_Required
Returns the device Openflow Datapath ID

GET /device/dpid

Returns the device Datapath ID.

Uses default content-types: application/json

200 OK

Datapath ID.

name: string
default

Error state.

Returns environment information

GET /device/environment

Returns various information about physical characteristics, namely status of the fans, PSU and temperature sensors.

Uses default content-types: application/json

200 OK

Load information.

fan: object[]
object
index: string
status: string

Information about the status of the fan unit.

speed_rate: string

Speed rate of the fan in percent.

mode: string

Information about the running mode of the fan.

psu: object[]
object
index: integer
status: string

Information about whether the PSU is present or not. Can be either PRESENT or ABSENT.

power: string

Information about the power state of the PSU. Can be either OK, FAIL or - (latter if the PSU is absent).

type: string

Information about the type of the PSU. Can be either AC, DC or - (if the PSU is absent or unplugged).

alert: string

Information about whether the PSU is in an alert state. Can be either NO (everything is running fine) or ALERT (power failure).

temp_sensors: object[]
object
index: integer
temp: integer

Current temperature reported by the temperature sensor.

lower_alarm: integer

Lower temperature threshold (degree C) at which alarm will be raised.

upper_alarm: integer

Upper temperature threshold (degree C) at which alarm will be raised.

critical_limit: integer

Temperature limit (degree C) at which device will turn off.

position: string

Location of the sensor if known, e.g. _"AROUNDCHIP", can be an empty string.

default

Error state.

Returns the generation

GET /device/generation

Returns the device model generation.

Uses default content-types: application/json

200 OK

Device model generation information.

generation: string

Generation of the model of device in use.

default

Error state.

Returns a map of all supported group select hash keys and their states

GET /device/grouphash

Returns a map of all supported group select hash keys and their states. The key is an hash key available on this device. The boolean value indicates whether that hash key is used (true = it is used).

Uses default content-types: application/json

200 OK

map of all group select hash keys.

macsa: boolean

Boolean value indicating whether MAC source address is used as a key.

macda: boolean

Boolean value indicating whether MAC destination address is used as a key.

ethertype: boolean

Boolean value indicating whether the ethertype value is used as a key.

ipsa: boolean

Boolean value indicating whether the IP source address is used as a key.

ipda: boolean

Boolean value indicating whether the IP destination address is used as a key.

ip_protocol: boolean

Boolean value indicating whether the IP protocol number is used as a key.

src_port: boolean

Boolean value indicating whether the source port is used as a key.

dst_port: boolean

Boolean value indicating whether the destination port is used as a key.

default

Error state.

Sets whether certain group select hash keys should be used or not

POST /device/grouphash

Sets whether certain group select hash keys should be used or not. User level has to be higher or equal to WRITE.

macsa

Boolean value indicating whether MAC source address should be used as a key.

queryboolean
macda

Boolean value indicating whether MAC destination address should be used as a key.

queryboolean
ether_type

Boolean value indicating whether the ethertype value should be used as a key.

queryboolean
ipsa

Boolean value indicating whether the IP source address should be used as a key.

queryboolean
ipda

Boolean value indicating whether the IP destination address should be used as a key.

queryboolean
ip_protocol

Boolean value indicating whether the IP protocol number should be used as a key.

queryboolean
src_port

Boolean value indicating whether the source port should be used as a key.

queryboolean
dst_port

Boolean value indicating whether the destination port should be used as a key.

queryboolean

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Write_Rights_Required
Sets the HTTPS setting

POST /device/https

Sets the HTTPS setting.

https_enabled

Whether to enable HTTPS

queryboolean
ssl_password

Password for certificate/key in plain text.

querystring

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Gets the device ID LED status

GET /device/idled

Shows whether the device ID LED is activated or not

Uses default content-types: application/json

200 OK

Result state.

activated: boolean
Sets the device ID LED

POST /device/idled

Activates or deactivates the device ID LED User level has to be higher or equal to WRITE.

activated

true enables the LED, false disables it.

queryboolean

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Write_Rights_Required
Returns the version of the active image

GET /device/imageversion

Returns the version of the active image.

Uses default content-types: application/json

200 OK

Image version information.

version: string

Version of image in use.

default

Error state.

Returns the IP config

GET /device/ipconfig

Returns the current and stored IP configuration of the management port.

Uses default content-types: application/json

200 OK

IP configuration information.

current_ip: string

Current IP address of the management port

current_netmask: string

Current netmask of the management port

current_gateway: string

Current default gateway of the management port

stored_ip: string

IP address of the management port after reboot

stored_netmask: string

Netmask of the management port after reboot

stored_gateway: string

Default gateway of the management port after reboot

default

Error state.

Sets the IP config

POST /device/ipconfig

Sets the current and stored (the one loaded on boot) IP configuration User level has to be higher or equal to SUPER.

ip

New IP address of the management port, e.g. '192.168.0.200' or '169.254.254.42'.

querystring
mask

New network mask of the management port, e.g. '255.255.0.0'.

querystring
gw

New default gateway of the management port, e.g. '192.168.0.1'.

querystring

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Super_Rights_Required
Returns load information

GET /device/loadaverage

Returns various information about the load on the OS, namely CPU usage.

Uses default content-types: application/json

200 OK

Load information.

average_1m: number (double)

Average CPU load over 1 minute.

average_5m: number (double)

Average CPU load over 5 minutes.

average_15m: number (double)

Average CPU load over 15 minutes.

proc_no_running: integer

Number of currenty running processes.

proc_no_total: integer

Total number of processes.

default

Error state.

Returns memory usage

GET /device/memoryusage

Returns total and free amount of memory.

Uses default content-types: application/json

200 OK

Memory usage information.

total: integer

Total memory in Kibibyte.

free: integer

Free memory in Kibibyte.

default

Error state.

Returns the device model

GET /device/model

Returns the device model.

Uses default content-types: application/json

200 OK

Device model information.

model: string

Model of the device.

default

Error state.

Returns the device label

GET /device/name

Returns the device label used in the web UI.

Uses default content-types: application/json

200 OK

Device label.

name: string
default

Error state.

Sets the device label

POST /device/name

Sets the device label used in the web UI, the one displayed in the right-left there. User level has to be higher or equal to SUPER.

device_name

New device name.

querystring

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Super_Rights_Required
Sets name resolution settings

GET /device/nameresolution

Returns the name resolution settings, namely the DNS servers.

Uses default content-types: application/json

200 OK

DNS servers (up to three).

dns: string[]

IP address of the DNS server.

string
default

Error state.

Sets the name resolution settings.

POST /device/nameresolution

Sets the name resolution settings, namely the DNS servers. If empty sets to default values ("8.8.8.8" and "8.8.4.4") User level has to be higher or equal to SUPER.

dns1

IP address of the first name server, e.g. 8.8.8.8. It is queried first.

querystring
dns2

IP address of the second name server, e.g. 8.8.4.4. It is queried after the first server.

querystring
dns3

IP address of the third name server. It is queried after the second server.

querystring

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Super_Rights_Required
Returns state of permanent mode

GET /device/permanentrulesmode

Returns the state of the permanent mode. Permanent mode means that the active rules/groups are always permanent and remain throughout reboots.

Uses default content-types: application/json

200 OK

Permanent rules mode.

state: boolean
default

Error state.

Sets the permanent mode

POST /device/permanentrulesmode

Sets the permanent mode. User level has to be higher or equal to SUPER.

state

New state of permanent mode, true = on.

queryboolean

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Super_Rights_Required
Device reboot

POST /device/reboot

Reboots the device right away. User level has to be higher or equal to SUPER.

Uses default content-types: application/json

200 OK

Result state (device might reboot before returning it)

default

Error state.

Super_Rights_Required
Restarts the webserver without a reboot.

POST /device/restartwebserver

Restarts the webserver right away. User level has to be higher or equal to SUPER.

Uses default content-types: application/json

200 OK

Result state (webserver might be restarting before returning it)

default

Error state.

Super_Rights_Required
Returns the rule storage mode setting

GET /device/rulestoragemode

Returns the rule storage mode setting.

Uses default content-types: application/json

200 OK

Rule storage mode ("simple"/"ipv6").

modeCurrent: string , x ∈ { simple , ipv6 }

Currently active rule storage mode.

modeNext: string , x ∈ { simple , ipv6 }

Rule storage mode after reboot.

default

Error state.

Sets the rule storage mode

POST /device/rulestoragemode

Sets the rule storage mode, might affect the matching and action capabilities of some devices, e.g. concerning IPv6. User level has to be higher or equal to SUPER.

mode

New rule storage mode ('simple' or 'ipv6').

querystring , x ∈ { simple , ipv6 }

Uses default content-types: application/json

200 OK

Rule storage mode ('simple' or 'ipv6').

modeCurrent: string , x ∈ { simple , ipv6 }

Currently active rule storage mode (the newly activated one)

modeNext: string , x ∈ { simple , ipv6 }

Rule storage mode after reboot.

default

Error state.

Super_Rights_Required
Returns the serial number

GET /device/serialno

Returns the serial number of the device.

Uses default content-types: application/json

200 OK

Serial number information.

generation: string

Serial no. of the device in use.

default

Error state.

Returns the revision

GET /device/serverrevision

Returns the revision.

Uses default content-types: application/json

200 OK

Revision information.

revision: string

Revision of cch machinery in use.

default

Error state.

Adds a license for this device

POST /device/setlicense

Adds and validates a license for this device

id

ID of the license

queryboolean
validUntil

date until the license is valid. Is not verified here. E.g. "2019-09-07"

queryboolean
serialNumber

Serial number of the device. Needs to be the same as the serial number on this device

queryboolean
signature

base64(md5(id+";"+serialNumber+";"+validUntil+";"+signature))

queryboolean

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Gets the device ID LED status

GET /device/telnet

Shows whether the device ID LED is activated or not

Uses default content-types: application/json

200 OK

Result state.

activated: boolean
Gets the device ID LED status

POST /device/telnet

Shows whether the device ID LED is activated or not

Uses default content-types: application/json

200 OK

Result state.

activated: boolean
Returns the maximum and currently used amount of TCAM flows

GET /flownumbers

Returns the maximum and currently used amount of TCAM flows. (Note that the maximum is only a lower bound of what is at least supported by all rules possible, depending on the rules overstepping it to some extend it might still be possible.)

Uses default content-types: application/json

200 OK

TCAM flow count info.

used_flows: integer

Number of TCAM flows currently utilized by the active rules.

maximum_flows: integer

Total number of TCAM flows (at least) supported.

default

Error state.

Deletes a group

DELETE /groups

Deletes an existing group specified by the group id given in 'gid'. User level has to be higher or equal to WRITE.

group_id

ID of the group to be deleted.

queryinteger

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Write_Rights_Required
Adds a group

POST /groups

Adds a group. Also deletes all rules which have this group as an action. User level has to be higher or equal to WRITE.

application/json

Groups JSON

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Write_Rights_Required
Modifies a group

PUT /groups

Modifies an existing group matched by its group ID. User level has to be higher or equal to WRITE.

application/json

Groups JSON

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Write_Rights_Required
Deletes all active groups

DELETE /groups/all

Deletes all active groups. Also deletes all rules which have any group as an action. User level has to be higher or equal to WRITE.

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Write_Rights_Required
Returns all currently active groups on the device

GET /groups/all

Returns all currently active groups on the device.

Uses default content-types: application/json

200 OK

Object with active groups.

rules: object[]
default

Error state.

Returns port configurations

GET /ports/config

Returns the configuration of all ports.

Uses default content-types: application/json

200 OK

Port configs.

port_config: PortConfig
default

Error state.

Configures a port

POST /ports/config

Sets the configuration of one port to the given values. User level has to be higher or equal to WRITE.

if_name

Interface Name, e.g. "eth-0-1/1"

querystring
speed

Speed setting, can be "10", "100", "1000", "10G", "40G", "100G", or "auto"

querystring , x ∈ { 10 , 100 , 1000 , 10G , 40G , 100G , auto }
duplex

Duplex setting, can be full, half, or auto.

querystring , x ∈ { full , half , auto }
unidirectional

Whether to be in unidirectional mode where TX is forced to be up, irrespective of the actual link state.

queryboolean
crc_check

Whether to accept incoming packets with invalid checksums.

queryboolean
crc_recalculation

Whether to correct the checksum of outgoing packets (e.g. after modifications like truncations).

queryboolean
xg_speed

Speed level, 1G/XG (XG normally means 10G) for devices which need to reboot for it to take effect

querystring , x ∈ { 1G , XG }
shutdown

Boolean controlling whether interface is shut down, otherwise it is up

queryboolean

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Write_Rights_Required
Returns status of the ports

GET /ports/info

Returns status and other information about the ports. Don't use if performance is a concern!

Uses default content-types: application/json

200 OK

Port info.

{
"result": [
{
"properties": {
"admin_status": "PORT_UP",
"duplex": "Full (auto)",
"if_name": "eth-0-1",
"link_status": "LINK_UP",
"mac_addr": "00:1e:08:0a:0d:78",
"port_no": 1,
"speed": "1Gb (auto)"
}
,
"type": "object"
}
]
}
result: object
port_no: string

Port ID, e.g. 1.

1
                                                                                                                    
if_name: string

Interface name, e.g. eth-0-1.

"eth-0-1"
                                                                                                                    
admin_status: string , x ∈ { PORT_UP , PORT_DOWN }

Set port status

link_status: string , x ∈ { LINK_UP , LINK_DOWN }

Link status.

duplex: string

Current duplex status, and duplex setting in parentheses

mac_addr: string

MAC address of the interface, hex bytes separated using colons

speed: string

Current speed, and speed setting in parentheses, e.g. 1Gb (auto)

"1Gb (auto)"
                                                                                                                    
default

Error state.

Returns information about the SFPs

GET /ports/sfpstatus

Returns the status of all SFPs.

Uses default content-types: application/json

200 OK

Port counters.

{
"result": "Port port-6 transceiver info: \nTransceiver Type: 1000BASE-T\n Transceiver Vendor Name : CISCO-FINISAR \n Transceiver PN : GEGB3RC-C \n Transceiver S/N : EC1501064242 \nTransceiver Output Wavelength: N/A\nSupported Link Type and Length: \n Link Length for copper: 100 m\nDigital diagnostic is not implemented.\n"
}
result: string

All the SFP info formatted for fixed-width display (e.g. a terminal)

default

Error state.

Returns the counters of all ports

GET /ports/stats

Returns the counters of all ports.

Uses default content-types: application/json

200 OK

Port counters.

object
portnum: string

ID of the port

rxpkts: integer

Number of received packets

rxbytes: integer

Number of received bytes

rxdrop: integer

Number of packets dropped on receiving

rxerrs: integer

Total number of packets dropped due to rx errors (sum or greater than rxframe+rxover+rxcrc)

rxframe: integer

Number of packets dropped due to frame alignment errors

rxover: integer

Number of packets dropped due to rx overrun

rxcrc: integer

Number of packets dropped due to CRC errors

txpkts: integer

Number of transmitted packets

txbytes: integer

Number of transmitted bytes

txdrop: integer

Number of packets dropped on sending

txerrs: integer

Total number of packets dropped due to tx errors (equal or greater than txcoll)

txcoll: integer

Number of packets dropped due to collisions

default

Error state.

Deletes a rule

DELETE /rules

Deletes the specified rule. A rule is identified by all match fields (including priority), all other fields are ignored and can be omitted. User level has to be higher or equal to WRITE.

priority

Priority of the rule to delete.

query integer , { x ∈ ℤ | 0 ≤ x ≤ 65535 }
match[(MATCH_FIELD)]...

(MATCH_FIELD) is placeholder for fields like 'in_port' which make up the match of a rule and this way unambiguously identify it (together with the priority). Depending on the match field in question the value might not matter and can be set to ''.

query string

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Write_Rights_Required
Adds a rule

POST /rules

Adds the given rule. User level has to be higher or equal to WRITE.

name

Name of the rule.

query string
cookie

Optional cookie value for identification.

query string
description

Description of the rule.

query string
priority

Priority of the rule. Higher priority rules are tried first, each packet can only be matched by a single rule.

query integer , { x ∈ ℤ | 0 ≤ x ≤ 65535 }
match[(MATCH_FIELD)]...

(MATCH_FIELD) is placeholder for fields like 'in_port' which make up the match of a rule and this way unambiguously identify it (together with the priority).

query string
actions

String with all actions (order matters!) separated by ','.

query string

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Write_Rights_Required
Modifies a rule

PUT /rules

Modifies an existing rule. Modifies the actions, the name or the description of a specified rule. The rule is identified by its match fields (including priority). The match (including priority) cannot be modified. User level has to be higher or equal to WRITE.

name

New name of the rule.

query string
cookie

Cookie value for identification.

query string
description

New description of the rule.

query string
priority

Priority of the rule to edit. If empty 32768 is assumed.

query integer , { x ∈ ℤ | 0 ≤ x ≤ 65535 }
match[(MATCH_FIELD)]...

(MATCH_FIELD) is placeholder for fields like 'in_port' which make up the match of a rule and this way unambiguously identify it (together with the priority). Depending on the match field in question the value might not matter and can be set to ''.

query string
actions

New string of all actions (order matters!), separated by ','.

query string

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Write_Rights_Required
Deletes all rules

DELETE /rules/all

Deletes all active rules.

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Write_Rights_Required
Returns all rules

GET /rules/all

Returns all active rules on this device.

Uses default content-types: application/json

200 OK

An object containing all active rules on this device.

rules: object[]
used_flows: integer

Number of TCAM flows utilized.

default

Error state.

Resets all rule counters

DELETE /rules/counters

Resets the packet and byte counters of all rules. User level has to be higher or equal to WRITE.

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Write_Rights_Required
Returns all rule and port save-points

GET /savepoints

Returns all rule and port save-points.

Uses default content-types: application/json

200 OK

Rule and port save-points.

RuleSavePoints: object[]
PortSavePoints: object[]
default

Error state.

Activates a port save-point

PUT /savepoints/activeportsavepoint

Activates a port save-point with the given name. User level has to be higher or equal to SUPER.

name

Name of the port save point to activate.

query string

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Super_Rights_Required
Activates a rule save-point

PUT /savepoints/activerulesavepoint

Activates a rule save-point with the given name making all rules and group active (or at least trying to, success depends on e.g. whether it matches the current port settings). Does not make the rule save-point permanent. User level has to be higher or equal to WRITE.

name

Name of the port save point to activate

query string

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Write_Rights_Required
Sets a rule save-point to be loaded on boot

PUT /savepoints/defaultrulesavepoint

Sets the rule save-point with the given name to be loaded on boot Does not make it active before next boot. There can be only one to be loaded on boot. User level has to be higher or equal to SUPER.

name

Name of the port save point to set to be loaded on boot

query string

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Super_Rights_Required
Returns selected rule and port save-points

GET /savepoints/export

Returns selected rule and port save-points (selected by names).

rule_save_point_names

Rule save-points to be exported.

query string[]
port_save_point_names

Port save-points to be exported.

query string[]

Uses default content-types: application/json

200 OK

Rule and port save-points.

meta_data: object
device: string

Device Model of the Device this Savepoint was created on.

software_version: string

Software Version of the Device this Savepoint was created on.

RuleSavePoints: object[]
PortSavePoints: object[]
default

Error state.

Modifies an existing port save-point

POST /savepoints/modportsavepoint

Renames the port save-point with the given name given in "oldname" to the name given in "newname". If the "override" parameter is equal to "true" the the currently active ports get saved into this port save point, thereby overwriting all existing ports in that save-point. Also modifies the description to the and the description given in "description". The description will not be modified if the "description" parameter is not set or "null". User level has to be higher or equal to SUPER.

old_name

Existing name of the port save point

query string
new_name

New name of the port save point

query string
description

Description of port save point (default is empty)

query string
override

If "true" (which is the default), save the currently active ports into this save-point

query boolean

Uses default content-types: application/json

200 OK

Port save point in question.

portSavePoints: object[]
default

Error state.

Super_Rights_Required
Modifies an existing rule save-point

POST /savepoints/modrulesavepoint

Modifies an existing rule save-point. Renames the rule save-point with the given name given in "oldname" to the name given in "newname". If the "override" parameter is equal to "true" the the currently active rules get saved into this rule save point, thereby overwriting all existing rules in that save-point. Also modifies the description to the and the description given in "description". The description will not be modified if the "description" parameter is not set or "null". User level has to be higher or equal to WRITE.

old_name

Existing name of the rule save point

query string
new_name

New name of the rule save point

query string
description

Description of rule save point (default is empty)

query string
override

If "true" (which is the default), save the currently active rules into this save-point

query boolean

Uses default content-types: application/json

200 OK

Rule save point in question.

default

Error state.

Write_Rights_Required
Deletes a port save-point

DELETE /savepoints/portsavepoint

Deletes the port save-point with the given name if it exists. User level has to be higher or equal to SUPER.

name

Name of the port save point to delete

query string

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Super_Rights_Required
Creates a new port save-point from current port settings

POST /savepoints/portsavepoint

Saves the current port config into a new port save-point with the name given in "name" and the description given in "description". Returns the new port save-point. User level has to be higher or equal to SUPER.

name

Name of new rule save point.

query string
description

Description of new rule save point.

query string

Uses default content-types: application/json

200 OK

New port save point.

default

Error state.

Super_Rights_Required
From current rules/groups creates a 'Quicksave' rule save-point set to load on boot

PUT /savepoints/quicksaverules

Saves the currently active rules and groups into a rule save-point with the name 'Quicksave' which will be set to load on boot. Any already existing rule save-point by this name will be replaced. User level has to be higher or equal to WRITE.

Uses default content-types: application/json

200 OK

The rule save-point in question.

RuleSavePoints: object[]
default

Error state.

Write_Rights_Required
Deletes a rule save-point

DELETE /savepoints/rulesavepoint

Deletes the rule save-point with the given name if it exists. User level has to be higher or equal to WRITE.

name

Name of the rule save point to delete

query string

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Write_Rights_Required
Creates a new rule save-point from current rules/groups

POST /savepoints/rulesavepoint

Saves the currently active rules and groups into a new rule save-point with the name given in "name" and the description given in "description". Returns the new rule save-point. User level has to be higher or equal to WRITE.

name

Name of new rule save point.

query string
description

Description of new rule save point.

query string

Uses default content-types: application/json

200 OK

New rule save point.

default

Error state.

Write_Rights_Required
Deletes an user

DELETE /users

Deletes a web UI user account. User level has to be higher or equal to SUPER.

name

User name of the account to delete.

query string

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Super_Rights_Required
Returns all users

GET /users

Returns all web UI user accounts.

Uses default content-types: application/json

200 OK

User accounts.

(USER_NAME): object

User name info object, (USER_NAME) stands for the user in question.

userid: integer

Internal user ID.

username: string

Username.

accesslevel: integer , x ∈ { 1 , 7 , 31 }

Access level; 1 = READ, 7 = WRITE, 31 = SUPER.

description: string

User account description.

default

Error state.

Adds an user

POST /users

Adds a web UI user account. User level has to be higher or equal to SUPER.

username

New user name.

query string
accesslevel

New access level; 1 = READ, 7 = WRITE, 31 = SUPER.

query integer , x ∈ { 1 , 7 , 31 }
password

New password.

query string
description

New user account descriptions.

query string
radius

If this is true, this user's password is checked against the RADIUS server.

query boolean

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Super_Rights_Required
Modifies an user

PUT /users

Modifies an existing web UI user account. User level has to be higher or equal to SUPER.

username

Current user name.

query string
new_username

New user name.

query string
password

New password.

query string
description

New user account description.

query string
access_level

New access level; 1 = READ, 7 = WRITE, 31 = SUPER.

query integer , x ∈ { 1 , 7 , 31 }
radius

If this is true, this user's password is checked against the RADIUS server.

query boolean

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Super_Rights_Required
Gets the RADIUS config

GET /users/radius

Gets the RADIUS basic configuration. User level has to be higher or equal to SUPER.

Uses default content-types: application/json

200 OK

UAC state.

enabled: boolean

Whether the RADIUS setting is enabled.

server: string

IP address or hostname of the RADIUS server.

port: integer

UDP port of the RADIUS server.

secret: string

RADIUS secret required to communicate with the RADIUS server.

radius_login_level: integer

RADIUS login level, either of [0 (No access), 1 (read access), 7 (write access), 31 (super user access)] Determines what user access level any user has, that loggs in via RADIUS, but does not have a local user profile.

refresh_rate: integer

Determines how many seconds a RADIUS session will be cached.

default

Error state.

Super_Rights_Required
Sets the RADIUS config

POST /users/radius

Sets the basic RADIUS configuration. User level has to be higher or equal to SUPER.

server

IP address or hostname of the RADIUS server.

query string
port

UDP port of the RADIUS server.

query integer
secret

RADIUS secret required to communicate with the RADIUS server.

query string
radius_login_level

RADIUS login level, either of [0 (No access), 1 (read access), 7 (write access), 31 (super user access)] Determines what user access level any user has, that loggs in via RADIUS, but does not have a local user profile.

query integer
refresh_rate

Determines how many seconds a RADIUS session will be cached.

query integer

Uses default content-types: application/json

200 OK

UAC state.

state: boolean

Boolean value indicating whether user access control is activated (true = on).

default

Error state.

Super_Rights_Required
Returns the UAC state

GET /users/uac

Returns the state of the UAC (mandatory user authentication and access control) setting, whether it is enabled or not.

Uses default content-types: application/json

200 OK

UAC state.

state: boolean

Boolean value indicating whether user access control is activated (true = on).

default

Error state.

Sets the UAC state

POST /users/uac

Sets the state of UAC (mandatory user authentication and access control). User level has to be higher or equal to SUPER.

state

New UAC state, true = active mandatory auth. and access control

query boolean

Uses default content-types: application/json

200 OK

UAC state.

state: boolean

Boolean value indicating whether user access control is activated (true = on).

default

Error state.

Super_Rights_Required
Deletes the logs

DELETE /weblog

Deletes the (cch) logs. User level has to be higher or equal to SUPER.

Uses default content-types: application/json

200 OK

Result state.

default

Error state.

Super_Rights_Required
Returns the logs

GET /weblog

Returns the (cch) logs.

Uses default content-types: application/json

200 OK

Log entries.

logs: string[]
string

Log entry.

systemDateTime: string

Date and time of the device.

default

Error state.

Schema definitions

App: object

canBeInstantiated: boolean

Whether an instance of the app can be started. False e.g. for apps which for which there can be only one instance running at the same time and this currently being the case.

paramFormat: string[]

Tuple consisting of:

  • Internal unique parameter name.
  • Human-readable name of the parameter.
  • Input Type.
  • Help text.
  • JS code. If the result of executing this code is false then this field is to be hidden.
  • Default value of this field.
string
name: string

Name of the app.

actions: object[]
object
description: string

Description of the app.

Error: object

error: string

Error info

GroupInput: string

(GID) stands for the group number.

{
"(GID)": {
"buckets": [
{
"actions": "<Actions for that bucket, similar to rule actions, seperated using commas>",
"watch_port": "<ID of the watch port>"
}
]
,
"group_id": "<Unique ID of the group>",
"type": "<'select' for loadbalancing; 'ff' for fast failover; 'all' clones the traffic and executes all buckets>"
}
}

GroupOutput: object

{
"buckets": [
{
"actions": "push_vlan:0x8100, set_field:4->vlan_vid, output:2",
"watch_port": 3
},
{
"actions": "push_vlan:0x8100, set_field:7->vlan_vid, output:5",
"watch_port": 6
}
]
,
"description": "test",
"group_id": 1,
"type": "ALL"
}
group_id: integer

Unique integer ID of the group

type: string

select for loadbalancing, ff for fast failover, all for cloning the traffic and executing all buckets

buckets: object[]

Bucket-related properties

object
watch_port: string

ID of the watch_port

actions: string

String containing all actions of that bucket

PortConfig: object

Port config.

{
"duplex": "auto",
"ifName": "1",
"mediaType": "auto-select",
"shutdown": false,
"speed": "auto",
"type": 1
}
if_name: string

Interface Name, e.g. "eth-0-1" or "eth-0-1/1".

"eth-0-1/1"
                                                        
type: integer , { x ∈ ℤ | 1 ≤ x ≤ 11 }
  1. RJ45;
  2. SFP, 1G only;
  3. Switchabe RJ45 to SFP, 1G only;
  4. SFP, 1G or 10G, changing speed requires reboot;
  5. SFP, 10G only;
  6. QSFP, 40G, splittable to 4x10G or 4x1G (breakout cable). Splitting requires reboot;
  7. QSFP, 40G or 100G, splittable to 4x10G or 4x1G (breakout cable). Splitting requires reboot;
  8. QSFP, 40G, splittable to 4x10G or 4x1G (breakout cable or SFP port). Splitting requires reboot;
  9. Split version of type 8, split to SFP port. 1G or 10G. Unsplitting requires reboot;
  10. Split version of port 6, 7 or 8, split to breakout cable. 1G or 10G. Unsplitting requires reboot;
  11. SFP, 1G or 10G, changing speed does not require reboot
media_type: string , x ∈ { sfp , rj45 , auto }

Optional field media type, any of ["sfp", "rj45", "auto"]

speed: string , x ∈ { 10 , 100 , 1000 , 10G , 100G , auto }

Speed setting, can be "10", "100", "1000", "10G", "40G", "100G", or "auto"

duplex: string , x ∈ { full , half , auto }

Duplex setting, can be full, half, or auto

xg_speed: object

Speed level, 1G/XG (XG normally means 10G) for devices which need to reboot for it to take effect

currSetting: string , x ∈ { 1G , XG }

Current setting.

nextSetting: string , x ∈ { 1G , XG }

Setting after reboot.

split: string , x ∈ { break-out , sfp , default }

Whether splittable port is split, can be break-out (split to breakout cable, type 6/7/8 only), sfp (split to breakout cable, type 8 only), or default

shutdown: boolean

Boolean controlling whether interface is shut down, otherwise it is up

PortSavePoint: object

(PORT_SAVE_POINT) is a placeholder for the name of the port save-point

(PORT_SAVE_POINT)...: object
name: string , x ∈ { (PORT_SAVE_POINT) }
ports: object[]
readonly: boolean

true if the port save-point cannot be edited/deleted.

type: string , x ∈ { PortSavePoint }
description: string

Port save-point description

Result: object

{
"result": "OK"
}
result: string

Result info, on success often just 'OK'

RuleOutput: object

{
"actions": "output:2",
"cookie": 1152921504606847000,
"datarate": "0 bit/s",
"datarate_raw": 0,
"description": "just an example",
"match": {
"in_port": 1
}
,
"n_bytes": 0,
"n_packets": 0,
"name": "example",
"priority": 32768,
"real_flow_ct": 1
}
cookie: integer

internal ID, maps information like name and description to a rule

name: string

Name of the rule

description: string

Description of the rule

priority: string

Priority value. Higher priority rules are tried first, each packet can only be matched by a single rule.

match: object

Match object with fields that make up match. Some match fields have are only keys, so their values will simply be empty strings.

object
actions: string

Actions of this rule in a string seperated using commas

datarate: string

Data rate in a human-readable format

n_bytes: string

Total byte size of all packets matched by this rule

n_packets: string

Number of packets that were handled by this rule

real_flow_ct: integer

Number of TCAM flows used

RuleSavePoint: object

(RULE_SAVE_POINT) is a placeholder for the name of the rule save-point

{
"Factory Default": {
"description": "Taps the connection between ports 1 and 2 to port 3. Also taps the connection between ports 5 and 6 to port 4. Does not affect the port configuration.",
"flowusage": 4,
"groups": [
{
"buckets": [
{
"actions": "output:1",
"watch_port": "1"
}
]
,
"description": "",
"group_id": "1",
"type": "ALL"
}
]
,
"groupusage": 1,
"readonly": false,
"rules": [
{
"actions": [
"output:2",
"output:3"
]
,
"cookie": "1152921504606846982",
"description": "",
"duration": "49s",
"duration_raw": "49.145",
"hard_age": "",
"match": {
"in_port": "1"
}
,
"n_bytes": "0",
"n_packets": "0",
"name": "",
"priority": "32768",
"real_flow_ct": 1,
"table": "0"
},
{
"actions": [
"output:4",
"output:5"
]
,
"cookie": "1152921504606846980",
"description": "",
"duration": "61s",
"duration_raw": "61.094",
"hard_age": "",
"match": {
"in_port": "6"
}
,
"n_bytes": "0",
"n_packets": "0",
"name": "",
"priority": "32768",
"real_flow_ct": 1,
"table": "0"
},
{
"actions": [
"output:4",
"output:6"
]
,
"cookie": "1152921504606846981",
"description": "",
"duration": "55s",
"duration_raw": "55.819",
"hard_age": "",
"match": {
"in_port": "5"
}
,
"n_bytes": "0",
"n_packets": "0",
"name": "",
"priority": "32768",
"real_flow_ct": 1,
"table": "0"
},
{
"actions": [
"output:1",
"output:3"
]
,
"cookie": "1152921504606846983",
"description": "",
"duration": "45s",
"duration_raw": "45.061",
"hard_age": "",
"match": {
"in_port": "2"
}
,
"n_bytes": "0",
"n_packets": "0",
"name": "",
"priority": "32768",
"real_flow_ct": 1,
"table": "0"
}
]
,
"type": "RuleSavePoint"
}
}
(RULE_SAVE_POINT)...: object
name: string , x ∈ { (RULE_SAVE_POINT) }
rules: object[]
groupusage: integer

How many groups this rule save-point utilizes.

readonly: boolean

true if the port save-point cannot be edited/deleted.

groups: object[]
type: string , x ∈ { RuleSavePoint }
flowusage: integer

How many TCAM flows this rule save-point utilizes.

description: string

Rule save-point description