karaf-2.2.x/manual/src/main/webapp/users-guide/remote-console.conf

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}