Mistake on this page? Email us

Debugging through terminal commands

Note: We provide this service for limited availability. To access it, please contact us.

If you need to debug a gateway, it is easier to find the issue if you can debug it by entering commands into terminals on gateways directly. You can do this using the Gateway Terminal Service, which acts as a terminal service in Device Management Portal for your region:

A terminal in the portal works exactly like a terminal inside the gateway, which provides remote access to terminals on gateways for debugging Izuma Edge gateways with efficiency and flexibility.

With Gateway Terminal Service, you can:

  • Access a gateway by opening a terminal in Device Management Portal.
  • Input text commands into a terminal to interact with a gateway.
  • Resize a terminal by adjusting the terminal window in Device Management Portal.
  • Close a terminal to terminate the terminal session on a gateway.

Gateway Terminal Service accepts user connections from the API domain (user mode) and gateway connections from the gateway domain (gateway mode). With the Gateway Terminal Service, you can access an edge gateway by opening a terminal in the browser. You can input text into the terminal to talk to the edge gateway, and the service sends the message back and forth between you and the edge gateway. You can also resize and close the terminal in the browser.

Gateway Terminal ServiceGateway Terminal Service

Using Gateway Terminal Service

Gateway Terminal Service accepts gateway connections from gateways and user connections from Device Management Portal. In general, a daemon program called relay-term running on gateways initializes connections from gateways. The portal initializes user connections when you open the terminal tab under the Device details page of a specific device.

To set up the relay-term daemon program on Izuma Edge:

  1. Provide the configuration parameter within a json file and named it as config.json. For example:

    {
        "cloud": "$GATEWAY_TERMINAL_SERVER_ADDRESS",
        "noValidate": true,
        "certificate": "$PATH_TO_CLIENT_CERTIFICATE",
        "key": "$PATH_TO_PRIVATE_KEY"
    }
    

    Parameters:

    • cloud: the server address of Gateway Terminal Service on Device Management.

      Example:

      "cloud": "http://gateways.mbed.com/relay-term"
      
    • noValidate: If noValidate is true, the daemon establishes the connection to the Gateway Terminal Service without providing TLS configuration. If noValidate is false, the following two parameters are required for the daemon to establish TLS-based connection to the Gateway Terminal Service.

      Example:

      "noValidate": true
      
    • certificate: path to the certificate file that you can authenticate with Device Management. If noValidate is false, this is required.

    • key: path to the private key file that you can authenticated with Device Management. If noValidate is false, this is required.

      If the device that you want to run the daemon is running Izuma Edge, you can set it up without providing any certificates because Izuma Edge can hand the authentication to Device Management.

      The configuration file is:

      {
          "cloud": "http://gateways.local:8080/relay-term",
          "noValidate": true,
      }
      

      Note: The host gateways.local will be resolved as IP address 127.0.0.1 that setup by Izuma Edge.

  2. Launch the daemon by running:

    $ git clone git://github.com/PelionIoT/edge-node-modules
    $ cd edge-node-modules/relay-term/src
    $ node index.js start config.json
    
  3. Verify the daemon launched:

    Example output when the daemon is successfully connecting to Device Management:

    $ Connecting to cloud at http://gateways********
    $ Connected to cloud at http://gateways********
    $ Relay term sending ping to server. Expecting pong within 60000 milliseconds
    $ Relay term received pong from server. Resetting pong timeout and scheduling next ping in 30000 milliseconds
    

    Example output when the daemon failed to connect to Device Management:

    $ Relay term tunnel connection disconnected:  1006
    $ Relay term tunnel attempting to establish cloud connection in 1seconds...
    $ Connecting to cloud at hhttp://gateways********
    $ Relay term tunnel connection disconnected:  1006
    $ Relay term tunnel attempting to establish cloud connection in 2seconds...
    $ Connecting to cloud at hhttp://gateways********
    $ Relay term tunnel connection disconnected:  1006
    $ Relay term tunnel attempting to establish cloud connection in 4seconds...
    

    If you see the failed log, check the parameters within config.json to make sure you're providing the correct cloud URL fpr Gateway Terminal Service and the correct certificate file and private key file.