Using remote instances
Configuring remote instances
It does not always make sense to manage an instance of Karaf using its local console. You can manage Karaf remotely using a remote console.
When you start Karaf, it enables a remote console that can be accessed over SSH from any other Karaf console or plain SSH client. The remote console provides all the features of the local console and gives a remote user complete control over the container and services running inside of it.
The SSH hostname and port number is configured in the etc/org.apache.karaf.shell.cfg configuration file with the following default values:
sshPort=8101
sshHost=0.0.0.0
sshRealm=karaf
hostKey=${karaf.base}/etc/host.key
You can change this configuration using the config commands or by editing the above file, but you'll need to restart the ssh console in order for it to use the new parameters.
# define helper functions
bundle-by-sn = { bm = new java.util.HashMap ; each (bundles) { $bm put ($it symbolicName) $it } ; $bm get $1 }
bundle-id-by-sn = { b = (bundle-by-sn $1) ; if { $b } { $b bundleId } { -1 } }
# edit config
config:edit org.apache.karaf.shell
config:propset sshPort 8102
config:update
# force a restart
osgi:restart --force (bundle-id-by-sn org.apache.karaf.shell.ssh)
Connecting and disconnecting remotely
Using the ssh:ssh command
You can connect to a remote Karaf's console using the ssh:ssh command.
karaf@root> ssh:ssh -l karaf -P karaf -p 8101 hostname
The default password is karaf but we recommend changing it. See the security section for more informations.
To confirm that you have connected to the correct Karaf instance, type shell:info at the karaf> prompt. Information about the currently connected instance is returned, as shown.
Karaf
Karaf home /local/apache-karaf-2.0.0
Karaf base /local/apache-karaf-2.0.0
OSGi Framework org.eclipse.osgi - 3.5.1.R35x_v20090827
JVM
Java Virtual Machine Java HotSpot(TM) Server VM version 14.1-b02
...
Using the Karaf client
The Karaf client allows you to securely connect to a remote Karaf instance without having to launch a Karaf instance locally.
For example, to quickly connect to a Karaf instance running in server mode on the same machine, run the following command:
bin/client
More commonly, you would provide a hostname, port, username and password to connect to a remote instance. And, if you were using the client within a larger script, you could append console commands as follows:
bin/client -a 8101 -h hostname -u karaf -p karaf features:install wrapper
To display the available options for the client, type:
> bin/client --help
Apache Karaf client
-a [port] specify the port 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
-v raise verbosity
-r [attempts] retry connection establishment (up to attempts times)
-d [delay] intra-retry delay (defaults to 2 seconds)
[commands] commands to run
If no commands are specified, the client will be put in an interactive mode
Using a plain SSH client
You can also connect using a plain SSH client from your *nix system or Windows SSH client like Putty.
~$ ssh -p 8101 karaf@localhost
karaf@localhost's password:
Disconnecting from a remote console
To disconnect from a remote console, press Ctrl+D, shell:logout or simply logout at the Karaf prompt.
Stopping a remote instance
Using the remote console
If you have connected to a remote console using the ssh:ssh command or the Karaf client, you can stop the remote instance using the osgi:shutdown command.
Pressing Ctrl+D in a remote console simply closes the remote connection and returns you to the local shell.
Using the Karaf client
To stop a remote instance using the Karaf client, run the following from the lib directory:
bin/client -u karaf -p karaf -a 8101 hostname osgi:shutdown