http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/webapp/users-guide/log.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/users-guide/log.conf b/manual/src/main/webapp/users-guide/log.conf deleted file mode 100644 index 86166b6..0000000 --- a/manual/src/main/webapp/users-guide/log.conf +++ /dev/null @@ -1,551 +0,0 @@ -h1. Log - -Apache Karaf provides a very dynamic and powerful logging system. - -It supports: - -* the OSGi Log Service -* the Apache Log4j framework -* the Apache Commons Logging framework -* the Logback framework -* the SLF4J framework -* the native Java Util Logging framework - -It means that the applications can use any logging framework, Apache Karaf will use the central log system to manage the -loggers, appenders, etc. - -h2. Configuration files - -The initial log configuration is loaded from {{etc/org.ops4j.pax.logging.cfg}}. - -This file is a [standard Log4j configuration file|http://logging.apache.org/log4j/1.2/manual.html]. - -You find the different Log4j element: - -* loggers -* appenders -* layouts - -You can add your own initial configuration directly in the file. - -The default configuration is the following: - -{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. -# -################################################################################ - -# Root logger -log4j.rootLogger=INFO, out, osgi:* -log4j.throwableRenderer=org.apache.log4j.OsgiThrowableRenderer - -# CONSOLE appender not used by default -log4j.appender.stdout=org.apache.log4j.ConsoleAppender -log4j.appender.stdout.layout=org.apache.log4j.PatternLayout -log4j.appender.stdout.layout.ConversionPattern=%d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n - -# File appender -log4j.appender.out=org.apache.log4j.RollingFileAppender -log4j.appender.out.layout=org.apache.log4j.PatternLayout -log4j.appender.out.layout.ConversionPattern=%d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n -log4j.appender.out.file=${karaf.data}/log/karaf.log -log4j.appender.out.append=true -log4j.appender.out.maxFileSize=1MB -log4j.appender.out.maxBackupIndex=10 - -# Sift appender -log4j.appender.sift=org.apache.log4j.sift.MDCSiftingAppender -log4j.appender.sift.key=bundle.name -log4j.appender.sift.default=karaf -log4j.appender.sift.appender=org.apache.log4j.FileAppender -log4j.appender.sift.appender.layout=org.apache.log4j.PatternLayout -log4j.appender.sift.appender.layout.ConversionPattern=%d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %m%n -log4j.appender.sift.appender.file=${karaf.data}/log/$\\{bundle.name\\}.log -log4j.appender.sift.appender.append=true -{code} - -The default configuration only define the {{ROOT}} logger, with {{INFO}} log level, using the {{out}} file appender. -You can change the log level to any Log4j valid values (from the most to less verbose): TRACE, DEBUG, INFO, WARN, ERROR, FATAL. - -The {{osgi:*}} appender is a special appender to send the log message to the OSGi Log Service. - -A {{stdout}} console appender is pre-configured, but not enabled by default. This appender allows you to display log -messages directly to standard output. It's interesting if you plan to run Apache Karaf in server mode (without console). - -To enable it, you have to add the {{stdout}} appender to the {{rootLogger}}: - -{code} -log4j.rootLogger=INFO, out, stdout, osgi:* -{code} - -The {{out}} appender is the default one. It's rolling file appender that maintain and rotate 10 log files of 1MB each. -The log files are located in {{data/log/karaf.log}} by default. - -The {{sift}} appender is not enabled by default. This appender allows you to have one log file per deployed bundle. -By default, the log file name format uses the bundle symbolic name (in the {{data/log}} folder). - -You can edit this file at runtime: any change will be reloaded and be effective immediately (no need to restart Apache Karaf). - -Another configuration file is used by Apache Karaf: {{etc/org.apache.karaf.log.cfg}}. This files configures the Log Service -used by the log commands (see later). - -h2. Commands - -Instead of changing the {{etc/org.ops4j.pax.logging.cfg}} file, Apache Karaf provides a set of commands allowing to -dynamically change the log configuration and see the log content: - -h3. {{log:clear}} - -The {{log:clear}} command clears the log entries. - -h3. {{log:display}} - -The {{log:display}} command displays the log entries. - -By default, it displays the log entries of the {{rootLogger}}: - -{code} -karaf@root()> log:display -2015-07-01 19:12:46,208 | INFO | FelixStartLevel | SecurityUtils | 16 - org.apache.sshd.core - 0.12.0 | BouncyCastle not registered, using the default JCE provider -2015-07-01 19:12:47,368 | INFO | FelixStartLevel | core | 68 - org.apache.aries.jmx.core - 1.1.1 | Starting JMX OSGi agent -{code} - -You can also display the log entries from a specific logger, using the {{logger}} argument: - -{code} -karaf@root()> log:display ssh -2015-07-01 19:12:46,208 | INFO | FelixStartLevel | SecurityUtils | 16 - org.apache.sshd.core - 0.12.0 | BouncyCastle not registered, using the default JCE provider -{code} - -By default, all log entries will be displayed. It could be very long if your Apache Karaf container is running since a long time. -You can limit the number of entries to display using the {{-n}} option: - -{code} -karaf@root()> log:display -n 5 -2015-07-01 06:53:24,143 | INFO | JMX OSGi Agent | core | 68 - org.apache.aries.jmx.core - 1.1.1 | Registering org.osgi.jmx.framework.BundleStateMBean to MBeanServer com.sun.jmx.mbeanserver.JmxMBeanServer@27cc75cb with name osgi.core:type=bundleState,version=1.7,framework=org.apache.felix.framework,uuid=5335370f-9dee-449f-9b1c-cabe74432ed1 -2015-07-01 06:53:24,150 | INFO | JMX OSGi Agent | core | 68 - org.apache.aries.jmx.core - 1.1.1 | Registering org.osgi.jmx.framework.PackageStateMBean to MBeanServer com.sun.jmx.mbeanserver.JmxMBeanServer@27cc75cb with name osgi.core:type=packageState,version=1.5,framework=org.apache.felix.framework,uuid=5335370f-9dee-449f-9b1c-cabe74432ed1 -2015-07-01 06:53:24,150 | INFO | JMX OSGi Agent | core | 68 - org.apache.aries.jmx.core - 1.1.1 | Registering org.osgi.jmx.framework.ServiceStateMBean to MBeanServer com.sun.jmx.mbeanserver.JmxMBeanServer@27cc75cb with name osgi.core:type=serviceState,version=1.7,framework=org.apache.felix.framework,uuid=5335370f-9dee-449f-9b1c-cabe74432ed1 -2015-07-01 06:53:24,152 | INFO | JMX OSGi Agent | core | 68 - org.apache.aries.jmx.core - 1.1.1 | Registering org.osgi.jmx.framework.wiring.BundleWiringStateMBean to MBeanServer com.sun.jmx.mbeanserver.JmxMBeanServer@27cc75cb with name osgi.core:type=wiringState,version=1.1,framework=org.apache.felix.framework,uuid=5335370f-9dee-449f-9b1c-cabe74432ed1 -2015-07-01 06:53:24,501 | INFO | FelixStartLevel | RegionsPersistenceImpl | 78 - org.apache.karaf.region.persist - 4.0.0 | Loading region digraph persistence -{code} - -You can also limit the number of entries stored and retain using the {{size}} property in {{etc/org.apache.karaf.log.cfg}} file: - -{code} -# -# The number of log statements to be displayed using log:display. It also defines the number -# of lines searched for exceptions using log:display exception. You can override this value -# at runtime using -n in log:display. -# -size = 500 -{code} - -By default, each log level is displayed with a different color: ERROR/FATAL are in red, DEBUG in purple, INFO in cyan, etc. -You can disable the coloring using the {{--no-color}} option. - -The log entries format pattern doesn't use the conversion pattern define in {{etc/org.ops4j.pax.logging.cfg}} file. -By default, it uses the {{pattern}} property defined in {{etc/org.apache.karaf.log.cfg}}. - -{code} -# -# The pattern used to format the log statement when using log:display. This pattern is according -# to the log4j layout. You can override this parameter at runtime using log:display with -p. -# -pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n -{code} - -You can also change the pattern dynamically (for one execution) using the {{-p}} option: - -{code} -karaf@root()> log:display -p "%d - %c - %m%n" -2015-07-01 07:01:58,007 - org.apache.sshd.common.util.SecurityUtils - BouncyCastle not registered, using the default JCE provider -2015-07-01 07:01:58,725 - org.apache.aries.jmx.core - Starting JMX OSGi agent -2015-07-01 07:01:58,744 - org.apache.aries.jmx.core - Registering MBean with ObjectName [osgi.compendium:service=cm,version=1.3,framework=org.apache.felix.framework,uuid=6361fc65-8df4-4886-b0a6-479df2d61c83] for service with service.id [13] -2015-07-01 07:01:58,747 - org.apache.aries.jmx.core - Registering org.osgi.jmx.service.cm.ConfigurationAdminMBean to MBeanServer com.sun.jmx.mbeanserver.JmxMBeanServer@27cc75cb with name osgi.compendium:service=cm,version=1.3,framework=org.apache.felix.framework,uuid=6361fc65-8df4-4886-b0a6-479df2d61c83 -{code} - -The pattern is a regular Log4j pattern where you can use keywords like %d for the date, %c for the class, %m for the log -message, etc. - -h3. {{log:exception-display}} - -The {{log:exception-display}} command displays the last occurred exception. - -As for {{log:display}} command, the {{log:exception-display}} command uses the {{rootLogger}} by default, but you can -specify a logger with the {{logger}} argument. - -h3. {{log:get}} - -The {{log:get}} command show the current log level of a logger. - -By default, the log level showed is the one from the root logger: - -{code} -karaf@root()> log:get -Logger | Level --------------- -ROOT | INFO -{code} - -You can specify a particular logger using the {{logger}} argument: - -{code} -karaf@root()> log:get ssh -Logger | Level --------------- -ssh | INFO -{code} - -The {{logger}} argument accepts the {{ALL}} keyword to display the log level of all logger (as a list). - -For instance, if you have defined your own logger in {{etc/org.ops4j.pax.logging.cfg}} file like this: - -{code} -log4j.logger.my.logger = DEBUG -{code} - -you can see the list of loggers with the corresponding log level: - -{code} -karaf@root()> log:get ALL -Logger | Level ------------------ -ROOT | INFO -my.logger | DEBUG -{code} - -The {{log:list}} command is an alias to {{log:get ALL}}. - -h3. {{log:log}} - -The {{log:log}} command allows you to manually add a message in the log. It's interesting when you create Apache Karaf -scripts: - -{code} -karaf@root()> log:log "Hello World" -karaf@root()> log:display -2015-07-01 07:20:16,544 | INFO | Local user karaf | command | 59 - org.apache.karaf.log.command - 4.0.0 | Hello World -{code} - -By default, the log level is INFO, but you can specify a different log level using the {{-l}} option: - -{code} -karaf@root()> log:log -l ERROR "Hello World" -karaf@root()> log:display -2015-07-01 07:21:38,902 | ERROR | Local user karaf | command | 59 - org.apache.karaf.log.command - 4.0.0 | Hello World -{code} - -h3. {{log:set}} - -The {{log:set}} command sets the log level of a logger. - -By default, it changes the log level of the {{rootLogger}}: - -{code} -karaf@root()> log:set DEBUG -karaf@root()> log:get -Logger | Level --------------- -ROOT | DEBUG -{code} - -You can specify a particular logger using the {{logger}} argument, after the {{level}} one: - -{code} -karaf@root()> log:set INFO my.logger -karaf@root()> log:get my.logger -Logger | Level ------------------ -my.logger | INFO -{code} - -The {{level}} argument accepts any Log4j log level: TRACE, DEBUG, INFO, WARN, ERROR, FATAL. - -By it also accepts the DEFAULT special keyword. - -The purpose of the DEFAULT keyword is to delete the current level of the logger (and only the level, the other properties -like appender are not deleted) -in order to use the level of the logger parent (logger are hierarchical). - -For instance, you have defined the following loggers (in {{etc/org.ops4j.pax.logging.cfg}} file): - -{code} -rootLogger=INFO,out,osgi:* -my.logger=INFO,appender1 -my.logger.custom=DEBUG,appender2 -{code} - -You can change the level of {{my.logger.custom}} logger: - -{code} -karaf@root()> log:set INFO my.logger.custom -{code} - -Now we have: - -{code} -rootLogger=INFO,out,osgi:* -my.logger=INFO,appender1 -my.logger.custom=INFO,appender2 -{code} - -You can use the DEFAULT keyword on {{my.logger.custom}} logger to remove the level: - -{code} -karaf@root()> log:set DEFAULT my.logger.custom -{code} - -Now we have: - -{code} -rootLogger=INFO,out,osgi:* -my.logger=INFO,appender1 -my.logger.custom=appender2 -{code} - -It means that, at runtime, the {{my.logger.custom}} logger uses the level of its parent {{my.logger}}, so {{INFO}}. - -Now, if we use DEFAULT keyword with the {{my.logger}} logger: - -{code} -karaf@root()> log:set DEFAULT my.logger -{code} - -We have: - -{code} -rootLogger=INFO,out,osgi:* -my.logger=appender1 -my.logger.custom=appender2 -{code} - -So, both {{my.logger.custom}} and {{my.logger}} use the log level of the parent {{rootLogger}}. - -It's not possible to use DEFAULT keyword with the {{rootLogger}} and it doesn't have parent. - -h3. {{log:tail}} - -The {{log:tail}} is exactly the same as {{log:display}} but it continuously displays the log entries. - -You can use the same options and arguments as for the {{log:display}} command. - -By default, it displays the entries from the {{rootLogger}}: - -{code} -karaf@root()> log:tail -2015-07-01 07:40:28,152 | INFO | FelixStartLevel | SecurityUtils | 16 - org.apache.sshd.core - 0.9.0 | BouncyCastle not registered, using the default JCE provider -2015-07-01 07:40:28,909 | INFO | FelixStartLevel | core | 68 - org.apache.aries.jmx.core - 1.1.1 | Starting JMX OSGi agent -2015-07-01 07:40:28,928 | INFO | FelixStartLevel | core | 68 - org.apache.aries.jmx.core - 1.1.1 | Registering MBean with ObjectName [osgi.compendium:service=cm,version=1.3,framework=org.apache.felix.framework,uuid=b44a44b7-41cd-498f-936d-3b12d7aafa7b] for service with service.id [13] -2015-07-01 07:40:28,936 | INFO | JMX OSGi Agent | core | 68 - org.apache.aries.jmx.core - 1.1.1 | Registering org.osgi.jmx.service.cm.ConfigurationAdminMBean to MBeanServer com.sun.jmx.mbeanserver.JmxMBeanServer@27cc75cb with name osgi.compendium:service=cm,version=1.3,framework=org.apache.felix.framework,uuid=b44a44b7-41cd-498f-936d-3b12d7aafa7b -{code} - -To exit from the {{log:tail}} command, just type CTRL-C. - -h2. JMX LogMBean - -All actions that you can perform with the {{log:*}} command can be performed using the LogMBean. - -The LogMBean object name is {{org.apache.karaf:type=log,name=*}}. - -h3. Attributes - -* {{Level}} attribute is the level of the ROOT logger. - -h3. Operations - -* {{getLevel(logger)}} to get the log level of a specific logger. As this operation supports the ALL keyword, it returns a Map with the level of each logger. -* {{setLevel(level, logger)}} to set the log level of a specific logger. This operation supports the DEFAULT keyword as for the {{log:set}} command. - -h2. Advanced configuration - -h3. Filters - -You can use filters on appender. Filters allow log events to be evaluated to determine if or how they should be published. - -Log4j provides ready to use filters: - -* The DenyAllFilter ({{org.apache.log4j.varia.DenyAllFilter}}) drops all logging events. - You can add this filter to the end of a filter chain to switch from the default "accept all unless instructed otherwise" - filtering behaviour to a "deny all unless instructed otherwise" behaviour. -* The LevelMatchFilter ({{org.apache.log4j.varia.LevelMatchFilter}} is a very simple filter based on level matching. - The filter admits two options {{LevelToMatch}} and {{AcceptOnMatch}}. If there is an exact match between the value of - the {{LevelToMatch}} option and the level of the logging event, then the event is accepted in case the {{AcceptOnMatch}} - option value is set to {{true}}. Else, if the {{AcceptOnMatch}} option value is set to {{false}}, the log event is rejected. -* The LevelRangeFilter ({{org.apache.log4j.varia.LevelRangeFilter}} is a very simple filter based on level matching, - which can be used to reject messages with priorities outside a certain range. The filter admits three options {{LevelMin}}, - {{LevelMax}} and {{AcceptOnMatch}}. If the log event level is between {{LevelMin}} and {{LevelMax}}, the log event is - accepted if {{AcceptOnMatch}} is true, or rejected if {{AcceptOnMatch}} is false. -* The StringMatchFilter ({{org.apache.log4j.varia.StringMatchFilter}}) is a very simple filter based on string matching. - The filter admits two options {{StringToMatch}} and {{AcceptOnMatch}}. If there is a match between the {{StringToMatch}} - and the log event message, the log event is accepted if {{AcceptOnMatch}} is true, or rejected if {{AcceptOnMatch}} is false. - -The filter is defined directly on the appender, in the {{etc/org.ops4j.pax.logging.cfg}} configuration file. - -The format to use it: - -{code} -log4j.appender.[appender-name].filter.[filter-name]=[filter-class] -log4j.appender.[appender-name].filter.[filter-name].[option]=[value] -{code} - -For instance, you can use the {{f1}} LevelRangeFilter on the {{out}} default appender: - -{code} -log4j.appender.out.filter.f1=org.apache.log4j.varia.LevelRangeFilter -log4j.appender.out.filter.f1.LevelMax=FATAL -log4j.appender.out.filter.f1.LevelMin=DEBUG -{code} - -Thanks to this filter, the log files generated by the {{out}} appender will contain only log messages with a level -between DEBUG and FATAL (the log events with TRACE as level are rejected). - -h3. Nested appenders - -A nested appender is a special kind of appender that you use "inside" another appender. -It allows you to create some kind of "routing" between a chain of appenders. - -The most used "nested compliant" appender are: - -* The AsyncAppender ({{org.apache.log4j.AsyncAppender}}) logs events asynchronously. This appender collects the events - and dispatch them to all the appenders that are attached to it. -* The RewriteAppender ({{org.apache.log4j.rewrite.RewriteAppender}}) forwards log events to another appender after possibly - rewriting the log event. - -This kind of appender accepts an {{appenders}} property in the appender definition: - -{code} -log4j.appender.[appender-name].appenders=[comma-separated-list-of-appender-names] -{code} - -For instance, you can create a AsyncAppender named {{async}} and asynchronously dispatch the log events to a JMS appender: - -{code} -log4j.appender.async=org.apache.log4j.AsyncAppender -log4j.appender.async.appenders=jms - -log4j.appender.jms=org.apache.log4j.net.JMSAppender -... -{code} - -h3. Error handlers - -Sometime, appenders can fail. For instance, a RollingFileAppender tries to write on the filesystem but the filesystem is full, or a JMS appender tries to send a message but the JMS broker is not there. - -As log can be very critical to you, you have to be inform that the log appender failed. - -It's the purpose of the error handlers. Appenders may delegate their error handling to error handlers, giving a chance to react to this appender errors. - -You have two error handlers available: - -* The OnlyOnceErrorHandler ({{org.apache.log4j.helpers.OnlyOnceErrorHandler}}) implements log4j's default error handling policy - which consists of emitting a message for the first error in an appender and ignoring all following errors. The error message - is printed on {{System.err}}. - This policy aims at protecting an otherwise working application from being flooded with error messages when logging fails. -* The FallbackErrorHandler ({{org.apache.log4j.varia.FallbackErrorHandler}}) allows a secondary appender to take over if the primary appender fails. - The error message is printed on {{System.err}}, and logged in the secondary appender. - -You can define the error handler that you want to use for each appender using the {{errorhandler}} property on the appender definition itself: - -{code} -log4j.appender.[appender-name].errorhandler=[error-handler-class] -log4j.appender.[appender-name].errorhandler.root-ref=[true|false] -log4j.appender.[appender-name].errorhandler.logger-ref=[logger-ref] -log4j.appender.[appender-name].errorhandler.appender-ref=[appender-ref] -{code} - -h3. OSGi specific MDC attributes - -The {{sift}} appender is a OSGi oriented appender allowing you to split the log events based on MDC (Mapped Diagnostic Context) attributes. - -MDC allows you to distinguish the different source of log events. - -The {{sift}} appender provides OSGi oritend MDC attributes by default: - -* {{bundle.id}} is the bundle ID -* {{bundle.name}} is the bundle symbolic name -* {{bundle.version}} is the bundle version - -You can use these MDC properties to create a log file per bundle: - -{code} -log4j.appender.sift=org.apache.log4j.sift.MDCSiftingAppender -log4j.appender.sift.key=bundle.name -log4j.appender.sift.default=karaf -log4j.appender.sift.appender=org.apache.log4j.FileAppender -log4j.appender.sift.appender.layout=org.apache.log4j.PatternLayout -log4j.appender.sift.appender.layout.ConversionPattern=%d{ABSOLUTE} | %-5.5p | %-16.16t | %-32.32c{1} | %-32.32C %4L | %m%n -log4j.appender.sift.appender.file=${karaf.data}/log/$\\{bundle.name\\}.log -log4j.appender.sift.appender.append=true -{code} - -h3. Enhanced OSGi stack trace renderer - -By default, Apache Karaf provides a special stack trace renderer, adding some OSGi specific specific information. - -In the stack trace, in addition of the class throwing the exception, you can find a pattern {{[id:name:version]}} at the -end of each stack trace line, where: - -* {{id}} is the bundle ID -* {{name}} is the bundle name -* {{version}} is the bundle version - -It's very helpful to diagnosing the source of an issue. - -For instance, in the following IllegalArgumentException stack trace, we can see the OSGi details about the source of the exception: - -{code} -java.lang.IllegalArgumentException: Command not found: *:foo - at org.apache.felix.gogo.runtime.shell.Closure.execute(Closure.java:225)[21:org.apache.karaf.shell.console:4.0.0] - at org.apache.felix.gogo.runtime.shell.Closure.executeStatement(Closure.java:162)[21:org.apache.karaf.shell.console:4.0.0] - at org.apache.felix.gogo.runtime.shell.Pipe.run(Pipe.java:101)[21:org.apache.karaf.shell.console:4.0.0] - at org.apache.felix.gogo.runtime.shell.Closure.execute(Closure.java:79)[21:org.apache.karaf.shell.console:4.0.0] - at org.apache.felix.gogo.runtime.shell.CommandSessionImpl.execute(CommandSessionImpl.java:71)[21:org.apache.karaf.shell.console:4.0.0] - at org.apache.karaf.shell.console.jline.Console.run(Console.java:169)[21:org.apache.karaf.shell.console:4.0.0] - at java.lang.Thread.run(Thread.java:637)[:1.7.0_21] -{code} - -h3. Custom appenders - -You can use your own appenders in Apache Karaf. - -The easiest way to do that is to package your appender as an OSGi bundle and attach it as a fragment of the -{{org.ops4j.pax.logging.pax-logging-service}} bundle. - -For instance, you create {{MyAppender}}: - -{code} -public class MyAppender extends AppenderSkeleton { -... -} -{code} - -You compile and package as an OSGi bundle containing a MANIFEST looking like: - -{code} -Manifest: -Bundle-SymbolicName: org.mydomain.myappender -Fragment-Host: org.ops4j.pax.logging.pax-logging-service -... -{code} - -Copy your bundle in the Apache Karaf {{system}} folder. The {{system}} folder uses a standard Maven directory layout: groupId/artifactId/version. - -In the {{etc/startup.properties}} configuration file, you define your bundle in the list before the pax-logging-service bundle. - -You have to restart Apache Karaf with a clean run (purging the {{data}} folder) in order to reload the system bundles. -You can now use your appender directly in {{etc/org.ops4j.pax.logging.cfg}} configuration file.
http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/webapp/users-guide/monitoring.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/users-guide/monitoring.conf b/manual/src/main/webapp/users-guide/monitoring.conf deleted file mode 100644 index 23229e8..0000000 --- a/manual/src/main/webapp/users-guide/monitoring.conf +++ /dev/null @@ -1,265 +0,0 @@ -h1. Monitoring and Management using JMX - -Apache Karaf provides a complete JMX layer. - -You can remotely connect to a running Apache Karaf instance using any JMX client (like jconsole). - -The Apache Karaf features provide a set of MBeans, dedicating for the monitoring and management. - -h2. Connecting - -Apache Karaf exposes a complete MBean server that you can use remotely. - -The default port number is 1099. - -The JMX URL to use by default is: - -{code} -service:jmx:rmi:///jndi/rmi://localhost:1099/karaf-root -{code} - -If don't need the remote JMX at all, users can remove -{code} --Dcom.sun.management.jmxremote -{code} -from bin/karaf|bin/karaf.bat to avoid opening the RMI listening port. - -You have to provide an username and password to access to the JMX layer. -The JMX layer user the security framework, and so, by default, it uses the users defined in {{etc/users.properties}}. - -You can change the port numbers of the JMX layer in the {{etc/org.apache.karaf.management.cfg}} configuration file. - -h2. Configuration - -The Apache Karaf JMX management layer is configured in the {{etc/org.apache.karaf.management.cfg}} configuration 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. -# -################################################################################ - -# -# The properties in this file define the configuration of Apache Karaf's JMX Management -# - -# -# Port number for RMI registry connection -# -rmiRegistryPort = 1099 - -# -# Port number for RMI server connection -# -rmiServerPort = 44444 - -# -# Name of the JAAS realm used for authentication -# -jmxRealm = karaf - -# -# The service URL for the JMXConnectorServer -# -serviceUrl = service:jmx:rmi://0.0.0.0:${rmiServerPort}/jndi/rmi://0.0.0.0:${rmiRegistryPort}/karaf-${karaf.name} - -# -# Whether any threads started for the JMXConnectorServer should be started as daemon threads -# -daemon = true - -# -# Whether the JMXConnectorServer should be started in a separate thread -# -threaded = true - -# -# The ObjectName used to register the JMXConnectorServer -# -objectName = connector:name=rmi - -# -# Role name used for JMX access authorization -# If not set, this defaults to the ${karaf.admin.role} configured in etc/system.properties -# -# jmxRole=admin -{code} - -* {{rmiRegistryPort}} property contains the port number of the JMX RMI registry. Default is {{1099}}. -* {{rmiServerPort}} property contains the port number of the JMX RMI server. Default is {{44444}}. -* {{jmxRealm}} is the security realm to use as authentication backend. By default it uses the {{karaf}} realm. - -h2. MBeans - -Apache Karaf provides a bunch of MBeans. - -The MBeans object names have the same format: - -{code} -org.apache.karaf:type=[feature],name=[instance] -{code} - -Installing additional Apache Karaf features and external applications can provide new MBeans. - -The following MBeans list is non exhaustive: - -* {{org.apache.karaf:type=bundle,name=*}}: management of the OSGi bundles. -* {{org.apache.karaf:type=config,name=*}}: management of the configurations. -* {{org.apache.karaf:type=diagnostic,name=*}}: creation of dumps containing the current Apache Karaf activity (used for diagnostic). -* {{org.apache.karaf:type=feature,name=*}}: management of the Apache Karaf features. -* {{org.apache.karaf:type=http,name=*}}: management of the HTTP service (provided by the {{http}} feature). -* {{org.apache.karaf:type=instance,name=*}}: management of the instances. -* {{org.apache.karaf:type=jdbc,name=*}}: management of the JDBC service (provided by the {{jdbc}} feature). -* {{org.apache.karaf:type=jms,name=*}}: management of the JMS service (provided by the {{jms}} feature). -* {{org.apache.karaf:type=jndi,name=*}}: management of the JNDI service (provided by the {{jndi}} feature). -* {{org.apache.karaf:type=kar,name=*}}: management of the KAR file. -* {{org.apache.karaf:type=log,name=*}}: management of the log service. -* {{org.apache.karaf:type=obr,name=*}}: management of the OBR service (provided by the {{obr}} feature). -* {{org.apache.karaf:type=package,name=*}}: details about packages exported/imported. -* {{org.apache.karaf:type=service,name=*}}: management of the OSGi services. -* {{org.apache.karaf:type=system,name=*}}: management of the Apache Karaf container itself (halt, restart, etc). -* {{org.apache.karaf:type=web,name=*}}: management of WebApplications (provided by the {{war}} feature). -* {{org.apache.karaf:type=wrapper,name=*}}: management of the service wrapper (provided by the {{wrapper}} feature). - -h2. RBAC - -Apache Karaf provides a complete Role-Based Access Control to the JMX MBeans and operations. - -Whenever a JMX operation is invoked, the roles of the user are checked against the required roles for this operation. - -The access lists are defined in configuration file in the {{etc}} folder. - -The relevant configuration is prefixed with {{jmx.acl}} and based on the JMX ObjectName that it applies to. - -For instance, specific configuration for a MBean with the object name {{foo.bar:type=Test}} can be placed in the -{{etc/jmx.acl.foo.bar.Test.cfg}} configuration file. - -More generic configurations can be placed in the domain (e.g. jmx.acl.foo.bar.cfg) or at the top level (jmx.acl.cfg). - -A simple configuration file looks like: - -{code} - # operation = role - test = admin - getVal = manager, viewer -{code} - -Apache Karaf looks for required roles using the following process -. -The most specific configuration file is tried first. It means that in the previous example, the {{etc/jmx.acl.foo.bar.Test.cfg}} is looked at first. -In this configuration, Apache Karaf looks for a: - -1. Specific match for the invocation, e.g. {{test(int)["17"] = role1}} - -2. Regex match for the invocation, e.g. {{test(int)[/[0-9]/] = role2}} - In both cases, the passed argument is converted to a String for the comparison. - If any of the above match, the search stops and the associated roles are used. - -3. Signature match for the invocation, e.g. {{test(int) = role3}} - If matched, the search stops and the associated roles are used. - -4. Method name match for the invocation, e.g. {{test = role4}} - If matched, the search stops and the associated roles are used. - -5. A method name wildcard match, e.g. {{te* = role5}} - For all the wildcard matches found in the current configuration file, the roles associated with the longest match are used. - So if you have te* and * and the method invoked is 'test', then the roles defined with te* are used, not the ones defined with *. - -If no matching definition is found, the most specific definition always takes the precedence. - -You can find some configuration examples: - -* Only a {{manager}} can call GC on the Memory MBean: -{code} -# etc/jmx.acl.java.lang.Memory.cfg - gc = manager -{code} - -* Bundles with ID between 0 and 49 can be stopped only by an {{admin}}, other bundles can be stopped by a {{manager}}: -{code} -# etc/jmx.acl.org.apache.karaf.bundles.cfg - stop(java.lang.String)[/([1-4])?([0-9]/] = admin - stop = manager -{code} - -The {{etc/jmx.acl.cfg}} configuration file contains the global configuration for the invocation on any MBean that -doesn't have a specific configuration: - -{code} -# etc/jmx.acl.cfg - list* = viewer - get* = viewer - is* = viewer - set* = admin - * = admin -{code} - -By default, all "read-only" operations ({{list*}}, {{get*}}, {{is*}}) can be performed by a {{viewer}}, whereas the "read-write" operations can be performed only by an {{admin}}. - -The {{org.apache.karaf:type=security,area=jmx}} MBean can be used to check whether the current user can access a certain MBean or invoke a specific operation on it. -This MBean can be used by management clients (monitoring tools, etc) to decide whether to show certain MBeans or operations to the end user. - -h2. JMX-HTTP bridge with Jolokia - -It's not always easy to use a JMX client with the RMI protocol. - -Some monitoring tools (Nagios, Zabbix, ...) are not native JMX clients. - -But most of them can use HTTP. - -More over, you may want to write your own application/web application. In that case, HTTP and JSON can be very interesting and easy to remotely manage Apache Karaf. - -[Jolokia|http://www.jolokia.org/] can be installed in Apache Karaf as a remote JMX-HTTP bridge. - -Karaf provides a jolokia feature, ready to install: - -{code} -karaf@root()> feature:install jolokia -{code} - -By default, Jolokia is listening on the port {{8181}} (see the [WebContainer (JSP/Servlet)|webcontainer] page for details about the HTTP configuration). - -If you point a browser on [http://localhost:8181/jolokia] you will see a JSON output like: - -{code} -{"timestamp":1421765829,"status":200,"request":{"type":"version"},"value":{"protocol":"7.2","config":{"useRestrictorService":"false","canonicalNaming":"true","includeStackTrace":"true","listenForHttpService":"true","historyMaxEntries":"10","agentId":"192.168.134.10-5922-6eb8d517-osgi","debug":"false","realm":"karaf","serializeException":"false","agentContext":"\/jolokia","agentType":"servlet","policyLocation":"classpath:\/jolokia-access.xml","user":"karaf","debugMaxEntries":"100","authMode":"jaas","mimeType":"text\/plain"},"agent":"1.2.4-SNAPSHOT","info":{"product":"felix","vendor":"Apache","version":"4.4.1"}}} -{code} - -You can manipulate the Apache Karaf JMX layer via HTTP and JSON, via system tools (like {{curl}}, {{jmx4perl}}, monitoring tools (supporting HTTP/JSON), or web applications. - -For instance, you can send a JSON request to get details about the current Apache Karaf heap memory usage. - -The format of the request is: - -{code} -{ - "type":"read", - "mbean":"java.lang:type=Memory", - "attribute":"HeapMemoryUsage", - "path":"used" -} -{code} - -We can send this JSON request using {{curl}} and get the result: - -{code} -curl -u karaf -d "{\"type\":\"read\",\"mbean\":\"java.lang:type=Memory\",\"attribute\":\"HeapMemoryUsage\",\"path\":\"used\"}" http://localhost:8181/jolokia/ && echo "" -Enter host password for user 'karaf': -{"timestamp":1421765948,"status":200,"request":{"mbean":"java.lang:type=Memory","path":"used","attribute":"HeapMemoryUsage","type":"read"},"value":69121000} -{code} - -You can find details on the [Jolokia website|http://www.jolokia.org] and in the [documentation|http://www.jolokia.org/reference/html/]. http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/webapp/users-guide/obr.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/users-guide/obr.conf b/manual/src/main/webapp/users-guide/obr.conf deleted file mode 100644 index 3e48180..0000000 --- a/manual/src/main/webapp/users-guide/obr.conf +++ /dev/null @@ -1,359 +0,0 @@ -h1. OBR - -The goal of OBR (OSGi Bundle Repository) is: - -1. to simplify deploying and using bundles -2. to encourage independent bundle development. - -OBR achieves the first goal by providing a service that can automatically install a bundle, with its deployment dependencies, -from a bundle repository. This makes it easier for people to experiment with existing bundles. - -The second goal is achieved by raising the visibility of the available bundles in a repository. - -OBR is an optional Apache Karaf feature. You have to install the {{obr}} feature to use OBR service: - -{code} -karaf@root()> feature:install obr -{code} - -The OBR feature turns Apache Karaf as an OBR client. It means that Apache Karaf can use a OBR repository to the installation -of the bundles, and during the installation of the features. - -The installation of the {{obr}} feature adds in Apache Karaf: - -* the OBR service -* the features OBR resolver -* the {{obr:*}} commands -* the JMX ObrMBean - -The OBR repository contains all bundles. The OBR service knows all requirements and capabilities of each bundle on an -OBR repository (it's the OBR metadata). - -Thanks to that, when you install ("deploy" in OBR wording) a bundle using the OBR service, it looks for all bundles -providing the capabilities matching the bundle requirements. -It will automatically install the bundles needed for the bundle. - -h2. Features OBR resolver - -If the feature specifies {{obr}} in the {{resolver}} attribute, Apache Karaf can use the OBR service to construct the list -of bundles to install with the features. - -The feature default resolver just consider the bundles described in the feature itself. - -Using the OBR resolver, Apache Karaf can extend the bundle list at the feature installation time using the OBR service. - -h2. Commands - -h3. {{obr:url-add}} - -The {{obr:url-add}} command registers the OBR repository at a given URL in the OBR service. - -Basically, an OBR repository is described by a {{repository.xml}} file. - -The {{obr:url-add}} command expects an {{url}} argument. The {{url}} argument is the URL to the OBR repository {{repository.xml}} file. -Any URL described in the [Artifacts repositories and URLs section|urls] is supported. - -For instance: - -{code} -karaf@root()> obr:url-add file:///user/.m2/repository/repository.xml -{code} - -h3. {{obr:url-list}} - -The {{obr:url-list}} command lists the OBR repository (with URL) registered in the OBR service: - -{code} -karaf@root()> obr:url-list -Index | OBR URL ---------------------------------------------------------- -0 | file:/user/.m2/repository/repository.xml -{code} - -h3. {{obr:url-refresh}} - -The {{obr:url-refresh}} command refresh an OBR repository (reloading the URL). - -The OBR service doesn't take "on the fly" the changes performed on an OBR repository {{repository.xml}}. You have to -reload the {{repository.xml}} URL to take the changes. It's the purpose of the {{obr:url-refresh}} command. - -Without argument, the {{obr:url-refresh}} command refreshes all repositories: - -{code} -karaf@root()> obr:url-refresh -{code} - -You can refresh only one repository by specifying the URL as argument: - -{code} -karaf@root()> obr:url-refresh file:/user/.m2/repository/repository.xml -{code} - -Instead of using the URL, you can use the repository index as displayed by the {{obr:url-list}} command. -To do so, you have to use the {{-i}} option: - -{code} -karaf@root()> obr:url-refresh -i 0 -{code} - -h3. {{obr:url-remove}} - -The {{obr:url-remove}} command removes an OBR repository from the OBR service. - -The {{obr:url-remove}} command expects the repository URL as argument: - -{code} -karaf@root()> obr:url-remove file:/user/.m2/repository/repository.xml -{code} - -Instead of using the URL, you can use the repository index as displayed by the {{obr:url-list}} command. -To do so, you have to use the {{-i}} option: - -{code} -karaf@root()> obr:url-remove -i 0 -{code} - -h3. {{obr:list}} - -The {{obr:list}} command lists all bundles available on the registered OBR repositories: - -{code} -karaf@root()> obr:list|more -Name | Symbolic Name | Version ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ -activemq-blueprint | org.apache.activemq.activemq-blueprint | 5.12.0.SNAPSHOT -activemq-camel | org.apache.activemq.activemq-camel | 5.12.0.SNAPSHOT -activemq-karaf | activemq-karaf | 5.12.0.SNAPSHOT -activemq-osgi | org.apache.activemq.activemq-osgi | 5.12.0.SNAPSHOT -Apache Aries Application API | org.apache.aries.application.api | 1.0.1.SNAPSHOT -... -{code} - -h3. {{obr:info}} - -The {{obr:info}} command displays the details about bundles available on the OBR service. Especially, it provides details about -capabilities and requirements of bundles. - -The {{obr:info}} command expects a bundle symbolic name as argument: - -{code} -karaf@root()> obr:info org.apache.karaf.wrapper.core -------------------------------- -Apache Karaf :: Wrapper :: Core -------------------------------- -id: org.apache.karaf.wrapper.core/4.0.0 -description: Core implementation and integration of the Java Service Wrapper. It provides a complete integration of Karaf with your Operating System. -documentation: http://www.apache.org/ -symbolicname: org.apache.karaf.wrapper.core -presentationname: Apache Karaf :: Wrapper :: Core -license: http://www.apache.org/licenses/LICENSE-2.0.txt -uri: file:/user/.m2/repository/org/apache/karaf/wrapper/org.apache.karaf.wrapper.core/4.0.0/org.apache.karaf.wrapper.core-4.0.0.jar -size: 1281352 -version: 4.0.0 -Requires: - service:(&(service=org.apache.aries.blueprint.NamespaceHandler)(osgi.service.blueprint.namespace=http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0)) - package:(&(package=javax.management)) - package:(&(package=org.apache.karaf.wrapper)) - package:(&(package=org.apache.karaf.wrapper.management)) - package:(&(package=org.fusesource.jansi)(version>=1.11.0)(!(version>=2.0.0))) - package:(&(package=org.osgi.framework)(version>=1.7.0)(!(version>=2.0.0))) - package:(&(package=org.osgi.framework.launch)(version>=1.1.0)(!(version>=2.0.0))) - package:(&(package=org.osgi.framework.startlevel)(version>=1.0.0)(!(version>=2.0.0))) - package:(&(package=org.osgi.service.blueprint)(version>=1.0.0)(!(version>=2.0.0))) - package:(&(package=org.slf4j)(version>=1.7.0)(!(version>=2.0.0))) -Capabilities: - bundle:{manifestversion=2, symbolicname=org.apache.karaf.wrapper.core, presentationname=Apache Karaf :: Wrapper :: Core, version=4.0.0} - service:{service=org.apache.karaf.wrapper.WrapperService} - package:{package=org.apache.karaf.wrapper, version=4.0.0} - package:{package=org.apache.karaf.wrapper.management, uses:=javax.management, version=4.0.0} -{code} - -The {{obr:info}} command uses the following syntax to identify the bundles: {{symbolic_name,version}} where {{version}} is optional. -It means that you have to use the following command to see the info about the wrapper core bundle with version 4.0.0: - -{code} -karaf@root()> obr:info org.apache.karaf.wrapper.core,4.0.0 -... -{code} - -You can specific multiple bundles separated by space: - -{code} -karaf@root()> obr:info org.apache.karaf.wrapper.core,4.0.0 org.apache.karaf.wrapper.command,4.0.0 -... -{code} - -h3. {{obr:source}} - -In addition of the bundles executable, the OBR service can also store the bundles sources. - -The {{obr:source}} command check the source URL in the OBR metadata for a given bundle, and download the sources on a target folder: - -{code} -karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core -{code} - -The {{obr:source}} command uses the following syntax to identify the bundles: {{symbolic_name,version}} where {{version}} is optional. -It means that you have to use the following command to download the source of wrapper core bundle with version 4.0.0: - -{code} -karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core,4.0.0 -{code} - -You can specify multiple bundles separated by space: - -{code} -karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core,4.0.0 org.apache.karaf.wrapper.command,4.0.0 -... -{code} - -h3. {{obr:resolve}} - -The {{obr:resolve}} command displays the resolution output for a given set of requirements. Actually, it show the bundles providing -the capabilities to match the requirements. It's what the OBR service does when executing {{obr:deploy}}. - -Optionally, the {{obr:resolve}} command can deploy the bundles as the {{obr:deploy}} command does. - -For instance, to know the OBR bundle resolving the {{org.apache.karaf.wrapper}} package requirement, you can do: - -{code} -karaf@root()> obr:resolve package=org.apache.karaf.wrapper -Required resource(s): ---------------------- - Apache Karaf :: Wrapper :: Core (4.0.0) -{code} - -h3. {{obr:find}} - -The {{obr:find}} command is similar to the {{obr:resolve}} one. It displays the bundles resolving the provided requirements, with details. - -For instance, to find the OBR bundle providing the {{org.apache.karaf.wrapper}} package, you can do: - -{code} -karaf@root()> obr:find package=org.apache.karaf.wrapper -------------------------------- -Apache Karaf :: Wrapper :: Core -------------------------------- -id: org.apache.karaf.wrapper.core/4.0.0 -description: Core implementation and integration of the Java Service Wrapper. It provides a complete integration of Karaf with your Operating System. -documentation: http://www.apache.org/ -symbolicname: org.apache.karaf.wrapper.core -presentationname: Apache Karaf :: Wrapper :: Core -license: http://www.apache.org/licenses/LICENSE-2.0.txt -uri: file:/user/.m2/repository/org/apache/karaf/wrapper/org.apache.karaf.wrapper.core/4.0.0/org.apache.karaf.wrapper.core-4.0.0.jar -size: 1281352 -version: 4.0.0 -Requirements: - service:(&(service=org.apache.aries.blueprint.NamespaceHandler)(osgi.service.blueprint.namespace=http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0)) - package:(&(package=javax.management)) - package:(&(package=org.apache.karaf.wrapper)) - package:(&(package=org.apache.karaf.wrapper.management)) - package:(&(package=org.fusesource.jansi)(version>=1.11.0)(!(version>=2.0.0))) - package:(&(package=org.osgi.framework)(version>=1.7.0)(!(version>=2.0.0))) - package:(&(package=org.osgi.framework.launch)(version>=1.1.0)(!(version>=2.0.0))) - package:(&(package=org.osgi.framework.startlevel)(version>=1.0.0)(!(version>=2.0.0))) - package:(&(package=org.osgi.service.blueprint)(version>=1.0.0)(!(version>=2.0.0))) - package:(&(package=org.slf4j)(version>=1.7.0)(!(version>=2.0.0))) -Capabilities: - bundle:{manifestversion=2, symbolicname=org.apache.karaf.wrapper.core, presentationname=Apache Karaf :: Wrapper :: Core, version=4.0.0} - service:{service=org.apache.karaf.wrapper.WrapperService} - package:{package=org.apache.karaf.wrapper, version=4.0.0} - package:{package=org.apache.karaf.wrapper.management, uses:=javax.management, version=4.0.0} -{code} - -h3. {{obr:deploy}} - -The {{obr:deploy}} command installs a bundle from the OBR repository, including all bundles required to satisfy the bundle requirements. - -{code} -karaf@root()> obr:deploy org.ops4j.pax.web.samples.helloworld-hs -Target resource(s): -------------------- - OPS4J Pax Web - Samples - Hello World - HttpService (4.0.0.SNAPSHOT) - -Required resource(s): ---------------------- - Apache ServiceMix :: Specs :: Activation API 1.4 (2.3.0.SNAPSHOT) - OPS4J Pax Web - Jetty Bundle (4.0.0.SNAPSHOT) - -Deploying...done. -{code} - -By default, the bundles are just installed, not started. You can use the {{-s}} option to start the bundles. - -The {{obr:deploy}} command uses the following syntax to identify the bundles: {{symbolic_name,version}} where {{version}} is optional. -It means that you have to use the following command to deploy the wrapper core bundle with version 4.0.0: - -{code} -karaf@root()> obr:deploy org.apache.karaf.wrapper.core,4.0.0 -{code} - -You can specify multiple bundles separated by space: - -{code} -karaf@root()> obr:deploy org.apache.karaf.wrapper.core,4.0.0 org.apache.karaf.wrapper.command,4.0.0 -... -{code} - -h2. {{obr:start}} - -The {{obr:start}} command does the same as {{obr:deploy -s}} command. It installs the bundle (and all required bundles to -satisfy the requirements) and starts all installed bundles. - -{code} -karaf@root()> obr:start org.ops4j.pax.web.samples.helloworld-hs -Target resource(s): -------------------- - OPS4J Pax Web - Samples - Hello World - HttpService (4.0.0.SNAPSHOT) - -Required resource(s): ---------------------- - Apache ServiceMix :: Specs :: Activation API 1.4 (2.3.0.SNAPSHOT) - OPS4J Pax Web - Jetty Bundle (4.0.0.SNAPSHOT) - -Deploying...done. -{code} - -The {{obr:start}} command uses the following syntax to identify the bundles: {{symbolic_name,version}} where {{version}} is optional. -It means that you have to use the following command to deploy and start the wrapper core bundle with version 4.0.0: - -{code} -karaf@root()> obr:start org.apache.karaf.wrapper.core,4.0.0 -{code} - -You can specify multiple bundles separated by space: - -{code} -karaf@root()> obr:start org.apache.karaf.wrapper.core,4.0.0 org.apache.karaf.wrapper.command,4.0.0 -... -{code} - -h2. JMX ObrMBean - -On the JMX layer, Apache Karaf provides a MBean dedicated to the management of the OBR service: the ObrMBean. - -The ObjectName to use is {{org.apache.karaf:type=obr,name=*}}. - -h3. Attributes - -The {{Urls}} attribute provides the list of registered OBR repositories URLs. - -The {{Bundles}} attribute provides a tabular data containing all bundles available on the registered OBR repositories. - -h3. Operations - -* {{addUrl(url)}} registers the OBR repository using the {{url}} to the {{repository.xml}}. -* {{removeUrl(url)}} removes the OBR repository at the given {{url}}. -* {{refreshUrl(url)}} refreshes the OBR repository at the given {{url}}. -* {{deployBundle(name)}} deploys a bundle (and all bundles required to satisfy the requirements) using the OBR service. The bundles are not automatically started. -* {{deployBundle(name, start, deployOptional)}} deploys a bundle (and all bundles required to satisfy the requirements) using the OBR service. - If {{start}} is {{true}}, the bundles are automatically started. If {{deployOptional}} is {{true}}, even the optional requirements will be resolved - by the OBR service (meaning installing more bundles to satisfy the optional requirements). - -The name to identify a bundle uses the following syntax: {{symbolic_name,version}} where version is optional. - -h2. Apache Karaf Cave - -In addition of being an OBR client, Apache Karaf can act as an OBR repositories server, thanks to Apache Karaf Cave. - -See the [Apache Karaf Cave sub-project|http://karaf.apache.org/index/subprojects/cave.html] for details. http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/webapp/users-guide/provisioning-schema.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/users-guide/provisioning-schema.conf b/manual/src/main/webapp/users-guide/provisioning-schema.conf deleted file mode 100644 index b57dcaa..0000000 --- a/manual/src/main/webapp/users-guide/provisioning-schema.conf +++ /dev/null @@ -1,46 +0,0 @@ -h1. Features XML Schemas (provisioning) - -Apache Karaf 4.0.0 supports different versions of the features XML schemas. - -The features XML schema can be found directly in the Apache Karaf sources, in the {{features/core}} module: - -{code} -features/core/src/main/resources/org/apache/karaf/features/karaf-features-1.3.0.xsd -features/core/src/main/resources/org/apache/karaf/features/karaf-features-1.2.1.xsd -features/core/src/main/resources/org/apache/karaf/features/karaf-features-1.2.0.xsd -features/core/src/main/resources/org/apache/karaf/features/karaf-features-1.1.0.xsd -features/core/src/main/resources/org/apache/karaf/features/karaf-features-1.0.0.xsd -{code} - -These schemas are also available on the Apache Karaf website: - -* [http://karaf.apache.org/xmlns/features/v1.3.0] -* [http://karaf.apache.org/xmlns/features/v1.2.1] -* [http://karaf.apache.org/xmlns/features/v1.2.0] -* [http://karaf.apache.org/xmlns/features/v1.1.0] -* [http://karaf.apache.org/xmlns/features/v1.0.0] - -h2. karaf-features-1.3.0.xsd - -{snippet:url=../features/core/src/main/resources/org/apache/karaf/features/karaf-features-1.3.0.xsd|lang=xml|pygmentize=true} -{snippet} - -h2. karaf-features-1.2.1.xsd - -{snippet:url=../features/core/src/main/resources/org/apache/karaf/features/karaf-features-1.2.1.xsd|lang=xml|pygmentize=true} -{snippet} - -h2. karaf-features-1.2.0.xsd - -{snippet:url=../features/core/src/main/resources/org/apache/karaf/features/karaf-features-1.2.0.xsd|lang=xml|pygmentize=true} -{snippet} - -h2. karaf-features-1.1.0.xsd - -{snippet:url=../features/core/src/main/resources/org/apache/karaf/features/karaf-features-1.1.0.xsd|lang=xml|pygmentize=true} -{snippet} - -h2. karaf-features-1.0.0.xsd - -{snippet:url=../features/core/src/main/resources/org/apache/karaf/features/karaf-features-1.0.0.xsd|lang=xml|pygmentize=true} -{snippet} http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/webapp/users-guide/provisioning.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/users-guide/provisioning.conf b/manual/src/main/webapp/users-guide/provisioning.conf deleted file mode 100644 index 67debc8..0000000 --- a/manual/src/main/webapp/users-guide/provisioning.conf +++ /dev/null @@ -1,670 +0,0 @@ -h1. Provisioning - -Apache Karaf supports the provisioning of applications and modules using the concept of Karaf Features. - -h2. Application - -By provisioning application, it means install all modules, configuration, and transitive applications. - -h2. OSGi - -It natively supports the deployment of OSGi applications. - -An OSGi application is a set of OSGi bundles. An OSGi bundles is a regular jar file, with additional metadata in the jar MANIFEST. - -In OSGi, a bundle can depend to other bundles. So, it means that to deploy an OSGi application, most of the time, you have -to firstly deploy a lot of other bundles required by the application. - -So, you have to find these bundles first, install the bundles. Again, these "dependency" bundles may require other bundles -to satisfy their own dependencies. - -More over, typically, an application requires configuration (see the [Configuration section|configuration] of the user guide). -So, before being able to start your application, in addition of the dependency bundles, you have to create or deploy the -configuration. - -As we can see, the provisioning of an application can be very long and fastidious. - -h2. Feature and resolver - -Apache Karaf provides a simple and flexible way to provision applications. - -In Apache Karaf, the application provisioning is an Apache Karaf "feature". - -A feature describes an application as: - -* a name -* a version -* a optional description (eventually with a long description) -* a set of bundles -* optionally a set configurations or configuration files -* optionally a set of dependency features - -When you install a feature, Apache Karaf installs all resources described in the feature. It means that it will -automatically resolves and installs all bundles, configurations, and dependency features described in the feature. - -The feature resolver checks the service requirements, and install the bundles providing the services matching the requirements. -The default mode enables this behavior only for "new style" features repositories (basically, the features repositories XML with -schema equal or greater to 1.3.0). It doesn't apply for "old style" features repositories (coming from Karaf 2 or 3). - -You can change the service requirements enforcement mode in {{etc/org.apache.karaf.features.cfg}} file, using the {{serviceRequirements}} property. - -{code} -serviceRequirements=default -{code} - -The possible values are: -* disable: service requirements are completely ignored, for both "old style" and "new style" features repositories -* default: service requirements are ignored for "old style" features repositories, and enabled for "new style" features repositories. -* enforce: service requirements are always verified, for "old style" and "new style" features repositories. - -Additionally, a feature can also define requirements. In that case, Karaf can automatically additional bundles or features -providing the capabilities to satisfy the requirements. - -A feature has a complete lifecycle: install, start, stop, update, uninstall. - -h2. Features repositories - -The features are described in a features XML descriptor. This XML file contains the description of a set of features. - -A features XML descriptor is named a "features repository". Before being able to install a feature, you have to register -the features repository that provides the feature (using {{feature:repo-add}} command or FeatureMBean as described later). - -For instance, the following XML file (or "features repository") describes the {{feature1}} and {{feature2}} features: - -{code:lang=xml} -<features xmlns="http://karaf.apache.org/xmlns/features/v1.3.0";> - <feature name="feature1" version="1.0.0"> - <bundle>...</bundle> - <bundle>...</bundle> - </feature> - <feature name="feature2" version="1.1.0"> - <feature>feature1</feature> - <bundle>...</bundle> - </feature> -</features> -{code} - -We can note that the features XML has a schema. Take a look on [Features XML Schema section|provisioning-schema] of the user guide -for details. -The {{feature1}} feature is available in version {{1.0.0}}, and contains two bundles. The {{<bundle/>}} element contains a URL -to the bundle artifact (see [Artifacts repositories and URLs section|urls] for details). If you install the {{feature1}} feature -(using {{feature:install}} or the FeatureMBean as described later), Apache Karaf will automatically installs the two bundles -described. -The {{feature2}} feature is available in version {{1.1.0}}, and contains a reference to the {{feature1}} feature and a bundle. -The {{<feature/>}} element contains the name of a feature. A specific feature version can be defined using the {{version}} -attribute to the {{<feature/>}} element ({{<feature version="1.0.0">feature1</feature>}}). If the {{version}} attribute is -not specified, Apache Karaf will install the latest version available. If you install the {{feature2}} feature (using {{feature:install}} -or the FeatureMBean as described later), Apache Karaf will automatically installs {{feature1}} (if it's not already installed) -and the bundle. - -A feature repository is registered using the URL to the features XML file. - -The features state is stored in the Apache Karaf cache (in the {{KARAF_DATA}} folder). You can restart Apache Karaf, the -previously installed features remain installed and available after restart. -If you do a clean restart or you delete the Apache Karaf cache (delete the {{KARAF_DATA}} folder), all previously features -repositories registered and features installed will be lost: you will have to register the features repositories and install -features by hand again. -To prevent this behaviour, you can specify features as boot features. - -h2. Boot features - -You can describe some features as boot features. A boot feature will be automatically install by Apache Karaf, even if it has -not been previously installed using {{feature:install}} or FeatureMBean. - -Apache Karaf features configuration is located in the {{etc/org.apache.karaf.features.cfg}} configuration file. - -This configuration file contains the two properties to use to define boot features: - -* {{featuresRepositories}} contains a list (coma separated) of features repositories (features XML) URLs. -* {{featuresBoot}} contains a list (come separated) of features to install at boot. - -h2. Features upgrade - -You can update a release by installing the same feature (with the same SNAPSHOT version or a different version). - -Thanks to the features lifecycle, you can control the status of the feature (started, stopped, etc). - -You can also use a simulation to see what the update will do. - -h2. Feature bundles - -h3. Start Level - -By default, the bundles deployed by a feature will have a start-level equals to the value defined in the {{etc/config.properties}} -configuration file, in the {{karaf.startlevel.bundle}} property. - -This value can be "overrided" by the {{start-level}} attribute of the {{<bundle/>}} element, in the features XML. - -{code:lang=xml} - <feature name="my-project" version="1.0.0"> - <bundle start-level="80">mvn:com.mycompany.myproject/myproject-dao</bundle> - <bundle start-level="85">mvn:com.mycompany.myproject/myproject-service</bundle> - </feature> -{code} - -The start-level attribute insure that the {{myproject-dao}} bundle is started before the bundles that use it. - -Instead of using start-level, a better solution is to simply let the OSGi framework know what your dependencies are by -defining the packages or services you need. It is more robust than setting start levels. - -h3. Simulate, Start and stop - -You can simulate the installation of a feature using the {{-t}} option to {{feature:install}} command. - -You can install a bundle without starting it. By default, the bundles in a feature are automatically started. - -A feature can specify that a bundle should not be started automatically (the bundle stays in resolved state). -To do so, a feature can specify the {{start}} attribute to false in the {{<bundle/>}} element: - -{code:lang=xml} - <feature name="my-project" version="1.0.0"> - <bundle start-level="80" start="false">mvn:com.mycompany.myproject/myproject-dao</bundle> - <bundle start-level="85" start="false">mvn:com.mycompany.myproject/myproject-service</bundle> - </feature> -{code} - -h3. Dependency - -A bundle can be flagged as being a dependency, using the {{dependency}} attribute set to true on the {{<bundle/>}} element. - -This information can be used by resolvers to compute the full list of bundles to be installed. - -h2. Dependent features - -A feature can depend to a set of other features: - -{code:lang=xml} - <feature name="my-project" version="1.0.0"> - <feature>other</feature> - <bundle start-level="80" start="false">mvn:com.mycompany.myproject/myproject-dao</bundle> - <bundle start-level="85" start="false">mvn:com.mycompany.myproject/myproject-service</bundle> - </feature> -{code} - -When the {{my-project}} feature will be installed, the {{other}} feature will be automatically installed as well. - -It's possible to define a version range for a dependent feature: - -{code:lang=xml} -<feature name="spring-dm"> - <feature version="[2.5.6,4)">spring</feature> - ... -</feature> -{code} - -The feature with the highest version available in the range will be installed. - -If a single version is specified, this version will be chosen. - -If nothing is specified, the highest available will be installed. - -h2. Feature configurations - -The {{<config/>}} element in a feature XML allows a feature to create and/or populate a configuration (identified by a configuration PID). - -{code:lang=xml} -<config name="com.foo.bar"> - myProperty = myValue -</config> -{code} - -The {{name}} attribute of the {{<config/>}} element corresponds to the configuration PID (see the [Configuration section|configuration] for details). - -The installation of the feature will have the same effect as dropping a file named {{com.foo.bar.cfg}} in the {{etc}} folder. - -The content of the {{<config/>}} element is a set of properties, following the key=value standard. - -h2. Feature configuration files - -Instead of using the {{<config/>}} element, a feature can specify {{<configfile/>}} elements. - -{code:lang=xml} -<configfile finalname="/etc/myfile.cfg" override="false">URL</configfile> -{code} - -Instead of directly manipulating the Apache Karaf configuration layer (as when using the {{<config/>}} element), the -{{<configfile/>}} element takes directly a file specified by a URL, and copy the file in the location specified by the -{{finalname}} attribute. - -If not specified, the location is relative from the {{KARAF_BASE}} variable. It's also possible to use variable like -${karaf.home}, ${karaf.base}, ${karaf.etc}, or even system properties. - -For instance: - -{code:lang=xml} -<configfile finalname="${karaf.etc}/myfile.cfg" override="false">URL</configfile> -{code} - -If the file is already present at the desired location it is kept and the deployment of the configuration file is skipped, -as a already existing file might contain customization. This behaviour can be overriden by {{override}} set to true. - -The file URL is any URL supported by Apache Karaf (see the [Artifacts repositories and URLs|urls] of the user guide for details). - -h3. Requirements - -A feature can also specify expected requirements. The feature resolver will try to satisfy the requirements. For that, it checks -the features and bundles capabilities and will automatically install the bundles to satisfy the requirements. - -For instance, a feature can contain: - -{code:lang=xml} -<requirement>osgi.ee;filter:="(&(osgi.ee=JavaSE)(!(version>=1.8)))"</requirement> -{code} - -The requirement specifies that the feature will work by only if the JDK version is not 1.8 (so basically 1.7). - -The features resolver is also able to refresh the bundles when an optional dependency is satisfy, rewiring the optional import. - -h2. Commands - -h3. {{feature:repo-list}} - -The {{feature:repo-list}} command lists all registered features repository: - -{code} -karaf@root()> feature:repo-list -Repository | URL --------------------------------------------------------------------------------------- -org.ops4j.pax.cdi-0.12.0 | mvn:org.ops4j.pax.cdi/pax-cdi-features/0.12.0/xml/features -org.ops4j.pax.web-4.1.4 | mvn:org.ops4j.pax.web/pax-web-features/4.1.4/xml/features -standard-4.0.0 | mvn:org.apache.karaf.features/standard/4.0.0/xml/features -enterprise-4.0.0 | mvn:org.apache.karaf.features/enterprise/4.0.0/xml/features -spring-4.0.0 | mvn:org.apache.karaf.features/spring/4.0.0/xml/features -{code} - -Each repository has a name and the URL to the features XML. - -Apache Karaf parses the features XML when you register the features repository URL (using {{feature:repo-add}} command -or the FeatureMBean as described later). If you want to force Apache Karaf to reload the features repository URL (and -so update the features definition), you can use the {{-r}} option: - -{code} -karaf@root()> feature:repo-list -r -Reloading all repositories from their urls - -Repository | URL --------------------------------------------------------------------------------------- -org.ops4j.pax.cdi-0.12.0 | mvn:org.ops4j.pax.cdi/pax-cdi-features/0.12.0/xml/features -org.ops4j.pax.web-4.1.4 | mvn:org.ops4j.pax.web/pax-web-features/4.1.4/xml/features -standard-4.0.0 | mvn:org.apache.karaf.features/standard/4.0.0/xml/features -enterprise-4.0.0 | mvn:org.apache.karaf.features/enterprise/4.0.0/xml/features -spring-4.0.0 | mvn:org.apache.karaf.features/spring/4.0.0/xml/features -{code} - -h3. {{feature:repo-add}} - -To register a features repository (and so having new features available in Apache Karaf), you have to use the -{{feature:repo-add}} command. - -The {{feature:repo-add}} command requires the {{name/url}} argument. This argument accepts: - -* a feature repository URL. It's an URL directly to the features XML file. Any URL described in the [Artifacts repositories and URLs section|urls] - of the user guide is supported. -* a feature repository name defined in the {{etc/org.apache.karaf.features.repos.cfg}} configuration file. - -The {{etc/org.apache.karaf.features.repos.cfg}} defines a list of "pre-installed/available" features repositories: - -{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. -# -################################################################################ - -# -# This file describes the features repository URL -# It could be directly installed using feature:repo-add command -# -enterprise=mvn:org.apache.karaf.features/enterprise/LATEST/xml/features -spring=mvn:org.apache.karaf.features/spring/LATEST/xml/features -cellar=mvn:org.apache.karaf.cellar/apache-karaf-cellar/LATEST/xml/features -cave=mvn:org.apache.karaf.cave/apache-karaf-cave/LATEST/xml/features -camel=mvn:org.apache.camel.karaf/apache-camel/LATEST/xml/features -camel-extras=mvn:org.apache-extras.camel-extra.karaf/camel-extra/LATEST/xml/features -cxf=mvn:org.apache.cxf.karaf/apache-cxf/LATEST/xml/features -cxf-dosgi=mvn:org.apache.cxf.dosgi/cxf-dosgi/LATEST/xml/features -cxf-xkms=mvn:org.apache.cxf.services.xkms/cxf-services-xkms-features/LATEST/xml -activemq=mvn:org.apache.activemq/activemq-karaf/LATEST/xml/features -jclouds=mvn:org.apache.jclouds.karaf/jclouds-karaf/LATEST/xml/features -openejb=mvn:org.apache.openejb/openejb-feature/LATEST/xml/features -wicket=mvn:org.ops4j.pax.wicket/features/LATEST/xml/features -hawtio=mvn:io.hawt/hawtio-karaf/LATEST/xml/features -pax-cdi=mvn:org.ops4j.pax.cdi/pax-cdi-features/LATEST/xml/features -pax-jdbc=mvn:org.ops4j.pax.jdbc/pax-jdbc-features/LATEST/xml/features -pax-jpa=mvn:org.ops4j.pax.jpa/pax-jpa-features/LATEST/xml/features -pax-web=mvn:org.ops4j.pax.web/pax-web-features/LATEST/xml/features -pax-wicket=mvn:org.ops4j.pax.wicket/pax-wicket-features/LATEST/xml/features -ecf=http://download.eclipse.org/rt/ecf/latest/site.p2/karaf-features.xml -decanter=mvn:org.apache.karaf.decanter/apache-karaf-decanter/LATEST/xml/features -{code} - -You can directly provide a features repository name to the {{feature:repo-add}} command. For install, to install Apache Karaf Cellar, you can do: - -{code} -karaf@root()> feature:repo-add cellar -Adding feature url mvn:org.apache.karaf.cellar/apache-karaf-cellar/LATEST/xml/features -{code} - -When you don't provide the optional {{version}} argument, Apache Karaf installs the latest version of the features repository available. -You can specify a target version with the {{version}} argument: - -{code} -karaf@root()> feature:repo-add cellar 4.0.0.RC1 -Adding feature url mvn:org.apache.karaf.cellar/apache-karaf-cellar/4.0.0.RC1/xml/features -{code} - -Instead of providing a features repository name defined in the {{etc/org.apache.karaf.features.repos.cfg}} configuration file, -you can directly provide the features repository URL to the {{feature:repo-add}} command: - -{code} -karaf@root()> feature:repo-add mvn:org.apache.karaf.cellar/apache-karaf-cellar/4.0.0.RC1/xml/features -Adding feature url mvn:org.apache.karaf.cellar/apache-karaf-cellar/4.0.0.RC1/xml/features -{code} - -By default, the {{feature:repo-add}} command just registers the features repository, it doesn't install any feature. -If you specify the {{-i}} option, the {{feature:repo-add}} command registers the features repository and installs all -features described in this features repository: - -{code} -karaf@root()> feature:repo-add -i cellar -{code} - -h3. {{feature:repo-refresh}} - -Apache Karaf parses the features repository XML when you register it (using {{feature:repo-add}} command or the FeatureMBean). -If the features repository XML changes, you have to indicate to Apache Karaf to refresh the features repository to load the changes. - -The {{feature:repo-refresh}} command refreshes the features repository. - -Without argument, the command refreshes all features repository: - -{code} -karaf@root()> feature:repo-refresh -Refreshing feature url mvn:org.ops4j.pax.cdi/pax-cdi-features/0.12.0/xml/features -Refreshing feature url mvn:org.ops4j.pax.web/pax-web-features/4.1.4/xml/features -Refreshing feature url mvn:org.apache.karaf.features/standard/4.0.0/xml/features -Refreshing feature url mvn:org.apache.karaf.features/enterprise/4.0.0/xml/features -Refreshing feature url mvn:org.apache.karaf.features/spring/4.0.0/xml/features -{code} - -Instead of refreshing all features repositories, you can specify the features repository to refresh, by providing the URL -or the features repository name (and optionally version): - -{code} -karaf@root()> feature:repo-refresh mvn:org.apache.karaf.features/standard/4.0.0/xml/features -Refreshing feature url mvn:org.apache.karaf.features/standard/4.0.0/xml/features -{code} - -{code} -karaf@root()> feature:repo-refresh cellar -Refreshing feature url mvn:org.apache.karaf.cellar/apache-karaf-cellar/LATEST/xml/features -{code} - -h3. {{feature:repo-remove}} - -The {{feature:repo-remove}} command removes a features repository from the registered ones. - -The {{feature:repo-remove}} command requires a argument: - -* the features repository name (as displayed in the repository column of the {{feature:repo-list}} command output) -* the features repository URL (as displayed in the URL column of the {{feature:repo-list}} command output) - -{code} -karaf@root()> feature:repo-remove karaf-cellar-4.0.0.RC1 -{code} - -{code} -karaf@root()> feature:repo-remove mvn:org.apache.karaf.cellar/apache-karaf-cellar/LATEST/xml/features -{code} - -By default, the {{feature:repo-remove}} command just removes the features repository from the registered ones: it doesn't -uninstall the features provided by the features repository. - -If you use {{-u}} option, the {{feature:repo-remove}} command uninstalls all features described by the features repository: - -{code} -karaf@root()> feature:repo-remove -u karaf-cellar-4.0.0.RC1 -{code} - -h3. {{feature:list}} - -The {{feature:list}} command lists all available features (provided by the different registered features repositories): - -{code} -Name | Version | Required | State | Repository | Description -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -pax-cdi | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI support -pax-cdi-1.1 | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI 1.1 support -pax-cdi-1.2 | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI 1.2 support -pax-cdi-weld | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld CDI support -pax-cdi-1.1-weld | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld CDI 1.1 support -pax-cdi-1.2-weld | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld CDI 1.2 support -pax-cdi-openwebbeans | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | OpenWebBeans CDI support -pax-cdi-web | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Web CDI support -pax-cdi-1.1-web | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Web CDI 1.1 support -... -{code} - -If you want to order the features by alphabetical name, you can use the {{-o}} option: - -{code} -karaf@root()> feature:list -o -Name | Version | Required | State | Repository | Description -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -deltaspike-core | 1.2.1 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Apache Deltaspike core support -deltaspike-data | 1.2.1 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Apache Deltaspike data support -deltaspike-jpa | 1.2.1 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Apache Deltaspike jpa support -deltaspike-partial-bean | 1.2.1 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Apache Deltaspike partial bean support -pax-cdi | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI support -pax-cdi-1.1 | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI 1.1 support -pax-cdi-1.1-web | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Web CDI 1.1 support -pax-cdi-1.1-web-weld | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld Web CDI 1.1 support -pax-cdi-1.1-weld | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld CDI 1.1 support -pax-cdi-1.2 | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI 1.2 support -... -{code} - -By default, the {{feature:list}} command displays all features, whatever their current state (installed or not installed). - -Using the {{-i}} option displays only installed features: - -{code} -karaf@root()> feature:list -i -Name | Version | Required | State | Repository | Description -------------------------------------------------------------------------------------------------------------------- -aries-proxy | 4.0.0 | | Started | standard-4.0.0 | Aries Proxy -aries-blueprint | 4.0.0 | x | Started | standard-4.0.0 | Aries Blueprint -feature | 4.0.0 | x | Started | standard-4.0.0 | Features Support -shell | 4.0.0 | x | Started | standard-4.0.0 | Karaf Shell -shell-compat | 4.0.0 | x | Started | standard-4.0.0 | Karaf Shell Compatibility -deployer | 4.0.0 | x | Started | standard-4.0.0 | Karaf Deployer -bundle | 4.0.0 | x | Started | standard-4.0.0 | Provide Bundle support -config | 4.0.0 | x | Started | standard-4.0.0 | Provide OSGi ConfigAdmin support -diagnostic | 4.0.0 | x | Started | standard-4.0.0 | Provide Diagnostic support -instance | 4.0.0 | x | Started | standard-4.0.0 | Provide Instance support -jaas | 4.0.0 | x | Started | standard-4.0.0 | Provide JAAS support -log | 4.0.0 | x | Started | standard-4.0.0 | Provide Log support -package | 4.0.0 | x | Started | standard-4.0.0 | Package commands and mbeans -service | 4.0.0 | x | Started | standard-4.0.0 | Provide Service support -system | 4.0.0 | x | Started | standard-4.0.0 | Provide System support -kar | 4.0.0 | x | Started | standard-4.0.0 | Provide KAR (KARaf archive) support -ssh | 4.0.0 | x | Started | standard-4.0.0 | Provide a SSHd server on Karaf -management | 4.0.0 | x | Started | standard-4.0.0 | Provide a JMX MBeanServer and a set of MBeans in -wrap | 0.0.0 | x | Started | standard-4.0.0 | Wrap URL handler -{code} - -h3. {{feature:install}} - -The {{feature:install}} command installs a feature. - -It requires the {{feature}} argument. The {{feature}} argument is the name of the feature, or the name/version of the feature. -If only the name of the feature is provided (not the version), the latest version available will be installed. - -{code} -karaf@root()> feature:install eventadmin -{code} - -We can simulate an installation using {{-t}} or {{--simulate}} option: it just displays what it would do, but it doesn't do it: - -{code} -karaf@root()> feature:install -t -v eventadmin -Adding features: eventadmin/[4.0.0,4.0.0] -No deployment change. - Managing bundle: - org.apache.felix.metatype / 1.0.12 -{code} - -You can specify a feature version to install: - -{code} -karaf@root()> feature:install eventadmin/4.0.0 -{code} - -By default, the {{feature:install}} command is not verbose. If you want to have some details about actions performed by the {{feature:install}} -command, you can use the {{-v}} option: - -{code} -karaf@root()> feature:install -v eventadmin -Adding features: eventadmin/[4.0.0,4.0.0] -No deployment change. -Done. -{code} - -If a feature contains a bundle which is already installed, by default, Apache Karaf will refresh this bundle. -Sometime, this refresh can cause issue to other running applications. If you want to disable the auto-refresh of installed -bundles, you can use the {{-r}} option: - -{code} -karaf@root()> feature:install -v -r eventadmin -Adding features: eventadmin/[4.0.0,4.0.0] -No deployment change. -Done. -{code} - -You can decide to not start the bundles installed by a feature using the {{-s}} or {{--no-auto-start}} option: - -{code} -karaf@root()> feature:install -s eventadmin -{code} - -h3. {{feature:start}} - -By default, when you install a feature, it's automatically installed. However, you can specify the {{-s}} option to the {{feature:install}} command. - -As soon as you install a feature (started or not), all packages provided by the bundles defined in the feature will be available, and can be used for -the wiring in other bundles. - -When starting a feature, all bundles are started, and so, the feature also exposes the services. - -h3. {{feature:stop}} - -You can also stop a feature: it means that all services provided by the feature will be stop and removed from the service registry. However, the packages -are still available for the wiring (the bundles are in resolved state). - -h3. {{feature:uninstall}} - -The {{feature:uninstall}} command uninstalls a feature. As the {{feature:install}} command, the {{feature:uninstall}} command -requires the {{feature}} argument. The {{feature}} argument is the name of the feature, or the name/version of the feature. -If only the name of the feature is provided (not the version), the latest version available will be installed. - -{code} -karaf@root()> feature:uninstall eventadmin -{code} - -The features resolver is involved during feature uninstallation: transitive features installed by the uninstalled feature can be uninstalled -themselves if not used by other feature. - -h2. Deployer - -You can "hot deploy" a features XML by dropping the file directly in the {{deploy}} folder. - -Apache Karaf provides a features deployer. - -When you drop a features XML in the deploy folder, the features deployer does: -* register the features XML as a features repository -* the features with {{install}} attribute set to "auto" will be automatically installed by the features deployer. - -For instance, dropping the following XML in the deploy folder will automatically install feature1 and feature2, whereas -feature3 won't be installed: - -{code:lang=xml} -<?xml version="1.0" encoding="UTF-8"?> -<features name="my-features" xmlns="http://karaf.apache.org/xmlns/features/v1.3.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation="http://karaf.apache.org/xmlns/features/v1.3.0 http://karaf.apache.org/xmlns/features/v1.3.0";> - - <feature name="feature1" version="1.0" install="auto"> - ... - </feature> - - <feature name="feature2" version="1.0" install="auto"> - ... - </feature> - - <feature name="feature3" version="1.0"> - ... - </feature> - -</features> -{code} - -h2. JMX FeatureMBean - -On the JMX layer, you have a MBean dedicated to the management of the features and features repositories: the FeatureMBean. - -The FeatureMBean object name is: {{org.apache.karaf:type=feature,name=*}}. - -h3. Attributes - -The FeatureMBean provides two attributes: - -* {{Features}} is a tabular data set of all features available. -* {{Repositories}} is a tabular data set of all registered features repositories. - -The {{Repositories}} attribute provides the following information: - -* {{Name}} is the name of the features repository. -* {{Uri}} is the URI to the features XML for this repository. -* {{Features}} is a tabular data set of all features (name and version) provided by this features repository. -* {{Repositories}} is a tabular data set of features repositories "imported" in this features repository. - -The {{Features}} attribute provides the following information: - -* {{Name}} is the name of the feature. -* {{Version}} is the version of the feature. -* {{Installed}} is a boolean. If true, it means that the feature is currently installed. -* {{Bundles}} is a tabular data set of all bundles (bundles URL) described in the feature. -* {{Configurations}} is a tabular data set of all configurations described in the feature. -* {{Configuration Files}} is a tabular data set of all configuration files described in the feature. -* {{Dependencies}} is a tabular data set of all dependent features described in the feature. - -h3. Operations - -* {{addRepository(url)}} adds the features repository with the {{url}}. The {{url}} can be a {{name}} as in the {{feature:repo-add}} command. -* {{addRepository(url, install)}} adds the features repository with the {{url}} and automatically installs all bundles if {{install}} is true. The {{url}} can be a {{name}} like in the {{feature:repo-add}} command. -* {{removeRepository(url)}} removes the features repository with the {{url}}. The {{url}} can be a {{name}} as in the {{feature:repo-remove}} command. -* {{installFeature(name)}} installs the feature with the {{name}}. -* {{installFeature(name, version)}} installs the feature with the {{name}} and {{version}}. -* {{installFeature(name, noClean, noRefresh)}} installs the feature with the {{name}} without cleaning the bundles in case of failure, and without refreshing already installed bundles. -* {{installFeature(name, version, noClean, noRefresh) }} installs the feature with the {{name}} and {{version}} without cleaning the bundles in case of failure, and without refreshing already installed bundles. -* {{uninstallFeature(name)}} uninstalls the feature with the {{name}}. -* {{uninstallFeature(name, version)}} uninstalls the feature with the {{name}} and {{version}}. - -h3. Notifications - -The FeatureMBean sends two kind of notifications (on which you can subscribe and react): - -* When a feature repository changes (added or removed). -* When a feature changes (installed or uninstalled).
