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()>
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
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).
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.portSpecifies the TCP port to use as the shutdown port. Setting this property to
-1disables the port. Default is0(for a random port).NoteIf 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 theetc/config.propertiesfile.karaf.shutdown.hostSpecifies the hostname to which the shutdown port is bound. This setting could be useful on a multi-homed host. Defaults to
localhost.NoteIf 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 theetc/config.propertiesfile.karaf.shutdown.port.file-
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${karaf.data}/port. karaf.shutdown.commandSpecifies 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, ifkaraf.shutdown.commandis already set, the Karaf server uses the pre-existing UUID value (which enables you to customize the UUID setting, if required).NoteIf 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’skaraf.shutdown.command. But beware that this setting also affects the Karaf server located on the same host as theetc/config.propertiesfile.
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”.
