You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@karaf.apache.org by an...@apache.org on 2015/01/25 12:57:10 UTC
[3/5] karaf git commit: show alternative documentation solution with
asciidoc
http://git-wip-us.apache.org/repos/asf/karaf/blob/677c6d46/manual/src/main/asciidoc/users-guide/jta.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/users-guide/jta.adoc b/manual/src/main/asciidoc/users-guide/jta.adoc
new file mode 100644
index 0000000..e8f473b
--- /dev/null
+++ b/manual/src/main/asciidoc/users-guide/jta.adoc
@@ -0,0 +1,105 @@
+= Transaction (JTA)
+
+Apache Karaf provides container managed transactions, available as OSGi services.
+
+As most of the enterprise features, it's an optional feature that you can install with:
+
+----
+karaf@root()> feature:install transaction
+----
+
+However, the `transaction` feature is installed (as a transitive dependency) when installing enterprise features
+(like `jdbc` or `jms` features for instance).
+
+== Apache Aries Transaction and ObjectWeb HOWL
+
+The `transaction` feature uses Apache Aries and ObjectWeb HOWL. Aapache Aries Transaction "exposes" the transaction
+manager as OSGi service. The actual implementation of the transaction manager is ObjectWeb HOWL.
+
+ObjectWeb HOWL is a logger implementation providing features required by the ObjectWeb JOTM project, with a public API
+that is generally usable by any Transaction Manager.
+ObjectWeb HOWL uses unformatted binary logs to maximize performance and specifies a journalization API with methods
+necessary to support JOTM recovery operations.
+
+ObjectWeb HOWL is intended to be used for logging of temporary data such as XA transaction events.
+It is not a replacement for traditional log kits such as LOG4J and Java SE Logging.
+
+In Apache Karaf, ObjectWeb HOWL (High-speed ObjectWeb Logger) is used to implement TransactionLog (in Aries Transaction),
+providing a very performant transaction manager in an OSGi way.
+
+== Configuration
+
+The installation of the `transaction` feature installs a new configuration: `org.apache.aries.transaction`.
+
+You can see the configuration properties using:
+
+----
+karaf@root()> config:list "(service.pid=org.apache.aries.transaction)"
+----------------------------------------------------------------
+Pid: org.apache.aries.transaction
+BundleLocation: mvn:org.apache.aries.transaction/org.apache.aries.transaction.manager/1.1.0
+Properties:
+ aries.transaction.recoverable = true
+ aries.transaction.timeout = 600
+ service.pid = org.apache.aries.transaction
+ org.apache.karaf.features.configKey = org.apache.aries.transaction
+ aries.transaction.howl.maxBlocksPerFile = 512
+ aries.transaction.howl.maxLogFiles = 2
+ aries.transaction.howl.logFileDir = /opt/apache-karaf-3.0.0/data/txlog
+ aries.transaction.howl.bufferSizeKBytes = 4
+----
+
+* `aries.transaction.recoverable` property is a flag to enable support of recoverable resource or not. A recoverable
+ resource is a transactional object whose state is saved to stable storage if the transaction is committed, and whose
+ state can be reset to what it was at the beginning of the transaction if the transaction is rolled back.
+ At commit time, the transaction manager uses the two-phase XA protocol when communicating with the recoverable resource
+ to ensure transactional integrity when more than one recoverable resource is involved in the transaction being committed.
+ Transactional databases and message brokers like Apache ActiveMQ are examples of recoverable resources.
+ A recoverable resource is represented using the javax.transaction.xa.XAResource interface in JTA.
+ Default is `true`.
+* `aries.transaction.timeout` property is the transaction timeout. If a transaction has a lifetime longer than this timeout
+ a transaction exception is raised and the transaction is rollbacked. Default is `600` (10 minutes).
+* `aries.transaction.howl.logFileDir` property is the directory where the transaction logs (journal) are stored.
+ Default is `KARAF_DATA/txlog`.
+* `aries.transaction.howl.maxLogFiles` property is the maximum number of transaction log files to retain. Combined with the
+ `aries.transaction.howl.maxBlocksPerFile`, it defines the transaction retention.
+
+You can change the configuration directly using the `config:*` commands, or the Config MBean.
+
+For instance, to increase the transaction timeout, you can do:
+
+----
+karaf@root()> config:edit org.apache.aries.transaction
+karaf@root()> config:property-set aries.transaction.timeout 1200
+karaf@root()> config:update
+karaf@root()> config:list "(service.pid=org.apache.aries.transaction)"
+----------------------------------------------------------------
+Pid: org.apache.aries.transaction
+BundleLocation: mvn:org.apache.aries.transaction/org.apache.aries.transaction.manager/1.1.0
+Properties:
+ aries.transaction.recoverable = true
+ aries.transaction.timeout = 1200
+ service.pid = org.apache.aries.transaction
+ org.apache.karaf.features.configKey = org.apache.aries.transaction
+ aries.transaction.howl.maxBlocksPerFile = 512
+ aries.transaction.howl.maxLogFiles = 2
+ aries.transaction.howl.logFileDir = /opt/apache-karaf-3.0.0/data/txlog
+ aries.transaction.howl.bufferSizeKBytes = 4
+----
+
+{warning}
+The `transaction` feature defines the configuration in memory by default. It means that changes that you can do will
+be lost in case of Apache Karaf restart.
+If you want to define your own transaction configuration at startup, you have to create a `etc/org.apache.aries.transaction.cfg`
+configuration file and set the properties and values in the file. For instance:
+
+----
+# etc/org.apache.aries.transaction.cfg
+aries.transaction.recoverable = true
+aries.transaction.timeout = 1200
+aries.transaction.howl.maxBlocksPerFile = 512
+aries.transaction.howl.maxLogFiles = 2
+aries.transaction.howl.logFileDir = /opt/apache-karaf-3.0.0/data/txlog
+aries.transaction.howl.bufferSizeKBytes = 4
+----
+{warning}
http://git-wip-us.apache.org/repos/asf/karaf/blob/677c6d46/manual/src/main/asciidoc/users-guide/kar.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/users-guide/kar.adoc b/manual/src/main/asciidoc/users-guide/kar.adoc
new file mode 100644
index 0000000..12f2ff0
--- /dev/null
+++ b/manual/src/main/asciidoc/users-guide/kar.adoc
@@ -0,0 +1,297 @@
+= KAR
+
+As described in the [Provisioning section|provisioning], Apache Karaf features describe applications.
+
+A feature defines different resources to resolve using URL (for instance, bundles URLs, or configuration files URLs).
+As described in the [Artifacts repositories and URLs section|urls], Apache Karaf looks for artifacts (bundles,
+configuration files, ...) in the artifact repositories.
+Apache Karaf may require to download artifacts from remote repositories.
+
+Apache Karaf provides a special type of artifact that package a features XML and all resources described in the features
+of this XML. This artifact is named a KAR (KAraf aRchive).
+
+A KAR file is a zip archive containing the
+
+Basically, the kar format is a jar (so a zip file) which contains a set of feature descriptor and bundle jar files.
+
+A KAR file contains a `repository` folder containing:
+
+* a set of features XML files
+* the artifacts following the Maven directory structure (`groupId/artifactId/version/artifactId-version.type`).
+
+For instance, the `spring-3.0.0.kar` contains:
+
+----
+~$ unzip -l spring-3.0.0.kar
+Archive: spring-3.0.0.kar
+ Length Date Time Name
+--------- ---------- ----- ----
+ 143 2013-12-06 10:52 META-INF/MANIFEST.MF
+ 12186 2013-12-06 10:52 repository/org/apache/karaf/features/spring/3.0.0/spring-3.0.0-features.xml
+ 575389 2013-12-06 10:52 repository/commons-collections/commons-collections/3.2.1/commons-collections-3.2.1.jar
+ 232019 2013-12-06 10:52 repository/commons-beanutils/commons-beanutils/1.8.3/commons-beanutils-1.8.3.jar
+ 673109 2013-12-06 10:52 repository/org/apache/servicemix/bundles/org.apache.servicemix.bundles.struts/1.3.10_1/org.apache.servicemix.bundles.struts-1.3.10_1.jar
+ 37084 2013-12-06 10:52 repository/org/springframework/org.springframework.web.struts/3.2.4.RELEASE/org.springframework.web.struts-3.2.4.RELEASE.jar
+ 7411 2013-12-06 10:52 repository/org/springframework/org.springframework.instrument/3.2.4.RELEASE/org.springframework.instrument-3.2.4.RELEASE.jar
+ 246881 2013-12-06 10:52 repository/org/springframework/org.springframework.transaction/3.2.4.RELEASE/org.springframework.transaction-3.2.4.RELEASE.jar
+ 16513 2013-12-06 10:52 repository/org/apache/servicemix/bundles/org.apache.servicemix.bundles.aopalliance/1.0_6/org.apache.servicemix.bundles.aopalliance-1.0_6.jar
+ 881124 2013-12-06 10:52 repository/org/springframework/org.springframework.core/3.2.4.RELEASE/org.springframework.core-3.2.4.RELEASE.jar
+ 199240 2013-12-06 10:52 repository/org/springframework/org.springframework.expression/3.2.4.RELEASE/org.springframework.expression-3.2.4.RELEASE.jar
+ 614646 2013-12-06 10:52 repository/org/springframework/org.springframework.beans/3.2.4.RELEASE/org.springframework.beans-3.2.4.RELEASE.jar
+ 340841 2013-12-06 10:52 repository/org/springframework/org.springframework.aop/3.2.4.RELEASE/org.springframework.aop-3.2.4.RELEASE.jar
+ 877369 2013-12-06 10:52 repository/org/springframework/org.springframework.context/3.2.4.RELEASE/org.springframework.context-3.2.4.RELEASE.jar
+ 130224 2013-12-06 10:52 repository/org/springframework/org.springframework.context.support/3.2.4.RELEASE/org.springframework.context.support-3.2.4.RELEASE.jar
+ 30640 2013-12-06 10:52 repository/org/apache/karaf/deployer/org.apache.karaf.deployer.spring/3.0.0/org.apache.karaf.deployer.spring-3.0.0.jar
+ 51951 2013-12-06 10:52 repository/org/springframework/org.springframework.aspects/3.2.4.RELEASE/org.springframework.aspects-3.2.4.RELEASE.jar
+ 411175 2013-12-06 10:52 repository/org/springframework/org.springframework.jdbc/3.2.4.RELEASE/org.springframework.jdbc-3.2.4.RELEASE.jar
+ 48049 2013-12-06 10:52 repository/javax/portlet/portlet-api/2.0/portlet-api-2.0.jar
+ 190883 2013-12-06 10:52 repository/org/springframework/org.springframework.web.portlet/3.2.4.RELEASE/org.springframework.web.portlet-3.2.4.RELEASE.jar
+ 635680 2013-12-06 10:52 repository/org/springframework/org.springframework.web/3.2.4.RELEASE/org.springframework.web-3.2.4.RELEASE.jar
+ 645946 2013-12-06 10:52 repository/org/springframework/org.springframework.web.servlet/3.2.4.RELEASE/org.springframework.web.servlet-3.2.4.RELEASE.jar
+ 464911 2013-12-06 10:52 repository/org/springframework/org.springframework.test/3.2.4.RELEASE/org.springframework.test-3.2.4.RELEASE.jar
+ 69784 2013-12-06 10:52 repository/org/springframework/osgi/spring-osgi-web/1.2.1/spring-osgi-web-1.2.1.jar
+ 16030 2013-12-06 10:52 repository/org/apache/geronimo/specs/geronimo-jta_1.1_spec/1.1.1/geronimo-jta_1.1_spec-1.1.1.jar
+ 32359 2013-12-06 10:52 repository/org/apache/geronimo/specs/geronimo-jms_1.1_spec/1.1.1/geronimo-jms_1.1_spec-1.1.1.jar
+ 208684 2013-12-06 10:52 repository/org/springframework/org.springframework.jms/3.2.4.RELEASE/org.springframework.jms-3.2.4.RELEASE.jar
+ 75672 2013-12-06 10:52 repository/org/springframework/org.springframework.oxm/3.2.4.RELEASE/org.springframework.oxm-3.2.4.RELEASE.jar
+ 393607 2013-12-06 10:52 repository/org/springframework/org.springframework.orm/3.2.4.RELEASE/org.springframework.orm-3.2.4.RELEASE.jar
+ 338559 2013-12-06 10:52 repository/org/apache/servicemix/bundles/org.apache.servicemix.bundles.cglib/3.0_1/org.apache.servicemix.bundles.cglib-3.0_1.jar
+ 35859 2013-12-06 10:52 repository/org/springframework/osgi/spring-osgi-io/1.2.1/spring-osgi-io-1.2.1.jar
+ 362889 2013-12-06 10:52 repository/org/springframework/osgi/spring-osgi-core/1.2.1/spring-osgi-core-1.2.1.jar
+ 120822 2013-12-06 10:52 repository/org/springframework/osgi/spring-osgi-extender/1.2.1/spring-osgi-extender-1.2.1.jar
+ 24231 2013-12-06 10:52 repository/org/springframework/osgi/spring-osgi-annotation/1.2.1/spring-osgi-annotation-1.2.1.jar
+ 12597 2013-12-06 10:52 repository/org/apache/karaf/bundle/org.apache.karaf.bundle.springstate/3.0.0/org.apache.karaf.bundle.springstate-3.0.0.jar
+ 31903 2013-12-06 10:52 repository/org/eclipse/gemini/blueprint/gemini-blueprint-io/1.0.0.RELEASE/gemini-blueprint-io-1.0.0.RELEASE.jar
+ 578205 2013-12-06 10:52 repository/org/eclipse/gemini/blueprint/gemini-blueprint-core/1.0.0.RELEASE/gemini-blueprint-core-1.0.0.RELEASE.jar
+ 178525 2013-12-06 10:52 repository/org/eclipse/gemini/blueprint/gemini-blueprint-extender/1.0.0.RELEASE/gemini-blueprint-extender-1.0.0.RELEASE.jar
+--------- -------
+ 9803140 38 files
+----
+
+As a KAR file is a simple zip file, you can create the KAR file by hand.
+
+For instance, the following Unix commands create a very simple KAR file:
+
+----
+~$ mkdir repository
+~$ cp /path/to/features.xml repository/features.xml
+~$ cp /path/to/my.jar repository/my/project/my/1.0.0/my-1.0.0.jar
+~$ zip -r my.kar repository
+updating: repository/ (stored 0%)
+ adding: repository/my/project/my/1.0.0/my-1.0.0.jar (deflated 0%)
+----
+
+You can create KAR files using Apache Maven, or directly in the Apache Karaf console.
+
+== Maven
+
+Apache Karaf provides a Maven plugin: `karaf-maven-plugin`.
+
+The Apache Karaf Maven plugin provides the `features-create-kar` goal.
+
+The `features-create-kar` goal does:
+1. Reads all features specified in the features XML.
+2. For each feature described in the features XML, the goal resolves the bundles described in the feature.
+3. The goal finally packages the features XML, and the resolved bundles in a zip file.
+
+You can also use the Karaf maven plugin. The features maven plugin provides an features-create-kar goal.
+
+The features-create-kar goal:
+1. Reads all features specified in the features descriptor.
+2. For each feature, it resolves the bundles defined in the feature.
+3. All bundles are packaged into the kar archive.
+
+For instance, the following Maven POM create `my-kar.kar`
+
+For instance, you can use the following POM to create a kar:
+
+{code:lang=xml}
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>my.groupId</groupId>
+ <artifactId>my-kar</artifactId>
+ <version>1.0</version>
+ <packaging>pom</packaging>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.karaf.tooling</groupId>
+ <artifactId>karaf-maven-plugin</artifactId>
+ <version>3.0.0</version>
+ <executions>
+ <execution>
+ <id>features-create-kar</id>
+ <goals>
+ <goal>features-create-kar</goal>
+ </goals>
+ <configuration>
+ <featuresFile>src/main/resources/features.xml</featuresFile>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+
+</project>
+----
+
+To create the KAR file, simply type:
+
+----
+~$ mvn install
+----
+
+Uou will have your kar in the `target` directory.
+
+== Commands
+
+Apache Karaf provides `kar:*` commands to manage KAR archives.
+
+=== `kar:list`
+
+The `kar:list` command lists the installed KAR archives.
+
+----
+karaf@root()> kar:list
+KAR Name
+-------------------
+my-kar-1.0-SNAPSHOT
+----
+
+A KAR is identified by its name.
+
+=== `kar:create`
+
+Instead of using the `karaf-maven-plugin` or create the KAR archive by hand, you can use the `kar:create` command.
+
+The `kar:create` command creates a KAR file using a registered features repository.
+
+For instance, you want to create a KAR file for the Pax Web repository.
+
+The `feature:repo-list` command gives you the list of registered features repositories:
+
+----
+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
+spring-3.0.0 | mvn:org.apache.karaf.features/spring/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
+----
+
+You can use one of these features repositories to create the kar file:
+
+----
+karaf@root()> kar:create org.ops4j.pax.web-3.0.5
+Adding feature pax-war
+Adding feature pax-http-whiteboard
+Adding feature pax-jetty
+Adding feature pax-tomcat
+Adding feature pax-http
+Kar file created : /opt/apache-karaf-3.0.0/data/kar/org.ops4j.pax.web-3.0.5.kar
+----
+
+You can see that the KAR file has been created in the `KARAF_DATA/kar` folder.
+
+By default, the `kar:create` command creates a KAR file, packaging all features in the features descriptor.
+
+You can provide the list of features that you want to package into the KAR file:
+
+----
+karaf@root()> kar:create org.ops4j.pax.web-3.0.5 pax-jetty pax-tomcat
+Adding feature pax-jetty
+Adding feature pax-tomcat
+Kar file created : /opt/apache-karaf-3.0.0/data/kar/org.ops4j.pax.web-3.0.5.kar
+----
+
+=== `kar:install`
+
+You can deploy a KAR file using `kar:install` command.
+
+The `kar:install` command expects the KAR URL. Any URL described in the [Artifacts repositories and URLs section|urls]
+is supported by the `kar:install` command:
+
+----
+karaf@root()> kar:install file:/tmp/my-kar-1.0-SNAPSHOT.kar
+----
+
+The KAR file is uncompressed and populated the `KARAF_BASE/system` folder.
+
+The Apache Karaf KAR service is looking for features XML files in the KAR file, registers the features XML and automatically
+installs all features described in the features repositories present in the KAR file.
+
+=== `kar:uninstall`
+
+The `kar:uninstall` command uninstall a KAR file (identified by a name).
+
+By uninstall, it means that:
+
+* the features previously installed by the KAR file are uninstalled
+* delete (from the `KARAF_DATA/system` repository) all files previously "populated" by the KAR file
+
+For instance, to uninstall the previously installed `my-kar-1.0-SNAPSHOT.kar` KAR file:
+
+----
+karaf@root()> kar:uninstall my-kar-1.0-SNAPSHOT
+----
+
+== Deployer
+
+Apache Karaf also provides a KAR deployer. It means that you can drop a KAR file directly in the `deploy` folder.
+
+Apache Karaf will automatically install KAR files from the `deploy` folder.
+
+You can change the behaviours of the KAR deployer in the `etc/org.apache.karaf.kar.cfg`:
+
+----
+################################################################################
+#
+# 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.
+#
+################################################################################
+
+#
+# Enable or disable the refresh of the bundles when installing
+# the features contained in a KAR file
+#
+noAutoRefreshBundles=false
+----
+
+By default, when the KAR deployer install features, by default, it refresh the bundles already installed.
+You can disable the automatic bundles refresh by setting the `noAutoRefreshBundles` property to `false`.
+
+== JMX KarMBean
+
+On the JMX layer, you have a MBean dedicated to the management of the KAR files.
+
+The ObjectName to use is `org.apache.karaf:type=kar,name=*`.
+
+=== Attributes
+
+The `Kars` attributes provides the list of KAR files (name) installed.
+
+=== Operations
+
+* `install(url)` installs the KAR file at the given `url`.
+* `create(repository, features)` creates a KAR file using the given features `repository` name, and optionally the
+list of `features` to include in the KAR file.
+* `uninstall(name)` uninstalls a KAR file with the given `name`.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/karaf/blob/677c6d46/manual/src/main/asciidoc/users-guide/log.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/users-guide/log.adoc b/manual/src/main/asciidoc/users-guide/log.adoc
new file mode 100644
index 0000000..07db14a
--- /dev/null
+++ b/manual/src/main/asciidoc/users-guide/log.adoc
@@ -0,0 +1,551 @@
+= 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.
+
+== 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:
+
+----
+################################################################################
+#
+# 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
+----
+
+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`:
+
+----
+log4j.rootLogger=INFO, out, stdout, osgi:*
+----
+
+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).
+
+== 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:
+
+=== `log:clear`
+
+The `log:clear` command clears the log entries.
+
+=== `log:display`
+
+The `log:display` command displays the log entries.
+
+By default, it displays the log entries of the `rootLogger`:
+
+----
+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
+----
+
+You can also display the log entries from a specific logger, using the `logger` argument:
+
+----
+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
+----
+
+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:
+
+----
+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
+----
+
+You can also limit the number of entries stored and retain using the `size` property in `etc/org.apache.karaf.log.cfg` file:
+
+----
+#
+# 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
+----
+
+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`.
+
+----
+#
+# 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
+----
+
+You can also change the pattern dynamically (for one execution) using the `-p` option:
+
+----
+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
+----
+
+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.
+
+=== `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.
+
+=== `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:
+
+----
+karaf@root()> log:get
+Logger | Level
+--------------
+ROOT | INFO
+----
+
+You can specify a particular logger using the `logger` argument:
+
+----
+karaf@root()> log:get ssh
+Logger | Level
+--------------
+ssh | INFO
+----
+
+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:
+
+----
+log4j.logger.my.logger = DEBUG
+----
+
+you can see the list of loggers with the corresponding log level:
+
+----
+karaf@root()> log:get ALL
+Logger | Level
+-----------------
+ROOT | INFO
+my.logger | DEBUG
+----
+
+The `log:list` command is an alias to `log:get ALL`.
+
+=== `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:
+
+----
+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
+----
+
+By default, the log level is INFO, but you can specify a different log level using the `-l` option:
+
+----
+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
+----
+
+=== `log:set`
+
+The `log:set` command sets the log level of a logger.
+
+By default, it changes the log level of the `rootLogger`:
+
+----
+karaf@root()> log:set DEBUG
+karaf@root()> log:get
+Logger | Level
+--------------
+ROOT | DEBUG
+----
+
+You can specify a particular logger using the `logger` argument, after the `level` one:
+
+----
+karaf@root()> log:set INFO my.logger
+karaf@root()> log:get my.logger
+Logger | Level
+-----------------
+my.logger | INFO
+----
+
+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):
+
+----
+rootLogger=INFO,out,osgi:*
+my.logger=INFO,appender1
+my.logger.custom=DEBUG,appender2
+----
+
+You can change the level of `my.logger.custom` logger:
+
+----
+karaf@root()> log:set INFO my.logger.custom
+----
+
+Now we have:
+
+----
+rootLogger=INFO,out,osgi:*
+my.logger=INFO,appender1
+my.logger.custom=INFO,appender2
+----
+
+You can use the DEFAULT keyword on `my.logger.custom` logger to remove the level:
+
+----
+karaf@root()> log:set DEFAULT my.logger.custom
+----
+
+Now we have:
+
+----
+rootLogger=INFO,out,osgi:*
+my.logger=INFO,appender1
+my.logger.custom=appender2
+----
+
+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:
+
+----
+karaf@root()> log:set DEFAULT my.logger
+----
+
+We have:
+
+----
+rootLogger=INFO,out,osgi:*
+my.logger=appender1
+my.logger.custom=appender2
+----
+
+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.
+
+=== `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`:
+
+----
+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
+----
+
+To exit from the `log:tail` command, just type CTRL-C.
+
+== 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=*`.
+
+=== Attributes
+
+* `Level` attribute is the level of the ROOT logger.
+
+=== 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.
+
+== Advanced configuration
+
+=== 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:
+
+----
+log4j.appender.[appender-name].filter.[filter-name]=[filter-class]
+log4j.appender.[appender-name].filter.[filter-name].[option]=[value]
+----
+
+For instance, you can use the `f1` LevelRangeFilter on the `out` default appender:
+
+----
+log4j.appender.out.filter.f1=org.apache.log4j.varia.LevelRangeFilter
+log4j.appender.out.filter.f1.LevelMax=FATAL
+log4j.appender.out.filter.f1.LevelMin=DEBUG
+----
+
+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).
+
+=== 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:
+
+----
+log4j.appender.[appender-name].appenders=[comma-separated-list-of-appender-names]
+----
+
+For instance, you can create a AsyncAppender named `async` and asynchronously dispatch the log events to a JMS appender:
+
+----
+log4j.appender.async=org.apache.log4j.AsyncAppender
+log4j.appender.async.appenders=jms
+
+log4j.appender.jms=org.apache.log4j.net.JMSAppender
+...
+----
+
+=== 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:
+
+----
+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]
+----
+
+=== 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:
+
+----
+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
+----
+
+=== 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:
+
+----
+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]
+----
+
+=== 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`:
+
+----
+public class MyAppender extends AppenderSkeleton {
+...
+}
+----
+
+You compile and package as an OSGi bundle containing a MANIFEST looking like:
+
+----
+Manifest:
+Bundle-SymbolicName: org.mydomain.myappender
+Fragment-Host: org.ops4j.pax.logging.pax-logging-service
+...
+----
+
+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/677c6d46/manual/src/main/asciidoc/users-guide/migration.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/users-guide/migration.adoc b/manual/src/main/asciidoc/users-guide/migration.adoc
new file mode 100644
index 0000000..57091a4
--- /dev/null
+++ b/manual/src/main/asciidoc/users-guide/migration.adoc
@@ -0,0 +1,52 @@
+= Migration from Karaf 2.x to 3.x
+
+This section shows the necessary changes you have to consider when upgrading karaf.
+
+== 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.
+
+== 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: |
+
+== 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/677c6d46/manual/src/main/asciidoc/users-guide/monitoring.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/users-guide/monitoring.adoc b/manual/src/main/asciidoc/users-guide/monitoring.adoc
new file mode 100644
index 0000000..ab940b2
--- /dev/null
+++ b/manual/src/main/asciidoc/users-guide/monitoring.adoc
@@ -0,0 +1,259 @@
+= 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.
+
+== 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:
+
+----
+service:jmx:rmi:///jndi/rmi://localhost:1099/karaf-root
+----
+
+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.
+
+== Configuration
+
+The Apache Karaf JMX management layer is configured in the `etc/org.apache.karaf.management.cfg` configuration file:
+
+----
+################################################################################
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+################################################################################
+
+#
+# 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
+----
+
+* `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.
+
+== MBeans
+
+Apache Karaf provides a bunch of MBeans.
+
+The MBeans object names have the same format:
+
+----
+org.apache.karaf:type=[feature],name=[instance]
+----
+
+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).
+
+== 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:
+
+----
+ # operation = role
+ test = admin
+ getVal = manager, viewer
+----
+
+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:
+----
+# etc/jmx.acl.java.lang.Memory.cfg
+ gc = manager
+----
+
+* Bundles with ID between 0 and 49 can be stopped only by an `admin`, other bundles can be stopped by a `manager`:
+----
+# etc/jmx.acl.org.apache.karaf.bundles.cfg
+ stop(java.lang.String)[/([1-4])?([0-9]/] = admin
+ stop = manager
+----
+
+The `etc/jmx.acl.cfg` configuration file contains the global configuration for the invocation on any MBean that
+doesn't have a specific configuration:
+
+----
+# etc/jmx.acl.cfg
+ list* = viewer
+ get* = viewer
+ is* = viewer
+ set* = admin
+ * = admin
+----
+
+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.
+
+== 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:
+
+----
+karaf@root()> feature:install jolokia
+----
+
+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:
+
+----
+{"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"`}
+----
+
+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:
+
+----
+{
+ "type":"read",
+ "mbean":"java.lang:type=Memory",
+ "attribute":"HeapMemoryUsage",
+ "path":"used"
+}
+----
+
+We can send this JSON request using `curl` and get the result:
+
+----
+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}
+----
+
+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/677c6d46/manual/src/main/asciidoc/users-guide/obr.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/users-guide/obr.adoc b/manual/src/main/asciidoc/users-guide/obr.adoc
new file mode 100644
index 0000000..60e6542
--- /dev/null
+++ b/manual/src/main/asciidoc/users-guide/obr.adoc
@@ -0,0 +1,359 @@
+= 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:
+
+----
+karaf@root()> feature:install obr
+----
+
+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.
+
+== 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.
+
+== Commands
+
+=== `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:
+
+----
+karaf@root()> obr:url-add file:///user/.m2/repository/repository.xml
+----
+
+=== `obr:url-list`
+
+The `obr:url-list` command lists the OBR repository (with URL) registered in the OBR service:
+
+----
+karaf@root()> obr:url-list
+Index | OBR URL
+---------------------------------------------------------
+0 | file:/user/.m2/repository/repository.xml
+----
+
+=== `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:
+
+----
+karaf@root()> obr:url-refresh
+----
+
+You can refresh only one repository by specifying the URL as argument:
+
+----
+karaf@root()> obr:url-refresh file:/user/.m2/repository/repository.xml
+----
+
+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:
+
+----
+karaf@root()> obr:url-refresh -i 0
+----
+
+=== `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:
+
+----
+karaf@root()> obr:url-remove file:/user/.m2/repository/repository.xml
+----
+
+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:
+
+----
+karaf@root()> obr:url-remove -i 0
+----
+
+=== `obr:list`
+
+The `obr:list` command lists all bundles available on the registered OBR repositories:
+
+----
+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
+...
+----
+
+=== `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:
+
+----
+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}
+----
+
+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:
+
+----
+karaf@root()> obr:info org.apache.karaf.wrapper.core,3.0.0
+...
+----
+
+You can specific multiple bundles separated by space:
+
+----
+karaf@root()> obr:info org.apache.karaf.wrapper.core,3.0.0 org.apache.karaf.wrapper.command,3.0.0
+...
+----
+
+=== `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:
+
+----
+karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core
+----
+
+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:
+
+----
+karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core,3.0.0
+----
+
+You can specify multiple bundles separated by space:
+
+----
+karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core,3.0.0 org.apache.karaf.wrapper.command,3.0.0
+...
+----
+
+=== `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:
+
+----
+karaf@root()> obr:resolve package=org.apache.karaf.wrapper
+Required resource(s):
+---------------------
+ Apache Karaf :: Wrapper :: Core (3.0.0)
+----
+
+=== `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:
+
+----
+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}
+----
+
+=== `obr:deploy`
+
+The `obr:deploy` command installs a bundle from the OBR repository, including all bundles required to satisfy the bundle requirements.
+
+----
+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.
+----
+
+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:
+
+----
+karaf@root()> obr:deploy org.apache.karaf.wrapper.core,3.0.0
+----
+
+You can specify multiple bundles separated by space:
+
+----
+karaf@root()> obr:deploy org.apache.karaf.wrapper.core,3.0.0 org.apache.karaf.wrapper.command,3.0.0
+...
+----
+
+== `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.
+
+----
+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.
+----
+
+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:
+
+----
+karaf@root()> obr:start org.apache.karaf.wrapper.core,3.0.0
+----
+
+You can specify multiple bundles separated by space:
+
+----
+karaf@root()> obr:start org.apache.karaf.wrapper.core,3.0.0 org.apache.karaf.wrapper.command,3.0.0
+...
+----
+
+== 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=*`.
+
+=== 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.
+
+=== 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.
+
+== 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/677c6d46/manual/src/main/asciidoc/users-guide/provisioning-schema.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/users-guide/provisioning-schema.adoc b/manual/src/main/asciidoc/users-guide/provisioning-schema.adoc
new file mode 100644
index 0000000..ea45211
--- /dev/null
+++ b/manual/src/main/asciidoc/users-guide/provisioning-schema.adoc
@@ -0,0 +1,32 @@
+= 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:
+
+----
+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
+----
+
+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]
+
+== 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}
+
+== 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}
+
+== 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