4.2. Remote Console
The remote console feature allows to connect to a running Karaf instance from a remote computer and perform all the operations that are usually accessible from the local console.
Launch options
The Karaf shell scripts supports a number of options to control the remote console:
console
: launch Karaf in the default mode (both local and remote console activated). This is the default modeserver
: launch Karaf in with a remote console but no local consoleclient
: launch Karaf in with a local console only
These options affect two system properties that can be set if you don't use the standard shell scripts:
karaf.startLocalConsole
karaf.startRemoteShell
Using the client jar
It is also possible to use a more lightweight way to connect to a Karaf instance using the following command line:
java -jar lib/karaf-client.jar
There are a few parameters that can be set on the command line to change the URL used to connect to the Kernel, the user or the password.
All these parameters are detailed in the help screen:
> java -jar lib/karaf-client.jar --help Apache Felix Karaf client -a [address] specify the URL to connect to -h [host] specify the host to connect to -u [user] specify the user name -p [password] specify the password --help shows this help message [commands] commands to run If no commands are specified, the client will be put in an interactive mode
For example, to shut down the Kernel from the command line, you can run the following command:
> java -jar lib/karaf-client.jar smx@root:/> osgi:shutdown smx@root:/> >
The client jar also supports passing command line arguments to the remote Karaf.
> java -jar lib/karaf-client.jar osgi:shutdown >
Using an SSH client
You can use any standard SSH client to connect to a Karaf instance. The default port is 8101.
> ssh -p 8101 -l karaf localhost karaf@localhost's password: karaf karaf@root:/>
Error messages when using some ssh clients
Some SSH clients will prompt some harmless warnings when connecting to ServiceMix Kernel.
In particular, openssh 5.1p1 will display the following output:
channel_by_id: 1: bad id: channel free channel_input_success_failure: 1: unknown channel_by_id: 1: bad id: channel free channel_input_success_failure: 1: unknown
Using another Kernel instance
First, open a terminal and launch Karaf in server mode (you could use a Karaf instance in console mode too):
bin/karaf server
On another terminal, start another Karaf instance in client mode:
bin/karaf client
User another Kernel instance to start the client
At this point in time, you can not use the same Karaf installation to start both the server and the client, so you need to create a new instance using the 'admin create xxx' command and use that one to start the client. If you are on a different host or already use another copy of Karaf, this requirement does not hold.
Once the console appears, you can run the remote rsh
command to connect to the other Kernel:
remote rsh tcp://localhost:8101/ -u karaf -p karaf
You can also do that in a single command line from the prompt by appending the previous ServiceMix command to the shell command:
bin/karaf client remote rsh tcp://localhost:8101/ -u karaf -p karaf
To verify that your are connected to the remote Kernel, run the following command:
info
and check the system informations.
Configuration
The TCP port is configured at the following location:
[KARAF]/etc/org.apache.felix.karaf.shell.cfg
The defaut configuration is as below:
startLocalConsole=${karaf.startLocalConsole} startRemoteShell=${karaf.startRemoteShell} sshPort=8101 sshRealm=karaf hostKey=${karaf.base}/etc/host.key
The port used can easily be changed by changing the default port 8101
in the sshPort
property.
The security realm used by the console when authenticating remote users is named karaf
, so you can override this realm as explained in the security section.