Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 15. Remote

Apache Karaf supports a complete remote mechanism allowing you to remotely connect to a running Apache Karaf instance. You can also browse, download, and upload files remotely to a running Apache Karaf instance.

Apache Karaf embeds a complete SSHd server.

15.1. SSHd server
Copy link

When you start Apache Karaf, it enables a remote console that can be accessed over SSH.

This 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. As the "local" console, the remote console is secured by a RBAC mechanism See Chapter 19, Security for details.

In addition to the remote console, Apache Karaf also provides a remote filesystem. This remote filesystem can be accessed using a SCP/SFTP client.

15.1.1. Configuration
Copy link

The configuration of the SSHd server is stored in the etc/org.apache.karaf.shell.cfg file: 

################################################################################
#
#    Licensed to the Apache Software Foundation (ASF) under one or more
#    contributor license agreements.  See the NOTICE file distributed with
#    this work for additional information regarding copyright ownership.
#    The ASF licenses this file to You under the Apache License, Version 2.0
#    (the "License"); you may not use this file except in compliance with
#    the License.  You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#    Unless required by applicable law or agreed to in writing, software
#    distributed under the License is distributed on an "AS IS" BASIS,
#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#    See the License for the specific language governing permissions and
#    limitations under the License.
#
################################################################################

#
# These properties are used to configure Karaf's ssh shell.
#

#
# Via sshPort and sshHost you define the address you can login into Karaf.
#
sshPort = 8101
sshHost = 0.0.0.0

#
# The sshIdleTimeout defines the inactivity timeout to logout the SSH session.
# The sshIdleTimeout is in milliseconds, and the default is set to 30 minutes.
#
sshIdleTimeout = 1800000

#
# sshRealm defines which JAAS domain to use for password authentication.
#
sshRealm = karaf

#
# The location of the hostKey file defines where the private/public key of the server
# is located. If no file is at the defined location it will be ignored.
#
hostKey = ${karaf.etc}/host.key

#
# Role name used for SSH access authorization
# If not set, this defaults to the ${karaf.admin.role} configured in etc/system.properties
#
# sshRole = admin

#
# Self defined key size in 1024, 2048, 3072, or 4096
# If not set, this defaults to 4096.
#
# keySize = 4096

#
# Specify host key algorithm, defaults to RSA
#
# algorithm = RSA

#
# Defines the completion mode on the Karaf shell console. The possible values are:
# - GLOBAL: it's the same behavior as in previous Karaf releases. The completion displays all commands and all aliases
#           ignoring if you are in a subshell or not.
# - FIRST: the completion displays all commands and all aliases only when you are not in a subshell. When you are
#          in a subshell, the completion displays only the commands local to the subshell.
# - SUBSHELL: the completion displays only the subshells on the root level. When you are in a subshell, the completion
#             displays only the commands local to the subshell.
# This property define the default value when you use the Karaf shell console.
# You can change the completion mode directly in the shell console, using shell:completion command.
#
completionMode = GLOBAL
Copy to Clipboard Toggle word wrap

The etc/org.apache.karaf.shell.cfg configuration file contains different properties to configure the SSHd server:

  • sshPort is the port number where the SSHd server is bound (by default, it’s 8101).
  • sshHost is the address of the network interface where the SSHd server is bound. The default value is 0.0.0.0, meaning that the SSHd server is bound on all network interfaces. You can bind on a target interface providing the IP address of the network interface.
  • hostKey is the location of the host.key file. By defaut, it uses etc/host.key. This file stores the public and private key pair of the SSHd server.
  • sshRole is the default role used for SSH access. The default value is the value of karaf.admin.role property defined in etc/system.properties. See the [Security section|security] of this user guide for details.
  • keySize is the key size used by the SSHd server. The possible values are 1024, 2048, 3072, or 4096. The default value is 1024.
  • algorithm is the host key algorithm used by the SSHd server. The possible values are DSA or RSA. The default value is DSA.

