Console Server REST API version v1

https://{cshost}/api/v1

  • cshost: required(string)

Console Server REST API

This API allows inspection of an Opengear Console Server Appliance.

/sessions

The sessions endpoint is used to authenticate the user and create a session token for accessing all other Lighthouse endpoints.

post

post

Create a new authenticated session.

Create a new authenticated session.

Body

Media type: application/json

Type: object

Properties
  • username: required(string)
  • password: required(string)

Example:

{
  "username": "root",
  "password": "default"
}

HTTP status code 200

Body

Media type: application/json

Type: object

Properties
  • state: required(string)
  • session: required(string)
  • user: (string)
  • last_challenge: (string)

Example:

{
  "state": "authenticated",
  "session": "71dcba707b6c177644ede1b224f69096",
  "user": "root"
}

HTTP status code 303

Redirect to new authentication session

Body

Media type: application/json

Type: any

Example:

{
  "sid": "71dcba707b6c177644ede1b224f69096",
  "message": "Redirecting to new session at {redirect-url}"
}

HTTP status code 400

Failed to initiate session creation due to error in post body.

Body

Media type: application/json

Type: any

Example:

{
  "type": "authError",
  "example": {
    "error": "Invalid request body"
  }
}

HTTP status code 401

Authentication failed due to invalid credentials or session.

Body

Media type: application/json

Type: any

Example:

{
  "error": [
    {
      "type": 7,
      "code": 41,
      "text": "Invalid login credentials",
      "args": {},
      "level": 1
    }
  ]
}

get put delete

get

Retrieve the state of an authentication session by ID. A session ID may be valid for some period after the user logs out.

put

Apply a challenge response to a session

delete

Log out of and delete a session

Retrieve the state of an authentication session by ID. A session ID may be valid for some period after the user logs out.

Secured by token

Console Server base authentication scheme

URI Parameters

  • sessionUid: required(string)

Headers

  • Authorization: required(string)

    Example:

    Token {{sessionUid}}

HTTP status code 200

Session exists

Body

Media type: application/json

Type: object

Properties
  • state: required(string)
  • session: required(string)
  • user: (string)
  • last_challenge: (string)

Example:

{
  "state": "authenticated",
  "session": "71dcba707b6c177644ede1b224f69096",
  "user": "root"
}

HTTP status code 304

Etag matched If-None-Match header

Body

Media type: application/json

Type: object

Example:

example1:

{}

HTTP status code 400

No session in data

Body

Media type: application/json

Type: object

Properties
  • error: required(string)

    An error string

Example:

example1:

{
  "error": "Failed to parse request data"
}

HTTP status code 401

Authentication failure

Body

Media type: application/json

Type: object

Properties
  • error: required(string)

    The authentication error string

Example:

example1:

{
  "error": "Invalid login credentials"
}

HTTP status code 404

Resource not found

Body

Media type: application/json

Type: object

Properties
  • error: required(string)

    An error string

Example:

example1:

{
  "error": "Resource not found"
}

HTTP status code 500

Internal error

Body

Media type: application/json

Type: object

Properties
  • error: required(string)

    An error string

Example:

example1:

{
  "error": "Failed to open configuration handle"
}

Secured by token

Headers

  • Authorization: required(string)

    authorization session token

    Example:

    Token 521a00e57d4a461b3e4bb0c55166f97c

Apply a challenge response to a session

Secured by token

Console Server base authentication scheme

URI Parameters

  • sessionUid: required(string)

Headers

  • Authorization: required(string)

    Example:

    Token {{sessionUid}}

Body

Media type: application/json

Type: object

