SSH Tunnel Utility

The SSH Tunnel Utility allows you to create secure reverse SSH-based connection tunnels to a remote SSH server (hub). Up to three concurrent tunnels can be established: one for local SSH console access, one for HTTPS Web server connections, and one additional (AUX) tunnel to any local service network port, such as a Modbus TCP Gateway server.

A tunnel is configured by setting the local TCP port of a network server and the remote TCP port for the tunnel on the remote SSH server. Connecting to the TCP port associated with a tunnel on the remote server will route the connection, and all established traffic, through the tunnel to the local TCP port defined in the tunnel configuration.

Configuration parameters are stored in the tunnel.ini file.

UI Lock and Configuration Logic

To prevent accidental configuration conflicts, the HSYCO web interface employs a protective lock:

• The Lock Button: When the tunnel is enabled, an "unlock" button (featuring a lock icon) spans over the enable/disable checkbox.
• Temporary Access: Clicking this button unlocks the Enabled switch for two minutes. If the tunnel is not disabled within this timeframe, the UI automatically re-locks to protect the active configuration.
• Applying Changes: In the Web UI, configuration changes are only finalized when you click the Save Changes button. This save action is only permitted while the tunnel is disabled.

Connection & Authentication Methods

During its first run, the HSYCO Server automatically generates a unique SSH key-pair (id_ed25519 and id_ed25519.pub). The utility authenticates on the remote SSH tunnel server using the public key (id_ed25519.pub, or id_rsa.pub for retro-compatiblity), which must be copied into the authorized_keys file on the hub for the designated user.

You can configure the tunnel connection in two ways:

1. Manual Configuration: Explicitly provide the SSH hub hostname/IP, the SSH user on the hub, and the desired SSH, HTTPS, and AUX ports.
2. Token Provisioning: Provide a secure provisioning token. Note: This feature only works if a specific provisioning token has been generated and provided to the customer by the service provider. When a valid token is entered, the server automatically contacts the gateway to fetch and assign the remote host, user, and necessary ports, simplifying deployment.

High Availability (HA) Integration

The SSH Tunnel Utility is fully integrated with HSYCO's High Availability architecture, allowing you to define distinct behaviors for Master and Slave units.

Crucial HA Rules:

• Global Enable: The enable option is a global configuration shared between the Master and Slave. However, the machine will actually connect to the gate hub only if necessary. For example, in Active-Only mode (see below the Operation Modes for further details), the standby unit will not establish a connection even if the tunnel is globally enabled.
• Master/Slave Synchronization: The tunnel configuration cannot be modified from the Slave machine. All configurations are managed on the Master, and the tunnel.ini configuration file is automatically synchronized from the Master to the Slave.
• Sharing Key-Pairs: HSYCO does not automatically synchronize the generated SSH private keys between Master and Slave units. If your configuration requires both units to share the exact same key-pair, you must manually copy the keys from the Master's operating system console to the Slave's console.

HA Operation Modes

The utility supports three HA modes (ha.mode):

0 - Disabled Standard standalone operation. The system acts as a single unit without HA logic.

1 - Active-Only The tunnel only connects on the unit that is currently the active node.

• Example Usage (Manual Configuration): You can configure the Master and Slave to use the same SSH key-pair (requires manual copying via console) or different key-pairs.
• Example Usage (Token Provisioning): You can use the same token and same key-pair (requires manual copying via console) across both units, OR a different token and different key-pair for each unit.

2 - Always Active Both the Master and the Slave units maintain active connections to the hub simultaneously.

• Example Usage: Because both units are online concurrently, their SSH key-pairs must differ between the Master and the Slave.
• Furthermore, if using token provisioning, the Master and Slave must be assigned different tokens to prevent port overlapping and connection drops. The system will reject attempts to save identical tokens in this mode.

Mode	Description	Key-Pair/Token Requirements
0 - Disabled	Standard standalone operation.	N/A
1 - Active-Only	Only the currently "Active" HSYCO node connects to the hub.	Units can use the same key-pair (requires manual copy) or different ones. The same applies to tokens.
2 - Always Active	Both Master and Slave maintain simultaneous active connections.	Key-pairs must differ between units. If using tokens, different tokens must be used for each unit to avoid port conflicts.

The Configuration API

The SSH Tunnel Utility can be dynamically configured, and the tunnel service enabled/disabled, using USER calls in EVENTS and the user() command in Java or JavaScript.

note

Important: The configuration API allows you to change parameters even while the tunnel is currently enabled. However, these changes are stored in memory and will only take effect the next time the tunnel is disabled and re-enabled.

User Commands

ID	Value	Description
sshtunnel.enable	true / false	Enable or disable the tunnels globally.
sshtunnel.host	<host>	The SSH hub hostname or IP address. Non-standard ports can be appended using :<port> (e.g., hub.example.com or hub.example.com:2222).
sshtunnel.user	<user>	The username on the SSH hub used to connect from this unit.
sshtunnel.ssh.port	<port>	The SSH port number on the hub that will be tunneled to this unit's SSH port.
sshtunnel.https.port	<port>	The HTTPS port number on the hub that will be tunneled to this unit's HTTPS port.
sshtunnel.aux.port	<port>	The AUX port number on the hub that will be tunneled to this unit's AUX port.
sshtunnel.aux.local.port	<port>	The local AUX port number on this unit.
sshtunnel.kill	true / false	If true, all running SSH processes will be killed at start-up to ensure clean connections.