A New Shell for Equinox - Introduction

Console Support in Equinox

The Equinox Framework has always provided a console administration option. You just have to start it with -console option and you get the well known osgi> prompt on the command line. It comes with a nice set of commands for install/uninstall/start/stop of bundles, inspection of bundles and service, etc. So far, so good.

However, Equinox usually is not used standalone, but as an OSGi implementation in much more complex systems, for example the Virgo Web Server. In such cases the ability to administer the framework through remote connections becomes important. And when the remote access enters the game, the problems are not far away.

Equinox provides a very basic support for remote access - it just listens for network connections, takes the socket input as it is, and writes the output back to the socket. It is not very user-friendly, I admit. And I do not even mention about security.

In the last two versions of Equinox - 3.6 and 3.7 - a support for extending the built-in console was introduced. This allows you to extend it with usability features, but still nothing ready-to-use comes with the framework.

What is New in the New Shell

To overcome the limitations of the default Equinox console, a brand new project was started in the Equinox incubator, whose purpose is to provide much more usable and secure console. It is based on the Apache Felix Gogo shell and adds a number of features to it.

Following are some of the major features of the new console:

• telnet and ssh connectivity
• command line editing
• JAAS based user authentication (for the ssh)
• tab completion

The new shell is backwards compatible - all commands available in the built-in Equinox console are available in the new one too.

Running the Console

The Console in Virgo Web Server

The new console is currently adopted in Virgo Web Server 3.0.0. You can find how to configure it in the Virgo Web Server documentation.

Running the Console Standalone

The most impatient, or those who do not want to spend time putting the parts of the shell together, may prefer to download the archive with everything necessary to run the console. You just need to execute the startup.bat script in the console folder of the archive after you unzip it in order to run the shell.

Now for the more curious - the following steps describes how to put together the different parts of the shell.

Step 1. Download Apache Gogo Shell from Eclipse Orbit repository

• Gogo Runtime
• Gogo Command
• Gogo Shell

Step 2. Download bundles for SSH support from Eclipse Orbit repository

• org.apache.mina.core
• org.apache.sshd.core

Step 3. Download the new console implementation bundles:
Download Equinox incubator build and take form it the following two bundles (located in the plugins folder):

• org.eclipse.equinox.console.jaas.fragment
• org.eclipse.equinox.console.supportability

Step 4. Download logging api and implementation, required by the ssh bundles:

• org.slf4j.api
• ch.qos.logback.slf4j
• ch.qos.logback.core
• ch.qos.logback.classic

Step 5. Configuring the console.

• Place the above bundles in a folder. Add to this folder the Equinox itself
• Create a subfolder called configuration.
  In configuration create a file config.ini
  
• config.ini file should have the following content:
  
osgi.bundles=./org.apache.felix.gogo.runtime_0.8.0.v201108120515.jar@start,\
  ./org.apache.felix.gogo.command_0.8.0.v201108120515.jar@start,\
  ./org.apache.felix.gogo.shell_0.8.0.v201108120515.jar@start,\
  ./org.slf4j.api_1.6.1.v20100831-0715.jar@start,\
  ./ch.qos.logback.core_0.9.27.v20110224-1110.jar@start,\
  ./ch.qos.logback.classic_0.9.27.v20110224-1110.jar@start,\
  ./ch.qos.logback.slf4j_0.9.27.v20110224-1110.jar,\
  ./org.apache.mina.core_2.0.2.v201108120515.jar@start,\
  ./org.apache.sshd.core_0.5.0.v201108120515.jar@start,\
  ./org.eclipse.equinox.console.supportability_1.0.0.N20110816-2000.jar@start,\
  ./org.eclipse.equinox.console.jaas.fragment_1.0.0.N20110816-2000.jar
osgi.console.enable.builtin=false
osgi.console=2223
osgi.console.ssh=2222
osgi.console.ssh.useDefaultSecureStorage=true

  
• Create a file with name org.eclipse.equinox.console.authentication.config in the configuration subfolder.
• Add the following entry to org.eclipse.equinox.console.authentication.config file:
  
equinox_console {
  org.eclipse.equinox.console.jaas.SecureStorageLoginModule REQUIRED;
};

  
• In the configuration subfolder create logging configuration file called logback.xml. For now write in it
  
<configuration>
  <root level="off" />
</configuration>

  to turn off logging by the ssh server.
• Start the Equinox framework with the following command (you may put this in a startup.bat file to easily start it every time):
  java -Dlogback.configurationFile=configuration/logback.xml
  -Dssh.server.keystore=configuration/hostkey.ser \
  -Dorg.eclipse.equinox.console.jaas.file=configuration/store \           -Djava.security.auth.login.config=configuration/org.eclipse.equinox.console.authentication.config \
  -jar org.eclipse.osgi_3.8.0.N20110816-2000.jar

  And voila! Now you should be able to access the console over telnet on port 2223 and over ssh on port 2222. The default username/password for ssh accdess are equinox/equinox. On the first login this user is deleted and you are prompted to create a new user.
  

Next time I will describe the different configuration options.