Tunnel Management

Use a Tunnel to reach a TCP service available to a WEDA Node through an assigned endpoint. The Node establishes an outbound tunnel, so you can access the service without opening an inbound firewall port to the device's network.

For example, a support engineer needs to inspect inference-container logs on a remote device. This guide creates an SSH tunnel, waits for it to become ready, connects with a standard SSH client and closes the session when the inspection is complete.

The diagram shows the traffic path after establishment. The client connects to the Tunnel endpoint; WEDA Node connects to the target service. The target can run on the Node or another host reachable from its local network.

Before You Connect

Prepare the following:

• Device: Use an Activated, Connected WEDA Node for this walkthrough. Retain its Device ID; the examples use 74fe488d5d54, which you must replace with your own.
• WEDA identity: Use an access token for an identity with Admin access in the device's Org. v1.2 requires Admin access to create tunnels for every service type. See User Authentication for obtaining a token.
• Target service: Confirm that the Node can reach the service at the intended host and port. This example uses 192.168.10.50:22 to represent the device's LAN IP and SSH port. Replace both with the actual reachable address and listening port for your setup.
• SSH client and device account: Prepare a standard SSH client and an account accepted by the target SSH service.
• Network access: The device needs outbound connectivity to the WEDA Cloud and tunnel endpoints configured for your deployment. Confirm DNS and firewall access with your network administrator. Your client also needs access to the assigned Tunnel endpoint.

Note: WEDA access and SSH login are separate

An Admin identity authorizes the WEDA tunnel request. After connecting, authenticate with the target device's SSH account. The Tunnel does not grant a device account, root access or sudo privileges.

Create a Tunnel

Use the session APIs below with your deployment's API base URL and Authorization: Bearer YOUR_ACCESS_TOKEN. The SSH connection later uses the device's credentials, not this API token.

1. Send Create Tunnel Session for the target Device ID:

   POST /api/v1/devices/74fe488d5d54/tunnels/sessions
   Content-Type: application/json
   Authorization: Bearer YOUR_ACCESS_TOKEN
   
   {
     "serviceType": "ssh",
     "applicationHost": "192.168.10.50",
     "applicationPort": 22,
     "purpose": "Inspect inference container logs",
     "tags": ["ops", "diagnostics"]
   }

   All five fields are required:

   Field	How to choose it
   serviceType	The service label. Use ssh for this standard-client example. The label does not create or configure the target SSH service.
   applicationHost	An IP address or hostname reachable from the Node. It is not your workstation's address or the Tunnel endpoint.
   applicationPort	The target service's listening port, from 1 to 65535. v1.2 rejects 0.
   purpose	A non-empty explanation of why this session is needed.
   tags	Labels for identifying and filtering related sessions.

   Note: Using the Node's local address

   For SSH on the Node itself, applicationHost can be 127.0.0.1 if the SSH service is reachable at that address. This refers to the remote Node's local environment. For a service on another LAN host, use that service's reachable LAN IP or hostname.

2. Retain the returned tunnelSessionId. A 202 Accepted response means the request was accepted; it does not mean the Tunnel is ready. The initial tunnelEndpoint can be empty.

3. Poll Get Session Details using that session ID:

   GET /api/v1/devices/74fe488d5d54/tunnels/sessions/{tunnelSessionId}
   Authorization: Bearer YOUR_ACCESS_TOKEN

   Continue only when sessionStatus is ESTABLISHED and tunnelEndpoint has a value. If the session fails or closes, read its termination information before creating another one.

Check the result: You have the intended device's session ID and its ready Tunnel endpoint. Connect promptly; unused sessions can be reclaimed automatically.

Connect to Your Service

Read the host and port from the current tunnelEndpoint. Keep the two addresses separate:

Address	Used by	Example
Target service	WEDA Node	192.168.10.50:22, supplied in the create request
Tunnel endpoint	Your SSH client	tunnel.example.com:31245, assigned by WEDA

For this illustrative result excerpt:

{
  "serviceType": "ssh",
  "sessionStatus": "ESTABLISHED",
  "applicationHost": "192.168.10.50",
  "applicationPort": 22,
  "tunnelEndpoint": "tunnel.example.com:31245"
}

connect from your workstation with:

ssh -p 31245 device-user@tunnel.example.com

Replace tunnel.example.com, 31245 and device-user with the actual returned host, returned port and device SSH username. Port 22 is the target service's port in this example; it is not the port to enter in your workstation's SSH command.

Authenticate using the method permitted by the device's SSH service. After signing in, use that account's permissions to inspect the relevant logs or run your maintenance commands.

Check the result: Your SSH client reaches the intended device and the device accepts the login. ESTABLISHED alone does not confirm either successful SSH authentication or successful maintenance.

For the browser-based terminal, see Web SSH. Its webssh session uses the returned webSsh URL rather than the standard SSH command shown here.

Monitor and Close the Session

Use Get Session Details to monitor the current session. To find sessions for a device, use List Tunnel Sessions:

GET /api/v1/devices/74fe488d5d54/tunnels/sessions?serviceType=ssh&maxResultCount=20&skipCount=0&sorting=createdAt%20desc

