Chapter 2. Starting and Stopping Apache Karaf

download PDF


Apache Karaf provides simple command-line tools for starting and stopping the server.

2.1. Starting Apache Karaf

The default way to deploy the Apache Karaf runtime is to deploy it as a standalone server with an active console. You can also deploy the runtime as a background process without a console.

2.1.1. Setting up your environment

You can start the Karaf runtime directly from the bin subdirectory of your installation, without modifying your environment. However, if you want to start it in a different folder you need to add the bin directory of your Karaf installation to the PATH environment variable, as follows:


set PATH=%PATH%;InstallDir\bin


export PATH=$PATH,InstallDir/bin`

2.1.2. Launching the runtime in console mode

If you are launching the Karaf runtime from the installation directory use the following command:





If Karaf starts up correctly you should see the following on the console:

Red Hat Fuse starting up. Press Enter to open the shell now...
100% [========================================================================]

Karaf started in 8s. Bundle stats: 220 active, 220 total

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

  Fuse (7.x.x.fuse-xxxxxx-redhat-xxxxx)

Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.

Open a browser to http://localhost:8181/hawtio to access the management console

Hit '<ctrl-d>' or 'shutdown' to shutdown Red Hat Fuse.


Since version Fuse 6.2.1, launching in console mode creates two processes: the parent process ./bin/karaf, which is executing the Karaf console; and the child process, which is executing the Karaf server in a java JVM. The shutdown behaviour remains the same as before, however. That is, you can shut down the server from the console using either Ctrl-D or osgi:shutdown, which kills both processes.

2.1.3. Launching the runtime in server mode

Launching in server mode runs Apache Karaf in the background, without a local console. You would then connect to the running instance using a remote console. See Section 17.2, “Connecting and Disconnecting Remotely” for details.

To launch Karaf in server mode, run the following





2.1.4. Launching the runtime in client mode

In production environments you might want to have a runtime instance accessible using only a local console. In other words, you cannot connect to the runtime remotely through the SSH console port. You can do this by launching the runtime in client mode, using the following command:


bin\fuse.bat client


./bin/fuse client

Launching in client mode suppresses only the SSH console port (usually port 8101). Other Karaf server ports (for example, the JMX management RMI ports) are opened as normal.

2.1.5. Running Fuse in debug mode

Running Fuse in debug mode helps identify and resolve errors more efficiently. This option is disabled by default. When enabled, Fuse starts a JDWP socket on port 5005.

You have three approaches to run Fuse in debug mode. Use the Karaf environment variable

This approach enables the KARAF_DEBUG environment variable (=1), and then you start the container.

$ export KARAF_DEBUG=1
$ bin/start Run Fuse debug

This approach runs debug where the suspend option is set to n (no).

$ bin/fuse debug Run Fuse debugs

This approach runs debugs where the suspend option is set to y (yes).


Setting suspend to yes causes the JVM to pause just before running main() until a debugger is attached and then it resumes execution.

$ bin/fuse debugs

2.2. Stopping Apache Karaf

You can stop an instance of Apache Karaf either from within a console, or using a stop script.

2.2.1. Stopping an instance from a local console

If you launched the Karaf instance by running fuse or fuse client, you can stop it by doing one of the following at the karaf> prompt:

  • Type shutdown
  • Press Ctrl+D

2.2.2. Stopping an instance running in server mode

You can stop a locally running Karaf instance (root container), by invoking the stop(.bat) from the InstallDir/bin directory, as follows:





The shutdown mechanism invoked by the Karaf stop script is similar to the shutdown mechanism implemented in Apache Tomcat. The Karaf server opens a dedicated shutdown port (not the same as the SSH port) to receive the shutdown notification. By default, the shutdown port is chosen randomly, but you can configure it to use a specific port if you prefer.

You can optionally customize the shutdown port by setting the following properties in the InstallDir/etc/ file:


Specifies the TCP port to use as the shutdown port. Setting this property to -1 disables the port. Default is 0 (for a random port).


If you wanted to use the bin/stop script to shut down the Karaf server running on a remote host, you would need to set this property equal to the remote host’s shutdown port. But beware that this setting also affects the Karaf server located on the same host as the etc/ file.

Specifies the hostname to which the shutdown port is bound. This setting could be useful on a multi-homed host. Defaults to localhost.


If you wanted to use the bin/stop script to shut down the Karaf server running on a remote host, you would need to set this property to the hostname (or IP address) of the remote host. But beware that this setting also affects the Karaf server located on the same host as the etc/ file.

After the Karaf instance starts up, it writes the current shutdown port to the file specified by this property. The stop script reads the file specified by this property to discover the value of the current shutdown port. Defaults to ${}/port.

Specifies the UUID value that must be sent to the shutdown port in order to trigger shutdown. This provides an elementary level of security, as long as the UUID value is kept a secret. For example, the etc/ file could be read-protected to prevent this value from being read by ordinary users.

When Apache Karaf is started for the very first time, a random UUID value is automatically generated and this setting is written to the end of the etc/ file. Alternatively, if karaf.shutdown.command is already set, the Karaf server uses the pre-existing UUID value (which enables you to customize the UUID setting, if required).


If you wanted to use the bin/stop script to shut down the Karaf server running on a remote host, you would need to set this property to be equal to the value of the remote host’s karaf.shutdown.command. But beware that this setting also affects the Karaf server located on the same host as the etc/ file.

2.2.3. Stopping a remote instance

You can stop a container instance running on a remote host as described in Section 17.3, “Stopping a Remote Container”.

Red Hat logoGithubRedditYoutubeTwitter


Try, buy, & sell


About Red Hat Documentation

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

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.

© 2024 Red Hat, Inc.