Skip to content

Remote Access

Features and Preconditions

Establish a remote connection to an asset to view and manage it via its web or SSH server. For web-based connections, IAH supports interactive communication over HTTP or HTTPS, including WebSocket-based traffic.

Supported mechanisms:

  • HTTP/HTTPS web applications
  • WebSocket-based applications, including Socket.IO over HTTP/HTTPS
  • RPC-style communication exposed by the asset web service over HTTP/HTTPS
  • Terminal sessions through ttyd over HTTP/HTTPS
  • SSH support

For a remote connection to work, the asset must expose its web server over HTTP or HTTPS on a specific port. For an SSH connection, the asset must expose its SSH server on a specific port. The user should have admin or supervisor role.

Note

If a remote connection remains inactive for 1 hour, credentials expire and a 404 error is shown. To reestablish the session, open the remote connection URL from the list of remote connections. Accessing multiple remote connection web/ssh servers within a single browser is supported. The session is valid for a maximum of 12 hours after which it is automatically terminated.

Remote access with Access groups

  • All users within the same tenant can view all remote connections for that tenant, but only users who have access to the asset's Access group can perform operations on those connections.
  • If the Access group of an asset with an active remote connection is changed, only users in the new Access group can perform operations on that connection.

For the step-by-step workflow to establish and view remote connections, refer to the Asset list page.

Remote access configuration

Configure whether an Asset Gateway permits remote connections to its assets. The Asset Gateway enforces this setting locally, independent of the cloud backend, so a gateway can block remote access even when the backend permits it.

Remote access is controlled by the appConfig.remoteAccessAgent.remoteAccess.enabled field in the gateway-config.json file that is downloaded when an Asset Gateway is added. For information on adding an Asset Gateway, refer to the Gateway Configuration page.

Note

Enabling remote access at the Asset Gateway does not bypass access control. Users still need the required role and Access group membership to establish a remote connection. For further information, refer to the Configure Access Management page.

When remote access is disabled, the Asset Gateway blocks remote connection jobs for its assets. A remote connection job created for such an asset moves to the Failed state, and the job details show the reason Remote Access not enabled on gateway. Check the status of remote connections on the Jobs page.

Default behavior

The onboarding service sets appConfig.remoteAccessAgent.remoteAccess.enabled to false in the generated gateway-config.json file. This protects the gateway until the operator explicitly enables remote access for that gateway.

Asset Gateways running version 1.8 or later include this setting. Gateways running an earlier version have remote access enabled by default.

Enable remote access

Enable remote access in one of two ways: during Asset Gateway onboarding or later by updating the gateway configuration.

  • When creating an Asset Gateway, a gateway-config.json file is generated. To enable remote access, under appConfig > remoteAccessAgent > remoteAccess set enabled: true.
{
  "gatewayId": "<gatewayID>",
  "gatewayName": "<gateway name>",
  "xfUrl": "<xf url>",
  "registrationToken": "<registration token>",
  "appConfig": {
    "remoteAccessAgent": {
      "remoteAccess": {
        "enabled": true
      }
    }
  }
}

After the Asset Gateway is onboarded, enable or disable remote access by updating the configuration and restarting the asset-gateway app. Ensure the configuration file includes the content below with appConfig > remoteAccessAgent > remoteAccess enabled flag set to true.

{
  "gatewayId": "<gateway-id>",
  "xfUrl": "<backend-url>",
  "appConfig": {
    "remoteAccessAgent": {
      "remoteAccess": {
        "enabled": true
      }
    }
  }
}

Any questions left?

Ask the community