Configuring and Managing Remote Access Using the Remote Access Subsystem

ThingWorx Remote Access Extension > Administrator Tasks for Remote Access > Configuring and Managing Remote Access Using the Remote Access Subsystem

The Remote Access Extension (RAE) adds the RemoteAccessSubsystem to the ThingWorx Platform. This subsystem is generic and is shared by all RemoteAccessProvider Things, which include Axeda Global Access Servers 6.9.2/6.9.3, ThingWorx Global Access Servers 7.x, and the ThingWorx Internal Remote Access Provider for AlwaysOn devices.

The Remote Access Subsystem is used to persist and update remote sessions. It also generates audit messages for remote sessions. These audit messages are collected by the ThingWorx Audit Subsystem. The Remote Session history is maintained by storing historical Remote Session entries into persistence once they are completed.

To ensure remote sessions do not execute forever, a Maximum Session Duration (in hours) setting for the Remote Access Subsystem is enforced. To ensure remote sessions are properly cleaned up, the Inactive Session Timeout (in minutes) is also enforced. Both settings are configurable. Refer to the section below on configuring the subsystem for details.

Two events result in audit messages, a remote session is created and a remote session is completed. The Remote Access Extension fires these events (SessionCreated and SessionCompleted) to the RemoteAccessible Thing associated with the session when a session is started or completed. The triggering of either of these events results in an audit entry being logged that contains session information.

The following sections explain the configuration of the Remote Access Subsystem, the services that enable GAS to register or unregister with a ThingWorx Platform and to update its status, the services the enable Remote Viewer management, and the services that enable you to clean up old sessions and terminate inactive sessions. Click the title of the section to display its content; click the title again to hide the content.

Configuring the Remote Access Subsystem

The subsystem has the following configuration settings:

Setting

Description

Maximum Number of Sessions to Return from Data Storage

The maximum number of persisted remote sessions to return when there is a request for remote sessions. The default value is 500 sessions.

Timeout to indicate that the RemoteAccessClient is not installed locally

The number of milliseconds to wait before generating a message that says the ThingWorx Remote Access Client (RAC) is not installed on the user's computer. The default value is 10 seconds (10,000 milliseconds).

Maximum Session Duration (in hours)

The maximum number of hours that a remote session can remain active. The default value is 24 hours, with a minimum value of 1 hour and a maximum value of 240 hours.

Inactive Session Timeout (in minutes)

The number of minutes that a remote session is allowed to remain inactive before it is timed out. The default value is 15 minutes, with a minimum value of 1 minute and a maximum value of 60 minutes.

Maximum Number of AutoLaunchConfigs to Return from Storage

The number of configuration entries for Auto Launch to retrieve from storage when the GetAutoLaunchConfigs service is run.

The AutoLaunchConfig entries are stored in a ThingWorx Data Table created when you import the RAE. The storage is limited only by the amount of available disk space that the database has access to. For guidance on storing data in ThingWorx, refer to Storing Data in ThingWorx in this help center.

Enable Auto Launch

Whether the Auto Launch feature is enabled in the Remote Access Subsystem on this ThingWorx Platform. The check mark indicates that Auto Launch is enabled. To disable it globally, clear the check box. When Auto Launch is disabled, end users can click the Launch command shown in the user interface of the Remote Access Client (RAC) to start the application they want to use during the remote session. For example, an SSH terminal or VNC Viewer.

If this setting is unchecked (false) and the GetAutoLaunchConfig services finds a configuration, the returned value of isAutoLaunch is always set to false, even when the stored configuration is true. The Remote Access Client (RAC) calls GetAutoLaunchConfig and if a configuration is returned with isAutoLaunch set to false, RAC does not attempt to execute the configured command. Instead, RAC supports "click to launch" functionality, where the end user must explicitly click the

button next to the command shown in the LAUNCH COMMAND field.

For details on using Auto Launch, refer to Configuring Auto Launch on the ThingWorx Platform. For information about the services available for Auto Launch, refer to AutoLaunchConfig Data Shape.

Modifying the configuration of the inactivity timeout, the maximum session duration, and the maximum number of AutoLaunchConfig entries to return, and enabling/disabling Auto Launch does not require a restart of the Remote Access Subsystem.

The Remote Access Subsystem will throw exceptions if attempts are made to set values outside of the minimum and maximum values. Values for the subsystem can be set through ThingWorx Composer, as shown below:

