Server Name Resolution

ScaleFT implements a custom name resolution system, which is used to resolve user-supplied names to a server registered with ScaleFT.

For example, if you run sft ssh web0, the name web0 will be resolved in ScaleFT. Likewise, if the agent on web0 has a config file specifying Bastion:, will be resolved in order to establish a tunnel to web0.

If ScaleFT is unable to resolve a name to an enrolled server, ScaleFT will fall back to using locally supported name resolution and authentication methods to access the server. For example, if you run sft ssh and ScaleFT is unable to resolve that name to a server enrolled in ScaleFT, the client will behave as though you had run ssh without using ScaleFT at all.

Active Servers

ScaleFT only matches names against active servers. A server is considered active if all of the following conditions are true:

  1. The server was enrolled in ScaleFT
  2. The server was not subsequently deleted from ScaleFT
  3. The ScaleFT agent was recently running on the server, and able to contact the ScaleFT platform. Currently the threshold is 96 hours (4 days), but this is subject to change.

As a special case, if an Unmanaged Server is created in ScaleFT it will be considered active until it is deleted.


When resolving a name, ScaleFT will look for any server matching one of the following values.

Server ID

The server’s id, a random UUID automatically assigned by the ScaleFT platform during enrollment.


The server’s hostname, as reported by the operating system on the server. If the OS hostname ends in “.local” this will be ignored by the platform. For example, if the OS hostname is “web0.local”, you will be able to access the server as “web0”, but not as “web0.local”.

If a CanonicalName value is specified in the ScaleFT agent config, this value will be used in place of the OS hostname.


Any AltNames values specified in the ScaleFT agent config file on the server. AltNames can be used to add additional aliases to servers.

Default IP Address

The default IP address of the server, as determined by ScaleFT.

Instance ID

If the server is an AWS or GCE cloud instance, the provider-assigned ID of the instance.

Ambiguous Names

If a name supplied to the ScaleFT client resolves to more than one server the client will return an error in order to avoid inadvertently connecting to an unintended server.

One side effect of this is that if a server is replaced with a new server bearing the same hostname, or if the agent is forced to re-enroll, a user with administrative privileges will need to manually delete the original server record before the new one can be addressed by the shared name. Alternatively, users can specify an unambiguous name such as the server ID, or wait for the original server record to become inactive.

If a Bastion name supplied in a ScaleFT agent configuration is ambiguous, the ScaleFT platform will attempt to choose the best fit by ranking matches in descending order of preference by matching:

  1. id or CanonicalName
  2. Cloud Instance ID
  3. Hostname
  4. AltNames
  5. Default IP Address

Ties are broken arbitrarily.

IP Addresses

Once a server has been resolved, ScaleFT will attempt to determine the IP address that should be used to address it.

If the server is being accessed directly by the ScaleFT client, the client will attempt to use the server’s Default IP Address as described below.

If the server is being accessed via one or more bastions, and the immediately preceding bastion resides in the same AWS VPC or GCE Network as the server, ScaleFT will prefer the server’s corresponding private IP address. Otherwise ScaleFT will use the Default IP Address.

Default IP Address

Each server enrolled in ScaleFT is assigned a Default IP Address, which will be the first available value from:

  1. An AccessAddress value specified in the ScaleFT agent configuration file
  2. An AWS instance’s public_ip_v4 based on the instance metadata
  3. A GCE or Azure instance’s external, or internal IP addresss, based on the instance’s metadata
  4. The numerically lowest v4 IP address in a public address range
  5. The numerically lowest v4 IP address in a private range