Integration in the operating system: the Service Wrapper

In the previous chapter, we saw the different scripts and commands to start, stop, restart Apache Karaf.

Instead of using these commands and scripts, you can integrate Apache Karaf directly in your operating system service control.

Apache Karaf provides the "Service Wrapper". The service wrapper allows you to directly integrate Apache Karaf:

  • like a native Windows Service

  • like a Unix daemon process

The "Service Wrapper" correctly handles "user’s log outs" under Windows, service dependencies, and the ability to run services which interact with the desktop.

It also includes advanced fault detection software which monitors an application. The "Service Wrapper" is able to detect crashes, freezes, out of memory and other exception events, then automatically react by restarting Apache Karaf with a minimum of delay. It guarantees the maximum possible uptime of Apache Karaf.

Supported platforms

  • Windows 8, 7, 2008 R2, 2003, Vista (32 and 64 bits architecture)

  • Linux RedHat Enterprise Linux, Debian, CentOS, Fedora, Ubuntu (32 and 64 bits architecture)

  • FreeBSD 9.x, 8.x

  • AIX 5.x, 6.x, 7.x (Power architecture)

  • Solaris 8, 9, 10 (x86/Sparc, 32 and 64 bits architecture)

  • HP-UX 10.x, 11.x (32 and 64 bits architecture)

  • SGI Irix

  • MacOS X

Installation

Apache Karaf Service Wrapper is an optional feature. You have to install the "Service Wrapper" installer first.

In the console:

karaf@root()> feature:install service-wrapper

Now, you have the wrapper:install command, to "register" Apache Karaf as service/daemon on your system:

karaf@root()> wrapper:install --help
DESCRIPTION
        wrapper:install

        Install the container as a system service in the OS.

SYNTAX
        wrapper:install [options]

OPTIONS
        -d, --display
                The display name of the service.
                (defaults to karaf)
        --help
                Display this help message
        -s, --start-type
                Mode in which the service is installed. AUTO_START or DEMAND_START (Default: AUTO_START)
                (defaults to AUTO_START)
        -n, --name
                The service name that will be used when installing the service. (Default: karaf)
                (defaults to karaf)
        -D, --description
                The description of the service.
                (defaults to )

Installation

Karaf Wrapper is an optional feature. To install it, simply type:

karaf@root> feature:install wrapper

Once installed, wrapper feature will provide wrapper:install new command in the Karaf shell:

karaf@root> wrapper:install --help
DESCRIPTION
        wrapper:install

        Install the container as a system service in the OS.

SYNTAX
        wrapper:install [options]

OPTIONS
        -s, --start-type
                Mode in which the service is installed. AUTO_START or DEMAND_START (Default: AUTO_START)
                (defaults to AUTO_START)
        --help
                Display this help message
        -n, --name
                The service name that will be used when installing the service. (Default: karaf)
                (defaults to karaf)
        -d, --display
                The display name of the service.
        -D, --description
                The description of the service.
                (defaults to )

The wrapper:install command detects the running Operating Service and provide the service/daemon ready to be integrated in your system.

For instance, on a Ubuntu/Debian Linux system:

karaf@root()> wrapper:install
Creating file: /opt/apache-karaf-3.0.5/bin/karaf-wrapper
Creating file: /opt/apache-karaf-3.0.5/bin/karaf-service
Creating file: /opt/apache-karaf-3.0.5/etc/karaf-wrapper.conf
Creating file: /opt/apache-karaf-3.0.5/lib/libwrapper.so
Creating file: /opt/apache-karaf-3.0.5/lib/karaf-wrapper.jar
Creating file: /opt/apache-karaf-3.0.5/lib/karaf-wrapper-main.jar

Setup complete.  You may wish to tweak the JVM properties in the wrapper configuration file:
        /opt/apache-karaf-3.0.5/etc/karaf-wrapper.conf
before installing and starting the service.


Ubuntu/Debian Linux system detected:
  To install the service:
    $ ln -s /opt/apache-karaf-3.0.5/bin/karaf-service /etc/init.d/

  To start the service when the machine is rebooted:
    $ update-rc.d karaf-service defaults

  To disable starting the service when the machine is rebooted:
    $ update-rc.d -f karaf-service remove

  To start the service:
    $ /etc/init.d/karaf-service start

  To stop the service:
    $ /etc/init.d/karaf-service stop

  To uninstall the service :
    $ rm /etc/init.d/karaf-service

You can note that wrapper:install command detected the running operating system ("Ubuntu/Debian Linux system detected").

You have a complete explanation and list of system commands to perform to integrate Apache Karaf in your systemV:

ln -s /opt/apache-karaf-3.0.5/bin/karaf-service /etc/init.d/
update-rc.d karaf-service defaults

Karaf also supports systemd service, so you can use systemctl instead of SystemV based service:

systemctl enable /opt/apache-karaf-3.0.5/bin/karaf.service

This will enable Karaf at system boot.

Uninstall

