This directory contains an minimal SSH Terminal server. It provides
concurrent access to multiple Terminal sessions via interactive SSH sessions.
Before using the component, please consult the _Notes_ section to learn
about the current subtleties.
For an example on how to use the server please look at the run script
provided by _repos/gems/run/ssh_terminal_ or _repos/gems/run/ssh_exec_channel_.
Configuration
~~~~~~~~~~~~~
Examplary configuration:
! <config port="2022" ed25519_key="/etc/ed25519_host_key
! allow_password="yes" allow_publickey="yes"/>
! <vfs>
! <policy label="noux-system" user="root" password="toor"/>
! <policy label="noux-user" user="user" pub_key="/etc/user.pub"/>
!
! <dir name="dev">
! <log/> <rtc/>
! <inline name="random">012345678</inline>
! </dir>
! <dir name="socket"> <lxip dhcp="yes"/> </dir>
! <dir name="etc"> <fs/> </dir>
! </vfs>
! <libc stdout="/dev/log" stderr="/dev/log" rtc="/dev/rtc" socket="/socket"/>
! </config>
The above config snippet shows a configuration where two Noux clients may
connect to the Terminal server and SSH connections with either a password or a
public are processed on port 2022. All SSH logins for the user 'root' are
linked to the 'noux-system' session, while all 'user' logins are forwarded
to the 'noux-user' session.
The '<config>' node has several mandatory attributes:
* 'port' specfies the TCP port the SSH server attempts to listen on.
* 'ecdsa_key', 'ed25519_key' and 'rsa_key' set the respective
path to the host key. At least one of them must be specified.
* 'allow_password' enables password logins while 'allow_publickey'
enables public-key logins. At least one of them must be specified.
Those Authentication methods are set for all logins even if they
are not useable by one or the other.
Aside from the mandatory attributes there are optional ones:
* 'log_logins' enables logging of login attempts. These attempts will
be printed to the LOG session. The default is 'yes'.
The relation between a Terminal session and a SSH session is established
by a '<policy>' node. It first specifies which Terminal client may access
the server. Second and more importantly it specifies which SSH session has
access to which Terminal session. The non policy-label specific attributes
of the node form a login that is used to authenticate access via the SSH
session:
* 'user' sets the name of a login and is used throughout the component
to establish the relation between Terminal and SSH session and is therefore
mandatory.
* 'password' sets the password of the login, which is used to authenticate
a login attempt.
* 'pub_key' sets the path to the public-key file, which is used to authenticate
a login attempt.
* 'multi_login' allows one Terminal session to be used by mutliple SSH
sessions concurrently, the default is false.
Either one of the 'password' or 'pub_key' attributes must be set in order for
the login to be valid.
Normally, all Terminal sessions are expected to be established before an SSH
connection is made. To accommodate the use-case where the Terminal client is
made available in a dynamic fashion, the 'request_terminal' attribute can by
set to 'yes'. In this case the SSH Terminal server will generate a report,
which then can be inspected and reacted upon by a management component,
whenever a SSH connection for a detached Terminal session is made. Data coming
from the SSH session will be ignored as long as the Terminal client is not
attached to the server. This mechanism is useful in cases where the attached
Terminal might terminate itself, e.g. a shell when receiving EOF, but a
subsequent login attempt expects the Terminal client to be still attached.
The following snippet shows such a report:
! <request_terminal user="baron"/>
The component will generate the report only once when the first login
via SSH is made and the corresponding Terminal session is not available.
All subsequent logins have to wait until the session is provided. Once the
Terminal session has been detached an 'exit' report is generated. Detaching a
terminal client will lead to a disconnect for the corresponding SSH session If
there are active SSH session after the Terminal in question has been detached, a
new report will be generated.
Notes
~~~~~
* A helper component is needed, in case an exec channel is required or when
Terminal sessions need to be started *after* the SSH connection is
established. An example can be found here: _repos/gems/src/test/exec_terminal/
* The SSH connection MUST be forcefully cut at the client in case the Terminal
session is established *before* the ssh channel is open. This can be done
when using OpenSSH by entering '~.'.
* Host keys can be generated by using ssh-keygen(1) on your host system
(e.g., 'ssh-keygen -t ed25519_key -f ed25519_key' without a passphrase and
then use the 'ed25519_key' file).
* Reports from concurrent logins will override each other and potentially lead
to lost reports.
* Although concurrent access to one Terminal session via multiple SSH sessions
at the same time is possible, it should better be avoided as there are no
safety measures in place.
eaefcc2c6f