karaf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jbono...@apache.org
Subject svn commit: r1546556 - in /karaf/trunk/manual/src/main/webapp/users-guide: index.conf wrapper.conf
Date Fri, 29 Nov 2013 13:22:35 GMT
Author: jbonofre
Date: Fri Nov 29 13:22:35 2013
New Revision: 1546556

URL: http://svn.apache.org/r1546556
Log:
[KARAF-2511] Review the Service Wrapper page of the documentation

Modified:
    karaf/trunk/manual/src/main/webapp/users-guide/index.conf
    karaf/trunk/manual/src/main/webapp/users-guide/wrapper.conf

Modified: karaf/trunk/manual/src/main/webapp/users-guide/index.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/index.conf?rev=1546556&r1=1546555&r2=1546556&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/index.conf (original)
+++ karaf/trunk/manual/src/main/webapp/users-guide/index.conf Fri Nov 29 13:22:35 2013
@@ -3,7 +3,7 @@ h1. Karaf Users Guide
 * [Installation|installation]
 * [Directory Structure|directory-structure]
 * [Start, stop, restart, connect|start-stop]
-* [Service Wrapper|wrapper]
+* [Integration in the operating system: the Service Wrapper|wrapper]
 * [Configuration|configuration]
 * [Using the console|using-console]
 * [Web console|web-console]

Modified: karaf/trunk/manual/src/main/webapp/users-guide/wrapper.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/wrapper.conf?rev=1546556&r1=1546555&r2=1546556&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/wrapper.conf (original)
+++ karaf/trunk/manual/src/main/webapp/users-guide/wrapper.conf Fri Nov 29 13:22:35 2013
@@ -1,22 +1,69 @@
-h1. Service Wrapper
+h1. Integration in the operating system: the Service Wrapper
 
-h2. Introduction
+In the previous chapter, we saw the different scripts and commands to start, stop, restart
Apache Karaf.
 
-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.
+Instead of using these commands and scripts, you can integrate Apache Karaf directly in your
operating system service control.
 
-The Wrapper correctly handles "user's log outs" under Windows, service dependencies, and
the ability to run services which interact with the desktop.
+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.
 
 h2. Supported platforms
 
-The following platforms are supported by the Karaf Wrapper:
-* AIX
-* FreeBSD
-* HP-UX, 32-bit and 64-bit versions
+* 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
-* 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.
+* MacOS X
+
+h2. Installation
+
+Apache Karaf Service Wrapper is an optional feature. You have to install the "Service Wrapper"
installer first.
+
+In the console:
+
+{code}
+karaf@root()> feature:install service-wrapper
+{code}
+
+Now, you have the {{wrapper:install}} command, to "register" Apache Karaf as service/daemon
on your system:
+
+{code}
+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 )
+{code}
 
 h2. Installation
 
@@ -54,106 +101,276 @@ OPTIONS
                 (defaults to )
 {code}
 
-Using {{wrapper:install}}, you can install Karaf as a service.
+The {{wrapper:install}} command detects the running Operating Service and provide the service/daemon
ready to be integrated in your system.
 
-For instance, to register Karaf as a service (depending of the running OS), in automatic
start mode, simply type:
+For instance, on a Ubuntu/Debian Linux system:
 
 {code}
-karaf@root> wrapper:install -s AUTO_START -n KARAF -d Karaf -D "Karaf Service"
-{code}
-
-For instance, on Linux, {{wrapper:install}} command will do:
-
-{code}
-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
+karaf@root()> wrapper:install
+Creating file: /opt/apache-karaf-3.0.0/bin/karaf-wrapper
+Creating file: /opt/apache-karaf-3.0.0/bin/karaf-service
+Creating file: /opt/apache-karaf-3.0.0/etc/karaf-wrapper.conf
+Creating file: /opt/apache-karaf-3.0.0/lib/libwrapper.so
+Creating file: /opt/apache-karaf-3.0.0/lib/karaf-wrapper.jar
+Creating file: /opt/apache-karaf-3.0.0/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
+        /opt/apache-karaf-3.0.0/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:
+Ubuntu/Debian Linux system detected:
   To install the service:
-    $ ln -s /home/onofreje/apache-karaf-2.1.3/bin/KARAF-service /etc/init.d/
-    $ chkconfig KARAF-service --add
+    $ ln -s /opt/apache-karaf-3.0.0/bin/karaf-service /etc/init.d/
 
   To start the service when the machine is rebooted:
-    $ chkconfig KARAF-service on
+    $ update-rc.d karaf-service defaults
 
   To disable starting the service when the machine is rebooted:
-    $ chkconfig KARAF-service off
+    $ update-rc.d -f karaf-service remove
 
   To start the service:
-    $ service KARAF-service start
+    $ /etc/init.d/karaf-service start
 
   To stop the service:
-    $ service KARAF-service stop
+    $ /etc/init.d/karaf-service stop
 
   To uninstall the service :
