http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/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 aeaec13..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 -2013-11-29 19:12:46,208 | INFO | FelixStartLevel | SecurityUtils | 16 - org.apache.sshd.core - 0.9.0 | BouncyCastle not registered, using the default JCE provider -2013-11-29 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 -2013-11-29 19:12:46,208 | INFO | FelixStartLevel | SecurityUtils | 16 - org.apache.sshd.core - 0.9.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 -2013-11-30 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 -2013-11-30 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 -2013-11-30 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 -2013-11-30 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 -2013-11-30 06:53:24,530 | INFO | FelixStartLevel | RegionsPersistenceImpl | 78 - org.apache.karaf.region.persist - 3.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" -2013-11-30 07:01:58,007 - org.apache.sshd.common.util.SecurityUtils - BouncyCastle not registered, using the default JCE provider -2013-11-30 07:01:58,725 - org.apache.aries.jmx.core - Starting JMX OSGi agent -2013-11-30 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] -2013-11-30 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 -2013-11-30 07:20:16,544 | INFO | Local user karaf | command | 59 - org.apache.karaf.log.command - 3.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 -2013-11-30 07:21:38,902 | ERROR | Local user karaf | command | 59 - org.apache.karaf.log.command - 3.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 -2013-11-30 07:40:28,152 | INFO | FelixStartLevel | SecurityUtils | 16 - org.apache.sshd.core - 0.9.0 | BouncyCastle not registered, using the default JCE provider -2013-11-30 07:40:28,909 | INFO | FelixStartLevel | core | 68 - org.apache.aries.jmx.core - 1.1.1 | Starting JMX OSGi agent -2013-11-30 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] -2013-11-30 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:3.0.0] - at org.apache.felix.gogo.runtime.shell.Closure.executeStatement(Closure.java:162)[21:org.apache.karaf.shell.console:3.0.0] - at org.apache.felix.gogo.runtime.shell.Pipe.run(Pipe.java:101)[21:org.apache.karaf.shell.console:3.0.0] - at org.apache.felix.gogo.runtime.shell.Closure.execute(Closure.java:79)[21:org.apache.karaf.shell.console:3.0.0] - at org.apache.felix.gogo.runtime.shell.CommandSessionImpl.execute(CommandSessionImpl.java:71)[21:org.apache.karaf.shell.console:3.0.0] - at org.apache.karaf.shell.console.jline.Console.run(Console.java:169)[21:org.apache.karaf.shell.console:3.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/9f08eb9e/manual/src/main/webapp/users-guide/migration.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/users-guide/migration.conf b/manual/src/main/webapp/users-guide/migration.conf deleted file mode 100644 index 9b88d88..0000000 --- a/manual/src/main/webapp/users-guide/migration.conf +++ /dev/null @@ -1,52 +0,0 @@ -h1. Migration from Karaf 2.x to 3.x - -This section shows the necessary changes you have to consider when upgrading karaf. - -h2. Updating an existing instance - -There is no simple upgrade path for an existing instance. The simplest way of upgraing is to redeploy your application to the new karaf instance and copy over the changed configurations. - -h2. Changes in command names - -In general the command names now have the scheme <object in singular>:<command on object>. -For cases when one scope cares for more than one object type like feature:* that cares for features and feature repositories the sheme is partly: <scope>:<object-command>. -The following table shows side by side the old and new command names. - -|| Name 2.x || Name 3.x || -| features:add-url | feature:repo-add | -| features:chooseurl | feature:repo-add | -| features:chooseurl | feature:repo-add | -| features:listrepositories | feature:repo-list | -| features:listurl | feature:repo-list | -| features:listversions | feature:version-list | -| features:refreshurl | feature:repo-add | -| features:removerepository | feature:repo-remove | -| features:removeurl | feature:repo-remove | -| features:* | feature:* | -| osgi:* | bundle:* | -| dev:dynamic-import | bundle:dynamic-import | -| dev:framework | system:framework | -| dev:print-stack-traces | shell:print-stack-traces | -| dev:restart | system:shutdown -r | -| dev:show-tree | bundle:tree-show | -| dev:watch | bundle:watch | -| admin:* | instance:* | -| config: | config: | -| jaas: | jaas: | - -h2. Changes in MBeans - -For Karaf 3 we did a major refactoring of the module and package structure of Karaf. So almost all mbean interfaces moved to a new package. So if you use the Java interface to access an mbean you will most likely have to change that. - -Like the commands the bean types have bean renamed to the singular form: - -|| Type Karaf 2.x || Type Karaf 3.x || -| admin | instance | -| bundles | bundle | -| features | feature | -| packages | package | -| services | service | - -Besides the type in the objectname a lot of the operations / attributes changed. - - http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/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 d60eebd..0000000 --- a/manual/src/main/webapp/users-guide/monitoring.conf +++ /dev/null @@ -1,257 +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} - -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 - - -* {{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. - -First, you have to install the {{http}} feature: - -{code} -karaf@root()> feature:install http -{code} - -Now, you can install directly the Jolokia bundle: - -{code} -karaf@root()> bundle:install -s mvn:org.jolokia/jolokia-osgi/1.1.5 -{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":1387552680,"status":200,"request":{"type":"version"},"value":{"protocol":"7.0","agent":"1.1.5","info":{"product":"felix","vendor":"Apache","version":"4.2.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 -d "{\"type\":\"read\",\"mbean\":\"java.lang:type=Memory\",\"attribute\":\"HeapMemoryUsage\",\"path\":\"used\"}" http://localhost:8080/jolokia/ && echo "" -{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/9f08eb9e/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 788189d..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.10.0.SNAPSHOT -activemq-camel | org.apache.activemq.activemq-camel | 5.10.0.SNAPSHOT -activemq-karaf | activemq-karaf | 5.10.0.SNAPSHOT -activemq-osgi | org.apache.activemq.activemq-osgi | 5.10.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/3.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/3.0.0/org.apache.karaf.wrapper.core-3.0.0.jar -size: 1281352 -version: 3.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=3.0.0} - service:{service=org.apache.karaf.wrapper.WrapperService} - package:{package=org.apache.karaf.wrapper, version=3.0.0} - package:{package=org.apache.karaf.wrapper.management, uses:=javax.management, version=3.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 3.0.0: - -{code} -karaf@root()> obr:info org.apache.karaf.wrapper.core,3.0.0 -... -{code} - -You can specific multiple bundles separated by space: - -{code} -karaf@root()> obr:info org.apache.karaf.wrapper.core,3.0.0 org.apache.karaf.wrapper.command,3.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 3.0.0: - -{code} -karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core,3.0.0 -{code} - -You can specify multiple bundles separated by space: - -{code} -karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core,3.0.0 org.apache.karaf.wrapper.command,3.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 (3.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/3.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/3.0.0/org.apache.karaf.wrapper.core-3.0.0.jar -size: 1281352 -version: 3.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=3.0.0} - service:{service=org.apache.karaf.wrapper.WrapperService} - package:{package=org.apache.karaf.wrapper, version=3.0.0} - package:{package=org.apache.karaf.wrapper.management, uses:=javax.management, version=3.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 3.0.0: - -{code} -karaf@root()> obr:deploy org.apache.karaf.wrapper.core,3.0.0 -{code} - -You can specify multiple bundles separated by space: - -{code} -karaf@root()> obr:deploy org.apache.karaf.wrapper.core,3.0.0 org.apache.karaf.wrapper.command,3.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 3.0.0: - -{code} -karaf@root()> obr:start org.apache.karaf.wrapper.core,3.0.0 -{code} - -You can specify multiple bundles separated by space: - -{code} -karaf@root()> obr:start org.apache.karaf.wrapper.core,3.0.0 org.apache.karaf.wrapper.command,3.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. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/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 4293465..0000000 --- a/manual/src/main/webapp/users-guide/provisioning-schema.conf +++ /dev/null @@ -1,32 +0,0 @@ -h1. Features XML Schemas (provisioning) - -Apache Karaf 3.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.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.2.0] -* [http://karaf.apache.org/xmlns/features/v1.1.0] -* [http://karaf.apache.org/xmlns/features/v1.0.0] - -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} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/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 a0a7f8d..0000000 --- a/manual/src/main/webapp/users-guide/provisioning.conf +++ /dev/null @@ -1,585 +0,0 @@ -h1. Provisioning - -Apache Karaf is OSGi powered container. - -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. - -Deploying all the requirements (bundles and configurations) of an application into a container is called the "provisioning". - -As we can see, the provisioning of an application can be very long and fastidious. - -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. - -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.2.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 - -Right now, Apache Karaf doesn't provide complete upgrade cycle for features. - -Basically, a feature upgrade means: - -* Uninstall the features first (eventually providing the feature version to uninstall), and the features repository. -* Register the new version of the features repository and install the features with the target version. - -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. Start and stop - -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} - -{warning} -Before Apache Karaf 3.0.0 the start-level was not considered during the feature startup, but only the order in which bundles -are defined in your feature.xml. -Starting with Apache Karaf 3.0.0, the start-level is considered correctly. -If you need to use the old behavior you can uncomment and set the {{respectStartLvlDuringFeatureStartup}} property to false in -{{etc/org.apache.karaf.features.xml}} configuration file. -Note that it will be removed in 4.0 and should therefore be used only temporarily. -{warning} - -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. The location is relative from the {{KARAF_BASE}} variable. 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). - -h2. Feature resolver - -A feature accepts a {{resolver}} attribute: - -{code:lang=xml} -<feature name="my-project" version="1.0.0" resolver="(obr)"> -... -</feature> -{code} - -This {{resolver}} attribute forces the usage of a specific resolver, instead of the default resolution process. - -A resolver is used to obtain the list of bundles to install, when installing the feature. - -The default resolver simply returns the list of bundles as described by the {{<bundle/>}} elements in a feature. - -You can install a OBR (OSGi Bundle Repository) resolver instead of the default one. -The OBR resolver use the OBR service to get the list of bundles to install (see the [OBR section|obr] of the user guide for details). - -h2. Commands - -h3. {{feature:repo-list}} - -The {{feature:repo-list}} command lists all registered features repository: - -{code} -karaf@root()> feature:repo-list -Repository | URL ------------------------------------------------------------------------------------------------- -standard-3.0.0 | mvn:org.apache.karaf.features/standard/3.0.0/xml/features -enterprise-3.0.0 | mvn:org.apache.karaf.features/enterprise/3.0.0/xml/features -org.ops4j.pax.web-3.0.5 | mvn:org.ops4j.pax.web/pax-web-features/3.0.5/xml/features -spring-3.0.0 | mvn:org.apache.karaf.features/spring/3.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 ------------------------------------------------------------------------------------------------- -standard-3.0.0 | mvn:org.apache.karaf.features/standard/3.0.0/xml/features -org.ops4j.pax.web-3.0.5 | mvn:org.ops4j.pax.web/pax-web-features/3.0.5/xml/features -enterprise-3.0.0 | mvn:org.apache.karaf.features/enterprise/3.0.0/xml/features -spring-3.0.0 | mvn:org.apache.karaf.features/spring/3.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 -# - -cellar = org.apache.karaf.cellar:apache-karaf-cellar:xml:features:(0,] -camel = org.apache.camel.karaf:apache-camel:xml:features:(0,] -camel-extras = org.apache-extras.camel-extra.karaf:camel-extra:xml:features:(0,] -cxf = org.apache.cxf.karaf:apache-cxf:xml:features:(0,] -cxf-dosgi = org.apache.cxf.dosgi:cxf-dosgi:xml:features:(0,] -activemq = org.apache.activemq:activemq-karaf:xml:features:(0,] -jclouds = org.jclouds.karaf:jclouds-karaf:xml:features:(0,] -openejb = org.apache.openejb:openejb-feature:xml:features:(0,] -wicket = org.ops4j.pax.wicket:features:xml:features:(0,] -hawtio = io.hawt:hawtio-karaf:xml:features:(0,] -{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 2.3.1 -Adding feature url mvn:org.apache.karaf.cellar/apache-karaf-cellar/2.3.1/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/2.3.1/xml/features -Adding feature url mvn:org.apache.karaf.cellar/apache-karaf-cellar/2.3.1/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.apache.karaf.features/standard/3.0.0/xml/features -Refreshing feature url mvn:org.apache.karaf.features/enterprise/3.0.0/xml/features -Refreshing feature url mvn:org.ops4j.pax.web/pax-web-features/3.0.4/xml/features -Refreshing feature url mvn:org.apache.karaf.features/spring/3.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/3.0.0-SNAPSHOT/xml/features -Refreshing feature url mvn:org.apache.karaf.features/standard/3.0.0-SNAPSHOT/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-3.0.0 -{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-3.0.0 -{code} - -h3. {{feature:list}} - -The {{feature:list}} command lists all available features (provided by the different registered features repositories): - -{code} -karaf@root()> feature:list -Name | Version | Installed | Repository | Description --------------------------------------------------------------------------------------------------------------------------------------------- -standard | 3.0.0 | x | standard-3.0.0 | Karaf standard feature -aries-annotation | 3.0.0 | | standard-3.0.0 | Aries Annotations -wrapper | 3.0.0 | | standard-3.0.0 | Provide OS integration -service-wrapper | 3.0.0 | | standard-3.0.0 | Provide OS integration (alias to wrapper feature) -obr | 3.0.0 | | standard-3.0.0 | Provide OSGi Bundle Repository (OBR) support -config | 3.0.0 | x | standard-3.0.0 | Provide OSGi ConfigAdmin support -region | 3.0.0 | x | standard-3.0.0 | Provide Region 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 | Installed | Repository | Description --------------------------------------------------------------------------------------------------------------------------------------------- -aries-annotation | 3.0.0-SNAPSHOT | | standard-3.0.0-SNAPSHOT | Aries Annotations -blueprint-web | 3.0.0-SNAPSHOT | | standard-3.0.0-SNAPSHOT | Provides an OSGI-aware Servlet ContextListener for -config | 3.0.0-SNAPSHOT | x | standard-3.0.0-SNAPSHOT | Provide OSGi ConfigAdmin support -eventadmin | 3.0.0-SNAPSHOT | | standard-3.0.0-SNAPSHOT | OSGi Event Admin service specification for event-b -http | 3.0.0-SNAPSHOT | | standard-3.0.0-SNAPSHOT | Implementation of the OSGI HTTP Service -http-whiteboard | 3.0.0-SNAPSHOT | | standard-3.0.0-SNAPSHOT | Provide HTTP Whiteboard pattern 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 | Installed | Repository | Description ----------------------------------------------------------------------------------------------------------------------- -standard | 3.0.0 | x | standard-3.0.0 | Karaf standard feature -config | 3.0.0 | x | standard-3.0.0 | Provide OSGi ConfigAdmin support -region | 3.0.0 | x | standard-3.0.0 | Provide Region Support -package | 3.0.0 | x | standard-3.0.0 | Package commands and mbeans -kar | 3.0.0 | x | standard-3.0.0 | Provide KAR (KARaf archive) support -ssh | 3.0.0 | x | standard-3.0.0 | Provide a SSHd server on Karaf -management | 3.0.0 | x | standard-3.0.0 | Provide a JMX MBeanServer and a set of MBeans in K -{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} - -{code} -karaf@root()> feature:install eventadmin/3.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 -Installing feature eventadmin 3.0.0 -Found installed bundle: org.apache.felix.eventadmin [80] -{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 -Installing feature eventadmin 3.0.0 -Installing bundle mvn:org.apache.felix/org.apache.felix.eventadmin/1.3.2 -{code} - -If the installation of a failure fails (for any reason), by default, Apache Karaf will uninstall all bundles installed by the feature. -It will go back in the state before the installation of the feature. - -If you want to keep the bundles in the feature successfully installed, you can use the {{-c}} option. Even if the complete feature -installation fails, the feature successfully installed bundles remain installed. - -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} - -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.2.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation="http://karaf.apache.org/xmlns/features/v1.2.0 http://karaf.apache.org/xmlns/features/v1.2.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). \ No newline at end of file