The wrapper:install provides the system commands to perform to uninstall the service/daemon).

For instance, on Ubuntu/Debian, to uninstall the Apache Karaf service, you have to remove the karaf-service script from the runlevel scripts:

rm /etc/init.d/karaf-service

If you prefered the systemd service instead of systemV:

systemctl disable karaf

You can remove the "Wrapper Service" installer after that:

karaf@root()> feature:uninstall service-wrapper

Note for MacOS users

On MacOS you can install the service for an user or for the system.

If you want to add bin/org.apache.karaf.KARAF as user service move this file into ~/Library/LaunchAgents/:

mv bin/org.apache.karaf.KARAF.plist ~/Library/LaunchAgents/

If you want to add org.apache.karaf.KARAF as system service move this into /Library/LaunchDaemons:

sudo mv bin/org.apache.karaf.KARAF.plist /Library/LaunchDaemons/

Change owner and rights:

sudo chown root:wheel /Library/LaunchDaemons/org.apache.karaf.KARAF.plist
sudo chmod u=rw,g=r,o=r /Library/LaunchDaemons/org.apache.karaf.KARAF.plist

You can test your service:

launchctl load ~/Library/LaunchAgents/org.apache.karaf.KARAF.plist
launchctl start org.apache.karaf.KARAF
launchctl stop org.apache.karaf.KARAF

Finally, after restart your session or system you can use launchctl command to start and stop your service.

If you want to remove the service call:

launchctl remove org.apache.karaf.KARAF

Configuration

When using scripts in the Apache Karaf bin folder, you can using bin/setenv Unix script (bin\setenv.bat on Windows) as described in the [Start, stop, restart, connect|start-stop] section of the documentation.

Note

The bin/setenv Unix script (bin\setenv.bat on Windows) is not used by the Apache Karaf Service Wrapper.

To configure Apache Karaf started by the Service Wrapper, you have to tune the etc/karaf-wrapper.conf file. If you provided the name option to the wrapper:install command, the file is etc/karaf-yourname.conf.

In this file, you can configure the different environment variables used by Apache Karaf. The Service Wrapper installer automatically populate these variables for you during the installation (using wrapper:install command). For instance:

  • set.default.JAVA_HOME is the JAVA_HOME used to start Apache Karaf (populated during Service Wrapper installation).

  • set.default.KARAF_HOME is the location of your Apache Karaf installation (populated during Service Wrapper installation).

  • set.default.KARAF_BASE is the location of your Apache Karaf installation (populated during Service Wrapper installation).

  • set.default.KARAF_DATA is the location of the Apache Karaf data folder (populated during Service Wrapper installation).

  • set.default.KARAF_ETC is the location of the Apache Karaf etc folder (populated during Service Wrapper installation).

  • wrapper.java.additional is used to pass additional arguments to the Java command, indexed by the argument number. The next index to use is 11.

  • wrapper.java.initmemory is the initial JVM memory size (the -Xms). It’s not set by default (JVM default).

  • wrapper.java.maxmemory is the maximum JVM memory size (the -Xmx). It’s set to 512M by default.

  • wrapper.logfile is the location of the Service Wrapper log file. It’s set to %KARAF_DATA%/log/wrapper.log by default.

  • wrapper.logfile.loglevel is the Service Wrapper log level. It’s set to INFO by default.

  • wrapper.logfile.maxsize is the Service Wrapper log file maximum size (before rotation). It’s set to 10m (10MB) by default.

  • wrapper.logfile.maxfiles is the number of Service Wrapper log files created (and rotated). It’s set to 5 by default.

  • wrapper.syslog.loglevel is the integration with Unix syslog daemon. By default, it’s set to none meaning disabled.

  • wrapper.ntservice.name is Windows service specific and defines the Windows service name. It’s set to the name option of the wrapper:install command, or karaf by default.

  • wrapper.ntservice.displayname is Windows service specific and defines the Windows service display name. It’s set to the display option of the wrapper:install command, or karaf by default.

  • wrapper.ntservice.description is Windows service specific and defines the Windows service description. It’s set to the description option of the wrapper:install command, or empty by default.

  • wrapper.ntservice.starttype is Windows service specific and defines if the Windows service is started automatically with the service, or just on demand. It’s set to AUTO_START by default, and could be switch to DEMAND_START.

This is a example of generated etc/karaf-wrapper.conf 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.
# ------------------------------------------------------------------------

#********************************************************************
# Wrapper Properties
#********************************************************************
set.default.JAVA_HOME=/opt/jdk/1.7.0_21
set.default.KARAF_HOME=/home/jbonofre/workspace/karaf/karaf/assemblies/apache-karaf/target/apache-karaf-3.0.5-SNAPSHOT
set.default.KARAF_BASE=/home/jbonofre/workspace/karaf/karaf/assemblies/apache-karaf/target/apache-karaf-3.0.5-SNAPSHOT
set.default.KARAF_DATA=/home/jbonofre/workspace/karaf/karaf/assemblies/apache-karaf/target/apache-karaf-3.0.5-SNAPSHOT/data
set.default.KARAF_ETC=/home/jbonofre/workspace/karaf/karaf/assemblies/apache-karaf/target/apache-karaf-3.0.5-SNAPSHOT/etc

