h1. Using remote instances

h2. 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:

{code}
sshPort=8101
sshHost=0.0.0.0
sshRealm=karaf
hostKey=${karaf.base}/etc/host.key
{code}

You can change this configuration using the [config commands|configuration] or by editing the above file, but you'll need to restart the ssh console in order for it to use the new parameters.

{code}
# 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)
{code}

h2. Connecting and disconnecting remotely

h3. Using the {{ssh:ssh}} command

You can connect to a remote Karaf's console using the [{{ssh:ssh}}|/commands/ssh-ssh] command.

{code}
karaf@root> ssh:ssh -l karaf -P karaf -p 8101 hostname
{code}

{warning}
The default password is {{karaf}} but we recommend changing it. See the [security] section for more informations.
{warning}

To confirm that you have connected to the correct Karaf instance, type [{{shell:info}}|/commands/shell-info] at the {{karaf>}} prompt. Information about the currently connected instance is returned, as shown.

{code}
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
  ...
{code}

h3. 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:
{code}
bin/client
{code}

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:
{code}
bin/client -a 8101 -h hostname -u karaf -p karaf features:install wrapper
{code}

To display the available options for the client, type:
{code}
> 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
{code}

h3. Using a plain SSH client

You can also connect using a plain SSH client from your *nix system or Windows SSH client like Putty.
{code}
~$ ssh -p 8101 karaf@localhost
karaf@localhost's password: 
{code}

h3. Disconnecting from a remote console

To disconnect from a remote console, press {{Ctrl+D}}, {{shell:logout}} or simply {{logout}} at the Karaf prompt.

h2. Stopping a remote instance

h3. Using the remote console 

If you have connected to a remote console using the [{{ssh:ssh}}|/commands/ssh-ssh] command or the Karaf client, you can stop the remote instance using the [{{osgi:shutdown}}|/commands/osgi-shutdown] command.

{info}
Pressing {{Ctrl+D}} in a remote console simply closes the remote connection and returns you to the local shell.
{info}

h3. Using the Karaf client

To stop a remote instance using the Karaf client, run the following from the {{[karaf-install-dir]/lib}} directory:
{code}
bin/client -u karaf -p karaf -a 8101 hostname osgi:shutdown
{code}