Repository: karaf
Updated Branches:
  refs/heads/karaf-4.0.x 89c575ca8 -> 24f753796


[KARAF-4703] Document system scripts (present in bin/contrib)


Project: http://git-wip-us.apache.org/repos/asf/karaf/repo
Commit: http://git-wip-us.apache.org/repos/asf/karaf/commit/24f75379
Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/24f75379
Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/24f75379

Branch: refs/heads/karaf-4.0.x
Commit: 24f753796fef1d85813163f3d28033a12fd6407b
Parents: 89c575c
Author: lburgazzoli <lburgazz...@gmail.com>
Authored: Fri Sep 9 17:26:58 2016 +0200
Committer: Jean-Baptiste Onofré <jbono...@apache.org>
Committed: Thu Sep 15 12:57:03 2016 +0200

----------------------------------------------------------------------
 manual/src/main/asciidoc/index.adoc             |   4 +-
 .../asciidoc/user-guide/os-integration.adoc     | 505 +++++++++++++++++++
 .../src/main/asciidoc/user-guide/wrapper.adoc   | 409 ---------------
 3 files changed, 507 insertions(+), 411 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/karaf/blob/24f75379/manual/src/main/asciidoc/index.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/index.adoc 
b/manual/src/main/asciidoc/index.adoc
index 4e37947..9348243 100644
--- a/manual/src/main/asciidoc/index.adoc
+++ b/manual/src/main/asciidoc/index.adoc
@@ -36,7 +36,7 @@ include::user-guide/directory-structure.adoc[]
 
 include::user-guide/start-stop.adoc[]
 
-include::user-guide/wrapper.adoc[]
+include::user-guide/os-integration.adoc[]
 
 include::user-guide/console.adoc[]
 
@@ -128,4 +128,4 @@ include::developer-guide/debugging.adoc[]
 
 include::developer-guide/writing-tests.adoc[]
 
-include::developer-guide/github-contributions.adoc[]
\ No newline at end of file
+include::developer-guide/github-contributions.adoc[]