The SSHd server configuration can be changed at runtime:

  • by editing the etc/org.apache.karaf.shell.cfg configuration file
  • by using the config:* commands

At runtime, when you change the SSHd server configuration, you have to restart the SSHd server to load the changes. You can do it with: 

karaf@root()> bundle:restart -f org.apache.karaf.shell.ssh
Copy to Clipboard Toggle word wrap

The Apache Karaf SSHd server supports key/agent authentication and password authentication.

15.1.2. Console clients
Copy link

15.1.2.1. System native clients
Copy link

The Apache Karaf SSHd server is a pure SSHd server, similar to OpenSSH daemon.

It means that you can use directly a SSH client from your system.

For instance, on Unix, you can directly use OpenSSH: 

~$ ssh -p 8101 karaf@localhost
Authenticated with partial success.
Authenticated with partial success.
Authenticated with partial success.
Password authentication
Password:
Karaf started in 7s. Bundle stats: 239 active, 239 total

 ____          _   _   _       _     _____
|  _ \ ___  __| | | | | | __ _| |_  |  ___|   _ ___  ___
| |_) / _ \/ _` | | |_| |/ _` | __| | |_ | | | / __|/ _ \
|  _ <  __/ (_| | |  _  | (_| | |_  |  _|| |_| \__ \  __/
|_| \_\___|\__,_| |_| |_|\__,_|\__| |_|   \__,_|___/___|

  Red Hat Fuse (7.0.0.fuse-000191-redhat-1)
  http://www.redhat.com/products/jbossenterprisemiddleware/fuse/


Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit 'system:shutdown' to shutdown Karaf.
Hit '<ctrl-d>' or type 'logout' to disconnect shell from current session.

karaf@root()>
Copy to Clipboard Toggle word wrap

On Windows, you can use Putty, Kitty, etc.

If you don’t have SSH client installed on your machine, you can use Apache Karaf client.

15.1.2.2. ssh:ssh command
Copy link

Apache Karaf itself provides a SSH client. When you are on the Apache Karaf console, you have the ssh:ssh command: 

karaf@root()> ssh:ssh --help
DESCRIPTION
        ssh:ssh

        Connects to a remote SSH server

SYNTAX
        ssh:ssh [options] hostname [command]

ARGUMENTS
        hostname
                The host name to connect to via SSH
        command
                Optional command to execute

OPTIONS
        --help
                Display this help message
        -p, --port
                The port to use for SSH connection
                (defaults to 22)
        -P, --password
                The password for remote login
        -q
                Quiet Mode. Do not ask for confirmations
        -l, --username
                The user name for remote login
Copy to Clipboard Toggle word wrap

Thanks to the ssh:ssh command, you can connect to another running Apache Karaf instance: 

karaf@root()> ssh:ssh -p 8101 karaf@192.168.134.2
Connecting to host 192.168.134.2 on port 8101
Connecting to unknown server. Add this server to known hosts ? (y/n)
Storing the server key in known_hosts.
Connected
Karaf started in 7s. Bundle stats: 239 active, 239 total

 ____          _   _   _       _     _____
|  _ \ ___  __| | | | | | __ _| |_  |  ___|   _ ___  ___
| |_) / _ \/ _` | | |_| |/ _` | __| | |_ | | | / __|/ _ \
|  _ <  __/ (_| | |  _  | (_| | |_  |  _|| |_| \__ \  __/
|_| \_\___|\__,_| |_| |_|\__,_|\__| |_|   \__,_|___/___|

  Red Hat Fuse (7.0.0.fuse-000191-redhat-1)
  http://www.redhat.com/products/jbossenterprisemiddleware/fuse/


Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit 'system:shutdown' to shutdown Karaf.
Hit '<ctrl-d>' or type 'logout' to disconnect shell from current session.

karaf@root()>
Copy to Clipboard Toggle word wrap

When you don’t provide the command argument to the ssh:ssh command, you are in the interactive mode: you have a complete remote console available, where you can type commands, etc.

You can also provide directly a command to execute using the command argument. For instance, to remotely shutdown a Apache Karaf instance: 

karaf@root()> ssh:ssh -p 8101 karaf@localhost system:shutdown -f
Connecting to host localhost on port 8101
Connected
Copy to Clipboard Toggle word wrap

As the ssh:ssh command is a pure SSH client, so it means that you can connect to a Unix OpenSSH daemon: 

karaf@root()> ssh:ssh user@localhost
Connecting to host localhost on port 22
Connecting to unknown server. Add this server to known hosts ? (y/n)
Storing the server key in known_hosts.
Agent authentication failed, falling back to password authentication.
Password: Connected
Last login: Sun Sep  8 19:21:12 2013
user@server:~$
Copy to Clipboard Toggle word wrap

15.1.2.3. Apache Karaf client
Copy link

The ssh:ssh command requires to be run into a running Apache Karaf console.

For commodity, the ssh:ssh command is "wrapped" as a standalone client: the bin/client Unix script (bin\client.bat on Windows). 

bin/client --help
{karaf} client
  -a [port]     specify the port to connect to
  -h [host]     specify the host to connect to
  -u [user]     specify the user name
  --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)
  -b            batch mode, specify multiple commands via standard input
  -f [file]     read commands from the specified file
  [commands]    commands to run
If no commands are specified, the client will be put in an interactive mode
Copy to Clipboard Toggle word wrap

For instance, to connect to local Apache Karaf instance (on the default SSHd server 8101 port), you can directly use bin/client Unix script (bin\client.bat on Windows) without any argument or option: 

bin/client
Logging in as karaf
343 [pool-2-thread-4] WARN org.apache.sshd.client.keyverifier.AcceptAllServerKeyVerifier - Server at /0.0.0.0:8101 presented unverified key:
Karaf started in 7s. Bundle stats: 239 active, 239 total

 ____          _   _   _       _     _____
|  _ \ ___  __| | | | | | __ _| |_  |  ___|   _ ___  ___
| |_) / _ \/ _` | | |_| |/ _` | __| | |_ | | | / __|/ _ \
|  _ <  __/ (_| | |  _  | (_| | |_  |  _|| |_| \__ \  __/
|_| \_\___|\__,_| |_| |_|\__,_|\__| |_|   \__,_|___/___|

  Red Hat Fuse (7.0.0.fuse-000191-redhat-1)
  http://www.redhat.com/products/jbossenterprisemiddleware/fuse/


Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit 'system:shutdown' to shutdown Karaf.
Hit '<ctrl-d>' or type 'logout' to disconnect shell from current session.

karaf@root()>
Copy to Clipboard Toggle word wrap

When you don’t provide the command argument to the bin/client Unix script (bin\client.bat on Windows), you are in the interactive mode: you have a complete remote console available, where you can type commands, etc.

You can also provide directly a command to execute using the command argument. For instance, to remotely shutdown a Apache Karaf instance: 

bin/client "system:shutdown -f"
Logging in as karaf
330 [pool-2-thread-3] WARN org.apache.sshd.client.keyverifier.AcceptAllServerKeyVerifier - Server at /0.0.0.0:8101 presented unverified key:
Copy to Clipboard Toggle word wrap

As the Apache Karaf client is a pure SSH client, you can use to connect to any SSHd daemon (like Unix OpenSSH daemon): 

bin/client -a 22 -h localhost -u user
Logging in as user
353 [pool-2-thread-2] WARN org.apache.sshd.client.keyverifier.AcceptAllServerKeyVerifier - Server at localhost/127.0.0.1:22 presented unverified key:
Password:
Welcome to Ubuntu 13.10 (GNU/Linux 3.11.0-13-generic x86_64)

 * Documentation:  https://help.ubuntu.com/

Last login: Tue Dec  3 18:18:31 2013 from localhost
Copy to Clipboard Toggle word wrap

15.1.2.4. Logout
Copy link

When you are connected to a remote Apache Karaf console, you can logout using:

  • using CTRL-D key binding. Note that CTRL-D just logout from the remote console in this case, it doesn’t shutdown the Apache Karaf instance (as CTRL-D does when used on a local console).
  • using shell:logout command (or simply logout)

15.1.3. Filsystem clients
Copy link

Apache Karaf SSHd server also provides complete fileystem access via SSH. For security reason, the available filesystem is limited to KARAF_BASE directory.

You can use this remote filesystem with any SCP/SFTP compliant clients.

15.1.3.1. Native SCP/SFTP clients
Copy link

On Unix, you can directly use scp command to download/upload files to the Apache Karaf filesystem. For instance, to retrieve the fuse.log file remotely: 

~$ scp -P 8101 karaf@localhost:/data/log/karaf.log .
Authenticated with partial success.
Authenticated with partial success.
Authenticated with partial success.
Password admin
Password:
fuse.log
Copy to Clipboard Toggle word wrap

As you have access to the complete KARAF_BASE directory, you can remotely change the configuration file in the etc folder, retrieve log files, populate the system folder.

On Windows, you can use WinSCP to access the Apache Karaf filesystem.

It’s probably easier to use a SFTP complient client.

For instance, on Unix system, you can use lftp or ncftp: 

$ lftp
lftp :~> open -u karaf sftp://localhost:8101
Password:
lftp karaf@localhost:~> ls
-rw-r--r--   1 jbonofre jbonofre    27754 Oct 26 10:50 LICENSE
-rw-r--r--   1 jbonofre jbonofre     1919 Dec  3 05:34 NOTICE
-rw-r--r--   1 jbonofre jbonofre     3933 Aug 18  2012 README
-rw-r--r--   1 jbonofre jbonofre   101041 Dec  3 05:34 RELEASE-NOTES
drwxr-xr-x   1 jbonofre jbonofre     4096 Dec  3 12:51 bin
drwxr-xr-x   1 jbonofre jbonofre     4096 Dec  3 18:57 data
drwxr-xr-x   1 jbonofre jbonofre     4096 Dec  3 12:51 demos
drwxr-xr-x   1 jbonofre jbonofre     4096 Dec  3 13:02 deploy
drwxr-xr-x   1 jbonofre jbonofre     4096 Dec  3 17:59 etc
drwxr-xr-x   1 jbonofre jbonofre     4096 Dec  3 13:02 instances
drwxr-xr-x   1 jbonofre jbonofre     4096 Dec  3 13:02 lib
-rw-r--r--   1 jbonofre jbonofre        0 Dec  3 13:02 lock
drwxr-xr-x   1 jbonofre jbonofre     4096 Dec  3 12:51 system
lftp karaf@localhost:/>
Copy to Clipboard Toggle word wrap

You can also use graphic client like filezilla, gftp, nautilus, etc.

On Windows, you can use filezilla, WinSCP, etc.

15.1.3.2. Apache Maven
Copy link

The Apache Karaf system folder is the Karaf repository, that use a Maven directory structure. It’s where Apache Karaf looks for the artifacts (bundles, features, kars, etc).

Using Apache Maven, you can populate the system folder using the deploy:deploy-file goal.

For instance, you want to add the Apache ServiceMix facebook4j OSGi bundle, you can do: 

mvn deploy:deploy-file -Dfile=org.apache.servicemix.bundles.facebook4j-2.0.2_1.jar -DgroupId=org.apache.servicemix.bundles -DartifactId=org.apache.servicemix.bundles.facebook4j -Dversion=2.0.2_1 -Dpackaging=jar -Durl=scp://localhost:8101/system
Copy to Clipboard Toggle word wrap

15.2. JMX MBeanServer
Copy link

Apache Karaf provides a JMX MBeanServer.

This MBeanServer is available remotely, using any JMX client like jconsole.

You can find details on the [Monitoring section|monitoring] of the user guide.

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat