Service Wrapper

Introduction

The Karaf Wrapper (for service wrapper) makes it possible to install Karaf as a Windows Service. Likewise, the scripts shipped with Karaf also make it very easy to install Karaf as a daemon process on Unix systems.

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

Supported platforms

The following platforms are supported by the Karaf Wrapper:

• AIX
• FreeBSD
• HP-UX, 32-bit and 64-bit versions
• SGI Irix
• Linux kernels 2.2.x, 2.4.x, 2.6.x. Known to work with Debian, Ubuntu, and Red Hat, but should work with any distribution. Currently supported on both 32-bit and 64-bit x86, Itanium, and PPC systems.
• Macintosh OS X
• Sun OS, Solaris 9 and 10. Currently supported on both 32-bit and 64-bit sparc, and x86 systems.
• Windows - Windows 2000, XP, 2003, Vista, 2008 and Windows 7. Currently supported on both 32-bit and 64-bit x86 and Itanium systems. Also known to run on Windows 98 and ME, however due the lack of support for services in the OS, the Wrapper can be run only in console mode.

Installation

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

karaf@root> features: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 )

Using wrapper:install, you can install Karaf as a service.

For instance, to register Karaf as a service (depending of the running OS), in automatic start mode, simply type:

karaf@root> wrapper:install -s AUTO_START -n KARAF -d Karaf -D "Karaf Service"

For instance, on Linux, wrapper:install command will do:

karaf@root> wrapper:install -s AUTO_START -n KARAF -d Karaf -D "Karaf Service"
Creating file: /home/onofreje/apache-karaf-2.1.3/bin/KARAF-wrapper
Creating file: /home/onofreje/apache-karaf-2.1.3/bin/KARAF-service
Creating file: /home/onofreje/apache-karaf-2.1.3/etc/KARAF-wrapper.conf
Creating file: /home/onofreje/apache-karaf-2.1.3/lib/libwrapper.so
Creating file: /home/onofreje/apache-karaf-2.1.3/lib/karaf-wrapper.jar
Creating file: /home/onofreje/apache-karaf-2.1.3/lib/karaf-wrapper-main.jar

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

The way the service is installed depends upon your flavor of Linux.

On Redhat/Fedora/CentOS Systems:
  To install the service:
    $ ln -s /home/onofreje/apache-karaf-2.1.3/bin/KARAF-service /etc/init.d/
    $ chkconfig KARAF-service --add

  To start the service when the machine is rebooted:
    $ chkconfig KARAF-service on

  To disable starting the service when the machine is rebooted:
    $ chkconfig KARAF-service off

  To start the service:
    $ service KARAF-service start

  To stop the service:
    $ service KARAF-service stop

  To uninstall the service :
    $ chkconfig KARAF-service --del
    $ rm /etc/init.d/KARAF-service

On Ubuntu/Debian Systems:
  To install the service:
    $ ln -s /home/onofreje/apache-karaf-2.1.3/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

Configuration Hints

By default, the wrapper sets the JAVA_HOME in etc/karaf-wrapper.conf file. However, the bin/karaf-service script uses java. If required, you have to define the JAVA_HOME in this bin/karaf-service script.

If you need to append parameters to the "java" invoke (like memory configurations) you add those in the KARAF-wrapper file using "wrapper.java.additional.n=PARAMETER" where "n" is the number of the additional config (typically you simply look for the last entry and use n+1) and PARAMETER is any JVM parameter you would like to append, such as "-XX:MaxPermSize=1024m".