Added: karaf/site/production/manual/latest/wrapper.html URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/wrapper.html?rev=1741445&view=auto ============================================================================== --- karaf/site/production/manual/latest/wrapper.html (added) +++ karaf/site/production/manual/latest/wrapper.html Thu Apr 28 15:03:08 2016 @@ -0,0 +1,1050 @@ + + + + + + + +Integration in the operating system: the Service Wrapper + + + + + + +
+
+

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-4.0.0/bin/karaf-wrapper
+Creating file: /opt/apache-karaf-4.0.0/bin/karaf-service
+Creating file: /opt/apache-karaf-4.0.0/etc/karaf-wrapper.conf
+Creating missing directory: /opt/apache-karaf-4.0.0/lib/wrapper
+Creating file: /opt/apache-karaf-4.0.0/lib/wrapper/libwrapper.so
+Creating file: /opt/apache-karaf-4.0.0/lib/wrapper/karaf-wrapper.jar
+Creating file: /opt/apache-karaf-4.0.0/lib/wrapper/karaf-wrapper-main.jar
+
+Setup complete.  You may wish to tweak the JVM properties in the wrapper configuration file:
+        /opt/apache-karaf-4.0.0/etc/karaf-wrapper.conf
+before installing and starting the service.
+
+
+Ubuntu/Debian Linux system detected:
+  To install the service:
+    $ ln -s /opt/apache-karaf-4.0.0/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
+
+
+
+ + + + + +
+
Note
+
+
+

You can install the wrapper without starting Karaf using bin/shell wrapper:install command.

+
+
+
+
+

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-4.0.0/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-4.0.2/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 preferred 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=/opt/apache-karaf-4.0.0
+set.default.KARAF_BASE=/opt/apache-karaf-4.0.0
+set.default.KARAF_DATA=/opt/apache-karaf-4.0.0/data
+set.default.KARAF_ETC=/opt/apache-karaf-4.0.0/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
+
+
+
+
+
+ + + \ No newline at end of file