Manager Configuration
Overview
The manager is configured like any other module:
{
"mgr": {
"handler": "nz.co.nsquared.slee.manager.ManagerVerticle",
"configuration": {
...
}
}
}
If a manager service is not specified, one will be started automatically
with the default options. Note that the name of the manager, if provided, must
be mgr
.
As many or as few of the manager service functions may be enabled, as suitable for your site. By default, the manager disallows all external access to management functions.
Configuration Options
Field | Type | Required? | Default | Description |
---|---|---|---|---|
console.http.enabled |
Boolean | No | false |
Whether or not the management GUI is available. |
console.http.interface |
String | No | 0.0.0.0 |
The interface the management GUI listens on, if enabled. |
console.http.port |
Integer | No | 5290 |
The port the management GUI listens on, if enabled. |
shell.telnet.enabled |
Boolean | No | false |
Whether or not the telnet shell is available. |
shell.telnet.interface |
String | No | 127.0.0.1 |
The interface the telnet shell listens on, if enabled. |
shell.telnet.port |
Integer | No | 5291 |
The port the telnet shell listens on, if enabled. |
shell.ssh.enabled |
Boolean | No | false |
Whether or not the SSH shell is available. |
shell.ssh.interface |
String | No | 0.0.0.0 |
The interface the SSH shell listens on, if enabled. |
shell.ssh.port |
Integer | No | 5292 |
The port the SSH shell listens on, if enabled. |
shell.ssh.config |
Object | Conditional | - | The Vert.X configuration options for the SSH shell. Required if the SSH shell is enabled. |
shell.http.enabled |
Boolean | No | false |
Whether or not the HTTP shell in the management GUI is available. |
auth.enabled |
Boolean | No | false |
Whether or note Keycloak authentication for the management GUI is enabled. |
auth.provider |
String | Conditional | - | The authentication model used by the JSLEE to authenticate the client. Currently jwt tokens are supported, this must be set to jwt . Required if auth is enabled. |
auth.jwt.publickey |
String | Conditional | - | The public key used by the auth provider. Required if auth is enabled. |
auth.jwt.rolepath |
String | No | resource_access/n2jslee/roles |
The path where we can find the users roles in the JWT. Only used if auth is enabled. |
auth.client |
Object | Conditional | - | The configuration for the authentication server. Required if auth is enabled, see management GUI authentication for more details. |
Management GUI
The manager can provide a management interface accessible from a web browser.
This feature provides information on the system’s running and configured services and endpoints and overall system health.
An example configuration for the management interface might be:
{
"mgr": {
"handler": "nz.co.nsquared.slee.manager.ManagerVerticle",
"configuration": {
"console.http.enabled": true,
"console.http.interface": "127.0.0.1",
"console.http.port": 12345
}
}
}
This configuration would enable the HTTP interface, available at http://127.0.0.1:12345
, with no authentication required.
Management GUI Authentication
Optionally, authentication can be provided for the Management GUI with the use of Keycloak.
This would require any user of the management GUI to log in through Keycloak before they can gain access to the management GUI.
An example configuration for the management interface authentication might be:
{
"mgr": {
"handler": "nz.co.nsquared.slee.manager.ManagerVerticle",
"configuration": {
"console.http.enabled": true,
"console.http.interface": "127.0.0.1",
"console.http.port": 12345,
"shell.http.enabled": true,
"auth.enabled": true,
"auth.provider": "jwt",
"auth.jwt.publickey": "the-public-RSA-key-for-Keycloak",
"auth.client": {
"realm": "nsquared",
"url": "http://keycloak-server",
"clientId": "n2jslee"
}
}
}
}
This configuration would enable the HTTP interface including the HTTP shell, available at http://127.0.0.1:12345
with authentication required on log in
using Keycloak as the authentication service.
Telnet Shell
A telnet interface for management commands is available. No authentication nor encryption is available for this access method.
An example configuration might be:
{
"mgr": {
"handler": "nz.co.nsquared.slee.manager.ManagerVerticle",
"configuration": {
"shell.telnet.enabled": true,
"shell.telnet.interface": "0.0.0.0",
"shell.telnet.port": 12346
}
}
}
This configuration would enable the telnet shell function as available on all interfaces at port 12346.
SSH Shell
An SSH interface to the command shell is also available, offering authentication and encryption.
An example configuration might be:
{
"mgr": {
"handler": "nz.co.nsquared.slee.manager.ManagerVerticle",
"configuration": {
"shell.ssh.enabled": true,
"shell.ssh.interface": "127.0.0.1",
"shell.ssh.port": 12347,
"shell.ssh.config": {
"authOptions": {
"provider": "mongo",
"config": {
"connection_string": "mongodb://database-server:27016"
}
},
"keyPairOptions": {
"path": "/home/nsquared/keystore.jks",
"password": "secret"
}
}
}
}
}
This configuration would enable the SSH shell function as available on the local host only
at port 12347. For authentication, the key store keystore.jks
would be used with the
supplied password and with a Mongo database as the authenticator.
Note that the SSH shell will be disconnected after ten minutes of user inactivity.
Vert.X SSH Configuration Options
The configuration elements within the shell.ssh.config
parameter are passed directly to
the relevant Vert.X classes for their own parsing. For details of the available options
and their usage:
authOptions
content as described in the Vert.X documentation for shell authentication.- All other content as described in the Vert.X documentation for SSH terminal configuration.
Note that the host
and port
options at this level are ignored in favour of the
explicitly-defined parameters at the higher level.
Note that SSH public/private key authentication methods will be used in preference automatically to any defined authentication options. However, an authentication backend must still be defined and available, even if it is not used.
Vert.X SSH Configuration Example
As an example, follow the below steps to set up SSH user authentication via a Mongo database authentication backend.
Generate Server Key File
Generate a local JKS key file for the server, updating the file location as appropriate:
keytool -genkey -keyalg RSA -keystore /path/to/ssh.jks -keysize 2048 -dname CN=localhost -keypass secret -storepass secret
Further reading: Vert.X Shell Introduction
Populate Mongo Database and Collection
For this example, our configuration expects to find a collection users
on a Mongo database
called n2jslee
. Connect to the database and create the collection, inserting a record
such as:
{
"username: "testuser",
"pwd": "password"
}
Further reading: Vert.X Mongo Authentication Options
HTTP shell
The management GUI also offers access to the command shell.
Example configuration is:
{
"mgr": {
"handler": "nz.co.nsquared.slee.manager.ManagerVerticle",
"configuration": {
"shell.http.enabled": true
}
}
}
This configuration would enable access to the command shell from within the management GUI.
Configure Manager Application
Apply the following manager configuration, updating values as required for your implementation:
{
"mgr": {
"handler": "nz.co.nsquared.slee.manager.ManagerVerticle",
"instance-count": 1,
"configuration": {
"shell.ssh.enabled": true,
"shell.ssh.config": {
"authOptions": {
"provider": "mongo",
"config": {
"connection_string": "mongodb://database-server:27016/n2jslee",
"collectionName": "users"
}
},
"keyPairOptions": {
"path": "/path/to/ssh.jks",
"password": "secret"
}
}
}
}
}
Connect To Manager
With the above configuration, you should be able to connect to the running JSLEE with:
ssh -p 5292 testuser@localhost
After authentication, you should see the Vert.X shell banner:
__ __ ______ _____ _______ __ __
\ \ / /| ____|| _ \|__ __| \ \ / /
\ \ / / | |____ | :_) | | | \ /
\ \/ / | ____|| __/ | | > /
\ / | |____ | |\ \ | | / //\
\/ |______||_| \_\ |_| o /_/ \_\
%