Chapter 2. Starting and Stopping Apache Karaf

Abstract

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:

Windows

set PATH=%PATH%;InstallDir\bin

Linux/UNIX

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:

Windows

bin\fuse.bat

Linux/UNIX

./bin/fuse

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)
  http://www.redhat.com/products/jbossenterprisemiddleware/fuse/

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.

karaf@root()>
Note

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

Windows

bin\start.bat

Linux/UNIX

./bin/start

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:

Windows

bin\fuse.bat client

Linux/UNIX

./bin/fuse client
Note

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.

2.1.5.1. 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

2.1.5.2. Run Fuse debug

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

$ bin/fuse debug

2.1.5.3. Run Fuse debugs

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

Note

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:

Windows

bin\stop.bat

Linux/UNIX

./bin/stop

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/config.properties file:

karaf.shutdown.port

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).

Note

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/config.properties file.

karaf.shutdown.host

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

Note

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/config.properties file.

karaf.shutdown.port.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 ${karaf.data}/port.
karaf.shutdown.command

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/config.properties 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/config.properties 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).

Note

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/config.properties 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”.