Chapter 2. Starting and Stopping Apache Karaf
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:
2.1.2. Launching the runtime in console mode
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()>
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 16.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:
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.2. Stopping Apache Karaf
You can stop an instance of Apache Karaf either from within a console, or using a
2.2.1. Stopping an instance from a local console
If you launched the Karaf instance by running
fuse client, you can stop it by doing one of the following at the
- 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
Specifies the TCP port to use as the shutdown port. Setting this property to
-1disables the port. Default is
0(for a random port).Note
If you wanted to use the
bin/stopscript 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
Specifies the hostname to which the shutdown port is bound. This setting could be useful on a multi-homed host. Defaults to
If you wanted to use the
bin/stopscript 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
After the Karaf instance starts up, it writes the current shutdown port to the file specified by this property. The
stopscript reads the file specified by this property to discover the value of the current shutdown port. Defaults to
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.propertiesfile 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.propertiesfile. Alternatively, if
karaf.shutdown.commandis 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/stopscript 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
2.2.3. Stopping a remote instance
You can stop a container instance running on a remote host as described in Section 16.3, “Stopping a Remote Container”.