Properties
  • session: required(string)
  • state: required(object)
    • challenge: required(string)

      Next challenge (if any)

    HTTP status code 200

    Response applied. Next challenge in {challenge} if required.

    Body

    Media type: application/json

    Type: object

    Properties
    • session: required(string)
    • state: required(object)
      • challenge: required(string)

        Next challenge (if any)

      HTTP status code 400

      Invalid request

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      HTTP status code 401

      Authentication failure

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        The authentication error string

      Example:

      {
  "error": "Invalid Session ID"
}

      HTTP status code 403

      Authentication failed. No more attempts allowed.

      HTTP status code 404

      Authentication failed.

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      HTTP status code 500

      Internal error

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      Secured by token

      Headers

      • Authorization: required(string)

        authorization session token

        Example:

        Token 521a00e57d4a461b3e4bb0c55166f97c

      Log out of and delete a session

      Secured by token

      Console Server base authentication scheme

      URI Parameters

      • sessionUid: required(string)

      Headers

      • Authorization: required(string)

        Example:

        Token {{sessionUid}}

      HTTP status code 200

      Session deleted

      Body

      Media type: application/json

      Type: object

      Properties
      • session: required(string)
      • success: required(string)
      • state: required(string)
      • user: required(string)

      HTTP status code 400

      Incomplete data

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      HTTP status code 401

      Authentication failure

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        The authentication error string

      Example:

      {
  "error": "Invalid Session ID"
}

      HTTP status code 404

      Session did not exist

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      HTTP status code 500

      Internal error

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      Secured by token

      Headers

      • Authorization: required(string)

        authorization session token

        Example:

        Token 521a00e57d4a461b3e4bb0c55166f97c

      /registration

      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 delete

      post
      delete
      Secured by token

      Console Server base authentication scheme

      Headers

      • Authorization: required(string)

        Example:

        Token {{sessionUid}}

      Body

      Media type: application/json

      Type: object

      Properties
      • id: required(string)

        The ID of the node - this is generated by Lighthouse

      • server: required(string)

        The address of the Lighthouse - this is either an IP address or a hostname

      • package_password: required(string)

        This is the password used to request the enrollment package from Lighthouse. Once enrolled, a certificate is used for all authentication

      HTTP status code 400

      Invalid request

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      Example:

      {
  "error": "Invalid request data."
}

      HTTP status code 401

      Authentication failure

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        The authentication error string

      Example:

      {
  "error": "Invalid Session ID"
}

      HTTP status code 404

      Resource not found

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      Example:

      example1:

      {
  "error": "Resource not found"
}

      HTTP status code 500

      Internal error

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      Example:

      example1:

      {
  "error": "Failed to open configuration handle"
}

      Secured by token

      Headers

      • Authorization: required(string)

        authorization session token

        Example:

        Token 521a00e57d4a461b3e4bb0c55166f97c

      put

      Update the server address of a connection to Lighthouse

      put
      Secured by token

      Console Server base authentication scheme

      URI Parameters

      • $id: required(string)

      Headers

      • Authorization: required(string)

        Example:

        Token {{sessionUid}}

      Body

      Media type: application/json

      Type: object

      Properties
      • address: required(string)

        updated server address

      Example:

      {
  "address": "192.168.128.6"
}

      HTTP status code 200

      Server address updated successfully

      Body

      Media type: application/json

      Type: any

      Example:

      {
  "message": "OK"
}

      HTTP status code 400

      Invalid request

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      Example:

      {
  "error": "Parameter 'id' not provided."
}

      HTTP status code 401

      Authentication failure

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        The authentication error string

      Example:

      {
  "error": "Invalid Session ID"
}

      HTTP status code 404

      Not found

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      HTTP status code 500

      Internal server error

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      Secured by token

      Headers

      • Authorization: required(string)

        authorization session token

        Example:

        Token 521a00e57d4a461b3e4bb0c55166f97c

      /auth

      The auth endpoint is used to update and retrieve the authentication configuration from the console server

      put get

      put
      get

      /groups

      The groups endpoint is used to update and retrieve the group configuration from the console server

      put get

      put
      get

      get

      Retrieve the configuration of a particular group

      get
      Secured by token

      Console Server base authentication scheme

      URI Parameters

      • $id: required(string)

      Headers

      • Authorization: required(string)

        Example:

        Token {{sessionUid}}

      HTTP status code 200

      Successful request

      Body

      Media type: application/json

      Type: object

      Properties
      • group: required(object)

        Console Server Group Configuration

        • name: required(string)

          The name of the group

        • description: (string)

          The description of the group

        • roles: required(array of string)

          The list of roles provided by the group

        • ports: required(array of boolean)

          A list of flags for whether the group has access to each serial port

        • system: required(boolean)

          A flag indicating whether or not this is a system group

      HTTP status code 304

      Etag matched If-None-Match header

      Body

      Media type: application/json

      Type: object

      Example:

      example1:

      {}

      HTTP status code 400

      Request data error

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      Example:

      example1:

      {
  "error": "Failed to parse request data"
}

      HTTP status code 401

      Authentication failure

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        The authentication error string

      Example:

      example1:

      {
  "error": "Invalid login credentials"
}

      HTTP status code 404

      Resource not found

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      Example:

      example1:

      {
  "error": "Resource not found"
}

      HTTP status code 500

      Internal error

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      Example:

      example1:

      {
  "error": "Failed to open configuration handle"
}

      Secured by token

      Headers

      • Authorization: required(string)

        authorization session token

        Example:

        Token 521a00e57d4a461b3e4bb0c55166f97c

      /users

      User list configuration for console server

      get put delete

      get

      Get full list of users and user configuration data

      put

      Update the full list of users configurations. Note 'password' is required for new users.

      delete

      Delete all users except root

      get

      Single user configuration for console server

      get

      Get single user configuration

      Get single user configuration

      Secured by token

      Console Server base authentication scheme

      URI Parameters

      • $id: required(string)

      Headers

      • Authorization: required(string)

        Example:

        Token {{sessionUid}}

      HTTP status code 200

      Body

      Media type: application/json

      Type: object

      Properties
      • user: required(object)

        Console server user configuration

        • id: required(string)
        • description: required(string)

          Must not contain ':'

        • username: required(string)
        • disabled: required(boolean)
        • groups: required(array of string)

          List of group names for which this user is a member

      Example:

      {
  "user": {
    "id": "user1",
    "username": "root",
    "description": "Root User",
    "disabled": false,
    "groups": []
  }
}

      HTTP status code 304

      Etag matched If-None-Match header

      Body

      Media type: application/json

      Type: object

      Example:

      example1:

      {}

      HTTP status code 400

      Request data error

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      Example:

      example1:

      {
  "error": "Failed to parse request data"
}

      HTTP status code 401

      Authentication failure

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        The authentication error string

      Example:

      example1:

      {
  "error": "Invalid login credentials"
}

      HTTP status code 404

      Resource not found

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      Example:

      example1:

      {
  "error": "Resource not found"
}

      HTTP status code 500

      Internal error

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      Example:

      example1:

      {
  "error": "Failed to open configuration handle"
}

      Secured by token

      Headers

      • Authorization: required(string)

        authorization session token

        Example:

        Token 521a00e57d4a461b3e4bb0c55166f97c

      /scripts

      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 get

      post

      Upload a shell script to be executed on the node

      get

      Retrieve the status of a script executing on the node by execution ID

      Upload a shell script to be executed on the node

      Secured by token

      Console Server base authentication scheme

      Headers

      • Authorization: required(string)

        Example:

        Token {{sessionUid}}

      Body

      Media type: multipart/form-data

      Type: object

      Properties
      • script_metadata: required(object)

        JSON object containing script_timeout in minutes and the script_checksum (SHA1).

        • script_timeout: required(integer)

          The number of minutes that the script is allowed to run

        • script_checksum: required(string)

          The SHA1 checksum of the script

        Example:

        {
  "script_timeout": 15,
  "script_checksum": "ca69c6a865dffa6b745f25f6c446d1ff24a7d394"
}
      • file: required(file)

        The file to be uploaded.

      HTTP status code 200

      Successful request

      Body

      Media type: application/json

      Type: object

      Properties
      • execution_id: required(string)
      • info: required(string)

      Example:

      {
  "info": "Script execution started successfully",
  "execution_id": "ASD123"
}

      HTTP status code 400

      Invalid request

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      Example:

      {
  "error": "Invalid script metadata"
}

      HTTP status code 401

      Authentication failure

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        The authentication error string

      Example:

      {
  "error": "Invalid Session ID"
}

      HTTP status code 404

      Resource not found

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      Example:

      example1:

      {
  "error": "Resource not found"
}

      HTTP status code 500

      Internal error

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      Example:

      example1:

      {
  "error": "Failed to open configuration handle"
}

      Secured by token

      Headers

      • Authorization: required(string)

        authorization session token

        Example:

        Token 521a00e57d4a461b3e4bb0c55166f97c

      /serialPorts

      The Serial port endpoint is used to retrieve the serial port configuration from the console server

      get

      get

      get

      Retrieve the configuration of a particular serial port

      get
      Secured by token

      Console Server base authentication scheme

      URI Parameters

      • $id: required(string)

      Headers

      • Authorization: required(string)

        Example:

        Token {{sessionUid}}

      HTTP status code 200

      Successful request

      Body

      Media type: application/json

      Type: object

      Properties
      • serialport: required(object)

        Console Server Serial Port Configuration

        • label: required(string)

          The label for the serial port

        • id: required(string)

          The id of the serial port. This ID can be used to fetch individual ports using the /serialPorts/{portid} endpoint

        • attachedDeviceType: required(one of unknown, none, remotePowerControl, uninterruptiblePowerSupply, environmentMonitor, nmeaSource, powerAlert)

          The type of device attached to the serial port. Ports in console server mode will have this property set to 'none'

        • hardwareType: required(one of unknown, builtInUART, builtInUSB, removableUSB)

          The underlying hardware type of the port. This is used to indicate if its a fixed or removable port.

        • mode: required(one of disabled, localConsole, consoleServer, sdtServer, bridge, terminalServer, reserved, powerman, unknown)

          The mode that the port is in

        • hardwareSettings: required(object)

          This group of properties define the hardware level configuration of the port

          • pinout: required(one of X0, X1, X2)

            The physical pinout of the port connector

          • protocol: required(one of RS232, RS422, RS485, RS485e)

            The data protocol the port is using when transmitting and receiving

          • uart: required(object)

            UART configuration settings

            • parity: required(one of none, unknown, even, mark, space)

              The format of the parity byte

            • baud: required(one of 50, 75, 110, 134, 150, 200, 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400)

              The communication rate of the port

            • stopBits: required(one of 1, 1.5, 2)

              The number of stop bits between characters

            • dataBits: required(one of 5, 6, 7, 8)

              The number of data bits in a character

            • flowControl: required(one of unknown, none, noneUnpowered, hardware, software, softwareUnpowered)

              The algorithm used for flow control.

        • modeSettings: required(union of consoleServer or terminalServer or bridge or sdtServer)

          This object contains mode specific configuration objects. Only the object corresponding to the 'mode' property will be present

        • nagios: required(object)

          This object contains Nagios related configuration settings for this port

          • enabled: required(boolean)

            Indicates if nagios checks are enabled for this port

          • serialStatus: required(boolean)

            Indicates if the nagios serial status check should be configured for this port

          • name: required(string)

            The Nagios name for the port (autogenerated from the hostname and the port name)

          • portLogging: required(boolean)

            Indicates if nagios port logging is enabled

        • logging: required(object)

          This object contains logging related configuration settings for this port

          • level: required(one of unknown, disabled, access, accessInputOutput, accessInput, accessOutput)

            Indicates the logging level for the port

          • priority: required(one of default, warning, notice, info, error, emergency, debug, critical, alert)

            The log priority to assign to log messages from this port when they're sent to a remote syslog server

          • facility: required(one of default, local0, local1, local2, local3, local4, local5, local6, local7, auth, authpriv, cron, daemon, ftp, kern, lpr, mail, news, user, uucp)

            The log facility to assign to log messages from this port when they're sent to a remote syslog server

      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": "~"
        },
        "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"
      }
    },
    "logging": {
      "level": "accessInputOutput",
      "priority": "default",
      "facility": "default"
    },
    "mode": "consoleServer",
    "nagios": {
      "enabled": false,
      "serialStatus": false,
      "name": "",
      "portLogging": false
    },
    "hardwareType": "builtInUART"
  }
}

      HTTP status code 304

      Serial Port configuration matches the provided Etag

      Body

      Media type: application/json

      Type: object

      Example:

      example1:

      {}

      HTTP status code 400

      Request data error

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      Example:

      example1:

      {
  "error": "Failed to parse request data"
}

      HTTP status code 401

      Authentication failure

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        The authentication error string

      Example:

      example1:

      {
  "error": "Invalid login credentials"
}

      HTTP status code 404

      Invalid Port ID

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      Example:

      example1:

      {
  "error": "Resource not found"
}

      HTTP status code 500

      Internal server error

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      Example:

      example1:

      {
  "error": "Failed to open configuration handle"
}

      Secured by token

      Headers

      • Authorization: required(string)

        authorization session token

        Example:

        Token 521a00e57d4a461b3e4bb0c55166f97c

      /secureShell

      This endpoint is used for getting the SSH port of the device

      get

      get

      get

      This endpoint is used for retrieving SSH keys, and modifying user's authorized keys lists

      get

      put

      This endpoint is used for modifying user's authorized keys lists

      put
      Secured by token

      Console Server base authentication scheme

      URI Parameters

      • username: required(string)

      Headers

      • Authorization: required(string)

        Example:

        Token {{sessionUid}}

      Body

      Media type: application/json

      Type: object

      Properties
      • keys: required(array of object)

        Items: items

        • keytype: required(one of ssh-rsa, ssh-ed25519, ssh-ecdsa)
        • key: required(string)

          The key as a base64 encoded string

        • identifier: required(string)

          Comment to identify the key. Usually an email address.

      Example:

      {
  "keys": [
    {
      "keytype": "ssh-ed25519",
      "key": "AAAAC3NzaC1lZDI1NTE5AAAAIAw5O2cMeS3LPPkNH7J846w00m7TDjuirsdnRMY2FxOM",
      "identifier": "user@somehost"
    }
  ]
}

      HTTP status code 200

      Successful Request

      Body

      Media type: application/json

      Type: object

      Properties
      • message: required(string)

      HTTP status code 400

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      HTTP status code 401

      Authentication failure

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        The authentication error string

      Example:

      {
  "error": "Invalid Session ID"
}

      HTTP status code 404

      Not found

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      HTTP status code 500

      Internal Error

      Body

      Media type: application/json

      Type: object

      Properties
      • error: required(string)

        An error string

      Secured by token

      Headers

      • Authorization: required(string)

        authorization session token

        Example:

        Token 521a00e57d4a461b3e4bb0c55166f97c

      /nodeDescription

      This endpoint is used to retrieve run-time details about the device

      get

      get