A New Shell for Equinox - Configurations

Configuring the New Shell

Last time I introduced the new shell and described how you can start using it. Now I will explain in more details the esoteric formulas in the configuration file for running the shell.

Let me start with the config.ini file.

The first entry there, osgi.bundles, specify which bundles should be started along with the start of the Equinox. Obviously, in our case these are all bundles, related with the shell. This is in case you don't want to install and start them manually after running the framework.

Not all of the bundles I have included in the configuration are absolutely necessary. If you want to have the full functionality of the shell, you do need all of them. But if you need only the shell or the shell with telnet access, you do not need most of them. In this partial scenario you will have to include in the configuration the three gogo bundles, and the org.eclipse.equinox.console.supportability bundle. All the rest are necessary only for the ssh support.

As I mentioned in the previous post, Equinox framework comes with a very basic console built into it. In order for the new shell to function properly, this default console should be disabled. This is exactly what the property osgi.console.enable.builtin set to the value false does.

The property osgi.console specifies the telnet port, on which the console listens. If you do not want the console to open a telnet port, do not specify this property. The value of the property could be just the port number, or may have the format <host>:<port>. In the latter case the port is opened only on the specified network interface. This is used to increase security. If you open the telnet on <localhost>:<port> or <127.0.0.1>:<port>, then the shell will be accessed on only from the localhost - remotely there will be no access. If the host is not specified, then the port is open on all network interfaces and connection is possible from remote hosts.

The property osgi.console.ssh specifies the port, on which the console listens for ssh connections. Again, a host may be specified with the format <host>:<port> as with telnet, but there is not much use of this since ssh is a secure protocol. If you do not want an ssh port to be opened by the console, or you do not want to support ssh at all, you may not specify this property in the configuration.

You may prefer not to specify the telnet and/or ssh hosts/ports in advance. Instead, you can start the telnet/ssh servers with console commands from command line after you start the shell.

The new console supports configuration through the Equinox Configuration Admin service. If you want to configure it this way, you should programmatically register two configurations in the Configuration Admin service - for the telnet and ssh, respectively. The PIDs of the two configurations are osgi.console.telnet and osgi.console.ssh, respectively. Both configurations should contain the following properties:

• enabled - if the telnet or ssh should be enabled by default. The values are true and false
• host - the host on which telnet/ssh connection should be accepted
• port - the port on which telnet/ssh connection should be accepted

If you configure the console through the Configuration Admin service, you shoud not specify the properties osgi.console and osgi.console.ssh in the config.ini file. Instead, you should add the property osgi.console.useConfigAdmin=true. Also, you need to install the Configuration Admin service.


The last property, osgi.console.ssh.useDefaultSecureStorage, specifies what storage does the ssh use for storing sensitive data like user passwords. The ssh in the console uses JAAS base user authentication. The default login module, which comes with the console, uses password based access. You can provide a custom login module, but if you decide to use the default one, this property must have value true.

The file org.eclipse.equinox.console.authentication.config specifies which login modules should the JAAS framework use for user authentication. In our case in the file we specify the name of the default login module of the console. If you provide a custom login module, you should change the entry in this file. The name of the file could be arbitrary, as long as you correctly pass it as an argument when you start the java process.

Following are the arguments, which should be passed to the JVM:

• logback.configurationFile specifies the location of the logback configuration file.
• ssh.server.keystore specifies the name of the file, where the ssh server will store its keys.
• org.eclipse.equinox.console.jaas.file specifies the name of the file, where the default JAAS login module will store user credentials. Credentials are encrypted. This property must be set if the default login module is used.
• java.security.auth.login.config specifies the name of the file, where the JAAS login modules are listed. In our case the value is org.eclipse.equinox.console.authentication.config

By default, when the new shell starts, it reads from standard input and writes to standards output, in addition to the telnet/ssh sessions support. If you want to start the shell non-interactively, that is the shell will not read and write to the standard streams, you should add to the argument gosh.args=--nointeractive to the VM arguments. In this case you still will be able to open telnet and/or ssh connections, if you have configured the shell accordingly.

A few more words about the logging bundles. In this blog the slf4j api and implementation from the Eclipse Orbit repository are used. Any slf4j implementation may be used instead. If you decide to use another slf4j implementation, you should also use the original slf4j api (instead of org.slf4j.api bundle from the Eclipse Orbit repository). You can take the original slf4j api and different implementations from here. If you decide to use any of them, do not forget to update the config.ini file by adding the new bundles and removing the old logging bundles. And also, do not forget to provide the correct logging configuration file, appropriate for the logger of you choice.