-    $ chkconfig KARAF-service --del
-    $ rm /etc/init.d/KARAF-service
+    $ 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/
+{code}
 
-  To start the service when the machine is rebooted:
-    $ update-rc.d KARAF-service defaults
+You can note that {{wrapper:install}} command detected the running operating system ("Ubuntu/Debian
Linux system detected").
 
-  To disable starting the service when the machine is rebooted:
-    $ update-rc.d -f KARAF-service remove
+You have a complete explanation and list of system commands to perform to integrate Apache
Karaf in your system:
 
-  To start the service:
-    $ /etc/init.d/KARAF-service start
+{code}
+ln -s /opt/apache-karaf-3.0.0/bin/karaf-service /etc/init.d/
+update-rc.d karaf-service defaults
+{code}
 
-  To stop the service:
-    $ /etc/init.d/KARAF-service stop
+h2. Uninstall
 
-  To uninstall the service :
-    $ rm /etc/init.d/KARAF-service
+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:
+
+{code}
+rm /etc/init.d/karaf-service
+{code}
+
+You can remove the "Wrapper Service" installer after that:
+
+{code}
+karaf@root()> feature:uninstall service-wrapper
 {code}
 
+h2. Note for MacOS users
+
 On MacOS you can install the service for an user or for the system.
 
-to add bin/org.apache.karaf.KARAF as user service move this file into ~/Library/LaunchAgents/
+If you want to add bin/org.apache.karaf.KARAF as user service move this file into ~/Library/LaunchAgents/:
+
 {code}
-> mv bin/org.apache.karaf.KARAF.plist ~/Library/LaunchAgents/
+mv bin/org.apache.karaf.KARAF.plist ~/Library/LaunchAgents/
 {code}
 
-to add org.apache.karaf.KARAF as system service move this into /Library/LaunchDaemons
+If you want to add org.apache.karaf.KARAF as system service move this into /Library/LaunchDaemons:
+
 {code}
-> sudo mv bin/org.apache.karaf.KARAF.plist /Library/LaunchDaemons/
+sudo mv bin/org.apache.karaf.KARAF.plist /Library/LaunchDaemons/
 {code}
-change owner and rights
+
+Change owner and rights:
+
 {code}
-> 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
+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
 {code}
 
-test your service
+You can test your service:
+
 {code}
-> launchctl load ~/Library/LaunchAgents/org.apache.karaf.KARAF.plist
-> launchctl start org.apache.karaf.KARAF
-> launchctl stop org.apache.karaf.KARAF
+launchctl load ~/Library/LaunchAgents/org.apache.karaf.KARAF.plist
+launchctl start org.apache.karaf.KARAF
+launchctl stop org.apache.karaf.KARAF
 {code}
 
-after restart your session or system
-you can use launchctl command to start and stop your service
+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:
 
-for removing the service call
 {code}
-> launchctl remove org.apache.karaf.KARAF
+launchctl remove org.apache.karaf.KARAF
+{code}
+
+h2. 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.
+
+{warning:title=Warning}
+The {{bin/setenv}} Unix script ({{bin\setenv.bat}} on Windows) is not used by the Apache
Karaf Service Wrapper.
+{warning}
+
+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:
+
 {code}
+# ------------------------------------------------------------------------
+# 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.
+# ------------------------------------------------------------------------
 
-h2. Configuration Hints
+#********************************************************************
+# 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.0-SNAPSHOT
+set.default.KARAF_BASE=/home/jbonofre/workspace/karaf/karaf/assemblies/apache-karaf/target/apache-karaf-3.0.0-SNAPSHOT
+set.default.KARAF_DATA=/home/jbonofre/workspace/karaf/karaf/assemblies/apache-karaf/target/apache-karaf-3.0.0-SNAPSHOT/data
+set.default.KARAF_ETC=/home/jbonofre/workspace/karaf/karaf/assemblies/apache-karaf/target/apache-karaf-3.0.0-SNAPSHOT/etc
 
-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.
+# 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-jmx-boot.jar
+wrapper.java.classpath.4=%KARAF_HOME%/lib/karaf-jaas-boot.jar
+wrapper.java.classpath.5=%KARAF_HOME%/lib/karaf-wrapper-main.jar
+wrapper.java.classpath.6=%KARAF_HOME%/lib/karaf-org.osgi.core.jar
+wrapper.java.library.path.1=%KARAF_HOME%/lib/
 
-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".
+# 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=-Djavax.management.builder.initial=org.apache.karaf.management.boot.KarafMBeanServerBuilder
+wrapper.java.additional.7=-Dkaraf.startLocalConsole=false
+wrapper.java.additional.8=-Dkaraf.startRemoteShell=true
+wrapper.java.additional.9=-Djava.endorsed.dirs=%JAVA_HOME%/jre/lib/endorsed:%JAVA_HOME%/lib/endorsed:%KARAF_HOME%/lib/endorsed
+wrapper.java.additional.10=-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
+{code}



Mime
View raw message