The subsystem is started automatically when the ThingWorx Platform is started.

The Remote Access Subsystem will throw exceptions if callers attempt to set values outside of the minimum and maximum value ranges from either ThingWorx Composer or the SetConfigurationTable service.

Registering, Unregistering, and Updating Session Info (GAS) with Services of the Remote Access Subsystem

For ThingWorx GAS 7.1.0 and the ThingWorx Remote Access Extension (RAE) 3.0.0, the following services were added to the Remote Access Subsystem to support direct communication with ThingWorx GAS:

Service	Description	Responsibilities
RegisterExternalRemoteAccessServer	Allows GAS to register itself.	GAS will show as "online" after this service is run.
UnregisterExternalRemoteAccessServer	Allows GAS to unregister itself.	GAS will show as "offline" after this service is run.
UpdateExternalRemoteAccessServerStatus	Allows GAS to send session count updates, remote session audit messages, and file transfer audit messages to the ThingWorx Platform.	The audit messages are available through the Audit Subsystem of the ThingWorx Platform. For more information about audit messages, refer to the topic, Querying Audit History for Remote Access. The session count updates appear as a change in the sessionCount property for the GAS Thing.

Managing Remote Viewers with Services of the Remote Access Subsystem

To support remote viewers, the subsystem provides the GetEndpointViewerConfiguration service. This service uses the sessionId to locate the target RemoteAccessible Thing, endpoint, and RemoteAccessProvider. This service invokes the GetRemoteServerConfiguration service of the RemoteAccessProvider to obtain the remote server configuration data for the specific Thing and then calls the GetEndpointViewerConfiguration service of the Thing that implements the RemoteViewerManager Thing Template. This service returns the viewer configuration that matches the configuration of the Thing, the configured default viewer, or nothing, if no default viewer configuration is defined. For the Axeda eMessage Agents, the Thing is created after you have imported the Remote Access Extension (RAE), followed by the Axeda Compatibility Extension (ACE), to the ThingWorx Platform.

Cleaning Up Old Remote Sessions and Terminating Inactive Sessions with Services of the Remote Access Extension

For 3.0.0 and later, the subsystem still provides the following services to clean up old sessions and end inactive sessions:

Service

Description

Responsibilities

CleanupOldSessions

Called every 30 minutes (1800000 ms) by default, this sevice cleans up any sessions that have exceeded the maximum session duration by updating status to CLOSE_REQUESTED.

To change the default, refer to RemoteAccessCleanupOldSessionsTimer Thing.

• Determine expirationTime (in milliseconds) by subtracting: System.currentTimeMillis - HOURS.toMillis(maxSessionDuration).

• Find all Remote Sessions with a createdTime field that is less than or equal to expirationTime.

• For each session returned, set status to CLOSE_REQUESTED and then set the terminationCause to "Remote session close was requested due to max session duration of %s hours" and then update the session by calling updateRemoteSession(session).

TerminateInactiveSessions

Called every minute (60000 ms) by default, this service ends any inactive sessions and sets the status to TERMINATED. To change the default, refer to TerminateInactiveSessionsTimer Thing.

• Determine inactiveTime (in milliseconds) by subtracting: System.currentTimeMillis - MINUTES.toMillis(maxSessionDuration).

• Find all Remote Sessions with a lastActivityTime field less than or equal to inactiveTime.

• For each session returned, set the status to CLOSE_REQUESTED if it is not already set to CLOSE_REQUESTED. If the status is already CLOSE_REQUESTED, set the status to TERMINATED and then set the terminationCause to "Remote session was terminated due to session inactive timeout of %s minutes". Then, update the session. The CleanupOldSessionsTime runs and sets the sessions that exceed max_session_duration to CLOSE_REQUESTED. The UpdateSession service automatically refreshes the lastActivityTime when it updates the session.

Since the status is TERMINATED, the session is removed from persistence and also from the subsystem.

The lastActivityTime property of a Thing is updated with each GAS status update and with status updates from the Remote Access Client (RAC). Any update from either GAS or RAC results in the lastActivityTime property being updated and the session does not time out. "Inactivity" to the ThingWorx Platform means only that the platform has not received a status update from either RAC or GAS. Inactivity does not mean that there are no bytes being transferred.