Difference between revisions of "SSH"

From HSYCO
Jump to navigation Jump to search
(Created page with "[http://www.arteco-global.com Arteco Everywhere] is a general purpose digital input-output Ethernet controller. It is available in two versions, a 4 inputs, 4 outputs module,...")
 
 
(40 intermediate revisions by 5 users not shown)
Line 1: Line 1:
[http://www.arteco-global.com Arteco Everywhere] is a general purpose digital input-output Ethernet controller.
+
Secure Shell (SSH) is a cryptographic network protocol for secure data communication, remote command-line login, remote command execution, and other secure network services between two networked computers that connects, via a secure channel over an insecure network, a server and a client (running SSH server and SSH client programs, respectively).
  
It is available in two versions, a 4 inputs, 4 outputs module, and an 8 inputs 8 outputs module.
+
The best-known application of the protocol is for access to shell accounts on Unix-like operating systems, but it can also be used in a similar fashion for accounts on Windows.
  
[[File:IO Servers Arteco Modules.png]]
+
It was designed as a replacement for Telnet and other insecure remote shell protocols, which send information, notably passwords, in plaintext, rendering them susceptible to interception and disclosure using packet analysis.
 +
 
 +
The encryption used by SSH is intended to provide confidentiality and integrity of data over an unsecured network, such as the Internet.
 +
 
 +
The SSH I/O Server implements the SSH-2 version of the protocol, and supports remote command execution and the SCP protocol for bidirectional file transfer. It uses HSYCO data points to execute commands and return command status, making it easy to use the SSH protocol in EVENTS, as well as JavaScript and Java.
 +
 
 +
The SSH I/O Server establishes a single SSH connection to the server, using keyboard-interactive or password-based authentication, and creates individual sessions to execute single commands.
 +
 
 +
{{tip|Commands are executed sequentially, not in parallel.}}
  
The ARTECOIO I/O Server in HSYCO creates a data point representation that you can use in the EVENTS language and Java to read the input pins and control the outputs. It also automatically allows you to create control objects for the Web user interface.
 
  
 
[[Category:I/O Server]]
 
[[Category:I/O Server]]
  
== Arteco Configuration ==
+
== SSH Remote Server Configuration ==
The IP address must correspond to the IP address of the Arteco module (the default address is 192.168.10.96). The port number is optional and can be omitted if the module is configured to the 80 default HTTP port number.
 
  
The user and password parameters are also optional, and can be omitted if the module is configured with the default ''admin'' user and ''arteco'' password.
+
The remote system should be configured to accept the SSH connection from the HSYCO server using the username and password defined in the I/O Server’s options.
 +
 
 +
If you need to execute operating system’s commands with superuser privileges (with the sudo program), the remote user name defined with the user option in the SSH I/O Server configuration must be allowed to execute “sudo” commands without asking for a password.
 +
 
 +
For example, if the user is hsyco, you could add the line:
 +
hsyco ALL=(ALL:ALL) NOPASSWD: ALL
 +
 
 +
at the end of the /etc/sudoers file (use the visudo command to edit the /etc/sudoers file).
 +
 
 +
{{tip|If the username and password are correct, but the remote server refuses the authentication (you will see a "Password authentication failed." message in the logs and the I/O Server will keep restarting), the most probable cause is that the remore SSH server is configured to refuse the "keyboard-interactive" or "password" authentication type. To make it work, you should change the remote server's configuration to enable either keyboard-interactive or password authentication.}}
  
 
== HSYCO Configuration ==
 
== HSYCO Configuration ==
 +
Add an SSH I/O Server in the [[Settings#I/O Servers|I/O Servers section of the Settings]] and set its parameters:
 +
 +
{{note|Note that the SSH I/O Server doesn't count in the I/O servers license total, so you don't need an extra I/O Server license to use SSH with HSYCO.}}
 +
 +
=== Communication ===
 +
*'''IP Address''': IP address of the remote device
 +
*'''IP Port''': IP port enabled for the SSH service on the remote device, leave blank for default port 22.
 +
 +
=== Authentication ===
 +
*'''User''': username to use on the remote device
 +
*'''Password''': password for the used username
 +
 +
=== High Availability ===
 +
*'''Shutdown when inactive''': defaults to false.
  
 
=== Options ===
 
=== Options ===
Line 23: Line 52:
 
!Values
 
!Values
 
!Description
 
!Description
 +
 
|-
 
|-
 
+
|rowspan="3"|stdout
|rowspan="2"|startupevents
+
|rowspan="3"|true
|rowspan="2"|false
 
 
|true
 
|true
|generate IO events also during the driver’s start-up phase
+
|when a remote command is executed, generate IO events containing the command's standard output and standard error streams
 
|-
 
|-
 
|false
 
|false
|start generating events only after HSYCO is aligned with the current status of the system
+
|do not generate IO events of the command's output and error streams
 
|-
 
|-
 +
|line
 +
|IO events are generated for each line of the command's standard output and standard error streams
  
|rowspan="2"|inputdiscovery
 
|rowspan="2"|false
 
|true
 
|automatically creates the list of all inputs in the systemtopo.txt file. Should be enabled to allow the automatic update of (button) objects’ states
 
|-
 
|false
 
|auto-detect for input devices is disabled
 
 
|-
 
|-
 
+
|rowspan="2"|persistentconnection
|rowspan="2"|outputdiscovery
+
|rowspan="2"|true
|rowspan="2"|false
 
 
|true
 
|true
|automatically creates the list of all outputs in the systemtopo.txt file. Should be enabled to allow the automatic update of (button) objects’ states
+
|the I/O Server establishes the SSH connection at start-up and keeps it open across multiple commands. Commands execution is faster, but a small amount of network traffic is present, even when no commands are executed, to keep the connection open
 
|-
 
|-
 
|false
 
|false
|auto-detect for output devices is disabled
+
|the I/O Server will not establish a connection to the remote server until a command is executed. The connection is closed 30 seconds after the execution of the last command
|-
 
 
 
|inputs
 
|8
 
|0...8
 
|use input pins from 0 to 8
 
|-
 
 
 
|outputs
 
|8
 
|0...8
 
|use output pins from 0 to 8
 
|-
 
 
 
 
|}
 
|}
  
 
== Datapoints ==
 
== Datapoints ==
 
The data points associated to the input pins are named “i0” to “i7”. The data points associated to the output pins are named “o0” to “o7”.
 
 
The I/O Server generates asynchronous events based on the status of the Arteco module’s input and output pins. The output data points can be written to control the output pins.
 
  
 
{| class="wikitable"
 
{| class="wikitable"
!ID
+
!width=160 |ID
!Value
+
!width=160 |Value
 
!R/W
 
!R/W
 
!Description
 
!Description
 +
 
|-
 
|-
 
+
|rowspan="3" |connection
|rowspan="2" |connection
 
 
|online
 
|online
 
|R
 
|R
|connection established
+
|SSH connection established (with successful authentication)
 
|-
 
|-
 
|offline
 
|offline
 
|R
 
|R
|HSYCO can't connect to the panel
+
|SSH connection closed
 
|-
 
|-
 +
|close
 +
|W
 +
|closes the SSH connection
  
|rowspan="2" |i<n>
+
|-
|0
+
|exec
 +
|rowspan="2" |&lt;command string&gt;
 +
|rowspan="2" |W
 +
|rowspan="2" |executes the command passed as value.
 +
An optional command execution timeout in seconds defines how long the command is allowed to wait reading from stdout and stderr. The default is 30 seconds
 +
|-
 +
|exec.<timeout>
 +
|-
 +
|exec
 +
|&lt;exit status&gt;
 
|R
 
|R
|input <n> is low
+
|
 +
* the command's exit status number
 +
* "error" if the command could not be sent to the remote server
 +
* "null" if the remote server failed to return an exit status code (some SSH servers do not return the exit status)
 +
 
 
|-
 
|-
|1
+
|err
 +
|&lt;error stream&gt;
 
|R
 
|R
|input <n> is high
+
|the executed command standard error stream, with lines separated by <nowiki>"<br>"</nowiki>, or an empty string if the command's error stream is empty
 +
 
 
|-
 
|-
 +
|out
 +
|&lt;error stream&gt;
 +
|R
 +
|the executed command standard output stream, with lines separated by <nowiki>"<br>"</nowiki>, or an empty string if the command's output stream is empty
  
|rowspan="7" |o<n>
 
|rowspan="2" |0
 
|R
 
|output <n> is low
 
 
|-
 
|-
 +
|rowspan="2" |get
 +
|&lt;source&gt; &lt;destination&gt;
 
|W
 
|W
|set output <n> to off
+
|retrieves the remote source file and writes it locally to the destination path name.<br>The source and destination string in value should be separated by one or more spaces.<br>Always use the "/" character as path separator.<br>Use "\" as the escape character if the file names have spaces.<br>The destination directory must exist and cannot be outside of the HSYCO's base directory, or the command will fail. If the destination name doesn't have a path, the file will be written to the HSYCO's base directory
 
|-
 
|-
 +
|&lt;exit status&gt;
 +
|R
 +
|
 +
* the total number of transferred bytes (should be equal to the actual file size)
 +
* "error" if the file transfer failed
  
|rowspan="2" |1
 
|R
 
|output <n> is high
 
 
|-
 
|-
 +
|rowspan="2" |put
 +
|&lt;source&gt; &lt;destination&gt;
 
|W
 
|W
|set output N to on
+
|copy the local source file to the remote server's destination path name.<br>The source and destination string in value should be separated by one or more spaces.<br>Always use the "/" character as path separator.<br>Use "\" as the escape character if the file names have spaces.<br>The source file cannot be outside of the HSYCO's base directory, or the command will fail. If the source name doesn't have a path, the file will be read from the HSYCO's base directory.<br>The file will be saved to the remote server with 600 (owner's only read and write) permission
 
|-
 
|-
 +
|&lt;exit status&gt;
 +
|R
 +
|
 +
* the total number of transferred bytes (should be equal to the actual file size)
 +
* "error" if the file transfer failed
  
|flip
+
|-
 +
|user
 +
|&lt;user name&gt;
 
|W
 
|W
|invert the status of output <n>
+
|overrides the "user" configuration parameter. This command can only be used when persistentconnection=false, and becomes effective after the current connection is closed. Set <user name> to an empty string to restore the original settings
 +
 
 
|-
 
|-
 +
|password
 +
|&lt;user password&gt;
 +
|W
 +
|overrides the "password" configuration parameter. This command can only be used when persistentconnection=false, and becomes effective after the current connection is closed. Set <user password> to an empty string to restore the original settings
  
|blink
 
|W
 
|continuously blink output <n>
 
 
|-
 
|-
 +
|}
 +
 +
 +
{{tip|The exec, err, out, get and put data points will trigger the IO events at the end of the command's execution even if the value is not changed. This allows you to easily intercept the exit status and other return information.}}
 +
 +
== Examples ==
 +
 +
{{tip|In the following examples, we assume that the id of the SSH I/O Server is "ssh".}}
 +
 +
=== Remote Command Execution ===
 +
 +
Reboot a remote system at midnight.
 +
 +
<syntaxhighlight lang="javascript">
 +
TIME 0000 : IO ssh.exec = "sudo reboot"
 +
</syntaxhighlight>
 +
 +
Turn off screen at midnight.
 +
 +
<syntaxhighlight lang="javascript">
 +
TIME 0000 : IO ssh.exec = "sudo vbetool dpms off"
 +
</syntaxhighlight>
 +
 +
Turn on screen at 7 o' clock.
 +
 +
<syntaxhighlight lang="javascript">
 +
TIME 0700 : IO ssh.exec = "sudo vbetool dpms on"
 +
</syntaxhighlight>
 +
 +
=== File Transfer ===
 +
 +
At midnight, copy HSYCO's internal database backup to a remote server.
 +
 +
<syntaxhighlight lang="javascript">
 +
TIME 0000 : IO ssh.put = "data_backup/hsyco.data /tmp/data_backup/hsyco.data",
 +
IO ssh.put = "data_backup/hsyco.properties /tmp/data_backup/hsyco.properties",
 +
IO ssh.put = "data_backup/hsyco.script /tmp/data_backup/hsyco.script"
 +
</syntaxhighlight>
 +
 +
=== Interactive Remote Command Project ===
 +
 +
Create a simple interactive command console in HSYCO.
  
|pulse
 
|W
 
|set output <n> to on, then off after 1 sec.
 
|-
 
  
|}
+
[[File:SSH_example_inteactive_command_interface.png|border|600px|center]]
  
== User Interface ==
+
'''The project's file'''
  
When using the default settings of the Arteco I/O Server, all output pins are available in the Project Editor and can be easily associated to any control button of the Web interface.  
+
<syntaxhighlight lang="text">
 +
(#skin blue)
 +
(#language it)
 +
(#size 980x640)
 +
(#style body-background-color=#FF00FF; pages-background-color=#770077)
 +
(#uiset $exec.eraseicon=true)
  
You can also set the ''inputdiscovery'' option in order to associate control buttons to the module’s inputs: the control buttons will show the input status, and have no effect when pressed.
+
(header SSH)
  
 +
(menu)
 +
(text!stderr r5c3;; (width:600px; text-align:left; height:400px; font-family:Courier New, Courier, monospace))
 +
(text!stdout r5c3;; (width:600px; text-align:left; height:400px; overflow:auto; font-family:Courier New, Courier, monospace))
 +
(input!$exec r4c3; (width:600px; font-family:Courier New, Courier, monospace); input)
 +
(text r1c1; $; font-size:200px)
 +
(text!exitcode r4c9;; font-size:24px)
 +
(endofmenu)
 +
</syntaxhighlight>
  
[[File:IO Servers Arteco Project Editor.png]]
 
  
== Release Notes ==
+
'''Events logic'''
=== 3.3.0 ===
 
*initial release
 
  
----
+
<syntaxhighlight lang="javascript">
 +
USER "$exec" : IO ssh.exec = $exec, UISET "$exec.focus" = true
 +
IO ssh.out : UISET stdout.text = IO ssh.out
 +
IO ssh.err : UISET stderr.text = IO ssh.err
 +
IO ssh.exec : UISET exitcode.text = IO ssh.exec
 +
</syntaxhighlight>
  
 +
== Release Notes ==
 +
=== 3.7.0 ===
 +
* the SSH I/O Server is now "free". Using it doesn't decrease the number of available I/O servers
 +
* new exec.<timeout> data point. Sets the command execution timeout in seconds; defaults to 30
 +
* new connection = close command: closes the SSH connection
 +
* new user = <user name> command; overrides the user configuration parameter
 +
* new password = <user password> command; overrides the password configuration parameter
 +
* new stdout=line option
  
''HSYCO and Home Systems Consulting are registered trademarks of Home Systems Consulting SpA. Java and JavaScript are registered trademarks of Oracle and/or its affiliates. ARTECO is a registered trademark of Arteco Srl. Other products or company names can be trademarks or registered trademarks of other companies and are used for demonstrative purposes only, with no violation intent.''
+
=== 3.4.0 ===
 +
* added support for the "keyboard-interactive" authentication method
 +
=== 3.3.0 ===
 +
* initial release

Latest revision as of 11:02, 1 April 2020

Secure Shell (SSH) is a cryptographic network protocol for secure data communication, remote command-line login, remote command execution, and other secure network services between two networked computers that connects, via a secure channel over an insecure network, a server and a client (running SSH server and SSH client programs, respectively).

The best-known application of the protocol is for access to shell accounts on Unix-like operating systems, but it can also be used in a similar fashion for accounts on Windows.

It was designed as a replacement for Telnet and other insecure remote shell protocols, which send information, notably passwords, in plaintext, rendering them susceptible to interception and disclosure using packet analysis.

The encryption used by SSH is intended to provide confidentiality and integrity of data over an unsecured network, such as the Internet.

The SSH I/O Server implements the SSH-2 version of the protocol, and supports remote command execution and the SCP protocol for bidirectional file transfer. It uses HSYCO data points to execute commands and return command status, making it easy to use the SSH protocol in EVENTS, as well as JavaScript and Java.

The SSH I/O Server establishes a single SSH connection to the server, using keyboard-interactive or password-based authentication, and creates individual sessions to execute single commands.

Note Commands are executed sequentially, not in parallel.

SSH Remote Server Configuration

The remote system should be configured to accept the SSH connection from the HSYCO server using the username and password defined in the I/O Server’s options.

If you need to execute operating system’s commands with superuser privileges (with the sudo program), the remote user name defined with the user option in the SSH I/O Server configuration must be allowed to execute “sudo” commands without asking for a password.

For example, if the user is hsyco, you could add the line:

hsyco ALL=(ALL:ALL) NOPASSWD: ALL

at the end of the /etc/sudoers file (use the visudo command to edit the /etc/sudoers file).

Note If the username and password are correct, but the remote server refuses the authentication (you will see a "Password authentication failed." message in the logs and the I/O Server will keep restarting), the most probable cause is that the remore SSH server is configured to refuse the "keyboard-interactive" or "password" authentication type. To make it work, you should change the remote server's configuration to enable either keyboard-interactive or password authentication.

HSYCO Configuration

Add an SSH I/O Server in the I/O Servers section of the Settings and set its parameters:

Note that the SSH I/O Server doesn't count in the I/O servers license total, so you don't need an extra I/O Server license to use SSH with HSYCO.


Communication

  • IP Address: IP address of the remote device
  • IP Port: IP port enabled for the SSH service on the remote device, leave blank for default port 22.

Authentication

  • User: username to use on the remote device
  • Password: password for the used username

High Availability

  • Shutdown when inactive: defaults to false.

Options

ID Default Values Description
stdout true true when a remote command is executed, generate IO events containing the command's standard output and standard error streams
false do not generate IO events of the command's output and error streams
line IO events are generated for each line of the command's standard output and standard error streams
persistentconnection true true the I/O Server establishes the SSH connection at start-up and keeps it open across multiple commands. Commands execution is faster, but a small amount of network traffic is present, even when no commands are executed, to keep the connection open
false the I/O Server will not establish a connection to the remote server until a command is executed. The connection is closed 30 seconds after the execution of the last command

Datapoints

ID Value R/W Description
connection online R SSH connection established (with successful authentication)
offline R SSH connection closed
close W closes the SSH connection
exec <command string> W executes the command passed as value.

An optional command execution timeout in seconds defines how long the command is allowed to wait reading from stdout and stderr. The default is 30 seconds

exec.<timeout>
exec <exit status> R
  • the command's exit status number
  • "error" if the command could not be sent to the remote server
  • "null" if the remote server failed to return an exit status code (some SSH servers do not return the exit status)
err <error stream> R the executed command standard error stream, with lines separated by "<br>", or an empty string if the command's error stream is empty
out <error stream> R the executed command standard output stream, with lines separated by "<br>", or an empty string if the command's output stream is empty
get <source> <destination> W retrieves the remote source file and writes it locally to the destination path name.
The source and destination string in value should be separated by one or more spaces.
Always use the "/" character as path separator.
Use "\" as the escape character if the file names have spaces.
The destination directory must exist and cannot be outside of the HSYCO's base directory, or the command will fail. If the destination name doesn't have a path, the file will be written to the HSYCO's base directory
<exit status> R
  • the total number of transferred bytes (should be equal to the actual file size)
  • "error" if the file transfer failed
put <source> <destination> W copy the local source file to the remote server's destination path name.
The source and destination string in value should be separated by one or more spaces.
Always use the "/" character as path separator.
Use "\" as the escape character if the file names have spaces.
The source file cannot be outside of the HSYCO's base directory, or the command will fail. If the source name doesn't have a path, the file will be read from the HSYCO's base directory.
The file will be saved to the remote server with 600 (owner's only read and write) permission
<exit status> R
  • the total number of transferred bytes (should be equal to the actual file size)
  • "error" if the file transfer failed
user <user name> W overrides the "user" configuration parameter. This command can only be used when persistentconnection=false, and becomes effective after the current connection is closed. Set <user name> to an empty string to restore the original settings
password <user password> W overrides the "password" configuration parameter. This command can only be used when persistentconnection=false, and becomes effective after the current connection is closed. Set <user password> to an empty string to restore the original settings


Note The exec, err, out, get and put data points will trigger the IO events at the end of the command's execution even if the value is not changed. This allows you to easily intercept the exit status and other return information.

Examples

Note In the following examples, we assume that the id of the SSH I/O Server is "ssh".

Remote Command Execution

Reboot a remote system at midnight.

TIME 0000 : IO ssh.exec = "sudo reboot"

Turn off screen at midnight.

TIME 0000 : IO ssh.exec = "sudo vbetool dpms off"

Turn on screen at 7 o' clock.

TIME 0700 : IO ssh.exec = "sudo vbetool dpms on"

File Transfer

At midnight, copy HSYCO's internal database backup to a remote server.

TIME 0000 : 	IO ssh.put = "data_backup/hsyco.data /tmp/data_backup/hsyco.data",
		IO ssh.put = "data_backup/hsyco.properties /tmp/data_backup/hsyco.properties",
		IO ssh.put = "data_backup/hsyco.script /tmp/data_backup/hsyco.script"

Interactive Remote Command Project

Create a simple interactive command console in HSYCO.


SSH example inteactive command interface.png

The project's file

(#skin blue)
(#language it)
(#size 980x640)
(#style body-background-color=#FF00FF; pages-background-color=#770077)
(#uiset $exec.eraseicon=true)

(header SSH)

(menu)
	(text!stderr r5c3;; (width:600px; text-align:left; height:400px; font-family:Courier New, Courier, monospace))
	(text!stdout r5c3;; (width:600px; text-align:left; height:400px; overflow:auto; font-family:Courier New, Courier, monospace))
	(input!$exec r4c3; (width:600px; font-family:Courier New, Courier, monospace); input)
	(text r1c1; $; font-size:200px)
	(text!exitcode r4c9;; font-size:24px)
(endofmenu)


Events logic

USER "$exec" : IO ssh.exec = $exec, UISET "$exec.focus" = true
IO ssh.out : UISET stdout.text = IO ssh.out
IO ssh.err : UISET stderr.text = IO ssh.err
IO ssh.exec : UISET exitcode.text = IO ssh.exec

Release Notes

3.7.0

  • the SSH I/O Server is now "free". Using it doesn't decrease the number of available I/O servers
  • new exec.<timeout> data point. Sets the command execution timeout in seconds; defaults to 30
  • new connection = close command: closes the SSH connection
  • new user = <user name> command; overrides the user configuration parameter
  • new password = <user password> command; overrides the password configuration parameter
  • new stdout=line option

3.4.0

  • added support for the "keyboard-interactive" authentication method

3.3.0

  • initial release