osgi.bundles=./org.apache.felix.gogo.runtime-0.8.0.jar@start,\
./org.apache.felix.gogo.command-0.8.0v<version>.jar@start,\
./org.apache.felix.gogo.shell-0.8.0v<version>.jar@start,\
./slf4j-api-<version>.jar@start,\
./<slf4j-api_impl>.jar,\
./org.apache.mina.core_2.0.2v<version>.jar@start,\
./org.apache.sshd.core_0.5.0v<version>.jar@start,\
./org.eclipse.equinox.console.supportability.jar@start,\
./org.eclipse.equinox.console.jaas.fragment.jar
osgi.console.enable.builtin=false
osgi.console.ssh=<port>
osgi.console.ssh.useDefaultSecureStorage=true
osgi.console=<port> instead of osgi.console.ssh in the config.ini file.
For both properties, you can also specify the host:
osgi.console=<host>:<port>
osgi.console.ssh=<host>:<port>
where <host> is either localhost or 127.0.0.1, so that the console listens for telnet connections only from the localhost.
equinox_console {
org.eclipse.equinox.console.jaas.SecureStorageLoginModule REQUIRED;
};
java -Djava.util.logging.config.file=configuration/logging.properties \
-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.jar
osgi.console.enable.builtin=false disables the Equinox built-in console. It must be disabled in order for the new console to work properly.osgi.console.ssh.useDefaultSecureStorage is necessary only if ssh is used and the default login mechanism is used (i. e., a custom login module is not provided)-Djava.security.auth.login.config accordingly.osgi.console.ssh.useDefaultSecureStorage must be set to
true. The file, where the users are stored, is specified through the property org.eclipse.equinox.console.jaas.file
Using Custom JAAS Authentication Login Module
Custom JAAS authentication login modules could be used with the ssh instead of the default one. If a custom login module is used,
then the property osgi.console.ssh.useDefaultSecureStorage must not be set at all. The custom module must be specified
in the file org.eclipse.equinox.console.authentication.config instead of the default entry there, or in a different file.
If a different file is used, then its name must be specified as the value of the property -Djava.security.auth.login.config
instead of org.eclipse.equinox.console.authentication.config.
Also, it will be necessary to create a fragment to sshd-core bundle, with which to import the package of the custom login module. This is necessary
for the sshd to be able to load the module class.
Configuring of telnet and ssh host and port through Configuration Admin service
The console provides the option to configure the telnet and ssh host and port through Configuration Admin instead of
through the properties osgi.console=<host>:<port> and osgi.console.ssh=<host>:<port>.
This could be helpful in more complex scenarios, for example when you want to run different instances of the console in different subsystems of the
framework. In this case if the port is configured through a system property, it is one and the same for all console instances and only one
will be able to bind to the socket.
If this feature is used, then you should:
- set the property
osgi.console.useConfigAdmin to true
- install and start, along with the console bundles, the org.eclipse.equinox.cm bundle and its dependencies
write a bundle to provide the configuration with the telnet and ssh properties
The configuration PID for the telnet configuration is osgi.console.telnet and for the ssh configuration is osgi.console.ssh.
Both configurations have the following properties:
hostportenabled
All must have values of type String.
The enabled property determines if telnet/ssh is to be started at all. If the value is true, telnet/ssh is started.
If the value is false, or the property enabled is absent, the telnet/ssh is not started.
Using Commands
The Gogo shell, on which the new console is based, supports different type of commands from these currently supported in Equinox. Currently in Equinox,
commands are provided by a class implementing the CommandProvider interface. The new console provides an adapter from this type of commands
to the new type of commands, used in Gogo and specified in RFC 147. The RFC 147 commands are arbitrary classes, registered as services, with two special
properties:
osgi.command.scope - specifies the scope of the commandosgi.command.function - specifies the commands provided by this service; this is a list of the names of public methods in the service class, which must be available for execution as commands
The commands in the new console use the notion of command scope. The scope can be used, for example,
to differentiate between commands with one and the same name, but provided by different providers. Then they should have different scopes.
The scope is a prefix of the command name, separated from it with a column. When writing the command in the console, the scope may or may not be specified.
If the scope is not specified, then the command with this name from the default scope is used. If in the default scope there is no command with such name,
all commands are searched.
If there is more than one command with the specified name in different scopes, it is not guaranteed which one will be actually
executed. Therefore, if you know that there are commands with the same name but different scopes, you must explicitly prefix the command name with the
scope to ensure that you will get executed exactly the command you want.
The legacy commands, adapted by the new console, have scope equinox.
Getting Help for Commands
The default help command in Gogo lists the names of the registered commands, and if it is called with a command name as an argument, it displays help message for the
specified command. The default help command does not provide help for the legacy Equinox commands, which are adapted by the new console. For this reason the
new console provides its own help command, which calls the default help, but could also provide help for the legacy commands.
If no argument is specified the names of all new commands are displayed.
If a command name is specified, the help message for this command is displayed. If the command is legacy and the CommandProvider, which provides this command,
does not provide separate help for each command (this is a new feature, introduced in Equinox 3.7), then the help messages for all commands in this CommandProvider are displayed.
The help command, provided by the new console, should be explicitly scoped, as in equinox:help.
There is also a man command. It accepts the same arguments as the help command and has the same semantics.
Writing RFC 147 Commands
Writing RFC 147 commands is easy. You have to do the following:
- Write your class with all commands you want implemented as public methods. Methods may have arbitrary arguments. Also, unlike Equinox command providers, in RFC 147 there is no interface that the class of the command provider should implement.
- Register the command provider as a service with the two properties, described above.
Something new for the RFC 147 commands are the converters and formatters.
The converter is a class which converts the arguments, passed on the command line, to the actual arguments,
which the command accepts. For example, the command may have one argument of type Bundle. There may be a converter, which from a long finds the bundle with this id.
Then the command may be called with the ID of the bundle as an argument, the converter will convert it to the corresponding Bundle object and the command method will
be called with this object as an argument.
The formatter is a class which displays the result, returned by the command method.
For more information on RFC 147 commands, you can check the Gogo documentation.
Tab Completion
The console provides tab completion. This feature is available only when connecting through telnet or ssh.
Completion is available for:
- command names
- variable names - these must be previously defined in the session; variable names may be passed as command arguments
- file names - passed as command arguments
When the tab key is typed, all possible candidates for completion for the current word are searched. If there is only one possible completion,
the current word is automatically completed. If there are more than one options, all are displayed in a column. The possible options can be iterated by hitting
tab multiple times, until the desired completion candidate is reached.
If longest common prefix of all available completion candidates is longer than the current word, then the current word is completed automatically to this prefix, before choosing
the final completion. For example, if we have the following available completions for the word bun:
- bundles
- bundle
- bundlelevel
the current word is completed automatically to bundle, and then by hitting tab you can choose which completion you like, or may type it for yourself.
The console allows custom command completers to be provided. A custom completer should implement the interface org.eclipse.equinox.console.common.Completer, provided by
the bundle of the new console. It has the single method getCandidates, which get as a parameter the whole command line and the current cursor position in it, and returns
a map with all completion candidates, and the position in the command line, on which the completion begins. The keys in the map are the candidates, and the values - the start position
for the completion.
Closing Telnet or Ssh Session
Both telnet and ssh sessions are closed with the disconnect command.
Running Non-interactive Shell
In some cases you may wish to run the console without an interactive session. In this case, the console can be connected from telnet and ssh, but is not available
on standard in and out. For this the following property should be specified: -Dgosh.args=--nointeractive