Apache Karaf Overview

Apache Karaf is a OSGi-based runtime which provides a lightweight container onto which various components and applications can be deployed.

Apache Karaf uses either Apache Felix Framework or Eclipse Equinox OSGi frameworks, and provide additional features on top of the framework.

Apache Karaf can be scaled from a very lightweight container to a fully features enterprise service: it's a very flexible and extensible container, covering all the major needs.

Here is a short list of provided features:

Hot deployment: simply drop a file in the deploy directory, Apache Karaf will detect the type of the file and
try to deploy it.
Complete Console: Apache Karaf provides a complete Unix-like console where you can completely manage the container.
Dynamic Configuration: Apache Karaf provides a set of command dedicated for the management of the configuration files.
All configuration files are centralized in the etc folder. Any change in a configuration file is taken on the fly.
Advanced Logging System: Apache Karaf supports a large set of Logging framework (slf4j, log4j, etc). Whatever the
logging framework you use, Apache Karaf centralizes the configuration in one file.
Provisioning: Apache Karaf supports a large set of URL where you can install your application (Maven repository, HTTP,
file, etc). It also provides the concept of "Karaf Feature" which is a way to describe your application.
Management: Apache Karaf is an enterprise-ready container, providing a lot of management indicators and operations
via JMX.
Remote: Apache Karaf embeds an SSHd server allowing you to use the console remotely. The management layer is also
accessible remotely.
Security: Apache Karaf provides a complete security framework (based on JAAS), and providing RBAC (Role-Based Access
Control) mechanism for console and JMX.
Instances: multiple instances of Apache Karaf can be managed directly from a main instance (root).
OSGi frameworks: Apache Karaf is not tight to one OSGi framework. By default, Apache Karaf runs with Apache Felix
Framework, but you can easily switch to Equinox (just change on property in a configuration file).

Installation

Apache Karaf is a lightweight container, very easy to install and administrate, on both Unix and Windows platforms.

Requirements

Hardware:

50 MB of free disk space for the Apache Karaf binary distribution.

Operating Systems:

Windows: Windows 8, Windows 7, Windows 2003, Windows Vista, Windows XP SP2, Windows 2000.
Unix: RedHat Enterprise Linux, Debian, SuSE/OpenSuSE, CentOS, Fedora, Ubuntu, MacOS, AIX, HP-UX, Solaris, any Unix platform that supports Java.

Environment:

Java SE 1.7.x or greater (http://www.oracle.com/technetwork/java/javase/).
The JAVA_HOME environment variable must be set to the directory where the Java runtime is installed,

Installation on Windows platform

NB: the JAVA_HOME environment variable has to be correctly defined. To accomplish that, press Windows key and Break key together, switch to "Advanced" tab and click on "Environment Variables".

From a browser, navigate to http://karaf.apache.org/index/community/download.html.
Download Apache Karaf binary distribution in the zip format: apache-karaf-3.0.4.zip.
Extract the files from the zip file into a directory of your choice (it's the KARAF_HOME.
NB: remember the restrictions concerning illegal characters in Java paths, e.g. !, % etc.
Apache Karaf is now installed.

Installation on Unix platforms

NB: the JAVA_HOME environment variable has to be correctly defined. Check the current value using

echo $JAVA_HOME

If it's not correct, fix it using:

export JAVA_HOME=....

From a browser, navigate to http://karaf.apache.org/index/community/download.html.
Download Apache Karaf binary distribution in the tar.gz format: apache-karaf-3.0.4.tar.gz.
Extract the files from the tar.gz file into a directory of your choice (it's the KARAF_HOME). For example:
```
gunzip apache-karaf-3.0.4.tar.gz
tar xvf apache-karaf-3.0.4.tar
```
NB: remember the restrictions concerning illegal characters in Java paths, e.g. !, % etc.
Apache Karaf is now installed.

Directory structure

The directory layout of a Karaf installation is as follows:

/bin: control scripts to start, stop, login, ...
/etc: configuration files
/data: working directory
- /cache: OSGi framework bundle cache
- /generated-bundles: temporary folder used by the deployers
- /log: log files
/deploy: hot deploy directory
/instances: directory containing instances
/lib: contains the bootstrap libraries
- /lib/ext: directory for JRE extensions
- /lib/endorsed: directory for endorsed libraries
/system: OSGi bundles repository, laid out as a Maven 2 repository

Start the server

Open a command line console and change the directory to <KARAF_HOME>.

To start the server, run the following command in Windows:

bin\karaf.bat

respectively on Unix:

bin/karaf

You should see the following information on the command line console:

        __ __                  ____
       / //_/____ __________ _/ __/
      / ,<  / __ `/ ___/ __ `/ /_
     / /| |/ /_/ / /  / /_/ / __/
    /_/ |_|\__,_/_/   \__,_/_/

  Apache Karaf (3.0.4)

Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit '<ctrl-d>' or type 'system:shutdown' or 'logout' to shutdown Karaf.

karaf@root()>

Service Wrapper

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

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 )

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-3.0.4/bin/KARAF-wrapper
Creating file: /home/onofreje/apache-karaf-3.0.4/bin/KARAF-service
Creating file: /home/onofreje/apache-karaf-3.0.4/etc/KARAF-wrapper.conf
Creating file: /home/onofreje/apache-karaf-3.0.4/lib/libwrapper.so
Creating file: /home/onofreje/apache-karaf-3.0.4/lib/karaf-wrapper.jar
Creating file: /home/onofreje/apache-karaf-3.0.4/lib/karaf-wrapper-main.jar

Setup complete. You may wish to tweak the JVM properties in the wrapper configuration file:
/home/onofreje/apache-karaf-3.0.4/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-3.0.4/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-3.0.4/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

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, Connection section of the documentation.

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, orkaraf by default.
wrapper.ntservice.displayname is Windows service specific and defines the Windows service display name. It's set to the display option of thewrapper: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 thewrapper: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:
#********************************************************************
# 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
.......................
........................
.........................
# 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

Reference

http://karaf.apache.org/

Apache and Java Explorations

Saturday 6 February 2016

Apache Karaf 3.x