#%RAML 1.0 title: Console Server REST API version: v1.9 documentation: - title: Console Server REST API content: This API allows inspection of an Opengear Console Server Appliance. baseUri: https://{cshost}/api/v1.9 protocols: [ HTTPS ] securitySchemes: token: description: Console Server base authentication scheme type: Basic Authentication describedBy: headers: Authorization: description: authorization session token type: string required: true displayName: Authorization example: Token 521a00e57d4a461b3e4bb0c55166f97c types: message: type: object properties: message: type: string error: type: object properties: error: type: string description: An error string required: true authError: type: object properties: error: description: The authentication error string required: true credentials: type: object properties: username: type: string required: true password: type: string required: true getSessionResponse: type: object properties: state: type: string session: type: string user: type: string required: false last_challenge: type: string required: false responseToSessionChallenge: type: object properties: session: type: string required: true state: type: object required: true challenge: description: Next challenge (if any) type: string deleteSessionResponse: type: object properties: session: type: string required: true success: type: string required: true state: type: string user: type: string extendSessionResponse: type: object properties: session: type: string success: type: boolean state: type: object seconds_remaining: type: integer format: int32 enrollmentPost: type: object properties: id: type: string description: The ID of the node - this is generated by Lighthouse required: true server: type: string description: The address of the Lighthouse - this is either an IP address or a hostname required: true package_password: type: string description: This is the password used to request the enrollment package from Lighthouse. Once enrolled, a certificate is used for all authentication required: true deleteEnrollmentResponse: type: object properties: message: type: string getSecureShellResponse: type: object properties: ssh: type: object properties: port: type: integer description: The host port that the SSH daemon is listening on getSecureShellHostKeysResponse: type: object properties: keys: type: object properties: ecdsa: type: string description: The ECDSA SSH host key - base64 encoded required: false ed25519: type: string description: The ED25519 host key - base64 encoded required: false rsa: type: string description: the RSA host key - base64 encoded required: false secureShellAuthorizedKeys: type: object properties: keys: type: array items: type: object properties: keytype: description: The encryption type for the key. type: string enum: [ "ssh-rsa", "ssh-ed25519", "ssh-ecdsa" ] key: description: The key as a base64 encoded string. type: string identifier: description: A comment to identify the key. Usually an email address. type: string secureShellAuthorizedKeysDelete: type: object properties: keys: type: array items: type: object properties: keytype: description: The encryption type for the key. type: string required: false key: description: The key as a base64 encoded string. type: string required: false identifier: description: A comment to identify the key. Usually an email address. type: string required: false getNodeDescriptionResponse: type: object properties: model_number: type: string description: The model of the Node serial_number: type: string description: The serial number of the Node. In some cases, this may not be programatically retrievable. 'N/A' will be returned in that case hostname: type: string description: The hostname of the node mac_address: type: string description: The MAC address of the NET 1 interface firmware_version: type: string description: The version of firmware that the Node is running interfaces: type: array description: An array of the configured interfaces items: type: object properties: name: type: string required: true description: The interface name ipv4_addresses: type: array required: true description: All IPv4 addresses assigned to the interface items: type: string required: false description: An IPv4 address ipv6_addresses: type: array required: true description: All IPv6 addresses assigned to the interface items: type: string required: false description: An IPv6 address auth: type: object properties: auth: type: object properties: auth_type: type: string required: true use_remote_groups: type: boolean required: true radius: type: object properties: auth_server: type: string required: true acct_server: type: string required: false password: type: string required: true require_msgauth: type: string required: false tacacs: type: object properties: auth_server: type: string required: true auth_method: type: string required: true service: type: string required: true password: type: string required: false ldap: type: object properties: server: type: string required: true bind_dn: type: string required: false base_dn: type: string required: false bind_password: type: string required: false username_attr: type: string required: false group_membership_attr: type: string required: false protocol: type: string required: false ignore_ssl_errors: type: boolean required: false ca_cert: type: string required: false getGroupsResponse: type: object properties: groups: type: array items: type: group meta: type: object required: false properties: total_pages: type: number required: false getGroupResponse: type: object properties: group: type: group group: description: "Console Server Group Configuration" type: object properties: name: required: true type: string description: The name of the group description: required: false type: string description: The description of the group roles: required: true type: array description: The list of roles provided by the group items: type: string ports: required: true type: array description: A list of flags for whether the group has access to each serial port items: type: boolean system: required: true type: boolean description: A flag indicating whether or not this is a system group userConfiguration: description: Console server user configuration type: object properties: id: type: string description: description: Must not contain ':' type: string username: type: string disabled: type: boolean groups: description: List of group names for which this user is a member type: array items: type: string userConfigurationList: type: object properties: users: type: array items: userConfiguration userConfigurationUpdate: description: Console server user configuration update. Note password is required for new users. type: object properties: id: type: string description: description: Must not contain ':' type: string username: type: string password: type: string required: false disabled: type: boolean groups: description: List of group names for which this user is a member type: array items: type: string userConfigurationListUpdate: type: object properties: users: type: array items: userConfigurationUpdate script_metadata: description: "Console Server Script Configuration" type: object properties: script_timeout: required: true type: integer description: The number of minutes that the script is allowed to run script_checksum: required: true type: string description: The SHA1 checksum of the script getSerialPortsResponse: type: object properties: serialports: type: array items: type: serialPort getSerialPortResponse: type: object properties: serialport: type: serialPort updateSerialPortRequest: type: object properties: serialport: type: serialPort properties: # The ctrlCode properties are required in update requests (PUT) - overide them ctrlCode: type: object required: true properties: quit: required: true type: number generateBreak: required: true type: number chooser: required: true type: number power: required: true type: number help: required: true type: number portLog: required: true type: number updateSerialPortResponse: type: getSerialPortResponse properties: serialport: type: serialPort properties: # The ctrlCode properties are required in the response of update requests (PUT) - overide them ctrlCode: type: object required: true properties: quit: required: true type: number generateBreak: required: true type: number chooser: required: true type: number power: required: true type: number help: required: true type: number portLog: required: true type: number serialPort: description: "Console Server Serial Port Configuration" type: object properties: label: type: string description: The label for the serial port id: type: string description: The id of the serial port. This ID can be used to fetch individual ports using the /serialPorts/{portid} endpoint attachedDeviceType: type: string description: The type of device attached to the serial port. Ports in console server mode will have this property set to 'none' enum: [ "unknown", "none", "remotePowerControl", "uninterruptiblePowerSupply", "environmentMonitor", "nmeaSource", "powerAlert", ] hardwareType: type: string description: The underlying hardware type of the port. This is used to indicate if its a fixed or removable port. enum: [ "unknown", "builtInUART", "builtInUSB", "removableUSB" ] mode: type: string description: The mode that the port is in enum: [ "disabled", "localConsole", "consoleServer", "bridge", "terminalServer", "reserved", "powerman", "unknown" ] hardwareSettings: type: object description: This group of properties define the hardware level configuration of the port properties: pinout: type: string description: The physical pinout of the port connector enum: [ "X0", "X1", "X2" ] protocol: description: The data protocol the port is using when transmitting and receiving type: string enum: [ "RS232", "RS422", "RS485", "RS485e" ] uart: type: object description: UART configuration settings properties: parity: type: string description: The format of the parity byte enum: [ "none", "unknown", "even", "mark", "space" ] baud: description: The communication rate of the port type: string enum: [ "50", "75", "110", "134", "150", "200", "300", "600", "1200", "2400", "4800", "9600", "19200", "38400", "57600", "115200", "230400" ] stopBits: description: The number of stop bits between characters type: string enum: [ "1", "1.5", "2" ] dataBits: description: The number of data bits in a character type: string enum: [ "5", "6", "7", "8" ] flowControl: description: The algorithm used for flow control. type: string enum: [ "unknown", "none", "noneUnpowered", "hardware", "software", "softwareUnpowered" ] dtrMode: description: When to assert DTR type: string enum: [ "alwayson", "activeuser" ] ctrlCode: description: Additional key sequences for pmshell control commands. Each is an integer in the range [0, 255] inclusive. type: object properties: quit: description: Additional control code for the 'Exit pmshell' control function type: number generateBreak: description: Additional control code for the 'Generate BREAK' control function type: number chooser: description: Additional control code for the 'Connect to port menu' control function type: number power?: description: Additional control code for the 'Power menu' control function type: number help: description: Additional control code for the 'Show help message' control function type: number portLog: description: Additional control code for the 'View History' control function type: number modeSettings: type: modeSettings description: This object contains mode specific configuration objects. Only the object corresponding to the 'mode' property will be present nagios: description: This object contains Nagios related configuration settings for this port type: object properties: enabled: description: Indicates if nagios checks are enabled for this port type: boolean serialStatus: description: Indicates if the nagios serial status check should be configured for this port type: boolean name: description: The Nagios name for the port (autogenerated from the hostname and the port name) type: string portLogging: description: Indicates if nagios port logging is enabled type: boolean logging: type: object description: This object contains logging related configuration settings for this port properties: level: description: Indicates the logging level for the port type: string enum: [ "unknown", "disabled", "access", "accessInputOutput", "accessInput", "accessOutput" ] priority: description: The log priority to assign to log messages from this port when they're sent to a remote syslog server type: string enum: [ 'default', 'warning', 'notice', 'info', 'error', 'emergency', 'debug', 'critical', 'alert' ] facility: description: The log facility to assign to log messages from this port when they're sent to a remote syslog server type: string enum: [ 'default', 'local0', 'local1', 'local2', 'local3', 'local4', 'local5', 'local6', 'local7', 'auth', 'authpriv', 'cron', 'daemon', 'ftp', 'kern', 'lpr', 'mail', 'news', 'user', 'uucp' ] nmeaStreaming: description: Only valid for predefined GPS serial ports. Will be rejected by PUT/PATCH on non-GPS ports. type: object required: false properties: enabled: description: Enable GPS NMEA data streaming type: boolean fixFrequency: description: The GPS fix rate, from 1-255 seconds. If changed, this field will not be applied until the device restarts, or NMEA streaming is disabled and re-enabled type: number patchSerialPortRequest: type: object properties: serialport: description: "Console Server Serial Port Configuration" type: object properties: label?: type: string description: The label for the serial port id?: type: string description: The id of the serial port. This ID can be used to fetch individual ports using the /serialPorts/{portid} endpoint attachedDeviceType?: type: string description: The type of device attached to the serial port. Ports in console server mode will have this property set to 'none' enum: [ "unknown", "none", "remotePowerControl", "uninterruptiblePowerSupply", "environmentMonitor", "nmeaSource", "powerAlert", ] hardwareType?: type: string description: The underlying hardware type of the port. This is used to indicate if its a fixed or removable port. enum: [ "unknown", "builtInUART", "builtInUSB", "removableUSB" ] mode?: type: string description: The mode that the port is in enum: [ "disabled", "localConsole", "consoleServer", "bridge", "terminalServer", "reserved", "powerman", "unknown" ] hardwareSettings?: type: object description: This group of properties define the hardware level configuration of the port properties: pinout?: type: string description: The physical pinout of the port connector enum: [ "X0", "X1", "X2" ] protocol?: description: The data protocol the port is using when transmitting and receiving type: string enum: [ "RS232", "RS422", "RS485", "RS485e" ] uart?: type: object description: UART configuration settings properties: parity?: type: string description: The format of the parity byte enum: [ "none", "unknown", "even", "mark", "space" ] baud?: description: The communication rate of the port type: string enum: [ "50", "75", "110", "134", "150", "200", "300", "600", "1200", "2400", "4800", "9600", "19200", "38400", "57600", "115200", "230400" ] stopBits?: description: The number of stop bits between characters type: string enum: [ "1", "1.5", "2" ] dataBits?: description: The number of data bits in a character type: string enum: [ "5", "6", "7", "8" ] flowControl?: description: The algorithm used for flow control. type: string enum: [ "unknown", "none", "noneUnpowered", "hardware", "software", "softwareUnpowered" ] dtrMode?: description: When to assert DTR type: string enum: [ "alwayson", "activeuser" ] ctrlCode?: description: Additional key sequences for pmshell control commands. Each is an integer in the range [0, 255] inclusive. type: object properties: quit?: description: Additional control code for the 'Exit pmshell' control function type: number generateBreak?: description: Additional control code for the 'Generate BREAK' control function type: number chooser?: description: Additional control code for the 'Connect to port menu' control function type: number power?: description: Additional control code for the 'Power menu' control function type: number help?: description: Additional control code for the 'Show help message' control function type: number portLog?: description: Additional control code for the 'View History' control function type: number modeSettings?: type: modeSettings description: This object contains mode specific configuration objects. Only the object corresponding to the 'mode' property will be present nagios?: description: This object contains Nagios related configuration settings for this port type: object properties: enabled?: description: Indicates if nagios checks are enabled for this port type: boolean serialStatus?: description: Indicates if the nagios serial status check should be configured for this port type: boolean name?: description: The Nagios name for the port (autogenerated from the hostname and the port name) type: string portLogging?: description: Indicates if nagios port logging is enabled type: boolean logging?: type: object description: This object contains logging related configuration settings for this port properties: level?: description: Indicates the logging level for the port type: string enum: [ "unknown", "disabled", "access", "accessInputOutput", "accessInput", "accessOutput" ] priority?: description: The log priority to assign to log messages from this port when they're sent to a remote syslog server type: string enum: [ 'default', 'warning', 'notice', 'info', 'error', 'emergency', 'debug', 'critical', 'alert' ] facility?: description: The log facility to assign to log messages from this port when they're sent to a remote syslog server type: string enum: [ 'default', 'local0', 'local1', 'local2', 'local3', 'local4', 'local5', 'local6', 'local7', 'auth', 'authpriv', 'cron', 'daemon', 'ftp', 'kern', 'lpr', 'mail', 'news', 'user', 'uucp' ] nmeaStreaming?: description: Only valid for predefined GPS serial ports. Will be rejected by PUT/PATCH on non-GPS ports. type: object required: false properties: enabled?: description: Enable GPS NMEA data streaming type: boolean fixFrequency?: description: The GPS fix rate, from 1-255 seconds. If changed, this field will not be applied until the device restarts, or NMEA streaming is disabled and re-enabled type: number modeSettings: type: object properties: consoleServer: type: consoleServer required: false description: Configuration items specific to Console Server Mode terminalServer: type: terminalServer required: false description: This object contains configuration settings for Terminal Server mode. Terminal server mode starts a getty on the console port, giving shell access to the console server bridge: type: bridge required: false description: This object contains configuration settings for Serial Bridge mode. consoleServer: type: object properties: ssh: type: object properties: enabled: description: Indicates if this port can be connected to via a port specific SSH port type: boolean unauthenticated: type: boolean description: Indicates if connections via a port specific SSH port should be authenticated tcp: type: object properties: enabled: description: Indicates if this port can be connected to via a port specific raw TCP port type: boolean rfc2217: type: object properties: enabled: description: Indicates if this port can be connected to via a port specific RFC2217 port type: boolean webShell: type: object properties: enabled: description: Indicates if this port can be connected to via a specific WebShell link type: boolean telnet: type: object properties: enabled: type: boolean description: Indicates if this port can be connected to via a port specific telnet port unauthenticated: type: boolean description: Indicates if connections via a port specific telnet port should be authenticated general: type: object properties: accumulateMS: type: integer description: The accumulation period is the amount of time that the port management software will buffer characters for before transmitting them over the network. This setting can be used to cut down on the per character traffic overhead, or to help transport of serial only protocols over the network. replaceBackspace: type: boolean description: This option specifies if backspace keystrokes should be replaced with a ^H powerMenuEnabled: type: boolean description: This option specifies if the power menu is available for this port escapeChar: type: string description: This option specifies an alternate escape character to '~' to use to access port menus or shortcuts singleConnection: type: boolean description: Limit the port to a single concurrent connection portShare: type: object description: This object contains configuration settings for PortShare, which is an alternate implementation of RFC2217 properties: enabled: description: This option indicates if PortShare is enabled for this port. This means that RFC2217 connections to this port will be served by PortShare type: boolean encryption: description: This option indicates if PortShare encryption is enabled for this port. type: boolean authentication: description: This option indicated if PortShare authentication is required for this port. type: boolean password: description: The PortShare password for this port. type: string ipAlias: description: This object contains IP Alias settings for the port. IP aliases allow specific IPs to be allocated per port. type: object properties: wan: description: A list of IPs with subnets that are aliases for this port on the WAN interface type: array items: type: string lan: description: A list of IPs with subnets that are aliases for this port on the LAN interface type: array items: type: string oobfo: description: A list of IPs with subnets that are aliases for this port on the OOBFO interface type: array items: type: string wlan: description: A list of IPs with subnets that are aliases for this port on the WLAN interface type: array items: type: string terminalServer: type: object properties: terminalType: description: The type of terminal provided on this port. type: string enum: [ 'unknown', 'vt220', 'vt102', 'vt100', 'linux', 'ansi' ] bridge: type: object properties: server: type: object properties: address: description: The IP address or domain name of the server to bridge this port to type: string required: false port: description: The port on the server to connect this port to type: integer required: false rfc2217: description: Indicates if RFC2217 should be the protocol used to connect to the remote server type: boolean sshTunnel: description: Indicates if SSH should be used to connect to the remote server type: boolean getSystemVersionResponse: description: "Console Server System Version" type: object properties: system_version: required: true type: object properties: rest_api_version: required: true type: string description: The REST API version e.g. v1.1 firmware_version: required: true type: string description: The console server firmware version e.g. 4.3.0 etc_version: required: true type: string description: The contents of /etc/version on console server romfs getInterfacesResponse: type: array items: type: object properties: href: description: Interface URI required: true type: string id: description: Interface Id required: true type: string enabled: description: Enabled required: true type: boolean links: type: array items: type: object properties: href: description: Link URI required: true type: string rel: description: Relationship required: true type: string getInterfaceStatusResponse: description: "Interface Status Information" type: object properties: interface: description: URI for the interface itself required: true type: string enabled: description: Is the interface currently enabled required: true type: boolean up: description: Is this link currently connected type: boolean required: true passthrough: description: Details about whether IP Passthrough is enabled for this interface required: false type: object properties: enabled: description: Is IP Passthrough enabled required: true type: boolean active: description: The current state of IP Passthrough required: true type: boolean ar_controlled: required: true type: boolean description: Is this interface controlled by the Auto-Response system failover: description: Details about whether failover is enabled to this interface required: false type: object properties: enabled: description: Is Failover enabled required: true type: boolean active: description: Is Failover active required: true type: boolean dormant: description: Does the interface stay up when not failed-over to required: true type: boolean links: description: The list of physical links type: array items: type: object properties: wwan: description: Details specifically related to cellmodem connections type: object required: false properties: mdn: description: Mobile Directory Number (MDN) type: string required: true signalStrength: description: Signal quality (%) type: integer required: true rssi: description: Received Signal Strength Indicator (RSSI) type: integer required: true technology: description: Access technology type: string required: true msid: description: Mobile station ID (MSID) type: string required: true failure_reason: description: Failure reason type: string required: true carrier: description: Carrier name type: string required: true modem_status: description: Modem status type: string required: true imei: description: IMEI type: string required: true imsi: description: IMSI type: string required: true iccid: description: ICCID type: string required: true current_bands: description: Current bands type: string required: true getInterfaceTestsResponse: description: "Interface Tests Information" type: array items: type: object properties: href: description: URI for the interface test required: true type: string rel: description: Test name required: true type: string interfaceTestRequest: description: "Common parameters for interface test requests" type: object properties: notifyUrl: description: List of URLs to POST the test result required: false type: array items: description: URL to POST the test result type: string expirySeconds: description: The number of seconds before an incomplete test is abandoned required: true type: number interfaceTestRequestPing: description: "Interface Ping Test Request" type: [interfaceTestRequest] properties: destination: description: Name or IP for the interface test required: true type: string interfaceTestRequestHttp: description: "Interface HTTP Test Request" type: [interfaceTestRequest] properties: url: description: URI for the interface test required: true type: string interfaceTestRequestDNS: description: "Interface DNS Test Request" type: [interfaceTestRequest] properties: server: description: Server to query for DNS interface test required: true type: string interfaceTestResponse: description: "Interface test response" type: object eventLog: description: > Describes an event log that receives serial port events such as TXDATA, RXDATA, LOGIN, LOGOUT. type: object properties: id: required: true type: string description: > The event log's unique ID. This is conventionally of the form "owner-type@owner-location[:sub-id]". The legacy, webui-only eventlog configuration has the reserved ID "remote". type: required: true type: string description: The eventlog receiver's type. Currently only "syslog" is supported. syslog: required: false type: object description: The eventlog description, required when the type is "syslog". properties: address: description: > hostname or IP/IPv6 address, or an URL of the form "tcp://{address}[:port]" or "udp://{address}[:port]". Defaults to port 514. type: string required: true eventLogPut: description: > Describes an event log that receives serial port events such as TXDATA, RXDATA, LOGIN, LOGOUT. type: object properties: type: required: true type: string description: The eventlog receiver's type. Currently only "syslog" is supported. syslog: required: false type: object description: The eventlog description, required when the type is "syslog". properties: address: description: > hostname or IP/IPv6 address, or an URL of the form "tcp://{address}[:port]" or "udp://{address}[:port]". Defaults to port 514. type: string required: true eventLogGetResponse: type: object properties: eventlog: type: eventLog eventLogPutRequest: type: object properties: eventlog: type: eventLogPut eventLogRef: description: "Reference to an event logger" type: object properties: id: required: true type: string description: > Unique ID for the eventlog. The reserved ID "remote" is managed by the local system. href: required: true type: string description: URI to the eventlog resourceTypes: base-type: get?: securedBy: [ token ] headers: Authorization: displayName: Authorization example: Token {{sessionUid}} responses: 500: description: Internal error body: application/json: type: error examples: example1: { "error": "Failed to open configuration handle" } 400: description: Request data error body: application/json: type: error examples: example1: { "error": "Failed to parse request data" } 401: description: Authentication failure body: application/json: type: authError examples: example1: error: "Invalid login credentials" 404: description: Resource not found body: application/json: type: error examples: example1: { "error": "Resource not found" } 304: description: Etag matched If-None-Match header body: application/json: type: object examples: example1: { } post?: securedBy: [ token ] headers: Authorization: displayName: Authorization example: Token {{sessionUid}} responses: 500: description: Internal error body: application/json: type: error examples: example1: { "error": "Failed to open configuration handle" } 400: body: application/json: type: error 401: description: Authentication failure body: application/json: type: authError example: "error": "Invalid Session ID" 404: description: Resource not found body: application/json: type: error examples: example1: { "error": "Resource not found" } put?: securedBy: [ token ] headers: Authorization: displayName: Authorization example: Token {{sessionUid}} responses: 400: body: application/json: type: error 401: description: Authentication failure body: application/json: type: authError example: "error": "Invalid Session ID" 404: description: Not found body: application/json: type: error 500: description: Internal error body: application/json: type: error delete?: securedBy: [ token ] headers: Authorization: displayName: Authorization example: Token {{sessionUid}} responses: 400: description: Incomplete data body: application/json: type: error 401: description: Authentication failure body: application/json: type: authError example: error: "Invalid Session ID" 404: description: Not found body: application/json: type: error 500: description: Internal error body: application/json: type: error patch?: securedBy: [ token ] headers: Authorization: displayName: Authorization example: Token {{sessionUid}} responses: 400: body: application/json: type: error 401: description: Authentication failure body: application/json: type: authError example: error: "Invalid Session ID" 404: description: Not found body: application/json: type: error 500: description: Internal error body: application/json: type: error /sessions: description: > The sessions endpoint is used to authenticate the user and create a session token for accessing all other Lighthouse endpoints. # Auth.session_create post: displayName: createSession description: Create a new authenticated session. body: application/json: type: credentials example: {"username":"root","password":"default"} responses: 400: description: Failed to initiate session creation due to error in post body. body: application/json: example: type: authError example: error: "Invalid request body" 401: description: Authentication failed due to invalid credentials or session. body: application/json: example: { "error": [ { type: 7, "code": 41, "text": "Invalid login credentials", "args": {}, "level": 1 } ] } 303: description: Redirect to new authentication session body: application/json: example: { "sid": "71dcba707b6c177644ede1b224f69096", "message": "Redirecting to new session at {redirect-url}" } 200: body: application/json: type: getSessionResponse example: { "state": "authenticated", "session": "71dcba707b6c177644ede1b224f69096", "user": "root" } /{sessionUid}: type: base-type # Auth.session_get get: displayName: getSession description: > Retrieve the state of an authentication session by ID. A session ID may be valid for some period after the user logs out. responses: 200: description: Session exists body: application/json: type: getSessionResponse example: { "state": "authenticated", "session": "71dcba707b6c177644ede1b224f69096", "user": "root" } 400: description: No session in data body: application/json: # Auth.session_apply_response put: body: application/json: type: responseToSessionChallenge displayName: responseToSessionChallenge description: Apply a challenge response to a session responses: 200: description: Response applied. Next challenge in {challenge} if required. body: application/json: type: responseToSessionChallenge 400: description: Invalid request body: application/json: type: error 403: description: Authentication failed. No more attempts allowed. 404: description: Authentication failed. # Auth.session_delete delete: displayName: deleteSession description: Log out of and delete a session responses: 200: description: Session deleted body: application/json: type: deleteSessionResponse 404: description: Session did not exist /registration: type: base-type description: The Registration endpoint is used by Lighthouse to provide the Node with the address and credentials to retrieve an enrollment package for the device post: body: application/json: type: enrollmentPost responses: 400: description: Invalid request body: application/json: example: { "error": "Invalid request data." } delete: responses: 200: description: "Enrollment Deleted" body: application/json: type: deleteEnrollmentResponse 500: description: "Error during processing" body: application/json: /{$id}: type: base-type description: Remove a connection to Lighthouse delete: responses: 200: description: Lighthouse connection removed successfully body: application/json: example: { "message":"OK" } 400: description: Invalid request body: application/json: example: { "error": "Parameter 'id' not provided." } 404: description: Not found body: application/json: 500: description: Internal server error body: application/json: /{$id}/server_address: type: base-type description: Update the server address of a connection to Lighthouse put: body: application/json: type: object properties: address: type: string description: updated server address required: true example: { "address":"192.168.128.6" } responses: 200: description: Server address updated successfully body: application/json: example: { "message":"OK" } 400: description: Invalid request body: application/json: example: { "error": "Parameter 'id' not provided." } 404: description: Not found body: application/json: 500: description: Internal server error body: application/json: /auth: type: base-type description: The auth endpoint is used to update and retrieve the authentication configuration from the console server put: body: application/json: type: auth example: { "auth": { "radius": { "password": "default", "auth_server": "192.168.0.1:5555", "acct_server": "192.168.0.2:5555", "require_msgauth": "off" }, "ldap": { "username_attr": "member", "base_dn": "basedn", "group_membership_attr": "group", "bind_dn": "binddn", "bind_password": "default", "server": "192.168.0.1:5555", "protocol": "ldaps_only", "ignore_ssl_errors": false, "ca_cert": "-----BEGIN CERTIFICATE-----\nMIIG ... ikTH/\n-----END CERTIFICATE-----\n" }, "tacacs": { "auth_server": "192.168.0.1:5555", "auth_method": "pap", "service": "raccess", "password": "secret" }, "auth_type": "RADIUS", "use_remote_groups": true } } responses: 400: description: Invalid request body: application/json: example: { "error": "Failed to parse request data" } 200: description: Successful request body: application/json: type: auth example: { "auth": { "radius": { "password": "default", "auth_server": "192.168.0.1:5555", "acct_server": "192.168.0.2:5555", "require_msgauth": "off" }, "ldap": { "username_attr": "member", "base_dn": "basedn", "group_membership_attr": "grou", "bind_dn": "binddn", "bind_password": "asdf", "server": "1.4.5.6:2345", "protocol": "ldaps_only", "ignore_ssl_errors": false, "ca_cert": "-----BEGIN CERTIFICATE-----\nMIIG ... ikTH/\n-----END CERTIFICATE-----\n" }, "tacacs": { "auth_server": "1.2.3.4", "auth_method": "pap", "service": "raccess" }, "auth_type": "Local", "use_remote_groups": true } } get: responses: 200: description: Successful request body: application/json: type: auth example: { "auth": { "radius": { "password": "default", "auth_server": "192.168.0.1:5555", "acct_server": "192.168.0.2:5555", "require_msgauth": "off" }, "ldap": { "username_attr": "member", "base_dn": "basedn", "group_membership_attr": "grou", "bind_dn": "binddn", "bind_password": "asdf", "server": "1.4.5.6:2345", "protocol": "ldaps_only", "ignore_ssl_errors": false, "ca_cert": "-----BEGIN CERTIFICATE-----\nMIIG ... ikTH/\n-----END CERTIFICATE-----\n" }, "tacacs": { "auth_server": "1.2.3.4", "auth_method": "pap", "service": "raccess" }, "auth_type": "Local", "use_remote_groups": true } } /groups: type: base-type description: The groups endpoint is used to update and retrieve the group configuration from the console server put: body: application/json: type: getGroupsResponse example: { "groups": [ { "name": "custom_group", "description": "A custom group", "roles": ["admin", "operators"], "ports": [ true, false, false, false, false, false, false, false, false, false ], "system": false } ] } responses: 400: description: Invalid request body: application/json: example: { "error": "Invalid request data." } 200: description: Successful request body: application/json: type: getGroupsResponse example: { "meta": { "total_pages": 1 }, "groups": [ { "name": "root", "description": "Default system super user group", "roles": [], "ports": [ false, false, false, false, false, false, false, false, false, false ], "system": true }, { "name": "custom_group", "description": "A custom group", "roles": ["admin", "operators"], "ports": [ true, false, false, false, false, false, false, false, false, false ], "system": false } ] } get: responses: 200: description: Successful request body: application/json: type: getGroupsResponse example: { "meta": { "total_pages": 1 }, "groups": [ { "name": "root", "description": "Default system super user group", "roles": [], "ports": [ false, false, false, false, false, false, false, false, false, false ], "system": true }] } /{$id}: type: base-type description: Retrieve the configuration of a particular group get: responses: 200: description: Successful request body: application/json: type: getGroupResponse /users: type: base-type description: User list configuration for console server get: description: Get full list of users and user configuration data responses: 200: body: application/json: type: object properties: users: type: array items: userConfiguration meta: type: object properties: total_pages: type: number example: { 'meta': {'total_pages': 1}, 'users': [ { 'id': 'user1', 'username': 'root', 'description': 'Root User', 'disabled': false, 'groups': [] }, { 'id': 'user2', 'username': 'coolguy', 'description': '', 'disabled': false, 'groups': ['cool'] }, { 'id': 'user3', 'username': 'alice', 'description': '', 'disabled': false, 'groups': ['pmadmin'] }]} put: description: Update the full list of users configurations. Note 'password' is required for new users. body: application/json: type: userConfigurationListUpdate example: { 'users': [ { 'id': 'user1', 'username': 'root', 'description': 'Root User', 'disabled': false, 'groups': [] }, { 'id': 'user2', 'username': 'coolguy', 'description': 'test', 'disabled': false, 'password': 'asdf1234', 'groups': ['cool'] }, { 'id': 'user3', 'username': 'alice', 'description': 'test', 'disabled': false, 'password': 'password', 'groups': ['pmadmin'] }]} responses: 201: description: On success the updated list of user configurations is returned body: application/json: type: userConfigurationList delete: description: Delete all users except root responses: 200: body: application/json: type: message example: { "message": "OK" } /{$id}: type: base-type description: Single user configuration for console server get: description: Get single user configuration responses: 200: body: application/json: type: object properties: user: type: userConfiguration example: { 'user': { 'id': 'user1', 'username': 'root', 'description': 'Root User', 'disabled': false, 'groups': [] } } /scripts: type: base-type description: The scripts endpoint is used to upload and execute custom user scripts on the console server and to retrieve the status of currently executing scripts post: description: Upload a shell script to be executed on the node body: multipart/form-data: properties: script_metadata: description: JSON object containing script_timeout in minutes and the script_checksum (SHA1). required: true type: script_metadata example: { "script_timeout": 15, "script_checksum": "ca69c6a865dffa6b745f25f6c446d1ff24a7d394" } file: description: The file to be uploaded. required: true type: file responses: 400: description: Invalid request body: application/json: example: { "error": "Invalid script metadata" } 200: description: Successful request body: application/json: type: object properties: execution_id: type: string info: type: string example: { "info": "Script execution started successfully", "execution_id": "ASD123" } get: description: Retrieve the status of a script executing on the node by execution ID queryParameters: execution_id: type: string example: "ASD123" required: true responses: 200: description: Successful request body: application/json: type: object example: { "script_status": "in_progress" } 400: description: Invalid request body: application/json: type: object example: { "error": "Script execution ID not provided" } 500: description: Unexpected error body: application/json: type: object example: { "error": "Script exit code not found" } /serialPorts: type: base-type description: The Serial port endpoint is used to retrieve the serial port configuration from the console server get: responses: 200: description: Successful request body: application/json: type: getSerialPortsResponse example: { "serialports": [ { "label": "sv.router", "id": "port1", "modeSettings": { "consoleServer": { "ssh": { "enabled": true, "unauthenticated": false }, "tcp": { "enabled": false }, "general": { "accumulateMS": 0, "replaceBackspace": false, "powerMenuEnabled": false, "escapeChar": "~", "singleConnection": false }, "portShare": { "enabled": false, "password": "secrets", "authentication": false, "encryption": false }, "rfc2217": { "enabled": false }, "webShell": { "enabled": false }, "telnet": { "enabled": true, "unauthenticated": false }, "ipAlias": { "wan": [], "oobfo": [], "wlan": [], "lan": [] } } }, "attachedDeviceType": "none", "hardwareSettings": { "pinout": "X2", "protocol": "RS232", "uart": { "parity": "none", "baud": "9600", "stopBits": "1", "dataBits": "8", "flowControl": "none", "dtrMode": "alwayson" } }, "ctrlCode": { "quit": 4, "generateBreak": 6, "chooser": 3, "help": 5, "portLog": 1, "power": 0 }, "logging": { "level": "accessInputOutput", "priority": "default", "facility": "default" }, "mode": "consoleServer", "nagios": { "enabled": false, "serialStatus": false, "name": "", "portLogging": false }, "hardwareType": "builtInUART", "nmeaStreaming" : { "enabled": false, "fixFrequency": 5 } }, { "label": "sv.fileserver", "id": "port2", "modeSettings": { "consoleServer": { "ssh": { "enabled": true, "unauthenticated": false }, "tcp": { "enabled": false }, "general": { "accumulateMS": 0, "replaceBackspace": false, "powerMenuEnabled": false, "escapeChar": "~", "singleConnection": false }, "portShare": { "enabled": false, "password": "secrets", "authentication": false, "encryption": false }, "rfc2217": { "enabled": false }, "webShell": { "enabled": false }, "telnet": { "enabled": true, "unauthenticated": false }, "ipAlias": { "wan": [], "oobfo": [], "wlan": [], "lan": [] } } }, "attachedDeviceType": "none", "hardwareSettings": { "pinout": "X2", "protocol": "RS232", "uart": { "parity": "none", "baud": "9600", "stopBits": "1", "dataBits": "8", "flowControl": "none", "dtrMode": "alwayson" } }, "ctrlCode": { "quit": 10, "generateBreak": 6, "chooser": 0, "help": 5, "portLog": 1, "power": 0 }, "logging": { "level": "accessInputOutput", "priority": "default", "facility": "default" }, "mode": "consoleServer", "nagios": { "enabled": false, "serialStatus": false, "name": "", "portLogging": false }, "hardwareType": "builtInUART", "nmeaStreaming" : { "enabled": false, "fixFrequency": 5 } }]} /{$id}: type: base-type description: Retrieve / update the configuration of a particular serial port get: responses: 200: description: Successful request body: application/json: type: getSerialPortResponse example: { "serialport": { "label": "sv.router", "id": "port1", "modeSettings": { "consoleServer": { "ssh": { "enabled": true, "unauthenticated": false }, "tcp": { "enabled": false }, "general": { "accumulateMS": 0, "replaceBackspace": false, "powerMenuEnabled": false, "escapeChar": "~", "singleConnection": false }, "portShare": { "enabled": false, "password": "secrets", "authentication": false, "encryption": false }, "rfc2217": { "enabled": false }, "webShell": { "enabled": false }, "telnet": { "enabled": true, "unauthenticated": false }, "ipAlias": { "wan": [], "oobfo": [], "wlan": [], "lan": [] } } }, "attachedDeviceType": "none", "hardwareSettings": { "pinout": "X2", "protocol": "RS232", "uart": { "parity": "none", "baud": "9600", "stopBits": "1", "dataBits": "8", "flowControl": "none", "dtrMode": "alwayson" } }, "ctrlCode": { "quit": 0, "generateBreak": 6, "chooser": 3, "power": 2, "help": 5, "portLog": 1 }, "logging": { "level": "accessInputOutput", "priority": "default", "facility": "default" }, "mode": "consoleServer", "nagios": { "enabled": false, "serialStatus": false, "name": "", "portLogging": false }, "hardwareType": "builtInUART", "nmeaStreaming": { "enabled": false, "fixFrequency": 5 } } } 404: description: Invalid Port ID body: application/json: type: error 304: description: Serial Port configuration matches the provided Etag 500: description: Internal server error body: application/json: type: error put: body: application/json: type: updateSerialPortRequest example: { "serialport": { "label": "Port 5", "id": "port5", "modeSettings": { "consoleServer": { "ssh": { "enabled": true, "unauthenticated": false }, "telnet": { "enabled": false, "unauthenticated": false }, "general": { "replaceBackspace": false, "escapeChar": "~", "singleConnection": false, "accumulateMS": 0, "powerMenuEnabled": false }, "portShare": { "password": "", "authentication": false, "enabled": false, "encryption": false }, "rfc2217": { "enabled": false }, "webShell": { "enabled": false }, "tcp": { "enabled": false }, "ipAlias": { "wan": [], "oobfo": [], "wlan": [], "lan": [] } } }, "attachedDeviceType": "none", "hardwareSettings": { "pinout": "X2", "protocol": "RS232", "uart": { "parity": "none", "baud": "9600", "stopBits": "1", "dataBits": "8", "flowControl": "none", "dtrMode": "alwayson" } }, "logging": { "priority": "default", "facility": "default", "level": "disabled" }, "ctrlCode": { "quit": 4, "generateBreak": 5, "chooser": 3, "power": 2, "help": 6, "portLog": 1 }, "hardwareType": "builtInUART", "mode": "consoleServer", "nagios": { "enabled": false, "serialStatus": false, "name": "", "portLogging": false } } } responses: 200: description: Successful update body: application/json: type: updateSerialPortResponse 400: description: Invalid request data body: application/json: type: error 404: description: Invalid Port ID body: application/json: type: error 412: description: Etag doesn't match (Indicates serial port config has changed since last get request) body: application/json: type: error 500: description: Internal server error body: application/json: type: error patch: body: application/json: type: patchSerialPortRequest example: { "serialport": { "label": "My Port" } } responses: 200: description: Successful update body: application/json: type: getSerialPortResponse 400: description: Invalid request data body: application/json: type: error 404: description: Invalid Port ID body: application/json: type: error 412: description: Etag doesn't match (Indicates serial port config has changed since last get request) body: application/json: type: error 500: description: Internal server error body: application/json: type: error /secureShell: type: base-type description: This endpoint is used for getting the SSH port of the device get: responses: 200: description: Successful Request body: application/json: type: getSecureShellResponse example: { "ssh": { "port": 22 } } 500: description: Internal Error body: application/json: type: error /keys/host: type: base-type description: This endpoint is used for retrieving SSH keys, and modifying user's authorized keys lists get: responses: 200: description: Successful Request body: application/json: type: getSecureShellHostKeysResponse example: { "keys": { "ecdsa": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBMhfUnZC8MD+iqxLq7vhvUCoFTzC1+lmieMXj2N6j+SUHYkKipoNkI9kks3PEXIMwShiVJ3ySW5cERFDvRsVT+c=", "ed25519": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIC59SOqiYAs3DfLEtdW6RE/W2OY1WCEkQi/1AqUkOvs5", "rsa": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDN+Gd1ul7tCYWiAC3CQ76MM+FfhesjKimeMSeVNUfIvK4rTGfL14LKUB37rJAU5PhO/snRw+xtQRaD5SHzDHzCh1xXzVlb+x77IqeasbeKhWNCCYfgHNx1sAxzwnAUA26UifoAZSv81HLmE9kJnCqTH0o54HKdRtUQGyo0a0F1tTweQKlrCPxQ6YoDfMbFhsYgPPX+66L6ku5xvcc4pbT5caJ1pw6cX5Fej49Bkbl+SHYiMYNFX05nIHSstpfgdWgOv3xm43DjAXLD3d5lGC5aYkqgJO0X5n6KjpoOGHaMZ9dn/t4O14ZX2Jl46SMSr8XQmSZoIijQyUP9AW8oUMTdSvUT/P1TLBlcPuw76MHJkij8TP2/r9ICyzXQSzhlCv0vGWAZsi1SZ8PQFv6iAtTu/2UXdvmBxdkuDx2IPwNtvC+e8GRcEYFY8ziUnWVlf7QjhaDkrcamdoAo7wErEKO1iV/hcgfKemLuIVvqkKS9Qj0rHS5wAnrfFx7WhjRa5BqCA/H4pBozgMBrdR/9lseYNu4vjMaGRYLaUhfZj1S2c7uKd+vEZI3nmCCQmBJ1qR2ih8USeZbIcrf2QMGhdKUIoFxjM9c3NabWmRNPSJIgL8N19+itb4Yz6ycs+wJyegdpJ5TCrSrHo8Tt5e/5PX604NuHtEDXpG+T/HjhccWNQ==" } } 500: description: Internal Error body: application/json: type: error /keys/user/${username}/authorized: type: base-type description: This endpoint is used for modifying user's authorized keys lists put: description: | Add authorized keys for the user. Note that existing keys that match both keytype and identifier will be replaced. This is designed to avoid adding duplicate entries. body: application/json: type: secureShellAuthorizedKeys example: { keys: [ { "keytype": "ssh-ed25519", "key": "AAAAC3NzaC1lZDI1NTE5AAAAIAw5O2cMeS3LPPkNH7J846w00m7TDjuirsdnRMY2FxOM", "identifier": "user@somehost" } ] } responses: 200: description: Successful Request body: application/json: type: message 500: description: Internal Error body: application/json: type: error delete: description: | Remove authorized keys for the user. Existing keys must match all of the supplied fields to be removed. body: application/json: type: secureShellAuthorizedKeysDelete example: { keys: [ { "keytype": "ssh-ed25519", "identifier": "user@somehost" } ] } responses: 200: description: Successful Request body: application/json: type: message 500: description: Internal Error body: application/json: type: error /nodeDescription: type: base-type description: This endpoint is used to retrieve run-time details about the device get: responses: 200: description: Successful Request body: application/json: type: getNodeDescriptionResponse example: { "model_number": "ACM7004-2", "serial_number": "70000261411598", "hostname": "acm7004-2", "interfaces": [ { "ipv4_addresses": [ "192.168.125.102" ], "name": "Network", "ipv6_addresses": [ "fd07:2218:1350:7d::1:8fcb", "fd07:2218:1350:7d:213:c6ff:fe01:d005", "fe80::213:c6ff:fe01:d005" ] }, { "ipv4_addresses": [ "10.250.100.5" ], "name": "Management LAN", "ipv6_addresses": [ "fd07:2218:1350:7d::1:78da", "fd07:2218:1350:7d:213:c6ff:fe01:d006", "fe80::213:c6ff:fe01:d006" ] } ], "mac_address": "00:13:c6:01:d0:05", "firmware_version": "4.8.0" } 500: description: Internal Error body: application/json: type: error /system/version: type: base-type description: The system/version endpoint is used to retrieve the system version from the console server get: responses: 200: description: Successful request body: application/json: type: getSystemVersionResponse example: { "system_version":{ "etc_version":"OpenGear/ACM700x Version 4.3.0 host:yavin4 branch:branch1 d732a8c4* -- Wednesday 11 July 23:14:11 UTC 2018", "rest_api_version":"v1.1", "firmware_version":"4.3.0" } } /interfaces: type: base-type description: This endpoint is used to list network interfaces (only cellmodem for now) get: responses: 200: description: Succesful request body: application/json: type: getInterfacesResponse example: [ { "href": "/api/v1.3/interfaces/cellmodem", "id": "cellmodem", "enabled": true, "links": [ { "href": "/api/v1.1/interfaces/cellmodem/status", "rel": "status" }, { "href": "/api/v1.1/interfaces/cellmodem/tests", "rel": "tests" } ] } ] /cellmodem: type: base-type description: Cellular modem end-points are nested under here /status: type: base-type description: This endpoint is used to retrieve status data about the cellular modem in the device get: responses: 200: description: Succesful request body: application/json: type: getInterfaceStatusResponse example: { "interface": "/api/v1.3/interfaces/cellmodem", "enabled": true, "up": true, "passthrough": { "enabled": true, "active": true }, "ar_controlled": false, "failover": { "enabled": false, "dormant": false, "active": false }, "links": [ { "wwan": { "mdn": "", "signalStrength": 89, "technology": "gsm-umts, lte", "msid": "", "rssi": -67, "failure_reason": "none", "carrier": "Telstra Corp. Ltd.", "modem_status": "connected", "imei": "359260080000588", "imsi": "403013419552809", "iccid": "29310160092730753632", "current_bands": "WCDMA 2100 MHz (Class I), WCDMA 3GPP 1800 MHz (Class III), WCDMA 3GPP UMTS 1900 MHz (Class II), WCDMA 3GPP AWS 1700/2100 MHz (Class IV), WCDMA 3GPP UMTS 800 MHz (Class VI), WCDMA 3GPP UMTS 850 MHz (Class V), WCDMA 3GPP UMTS 900 MHz (Class VIII), WCDMA 3GPP UMTS 1700 MHz (Class IX), E-UTRAN band I, E-UTRAN band II, E-UTRAN band III, E-UTRAN band IV, E-UTRAN band V, E-UTRAN band VII, E-UTRAN band VIII, E-UTRAN band IX, E-UTRAN band XII, E-UTRAN band XIII, E-UTRAN band XVIII, E-UTRAN band XIX, E-UTRAN band XX, E-UTRAN band XLI, E-UTRAN band XLI, E-UTRAN band XLIII" } } ], } /tests: type: base-type description: This endpoint is used to list available cell modem tests get: responses: 200: description: Succesful request body: application/json: type: getInterfaceTestsResponse example: [ { "rel": "ping", "href": "/api/v1.3/interfaces/cellmodem/tests/ping", }, { "rel": "http", "href": "/api/v1.3/interfaces/cellmodem/tests/http" }, { "rel": "dns", "href": "/api/v1.3/interfaces/cellmodem/tests/dns" } ] /ping: type: base-type description: This endpoint is used to test ping on a cellmodem interface post: body: application/json: type: interfaceTestRequestPing responses: 201: description: Ping test created body: application/json: type: interfaceTestResponse example: { } /http: type: base-type description: This endpoint is used to test HTTP on a cellmodem interface post: body: application/json: type: interfaceTestRequestHttp responses: 201: description: HTTP test created body: application/json: type: interfaceTestResponse example: { } /dns: type: base-type description: This endpoint is used to test DNS on a cellmodem interface post: body: application/json: type: interfaceTestRequestDNS responses: 201: description: DNS test created body: application/json: type: interfaceTestResponse example: { } /backup: type: base-type description: This endpoint is used to request a system configuration backup file get: responses: 200: description: System configuration backup file attached body: application/octet-stream: /eventLogs: type: base-type description: This endpoint is used to retrieve the active event log receivers get: responses: 200: description: Array of event log descriptors body: application/json: type: object properties: eventlog: type: array items: type: eventLogRef example: { "eventlog": [ { "id": "application@example.com", "href": "/api/v1.9/eventLogs/remote", } ] } /{$id}: type: base-type description: An instance of an event log receiver get: responses: 200: description: Successful request body: application/json: type: eventLogGetResponse example: { "eventlog": { "id": "application@example.com", "type": "syslog", "syslog": { "address": "syslog.example.com", } } } put: body: application/json: type: eventLogPutRequest example: { "eventlog": { "type": "syslog", "syslog": { "address": "syslog.example.com", } } } responses: 400: description: Bad request body: application/json: type: error 201: description: Accepted body: application/json: type: message delete: responses: 204: description: Deleted