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 [karaf_install_dir]/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 from the karaf-install-dir directory:

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 karaf-install-dir/lib directory:

bin/client -u karaf -p karaf -a 8101 hostname osgi:shutdown