The list returns items and totalCount. You can also filter by sessionStatus and tags; the tag filter matches sessions containing any of the supplied tags. Use skipCount and maxResultCount to page through results.

Read these fields together:

• Identity and destination: tunnelSessionId, deviceId, applicationHost and applicationPort identify the session and service you intended to access.
• sessionStatus: The Tunnel lifecycle state. Only an established session with an endpoint is ready for the client.
• activeConns: The reported number of active client connections. It is not a count of authenticated SSH users or proof that a command succeeded.
• lastHeartbeatTime: The last reported Tunnel heartbeat. Use this when checking the freshness of the connection information.
• healthStatus: Additional diagnostics on the detail response. Possible values are HEALTHY, DEGRADED, UNHEALTHY and UNKNOWN.
• Termination information: Read terminationSource, terminationReason and terminatedTime when a session ends or fails.

Session state reference

State	Meaning for the client
REQUESTED	The session has been requested. Wait for establishment.
ESTABLISHING	The Node is establishing the Tunnel. Wait and query again.
ESTABLISHED	The Tunnel is established. Use the returned endpoint and authenticate with the target service.
RECONNECTING	Reserved; not used in this version.
TERMINATING	Shutdown is in progress.
TERMINATED	The session has closed. Create a new session when access is needed again.
FAILED	The session failed. Inspect its health and termination details.

Note: Use the right timestamp

v1.2 uses createdAt and updatedAt for session audit timestamps. Use lastHeartbeatTime for the last Tunnel heartbeat. updatedAt is not a measure of SSH user activity.

Session limits apply at different points:

Limit	What to expect
Waiting for establishment	A session in REQUESTED or ESTABLISHING is closed after 60 seconds without a status update by default.
Established but unused	An ESTABLISHED session with no client connection is closed 60 seconds after creation or after its last connection ended by default. These rules apply to every serviceType.
Maximum lifetime	The documented maximum is 3600 seconds (1 hour) from creation, regardless of activity. Plan to create a new session if you need access again.
SSH shell idle	The device's SSH or shell policy can end a login independently. An open Tunnel does not keep an idle SSH shell signed in.

Always use the reported state to determine whether the session is still available. An automatic reclaim can take time to appear in the next status result.

Close the session when finished:

1. End the SSH login with exit. Closing the SSH client does not itself request Tunnel termination.

2. Send Terminate Session with the same device and session IDs:

   DELETE /api/v1/devices/74fe488d5d54/tunnels/sessions/{tunnelSessionId}
   Content-Type: application/json
   Authorization: Bearer YOUR_ACCESS_TOKEN
   
   {
     "reason": "Inference container inspection complete",
     "graceful": true,
     "forceTimeout": 30
   }
   • reason explains why you are closing the session.
   • graceful: true requests graceful closure; forceTimeout is the maximum wait in seconds before forcing closure.
   • graceful: false is the default and requests immediate closure. forceTimeout still limits the wait for the device to close the Tunnel.
   • If forceTimeout is omitted, zero or negative, WEDA uses the deployment default, normally 60 seconds. This example explicitly requests 30 seconds.

3. A 202 response accepts the termination request. Query the detail again until it reports TERMINATED. If it reports a failure, inspect the termination details.

Termination is available from REQUESTED, ESTABLISHING, ESTABLISHED or RECONNECTING. If the session is already terminating, closed or failed, refresh its detail instead of repeatedly sending DELETE.

In this version, termination requested through this API reports terminationSource: TunnelMgmt rather than User.

Check the result: The session reports TERMINATED and no longer provides access for your SSH client.

Troubleshooting

Check the layer that failed before creating another session:

Observation	Check next
Create returns 403	Confirm that the token identity has Admin access in the device's Org. The v1.2 creation requirement applies to ssh as well as webssh.
Create returns 400	Check required fields, the target host and the port range. applicationPort: 0 is invalid. Read the response's validation details.
API returns 404	Confirm the Device ID and session ID belong together and still identify an existing resource.
Session stays establishing or becomes FAILED	Check device connectivity, outbound access to the configured Cloud and Tunnel endpoints, DNS and terminationReason. If the network uses a proxy or filters WebSocket traffic, have its configuration checked with your WEDA support team.
ESTABLISHED, but the SSH client cannot reach the endpoint	Use the current returned host and port. Check your workstation's network access, then confirm that the Node can reach the target SSH service.
SSH prompts for login, then rejects the account	Check the device's SSH account and permitted authentication method. WEDA Admin access does not supply SSH credentials.
Session closes before you connect or after clients disconnect	Inspect its state and termination reason. It may have been reclaimed while activeConns was zero. Create a new session when you are ready to connect.
Login succeeds, but a maintenance command is denied	Check the device account's permissions. Tunnel access does not change OS authorization.
DELETE is rejected because of the current state	Refresh the session detail. A session that is already terminating or terminal accepts no further termination request.

When asking for support, include the device and session IDs, the time of the attempt, sessionStatus and the available termination details.