Gateway Terminal Service
Note: We provide this service for limited availability. To access it, please contact your Pelion representative.
Gateway Terminal Service
If you need to debug a gateway, it is easier to find the issue if you can debug it at the system level. Some gateway debugging tools require specialized gateway and embedded engineering knowledge, but with a terminal, you can debug even if you only have a general programming background. A terminal in the browser works exactly like a terminal inside the gateway. You can use Gateway Terminal Service, which provides remote access to a terminal in the browser, for debugging Pelion Edge gateways.
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.
Using the service
To establish the connection for two-way communication, send a handshake WebSocket request to Gateway Terminal Service:
GET /v3alpha/devices/{id}/console ...
Upgrade: websocket
Connection: Upgrade
Host: $cloud_url
Origin: ...
Sec-WebSocket-Key: ...
Sec-WebSocket-Version: ...
The same handshake WebSocket request works for both modes.
Modes
Gateway Terminal Service has two modes: user mode and gateway mode. The user mode accepts connections from users in the form of API domain requests, and the gateway mode accepts connections from gateways in the form of gateway domain requests. You can initialize either mode through the configuration parameters you choose.
User mode
In user mode, you (and every other user) are assigned a unique randomly generated session ID as your routing key when you connect to the service. Every API domain request is first passed to the API gateway. Gateway Terminal Service receives it with the account ID and the user ID.
When forwarding messages, Gateway Terminal Service sends ping messages to the established WebSocket to make sure you are still online. If the service doesn't receive the pong message from the WebSocket, it assumes you are not active anymore, and the handler of this request ends. Gateway Terminal Service provides multiple terminal sessions at a time, so different users can have remote terminal access at the same time. A map maintaining a list of connected users for the connected gateways allows the application to send heartbeat messages periodically to check whether users are still online.
Gateway mode
In gateway mode, every request comes with an HTTP header that identifies the gateway that made the request. Every gateway uses its unique gateway ID from the header as its routing key when it connects to the server. If a new gateway tries to connect and its routing key already exists, Gateway Terminal Service closes the WebSocket connection of the old one and lets the new one in.
Every gateway domain request is routed to the gateway auth server with a client certificate that contains the account ID and the device ID of the gateway. The gateway auth server ensures the appropriate certificate authority (CA) signed the certificate. Gateway Terminal Service receives the device ID and the account ID only if authentication is successful.
To enable two-way communication between the gateway and Gateway Terminal Service, the gateway sends a handshake WebSocket request to Gateway Terminal Service to establish the connection. Once the connection is established, the gateway and Gateway Terminal Service can send plain-text data back and forth. Like it does in user mode, Gateway Terminal Service sends ping messages to the established WebSocket. If the service doesn't receive a pong message, it assumes the expected gateway is not active anymore, and the handler of this request ends.
How it works
Protocol message envelopes contain all messages sent between users and gateways. There are several kinds of protocol message envelopes. Each one contains a type field describing the format of the payload.
Example format:
{"type": [string], "payload": [any]}
This table shows protocol message envelopes and the format of their payloads:
| Message type | Payload format | Description |
|---|---|---|
| Resize | ResizePayload | When you resize the terminal window, the server sends a resize protocol message envelope to the gateway, so the gateway can adjust the window size of the local terminal session. |
| Input | String | When you send keyboard input to a terminal in the browser, you send an input protocol message envelope, which contains the terminal keyboard input, to the gateway. |
| Output | String | The gateway sends you an output protocol message envelope, which includes the output of terminal keyboard input from gateway. In gateway mode, a gateway only sends output protocol message envelopes when it receives input protocol message envelopes. |
| Start | String | When you connect as a new user, the server sends a start protocol message envelope to the gateway, and the gateway creates a new session with the session ID from the start protocol message envelope. |
| End | String | When you disconnect, the server sends an end protocol message envelope to the gateway, and the gateway terminates the session by using the session ID contained in the end protocol message envelope. |
Security considerations
- Gateway Terminal Service only accepts HTTPS connections, which are secured by Secure Sockets Layer (SSL) protocol. It provides privacy and data integrity between two or more communicating applications.
- You can only talk to a gateway if you are part of the account tied to that gateway.
- For gateway domain requests, the gateway auth server has to confirm whether the request is from a valid gateway.
- All requests made to the API domain must pass through the API gateway, which ensures the request contains a valid access token. The Gateway Terminal Service assumes the API gateway handles authentication for API domain requests.