Repository: karaf Updated Branches: refs/heads/master b23cbafa4 -> 82cee21fd
[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/5b8806d5 Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/5b8806d5 Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/5b8806d5 Branch: refs/heads/master Commit: 5b8806d5e8807553a4686656346edd682d39bcf4 Parents: b23cbaf 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:55:52 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/5b8806d5/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/5b8806d5/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/5b8806d5/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 -----
