IP Cycling for the Remote Access Client (RAC)
By default, the ThingWorx Remote Access Client (RAC) uses port cycling to establish local remote session tunnels to Axeda Agents. With port cycling, the RAC tries to use the connect port defined at the Agent and stored in the endpoints property of the Agent Thing. If that connect port is in use, the RAC tries a random port number until the connection succeeds.
Recall that when registering and binding with its related Thing on the ThingWorx Platform, an Axeda Agent sends the configuration of its endpoints for remote sessions. The following Properties page for an Axeda Agent Thing shows this property:
To establish a remote session, the RAC parses the endpoints property of the Axeda Agent Thing to determine the “connect” ports configured for each Agent endpoint. For example, here are the endpoint configurations for an example Axeda Agent Thing, ra-test-agent. ra-test-agent has six endpoints, each with its own providerConfig:
For purposes of this example, consider the providerConfig of the ssh-app endpoint, which contains the following connectionInformation:
{
"connectionInformation": [
{
"startPort": 22,
"type": "C"
}
],
"launchOption": "auto"
}
To initiate the remote access tunnel with the ra-test-agent, the RAC parses this connection information and attempts to start a local TCP server, running on localhost on port 22. If the local server cannot be started on port 22, the RAC attempts to start it on a random port. This method of failover is the default behavior and is called port cycling.
 | The providerConfig can specify multiple ports or port ranges if the agent requires multiple connections. In these scenarios, RAC starts a local server for each port defined in the configuration. |
Some PTC customers need to run the RAC in environments where they are not allowed to start one to many local servers on localhost. Instead, these customers need the ability to specify a range of IP addresses that RAC should use to start the local server. This RAC feature is called IP cycling.
IP cycling works with single port and multiple port connections during a single remote session. For example, you may want to have your web interface use one port, such as 443, and the web services processing use a different port, such as 9090, both during the same remote session.
The following sections explain how to configure IP cycling, show different scenarios for IP cycling, show the RAC user interface for a single port and port cycling, and explain how IP cycling works. Click the title of a section to display its content. Click the title again to hide the content.
Configuring IP Cycling
| | While the instructions here take you through the Data Shape to configure the metadata property, consider creating a mashup for users of remote sessions. Include a configuration screen for the StartSession service that presents the required settings and accepts user input. |
For the RAC to use IP cycling, you must configure it in the metadata field of the RemoteSessionParameters Data Shape when starting the remote session. The following screen shot shows this field in its parent Data Shape:
The metadata field has a JSON Base Type and can be used to specify a description of a remote session using a description key. For example:
{
"description" : "Remote session to debug MRI machine"
}
To set up the configuration of IP cycling in a mashup, use the ipCycling JSON object and the following properties:
Property | Base Type | Description | ||
|---|---|---|---|---|
startIP | STRING | The IP address to use first for IP cycling. If not specified. the RAC uses the default value, 127.0.0.1. The highest IP address that can be used is 127.255.255.254. Otherwise, RAC rejects it.
| ||
maxIPs | NUMBER | The maximum number of IP addresses to attempt. If the startIP is set to 127.0.0.8 and the maxIPs is set to 5, the RAC attempts to start a local server on 127.0.0.8 through 127.0.0.12, until it succeeds in starting the server. If the maxIPs value is not specified, the RAC uses the default value of 1. Note that the RAC limits the fourth octet of the IP address to 254. | ||
portCycleOnFailure | BOOLEAN | Whether the RAC should use port cycling if IP cycling fails on all IP addresses in the specified range. If this property is not specified, the RAC uses the default value of true. When this property is set to true and all IP addresses fail for the connect port(s), the RAC attempts to start the server on a random port for each IP address in the range. |
Here is an example of the metadata field:
{
"description":"Remote session to debug MRI machine",
"ipCycling":{
"startIP":"127.0.0.8",
"maxIPs":5
"portCycleOnFailure": true
}
}
IP Cycling Scenarios and RAC Behavior
The following scenarios present various remote sessions using IP cycling:
Scenario 1. Connect port with success on first IP address
Agent defines connect port 22.
The startIP is 127.0.0.8 and maxIPs is set to 5.
RAC attempts to start server on 127.0.0.8:22 and succeeds.
RAC UI is updated to show 127.0.0.8:22 → 22.
The arrow indicates that port 22 on IP address 127.0.0.8 is mapped to Agent connect port 22, as shown here:
Scenario 2. Connect port 22 is already used by another application. RAC cycles through configured IP addresses for port 22, and fails over to use a random port.
Agent defines connect port 22.
The startIP is 127.0.0.8 and maxIPs is set to 5.
RAC attempts to start a local server on IP address 127.0.0.8, port 22 and finds that port 22 is in use.
RAC cycles through the remaining IP addresses, trying to connect on port 22. These IP addresses are 127.0.0.9, 127.0.0.10, 127.0.0.11, and 127.0.0.12. It fails on all of them because port 22 is in use by another application.
As long as portCycleOnFailure is set to true, the RAC next tries random port 41573 on the first IP address, 127.0.0.8, and succeeds. In the RAC UI, you see the IP address with the random port number in the green area. In the grey area, you see the IP address, the random port number used, followed by a pointer to the original connect port, 22. Showing the Agent's connect port as well as the port actually used enables you to identify any ports that have been aliased, as shown here:
In the figure above, you are seeing how the local tunnel is set up. The IP address 127.0.0.8 is using random port 41573, which is mapped to remote port 22 (the arrow shows that the port is mapped) on the agent asset.
Scenario 3. If a remote session is established successfully on the first IP and port, what happens if an attempt is made to start another remote session on a different IP with the same port?
Agent defines connect port 22.
User starts a remote session, using IP cycling, starting on IP 127.0.0.8, port 22, with a maximum of two IP addresses.
RAC attempts to start server on IP address 127.0.0.8, port 22 and succeeds because no application is using port 22.
User leaves the first session running and attempts to start a new remote session on 127.0.0.8 with IP cycling, starting on port 22, with a maximum of two IP addresses. This attempt fails over to IP address 127.0.0.9 and port 22 because 127.0.0.8, port 22, is taken. This failover succeeds. The following figure shows RAC with the two sessions from the same localhost, using IP cycling:
Scenario 4. Multiple ports are defined on an endpoint.
The endpoints property for the ra-test-agent Thing has an endpoint named ssh-multiple. The connection information for this endpoint includes two ports, 3022 and 3023. Both ports must be available for a remote session that uses both ports to succeed. Here is the configuration:
Agent defines connect ports 3022 and 3023.
User starts a remote session, using IP cycling, starting on IP 127.0.0.12, with a maximum of five IP addresses.
RAC attempts to start a local server on IP address 127.0.0.12, port 3022 and port 3023. Since both ports are available, the remote session succeeds, as shown below. Note that the grey area always shows a comma-separated list of all IP address:port → <mapped_to_port> combinations. For this example, two entries are shown. both with IP address 127.0.0.12 and each with a different port, 3022 and 3023. However, the green oval shows only the first IP address and port combination.
What if you start another remote session with this same endpoint and IP cycling? The first IP address, 127.0.0.12, and ports 3022 and 3023 are in use. The IP cycling moves to the next IP address, 127.0.0.13. As long as ports 3022 and 3023 are available on that IP address, the second remote session succeeds. The RAC displays both sessions, each with two ports, as shown below:
Scenario 5. User attempts to enter an IP Address that is not in the loopback range.
User enters an IP address of 192.168.1.1 as the start IP address. This address is invalid because it is not a valid loopback address. That is, it is not in the loopback range, 127.0.0.0 through 127.255.255.254. RAC displays the following error message:
Scenario 6. The user enters an IP address that goes above 127.0.0.254.
User enters the IP address 127.0.0.255 as the start IP address. This particular address is not allowed. The RAC displays the following error message:
Scenario 7. Connect port with failure on first IP address
The Agent defines connect port 22.
The user sets a startIP address of 127.0.0.2 and a maxIPs value of 5.
The RAC attempts to start server on 127.0.0.2:22 and fails.
The RAC attempts to start server on 127.0.0.3:22 and succeeds.
The RAC UI is updated to show 127.0.0.3:22 → 22.
Scenario 8. Multiple connect ports with one failure on first IP
The Agent defines connect ports 22 and 1022.
The user sets a startIP address of 127.0.0.2 and a maxIPs value of 2.
The RAC attempts to start server on 127.0.0.2:22 and succeeds.
RAC attempts to start server on 127.0.0.2:1022 and fails.
 | One IP failure triggers a complete failure for the IP address 127.0.0.2 even through the RAC succeeded on the first port. |
