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

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  /_/ \_\


%