Difference between revisions of "SSH Tunnel Utility"

From HSYCO
Jump to navigation Jump to search
 
(22 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
[[Category:Manager]]
 
[[Category:Manager]]
 
[[File:Manager SSH Tunnel Utility Icon.png|class=appIcon]]
 
[[File:Manager SSH Tunnel Utility Icon.png|class=appIcon]]
−
The SSH Tunnel Utility is an application that allows you to easily setup repetitive polling read requests and monitor the performance and status of each request.
+
The SSH Tunnel Utility allows 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 the HTTPS Web server connections and one additional (AUX) tunnel to any local service network port like, for example, the Modbus TCP Gateway server.
  
−
Each read request is defined with a repeat interval in seconds. The Modbus Utility internal scheduler will try to repeat the execution of each request as close as possible to the preset interval. It will also sequence all requests to the same Modbus I/O server so they never overlap.
+
[[File:SSHTunnelUtility1.png|border|600px|center|SSH Tunnel Utility]]
  
−
You can optionally assign a variable to each request for conditional execution. If a variable is defined, it has to exist and have value “1” to activate the request polling. Requests that are not active are highlighted in grey.
 
  
−
The optional "Error Tolerance" parameter is used to set the number of consecutive errors accepted before the Modbus error data point is set to report an error condition. The default is zero, so that even a single error will set the error data point. For example, setting the error tolerance to two means that up to two consecutive errors will be tolerated, and only the third consecutive error will set the error data point.
+
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 to 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.
  
−
The optional "Error Skip Interval" defines for how long the Modbus Utility should stop executing a Modbus request if an error occurs.
+
Thanks to the SSH tunnels, a local HSYCO Server that lacks inbound connectivity, could still be accessed via a remote and accessible SSH server configured as a tunnel end-point.
  
 +
The tunnel configuration parameters can be modified only when tunneling is not enabled.
  
−
[[File:ModbusUtility1.png|border|600px|center|Modbus utility.]]
+
The "SSH hub host name" is the network name or IP address of the remote SSH tunnel server (hub).
  
 +
Not standard ssh port numbers can be used following the host name or address with ":<port>".
  
−
The Modbus Utility tracks the actual repeat interval and compares it with the defined interval. If the difference is more than 25% from the target value, the request is marked as “slow” and highlighted in yellow. The difference between defined and actual interval is reported in the “delta” field.  
+
In order to establish a secure connection, the SSH Tunnel Utility authenticates on the remote SSH tunnel server with the user id set in "SSH user on hub" and the "SSH public key" of the HSYCO Server, that must be copied into the "authorized_keys" file on the hub for that user.
  
−
Requests that return errors are also tracked and highlighted in red.
+
If the SSH, HTTPS or AUX port number fields are left empty, the corresponding tunnel is not activated.
  
−
The minimum and maximum response time is also tracked for each request, and displayed in the “min. time” and “max. time” fields in the requests list.
+
{{note|Note that the tunnels are only active while HSYCO is running. Restarting HSYCO, all connections established through the tunnels, including the SSH connection, are dropped.}}
  
−
You can reset the status, delta, minimum and maximum time using the “refresh” button.
 
  
−
You can use filters to only show a subset of requests in the user interface. Entering a text in the search field will only show requests having a data point name that contains the search text. You can also filter by status, selecting slow, skipped, errors, or successful requests.
+
== The configuration API ==
  
−
{{note|Note that filters act globally, so if you set a filter all other users will also share the same view of the filtered list. Also note that, to reduce performance overhead, the status and performance data in the list of requests stops being updated after about 60 seconds of inactivity. This is also shared by all users. The refresh of requests’ data has no effect on the actual request scheduler, that runs independently and is never interrupted.}}
+
The SSH Tunnel Utility can be dynamically configured, and the tunnel service enabled and disabled, with USER calls in ENVENTS and the user() command in Java or JavaScript.
  
 +
In the following EVENTS example, the tunnel is enabled at 08:00 and disabled at 18:00.
  
−
[[File:ModbusUtility2.png|border|600px|center|BACnet utility.]]
+
TIME 0800 : USER sshtunnel.enable = true
 +
TIME 1800 : USER sshtunnel.enable = false
  
 +
=== User commands ===
  
−
The Modbus Utility configuration is stored in a human readable file named modbus-scheduler.ini and located in HSYCO’s main directory. If you manually edit this file, it will be automatically reloaded within a few seconds after it is saved. In a high availability setup, the Modbus Utility is also automatically mirrored from the master to the slave server.
+
{| class="wikitable"
 +
!ID
 +
!Value
 +
!Description
 +
 
 +
|-
 +
|rowspan="2" |sshtunnel.enable
 +
|true
 +
|enable the tunnels
 +
|-
 +
|false
 +
|disable the tunnels
 +
 
 +
|-
 +
|sshtunnel.host
 +
|<host>
 +
|the SSH hub host name or IP address. Not standard ssh port numbers can be used following the host name or address with ":<port>"
 +
 
 +
|-
 +
|sshtunnel.user
 +
|<user>
 +
|the user name on SSH hub used to connect from this unit
 +
 
 +
|-
 +
|sshtunnel.ssh.port
 +
|<port>
 +
|the SSH port number on hub that will be tunnelled to this unit's SSH port
 +
 
 +
|-
 +
|sshtunnel.https.port
 +
|<port>
 +
|the HTTPS port number on hub that will be tunnelled to this unit's HTTPS port
 +
 
 +
|-
 +
|sshtunnel.https.local.port
 +
|<port>
 +
|the local HTTPS port number
 +
 
 +
|-
 +
|sshtunnel.aux.port
 +
|<port>
 +
|the AUX port number on hub that will be tunnelled to this unit's AUX port
 +
 
 +
|-
 +
|sshtunnel.aux.local.port
 +
|<port>
 +
|the local AUX port number
 +
 
 +
|-
 +
|rowspan="2" |sshtunnel.kill
 +
|true
 +
|all running SSH processes will be killed at start-up
 +
|-
 +
|false
 +
|don't kill SSH processes at start-up
 +
 
 +
|}
 +
 
 +
{{note|The tunnel utility must not be enabled to change the configuration parameters with API commands.}}

Latest revision as of 13:08, 15 March 2021

Manager SSH Tunnel Utility Icon.png The SSH Tunnel Utility allows 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 the HTTPS Web server connections and one additional (AUX) tunnel to any local service network port like, for example, the Modbus TCP Gateway server.

SSH Tunnel Utility


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 to 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.

Thanks to the SSH tunnels, a local HSYCO Server that lacks inbound connectivity, could still be accessed via a remote and accessible SSH server configured as a tunnel end-point.

The tunnel configuration parameters can be modified only when tunneling is not enabled.

The "SSH hub host name" is the network name or IP address of the remote SSH tunnel server (hub).

Not standard ssh port numbers can be used following the host name or address with ":<port>".

In order to establish a secure connection, the SSH Tunnel Utility authenticates on the remote SSH tunnel server with the user id set in "SSH user on hub" and the "SSH public key" of the HSYCO Server, that must be copied into the "authorized_keys" file on the hub for that user.

If the SSH, HTTPS or AUX port number fields are left empty, the corresponding tunnel is not activated.

Note that the tunnels are only active while HSYCO is running. Restarting HSYCO, all connections established through the tunnels, including the SSH connection, are dropped.


The configuration API

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

In the following EVENTS example, the tunnel is enabled at 08:00 and disabled at 18:00. 

TIME 0800 : USER sshtunnel.enable = true
TIME 1800 : USER sshtunnel.enable = false

User commands

ID Value Description
sshtunnel.enable true enable the tunnels
false disable the tunnels
sshtunnel.host <host> the SSH hub host name or IP address. Not standard ssh port numbers can be used following the host name or address with ":<port>"
sshtunnel.user <user> the user name on SSH hub used to connect from this unit
sshtunnel.ssh.port <port> the SSH port number on hub that will be tunnelled to this unit's SSH port
sshtunnel.https.port <port> the HTTPS port number on hub that will be tunnelled to this unit's HTTPS port
sshtunnel.https.local.port <port> the local HTTPS port number
sshtunnel.aux.port <port> the AUX port number on hub that will be tunnelled to this unit's AUX port
sshtunnel.aux.local.port <port> the local AUX port number
sshtunnel.kill true all running SSH processes will be killed at start-up
false don't kill SSH processes at start-up
The tunnel utility must not be enabled to change the configuration parameters with API commands.
Retrieved from "https://wiki.hsyco.com/3.8/index.php?title=SSH_Tunnel_Utility&oldid=9750"