http://git-wip-us.apache.org/repos/asf/karaf/blob/24f75379/manual/src/main/asciidoc/user-guide/os-integration.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/user-guide/os-integration.adoc 
b/manual/src/main/asciidoc/user-guide/os-integration.adoc
new file mode 100644
index 0000000..823c302
--- /dev/null
+++ b/manual/src/main/asciidoc/user-guide/os-integration.adoc
@@ -0,0 +1,505 @@
+//
+// Licensed 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.
+//
+
+=== Integration in the operating system
+
+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 using:
+
+* <<Service Wrapper>>
+* <<Service Script Templates>>
+
+The above methods allow you to directly integrate Apache Karaf:
+
+* like a native Windows Service
+* like a Unix daemon process
+
+===== Service Wrapper
+
+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 )
+----
+
+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
+----
+
+===== Service Script Templates
+
+By using the "Service Script Templates", you can run Apache Karaf with the 
help of operating system specific init scripts.
+
+[NOTE]
+====
+As opposite of Service Wrapper, the templates targeting Unix system do not 
rely on a 3th party binaries
+====
+
+You can find these templates under the bin/contrib directory.
+
+{nbsp} +
+
+====== Unix
+
+The karaf-service.sh utility helps you to customize the templates.
+This utility will automatically identify the operating system and the default 
init system and generates ready to use init scripts.
+
+[NOTE]
+====
+You may still need to customize the generated scripts to adapt them to your 
environment.
+====
+
+The karaf-service.sh can be customized by define an environment variable or by 
passing command line options:
+
+,===
+Command line option, Environment variable, Description
+-k, KARAF_SERVICE_PATH       , Karaf installation path (mandatory)
+-d, KARAF_SERVICE_DATA       , Karaf data path (default to 
${KARAF_SERVICE_PATH}/data)
+-c, KARAF_SERVICE_CONF       , Karaf configuration file (default to 
${KARAF_SERVICE_PATH/etc/${KARAF_SERVICE_NAME}.conf
+-t, KARAF_SERVICE_ETC        , Karaf etc path (default to 
${KARAF_SERVICE_PATH/etc}
+-p, KARAF_SERVICE_PIDFILE    , Karaf pid path (default to 
${KARAF_SERVICE_DATA}/${KARAF_SERVICE_NAME}.pid)
+-n, KARAF_SERVICE_NAME       , Karaf service name (default karaf)
+-e, KARAF_ENV                , Karaf environment variable (can be repeated)
+-u, KARAF_SERVICE_USER       , Karaf user
+-g, KARAF_SERVICE_GROUP      , Karaf group (default ${KARAF_SERVICE_USER)
+-l, KARAF_SERVICE_LOG        , Karaf console log (default to 
${KARAF_SERVICE_DATA}/log/${KARAF_SERVICE_NAME}-console.log)
+-f, KARAF_SERVICE_TEMPLATE   , Template file to use
+-x, KARAF_SERVICE_EXECUTABLE , Karaf executable name (defaul karaf, should 
support daemon and stop commands)
+,===
+
+{nbsp} +
+
+====== Systemd
+
+When karaf-service.sh detect Systemd, it generates two files:
+
+- a systemd unit file to manage the root Apache Karaf container
+- a systemd environment file with variables used by the root Apache Karaf 
container
+- a systemd template unit file to manage Apache Karaf child containers
+
+.Example
+....
+$ ./karaf-service.sh -k /opt/karaf-4 -n karaf-4
+Writing service file "/opt/karaf-4/bin/contrib/karaf-4.service"
+Writing service configuration file ""/opt/karaf-4/etc/karaf-4.conf"
+Writing service file "/opt/karaf-4/bin/contrib/karaf-4@.service"
+
+$ cp /opt/karaf-4/bin/contrib/karaf-4.service /etc/systemd/system
+$ cp /opt/karaf-4/bin/contrib/karaf-4@.service /etc/systemd/system
+
+$ systemctl enable karaf-4.service
+....
+
+{nbsp} +
+
+====== SysV
+
+When karaf-service.sh detect a SysV system, it generates two files:
+
+- an init script to manage the root Apache Karaf container
+- an environment file with variables used by the root Apache Karaf container
+
+.Example
+....
+$ ./karaf-service.sh -k /opt/karaf-4 -n karaf-4
+Writing service file "/opt/karaf-4/bin/contrib/karaf-4"
+Writing service configuration file "/opt/karaf-4/etc/karaf-4.conf"
+
+$ ln -s /opt/karaf-4/bin/contrib/karaf-4 /etc/init.d/
+$ chkconfig karaf-4 on
+....
+
+[NOTE]
+====
+To enable service startup upon boot, please consult your operating system init 
guide
+====
+
+{nbsp} +
+
+====== Solaris SMF
+
+When karaf-service.sh detect a Solaris system, it generates a single file:
+
+.Example
+....
+$ ./karaf-service.sh -k /opt/karaf-4 -n karaf-4 -u lburgazz -g lburgazz
+Writing service file "/opt/karaf-4/bin/contrib/karaf-4.xml"
+
+$ svccfg validate /opt/karaf-4/bin/contrib/karaf-4.xml
+$ svccfg import /opt/karaf-4/bin/contrib/karaf-4.xml
+....
+
+[NOTE]
+====
+The generated SMF descriptor is defined as transient so the start method is 
executed only once
+====
+
+{nbsp} +
+
+====== Windows
+
+Installation of Apache Karaf as windows service is supported through 
https://github.com/kohsuke/winsw[winsw].
+
+Steps:
+
+- Rename karaf-service-win.exe to the service name i.e karaf-4.exe
+- Rename karaf-service-win.xml to match the service name i.e. karaf-4.xml
+- Customize the service descriptor to fit your needs
+- Use the service executable to install/star/stop the service
+
+.Example
+....
+C:\opt\apache-karaf-4\bin\contrib> karaf-4.exe install
+C:\opt\apache-karaf-4\bin\contrib> karaf-4.exe start
+....

http://git-wip-us.apache.org/repos/asf/karaf/blob/24f75379/manual/src/main/asciidoc/user-guide/wrapper.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/user-guide/wrapper.adoc 
b/manual/src/main/asciidoc/user-guide/wrapper.adoc
deleted file mode 100644
index 5ab8cf9..0000000
--- a/manual/src/main/asciidoc/user-guide/wrapper.adoc
+++ /dev/null
@@ -1,409 +0,0 @@
-//
-// Licensed 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.
-//
-
-=== 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
-----

Reply via email to