Agent and Master Secure Connection

In order to provide strict control over which Tidal Automation Masters can connect to a specific agent, a Masters.cfg file has been implemented at the Agent. By specifying the Master 'alias', the Master 'alias' and a specific 'local' TCP/IP address or the Master 'alias', the specific 'local' TCP/IP address and a 'global' TCP/IP address you can uniquely identify the specific TA Masters to which a TA Agent will create connections.

The Masters.cfg file must be created in the Agents local directory. This directory is in the install path of the Agent and has the name of the Agent as it was specified when the Agent was defined. For example, by default, this would be something like:

  • For 32-bit Windows

    C:\Program Files\TIDAL\Agent\TIDAL_AGENT_1

  • For 64-bit Windows

    C:\Program Files(x86)\TIDAL\Agent\TIDAL_AGENT_1

  • For Unix (Linux, z/OS)

    /opt/TIDAL/Agent/TidalAgent1

  • For OVMS

    sys$sysdevice:[tidal.agent.tidalagent1]

This file should have limited access using native system access control definitions.

Agent Connect Protocol

It describes the normal connection sequence for an Agent to Master connection to be established.

The Master connects to the Agent well-known port (default 5912, configurable). The Master sends a registration message to the Agent specifying the Masters IP address and listening port (and some other configuration information). This connection is then terminated.

For each Master that has registered as above, the Agent will attempt to connect using the information from the registration. This will happen each time the connection is lost for any reason.

The Agent will attempt to connect to the IP and port provided by the Master in the registration message. If this fails, the Agent will attempt to connect to the IP obtained from the network as the source IP (may be firewall IP) and the port provided in the registration message.

When the connection is made, the Agent will generate an encryption key based on a random seed. This encryption key and other configuration information about the Agent will be sent to the Master. The encryption key is 'wrapped' by a method that the Master knows how to 'unwrap' in order to get the raw key. This key is used to encrypt the body of all future messages (encryption is a configurable option that is on by default).

Masters.cfg

The Masters.cfg file contains this structure:

Optional INCLUDE or EXCLUDE statement on first line. If specified, these one word entries must be on the first line. INCLUDE is the default if nothing is specified.

  • INCLUDE - only the specified Masters with optionally specified IP addresses will be connected to by the Agent.

  • EXCLUDE - the specified Masters will be specifically excluded from being connected to by the Agent.

Master entries of the form:

  • MasterAlias

    The MasterAlias typically has the form 'ES_<hostname of master>_1' and is case-insensitive. If specified alone on the line, then only the MasterAlias will be verified that it matches what was presented by the Master in its registration message.

  • MasterAlias:IPaddress1

    For connections that are 'local', i.e. their Master host machine IP addresses are directly accessible by the Agent, then only IPaddress1 needs to be specified. This address will be verified against the IP address presented by the Master in its registration message and the IP address obtained from the network as the origination of the connection that provided the registration message.

  • MasterAlias:IPaddress1;IPaddress2

    For connections that must traverse a firewall, then IPaddress2 must be specified. IPaddress2 will be the externally known address of the firewall. The externally known address of the firewall is what will be obtained by the Agent when it retrieves the IP address of the origination of the connection through which the registration message was delivered.

    For situations where a Master could have multiple IPs, Failover scenarios, or disaster recovery situations, the same MasterAlias can be specified with different IPaddress parameters.

    A Masters.cfg file:

    INCLUDE
    hou-testvm-531:192.168.48.111;172.19.25.125 hou-testvm-531:192.168.55.211;172.19.25.125
    zostest:192.168.95.92 zostest:192.168.42.92 catest