# Java Application
wrapper.working.dir=%KARAF_BASE%
wrapper.java.command=%JAVA_HOME%/bin/java
wrapper.java.mainclass=org.apache.karaf.wrapper.internal.Main
wrapper.java.classpath.1=%KARAF_HOME%/lib/karaf-wrapper.jar
wrapper.java.classpath.2=%KARAF_HOME%/lib/karaf.jar
wrapper.java.classpath.3=%KARAF_HOME%/lib/karaf-jaas-boot.jar
wrapper.java.classpath.4=%KARAF_HOME%/lib/karaf-wrapper-main.jar
wrapper.java.classpath.5=%KARAF_HOME%/lib/karaf-org.osgi.core.jar
wrapper.java.library.path.1=%KARAF_HOME%/lib/

# Application Parameters.  Add parameters as needed starting from 1
#wrapper.app.parameter.1=

# JVM Parameters
# note that n is the parameter number starting from 1.
wrapper.java.additional.1=-Dkaraf.home=%KARAF_HOME%
wrapper.java.additional.2=-Dkaraf.base=%KARAF_BASE%
wrapper.java.additional.3=-Dkaraf.data=%KARAF_DATA%
wrapper.java.additional.4=-Dkaraf.etc=%KARAF_ETC%
wrapper.java.additional.5=-Dcom.sun.management.jmxremote
wrapper.java.additional.6=-Dkaraf.startLocalConsole=false
wrapper.java.additional.7=-Dkaraf.startRemoteShell=true
wrapper.java.additional.8=-Djava.endorsed.dirs=%JAVA_HOME%/jre/lib/endorsed:%JAVA_HOME%/lib/endorsed:%KARAF_HOME%/lib/endorsed
wrapper.java.additional.9=-Djava.ext.dirs=%JAVA_HOME%/jre/lib/ext:%JAVA_HOME%/lib/ext:%KARAF_HOME%/lib/ext

# Uncomment to enable jmx
#wrapper.java.additional.n=-Dcom.sun.management.jmxremote.port=1616
#wrapper.java.additional.n=-Dcom.sun.management.jmxremote.authenticate=false
#wrapper.java.additional.n=-Dcom.sun.management.jmxremote.ssl=false

# Uncomment to enable YourKit profiling
#wrapper.java.additional.n=-Xrunyjpagent

# Uncomment to enable remote debugging
#wrapper.java.additional.n=-Xdebug -Xnoagent -Djava.compiler=NONE
#wrapper.java.additional.n=-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005

# Initial Java Heap Size (in MB)
#wrapper.java.initmemory=3

# Maximum Java Heap Size (in MB)
wrapper.java.maxmemory=512


#********************************************************************
# Wrapper Logging Properties
#********************************************************************
# Format of output for the console.  (See docs for formats)
wrapper.console.format=PM

# Log Level for console output.  (See docs for log levels)
wrapper.console.loglevel=INFO

# Log file to use for wrapper output logging.
wrapper.logfile=%KARAF_DATA%/log/wrapper.log

# Format of output for the log file.  (See docs for formats)
wrapper.logfile.format=LPTM

# Log Level for log file output.  (See docs for log levels)
wrapper.logfile.loglevel=INFO

# Maximum size that the log file will be allowed to grow to before
#  the log is rolled. Size is specified in bytes.  The default value
#  of 0, disables log rolling.  May abbreviate with the 'k' (kb) or
#  'm' (mb) suffix.  For example: 10m = 10 megabytes.
wrapper.logfile.maxsize=10m

# Maximum number of rolled log files which will be allowed before old
#  files are deleted.  The default value of 0 implies no limit.
wrapper.logfile.maxfiles=5

# Log Level for sys/event log output.  (See docs for log levels)
wrapper.syslog.loglevel=NONE

#********************************************************************
# Wrapper Windows Properties
#********************************************************************
# Title to use when running as a console
wrapper.console.title=karaf

#********************************************************************
# Wrapper Windows NT/2000/XP Service Properties
#********************************************************************
# WARNING - Do not modify any of these properties when an application
#  using this configuration file has been installed as a service.
#  Please uninstall the service before modifying this section.  The
#  service can then be reinstalled.

# Name of the service
wrapper.ntservice.name=karaf

# Display name of the service
wrapper.ntservice.displayname=karaf

# Description of the service
wrapper.ntservice.description=

# Service dependencies.  Add dependencies as needed starting from 1
wrapper.ntservice.dependency.1=

# Mode in which the service is installed.  AUTO_START or DEMAND_START
wrapper.ntservice.starttype=AUTO_START

# Allow the service to interact with the desktop.
wrapper.ntservice.interactive=false
systemd

The Karaf service wrapper also support Linux systemd service.