The RAC cleans up the server for IP address 127.0.0.2:22, then attempts to start the server on 127.0.0.3:22, and succeeds.
The RAC attempts to start the server on 127.0.0.3:1022 and succeeds.
The RAC UI is updated to show 127.0.0.3:22 → 22, 127.0.0.3:1022 → 1022.
Scenario 9. Multiple connect ports with at least one failure on all IP addresses
As you will see in this scenario, after it tries every IP address in the configured range and fails to connect, IP cycling circles back to the first IP address in the configured range and uses port cycling on that first IP address until an open port is found.
Agent defines connect ports 22 and 1022.
RAC attempts to start server on 127.0.0.2:22 and succeeds.
RAC attempts to start server on 127.0.0.2:1022 and fails.
| | This triggers a complete failure for the IP address 127.0.0.2 even through RAC succeeded on the first IP and port. |
RAC attempts to start server on 127.0.0.3:22 and succeeds.
RAC attempts to start server on 127.0.0.3:1022 and fails.
RAC attempts to start server on 127.0.0.4:22 and fails.
RAC attempts to start server on 127.0.0.4:1022 and fails.
If portCycleOnFailure setting is true, the RAC attempts to start server on 127.0.0.2:randomPort and on 127.0.0.2:randomPort and succeeds.
The RAC UI is updated to show 127.0.0.2:randomPort → 22, 127.0.0.2:randomPort → 1022.
What You'll See in the RAC UI for Single Port and Port Cycling
The RAC UI for a single port and the default port cycling has been updated to show localhost:<port_used> in the UI. In the grey area, you can also see the port mapping if the configured port was already in use. In the green oval, you no longer see only the port number. For example:
How IP Cycling Works
The Remote Access Client (RAC) attempts to start a local TCP server on the IP address specified in startIP and the port set as the connect port at the Agent. As shown in the scenarios above the RAC tries each IP address and port combination until it succeeds. When it has tried all the IP addresses defined by the startIP and maxIPs properties, the RAC checks the value of the property, portCycleOnFailure. If it is set to true, the RAC circles back to first IP and starts port cycling with random ports until it succeeds or until it has failed on all of the configured IP addresses.
Port cycling is the default behavior of the RAC, unless you configure IP cycling. When you configure IP cycling, you can decide whether you want the RAC to use port cycling when IP cycling fails by setting the portCycleOnFailure property.
| | You cannot do IP cycling on a Mac computer. If using the RAC on a Mac, keep in mind that the RAC can use only the 127.0.0.1 IP address. |