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:11 UTC
[4/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/deployers.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/users-guide/deployers.adoc b/manual/src/main/asciidoc/users-guide/deployers.adoc
new file mode 100644
index 0000000..2c346eb
--- /dev/null
+++ b/manual/src/main/asciidoc/users-guide/deployers.adoc
@@ -0,0 +1,272 @@
+= Deployers
+
+The following picture describes the architecture of the deployers.
+
+!/images/deployer.png!
+
+Apache Karaf polls the `deploy` folder for new files.
+
+You can configure the location of the `deploy` folder, and the polling behaviour in the `etc/org.apache.felix.fileinstall-deploy.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.
+#
+################################################################################
+
+felix.fileinstall.dir = ${karaf.base}/deploy
+felix.fileinstall.tmpdir = ${karaf.data}/generated-bundles
+felix.fileinstall.poll = 1000
+felix.fileinstall.start.level = 80
+felix.fileinstall.active.level = 80
+----
+
+* `felix.fileinstall.dir` defines the location of the `deploy` folder. Default value is `KARAF_BASE/deploy`.
+* `felix.fileinstall.tmpdir` defines a temporary folder where the deployers store their files. Default value is `KARAF_DATA/generated-bundles`.
+* `felix.fileinstall.poll` defines the polling interval (in milliseconds). Default value is 1 second.
+
+When Apache Karaf polls a file from the `deploy` folder, it "delegates" the file handling to a deployer.
+
+By default, Apache Karaf provides a set of deployers:
+
+* Blueprint deployer is able to handle Blueprint XML files.
+* Spring deployer is able to handle Spring XML files.
+* Features deployer is able to handle Apache Karaf features XML files (see [Provisioning section|provisioning] for details).
+* KAR deployer is able to handle KAR files (see [KAR section|kar] for details).
+* Wrap deployer is able to handle non-OSGi jar files and turns it as OSGi bundles "on the fly".
+* Optionally, WAR deployer (if you install the war feature) is able to handle WAR files.
+
+== Blueprint deployer
+
+The Blueprint deployer is able to handle plain Blueprint XML configuration files.
+
+The Blueprint deployer is able to transform "on the fly" any Blueprint XML file into valid OSGi bundle.
+
+The generated OSGi MANIFEST will contain the following headers:
+
+----
+Manifest-Version: 2
+Bundle-SymbolicName: [name of the file]
+Bundle-Version: [version of the file]
+Import-Package: [required packages]
+DynamicImport-Package: *
+----
+
+The `name` and `version` of the file are extracted using a heuristic that will match common patterns.
+
+For example `my-config-1.0.1.xml` will lead to `name = my-config` and `version = 1.0.1`.
+
+The default imported packages are extracted from the spring file definition and includes all classes referenced directly.
+
+If you need to customize the generated manifest, you can do so by including an xml element in your blueprint configuration:
+
+{code:lang=xml}
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
+ <manifest xmlns="http://karaf.apache.org/xmlns/deployer/blueprint/v1.0.0">
+ Require-Bundle= my-bundle
+ </manifest>
+----
+
+== Spring deployer
+
+The Spring deployer is similar to the Blueprint deployer.
+
+The Spring deployer is able to deploy Spring XML files.
+
+Like the Blueprint deployer, the generated OSGi MANIFEST will contain the following headers:
+
+----
+Manifest-Version: 2
+Bundle-SymbolicName: [name of the file]
+Bundle-Version: [version of the file]
+Spring-Context: *;publish-context:=false;create-asynchronously:=true
+Import-Package: [required packages]
+DynamicImport-Package: *
+----
+
+If you need to customize the generated manifest, you can do so by including a XML element in your Spring configuration:
+
+{code:lang=xml}
+<spring:beans ...>
+ <manifest xmlns="http://karaf.apache.org/xmlns/deployer/spring/v1.0.0">
+ Require-Bundle= my-bundle
+ </manifest>
+----
+
+== Features deployer
+
+See the [Provisioning section|provisioning] for details.
+
+== KAR deployer
+
+See the [KAR section|kar] for details.
+
+== War deployer
+
+The installation of the WAR feature enables a WAR deployer.
+
+It means that with the war feature installed, Apache Karaf is a complete OSGi WebContainer (like Tomcat) where
+you can deploy WAB (WebApplication Bundle) or pure WAR (WebApplication aRchive).
+
+You can install the war feature with:
+
+----
+karaf@root()> feature:install -v war
+Installing feature war 3.0.0
+Installing feature pax-war 3.0.5
+Installing feature pax-http-whiteboard 3.0.5
+Installing feature pax-http 3.0.5
+Installing feature pax-jetty 8.1.14.v20131031
+Found installed bundle: org.apache.servicemix.specs.activation-api-1.1 [81]
+Found installed bundle: org.apache.geronimo.specs.geronimo-servlet_3.0_spec [82]
+Found installed bundle: javax.mail [83]
+Found installed bundle: org.apache.geronimo.specs.geronimo-jta_1.1_spec [84]
+Found installed bundle: org.apache.geronimo.specs.geronimo-annotation_1.1_spec [85]
+Found installed bundle: org.apache.geronimo.specs.geronimo-jaspic_1.0_spec [86]
+Found installed bundle: org.apache.servicemix.bundles.asm [87]
+Found installed bundle: org.eclipse.jetty.aggregate.jetty-all-server [88]
+Checking configuration file mvn:org.ops4j.pax.web/pax-web-features/3.0.5/xml/jettyconfig
+Installing bundle mvn:org.ops4j.base/ops4j-base-lang/1.4.0
+Found installed bundle: org.ops4j.pax.swissbox.core [89]
+Found installed bundle: org.ops4j.pax.swissbox.optional.jcl [90]
+Found installed bundle: org.apache.xbean.bundleutils [91]
+Found installed bundle: org.apache.xbean.asm-shaded [92]
+Found installed bundle: org.apache.xbean.reflect [93]
+Found installed bundle: org.apache.xbean.finder-shaded [94]
+Found installed bundle: org.ops4j.pax.web.pax-web-api [95]
+Found installed bundle: org.ops4j.pax.web.pax-web-spi [96]
+Found installed bundle: org.ops4j.pax.web.pax-web-runtime [97]
+Found installed bundle: org.ops4j.pax.web.pax-web-jetty [98]
+Found installed bundle: org.ops4j.pax.web.pax-web-jsp [99]
+Found installed bundle: org.ops4j.pax.web.pax-web-extender-whiteboard [100]
+Installing bundle mvn:org.ops4j.pax.web/pax-web-jsp/3.0.5
+Found installed bundle: org.ops4j.pax.web.pax-web-extender-war [101]
+Installing bundle mvn:org.ops4j.pax.web/pax-web-extender-whiteboard/3.0.5
+Found installed bundle: org.ops4j.pax.web.pax-web-deployer [102]
+Found installed bundle: org.ops4j.pax.url.war [103]
+Found installed bundle: org.ops4j.pax.url.commons [104]
+Found installed bundle: org.ops4j.pax.swissbox.pax-swissbox-bnd [105]
+Found installed bundle: org.ops4j.pax.swissbox.property [106]
+Installing bundle mvn:org.ops4j.base/ops4j-base-net/1.4.0
+Installing bundle mvn:org.ops4j.base/ops4j-base-lang/1.4.0
+Installing bundle mvn:org.ops4j.base/ops4j-base-monitors/1.4.0
+Installing bundle mvn:org.ops4j.base/ops4j-base-util-property/1.4.0
+Found installed bundle: biz.aQute.bndlib [107]
+Found installed bundle: org.apache.karaf.web.core [108]
+Found installed bundle: org.apache.karaf.web.command [109]
+----
+
+We can note that the Pax Web deployer (WAR deployer) has been started:
+
+----
+...
+Found installed bundle: org.ops4j.pax.web.pax-web-deployer [102]
+...
+----
+
+The WAR deployer supports:
+
+* WAB files
+* WAR files
+* exploded WAR (as a directory named `*.war`).
+
+The only requirement of the WAR deployer is that the archive contains the `WEB-INF/web.xml` file.
+
+== Wrap deployer
+
+The wrap deployer allows you to "hot deploy" non-OSGi jar files ("classical" jar files) from the deploy folder.
+
+The wrap deployer creates "on the fly" an OSGi bundle with a non-OSGi jar file.
+
+The wrap deployer looks for jar files in the deploy folder. A jar file is considered as non-OSGi if the MANIFEST doesn't
+contain the `Bundle-SymbolicName` and `Bundle-Version` attributes, or if there is no MANIFEST at all.
+
+The wrap deployer "transforms" non-OSGi jar file into an OSGi bundle.
+
+The wrap deployer tries to populate the Bundle-SymbolicName and Bundle-Version extracted from the jar file path.
+
+For example, if you simply copy commons-lang-2.3.jar (which is not an OSGi bundle) into the deploy folder, you
+will see:
+
+----
+karaf@root()> la|grep -i commons-lang
+80 | Active | 80 | 2.3 | commons-lang
+----
+
+If you take a look on the commons-lang headers, you can see that the bundle exports all packages with optional resolution
+and that `Bundle-SymbolicName` and `Bundle-Version` have been populated:
+
+----
+karaf@root()> bundle:headers 80
+
+commons-lang (80)
+-----------------
+Specification-Title = Commons Lang
+Tool = Bnd-2.1.0.20130426-122213
+Specification-Version = 2.3
+Specification-Vendor = Apache Software Foundation
+Implementation-Version = 2.3
+Generated-By-Ops4j-Pax-From = wrap:file:/opt/apache-karaf-3.0.0/deploy/commons-lang-2.3.jar$Bundle-SymbolicName=commons-lang&Bundle-Version=2.3
+Implementation-Vendor-Id = org.apache
+Created-By = 1.7.0_21 (Oracle Corporation)
+Implementation-Title = Commons Lang
+Manifest-Version = 1.0
+Bnd-LastModified = 1386339925753
+X-Compile-Target-JDK = 1.1
+Originally-Created-By = 1.3.1_09-85 ("Apple Computer, Inc.")
+Ant-Version = Apache Ant 1.6.5
+Package = org.apache.commons.lang
+X-Compile-Source-JDK = 1.3
+Extension-Name = commons-lang
+Implementation-Vendor = Apache Software Foundation
+
+Bundle-Name = commons-lang
+Bundle-SymbolicName = commons-lang
+Bundle-Version = 2.3
+Bundle-ManifestVersion = 2
+
+Export-Package =
+ org.apache.commons.lang;uses:=org.apache.commons.lang.exception,
+ org.apache.commons.lang.builder,
+ org.apache.commons.lang.enum,
+ org.apache.commons.lang.enums,
+ org.apache.commons.lang.exception,
+ org.apache.commons.lang.math,
+ org.apache.commons.lang.mutable,
+ org.apache.commons.lang.text,
+ org.apache.commons.lang.time,
+ org,
+ org.apache,
+ org.apache.commons
+
+----
+
+You can specify some MANIFEST headers by specifying the headers as URL parameters.
+
+In the URL parameters, you can specify the headers using the '$' character and '&' to separate the different headers.
+For instance:
+
+----
+karaf@root()> bundle:install -s 'wrap:mvn:jboss/jbossall-client/4.2.3.GA/$Bundle-SymbolicName=jbossall-client&Bundle-Version=4.2.3.GA&Export-Package=org.jboss.remoting;version="4.2.3.GA",\!*'
+----
+
+When defined in a features.xml file, it's necessary to escape any ampersands and quotes, or use a CDATA tag:
+
+{code:lang=xml}
+<bundle>wrap:mvn:jboss/jbossall-client/4.3.2.GA/$Bundle-SymbolicName=jbossall-client&Bundle-Version=4.3.2.GA&Export-Package=org.jboss.remoting;version="4.3.2.GA",!*</bundle>
+----
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/karaf/blob/677c6d46/manual/src/main/asciidoc/users-guide/directory-structure.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/users-guide/directory-structure.adoc b/manual/src/main/asciidoc/users-guide/directory-structure.adoc
new file mode 100644
index 0000000..bdd5a91
--- /dev/null
+++ b/manual/src/main/asciidoc/users-guide/directory-structure.adoc
@@ -0,0 +1,20 @@
+= Directory structure
+
+The directory layout of a Karaf installation is as follows:
+
+* `/bin`: control scripts to start, stop, login, ...
+* `/etc`: configuration files
+* `/data`: working directory
+** `/cache`: OSGi framework bundle cache
+** `/generated-bundles`: temporary folder used by the deployers
+** `/log`: log files
+* `/deploy`: hot deploy directory
+* `/instances`: directory containing [instances|instances]
+* `/lib`: contains the bootstrap libraries
+** `/lib/ext`: directory for JRE extensions
+** `/lib/endorsed`: directory for endorsed libraries
+* `/system`: OSGi bundles repository, laid out as a Maven 2 repository
+
+TIP: The `data` folder contains all the working and temporary files for Karaf.
+If you want to restart from a clean state, you can wipe out this directory, which has the same effect as
+[using the clean option|start-stop#Starting Karaf from clean].
http://git-wip-us.apache.org/repos/asf/karaf/blob/677c6d46/manual/src/main/asciidoc/users-guide/ejb.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/users-guide/ejb.adoc b/manual/src/main/asciidoc/users-guide/ejb.adoc
new file mode 100644
index 0000000..4316062
--- /dev/null
+++ b/manual/src/main/asciidoc/users-guide/ejb.adoc
@@ -0,0 +1,80 @@
+= EJB
+
+This section describes how to add support of EJB in Apache Karaf. It doesn't describe how to develop EJB applications.
+See the developer guide for that.
+
+== Apache OpenEJB
+
+Apache Karaf doesn't provide "native" support of EJB (Enterprise Java Beans).
+
+Apache OpenEJB provides EJB support for Apache Karaf by providing a set of features.
+
+You have to update some Karaf configuration to have full OpenEJB support.
+
+First, in the `etc/system.properties`, you have to append the following properties:
+
+----
+...
+#
+# OpenEJB scanner
+#
+openejb.deployments.classpath.exclude=bundle:*
+openejb.deployments.classpath.filter.descriptors=true
+----
+
+Due to some OpenEJB version constraint, you also have to update the `etc/jre.properties` by changing the version of
+the `javax.xml.namespace` package, and remove the version of the `javax.annotation` package (provided by Geronimo
+Annotation API spec bundle, used by OpenEJB):
+
+----
+...
+javax.annotation, \
+javax.annotation.processing, \
+...
+javax.xml.namespace;version="1.0.0", \
+...
+----
+
+It enables the OpenEJB bundles scanning, looking for EJBs.
+
+After starting/restart Karaf to take these changes, we can install the OpenEJB feature:
+
+----
+karaf@root()> feature:repo-add openejb
+----
+
+By default, the `feature:repo-add openejb` command will install the latest OpenEJB version available.
+
+You can specify a target version using the `version` argument:
+
+----
+karaf@root()> feature:repo-add openejb 4.5.2
+----
+
+Now, you have a set of new OpenEJB features available in your Apache Karaf container:
+
+----
+karaf@root()> la
+...
+openejb-core | 4.5.2 | | openejb-features |
+openejb-server | 4.5.2 | | openejb-features |
+openejb-cxf | 4.5.2 | | openejb-features |
+openejb-rest | 4.5.2 | | openejb-features |
+openejb-soap | 4.5.2 | | openejb-features |
+----
+
+You can add EJB support installing the `openejb-core` feature:
+
+----
+karaf@root()> feature:install openejb-core
+----
+
+== Apache KarafEE
+
+A custom distribution of Apache Karaf embedding OpenEJB is available in the Apache TomEE project.
+
+The name of this custom distribution is KarafEE:
+
+[https://svn.apache.org/repos/asf/tomee/karafee/]
+
+However, this project is now "deprecated", and all resources from KarafEE will move directly in Apache Karaf soon.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/karaf/blob/677c6d46/manual/src/main/asciidoc/users-guide/enterprise.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/users-guide/enterprise.adoc b/manual/src/main/asciidoc/users-guide/enterprise.adoc
new file mode 100644
index 0000000..c2aaefc
--- /dev/null
+++ b/manual/src/main/asciidoc/users-guide/enterprise.adoc
@@ -0,0 +1,21 @@
+= Enterprise
+
+Apache Karaf provides a set of enterprise class features.
+
+These features are not installed by default, you have to install yourself depending of your needs.
+
+The enterprise features available are:
+
+* [Http Service|http] provide basic OSGi HttpServices
+* [WebContainer (JSP/Servlet)|webcontainer] providing a complete JSP/Servlet support. These feature turns Apache Karaf as a complete
+ web container where you can deploy web application (as you can do in Apache Tomcat, or other JEE application servers).
+* [Naming (JNDI)|jndi] providing a complete Java Naming and Directory Interface support. Apache Karaf provides a complete
+ JNDI "server" (context) where you can create name to identify Objects (especially OSGi services).
+* [Transaction (JTA)|jta] providing a complete transaction manager as an OSGi service.
+* [DataSources (JDBC)|jdbc] providing useful OSGi service, console commands, and MBean to manipulate JDBC datasources and perform database operations.
+* [MOM (JMS)|jms] providing useful OSGi service, console commands, and MBean to manipulate JMS connection factories and perform messaging operations.
+* [Persistence (JPA)|jpa] providing ready to use JPA engines and entity manager as an OSGi service.
+* [EJB|ejb] adding EJB support in Apache Karaf.
+* [CDI|cdi] providing ready to use CDI containers in Apache Karaf.
+* [HA/failover and cluster|failover] providing active/passive or active/active topologies with multiple Apache Karaf instances.
+
http://git-wip-us.apache.org/repos/asf/karaf/blob/677c6d46/manual/src/main/asciidoc/users-guide/failover.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/users-guide/failover.adoc b/manual/src/main/asciidoc/users-guide/failover.adoc
new file mode 100644
index 0000000..fa3f964
--- /dev/null
+++ b/manual/src/main/asciidoc/users-guide/failover.adoc
@@ -0,0 +1,229 @@
+= HA/failover and cluster
+
+Apache Karaf natively provides a failover mechanism. It uses a kind of master/slave topology where one instance is active
+and the others are in standby.
+
+If you are looking for cluster of Apache Karaf instances (active/active), [Apache Karaf Cellar|http://karaf.apache.org/index/subprojects/cellar.html] is a solution.
+
+Karaf provides failover capability using either a simple lock file or a JDBC locking mechanism.
+In both cases, a container-level lock system allows bundles to be preloaded into the slave Karaf instance in order to provide faster failover performance.
+
+== HA/failover (active/passive)
+
+The Apache Karaf failover capability uses a lock system.
+
+This container-level lock system allows bundles installed on the master to be preloaded on the slave, in order to provide faster failover performance.
+
+Two types of lock are supported:
+
+* filesystem lock
+* database lock
+
+When a first instance starts, if the lock is available, it takes the lock and become the master.
+If a second instance starts, it tries to acquire the lock. As the lock is already hold by the master, the instance becomes
+a slave, in standby mode (not active). A slave periodically check if the lock has been released or not.
+
+=== Filesystem lock
+
+The Apache Karaf instances share a lock on the filesystem. It means that the filesystem storing the lock has to be accessible
+to the different instances (using SAN, NFS, ...).
+
+The configuration of the lock system has to be defined in the `etc/system.properties` file, on each instance (master/slave):
+
+----
+karaf.lock=true
+karaf.lock.class=org.apache.karaf.main.SimpleFileLock
+karaf.lock.dir=<PathToLockFileDirectory>
+karaf.lock.delay=10
+----
+
+* `karaf.lock` property enables the the HA/failover mechanism
+* `karaf.lock.class` property contains the class name providing the lock implementation. Here, we use the filesystem lock.
+* `karaf.lock.dir` property contains the location where the lock will be written. All instances have to share the same lock.
+* `karaf.lock.delay` property is the interval period (in seconds) to check if the lock has been released or not.
+
+=== Database lock
+
+It's not always possible and easy to have a shared filesystem between multiple Apache Karaf instances.
+
+Instead of sharing a filesystem, Apache Karaf supports sharing a database.
+
+The master instance holds the lock by locking a table in the database. If the master loses the lock, a waiting slave
+gains access to the locking table, acquire the lock on the table and starts.
+
+The database lock uses JDBC (Java DataBase Connectivity). To use database locking, you have to:
+
+* copy the JDBC driver in the `lib/ext` folder on each instance. The JDBC driver to use is the one corresponding to the
+ database used for the locking system.
+* update `etc/system.properties` file on each instance:
+
+----
+karaf.lock=true
+karaf.lock.class=org.apache.karaf.main.DefaultJDBCLock
+karaf.lock.level=50
+karaf.lock.delay=10
+karaf.lock.jdbc.url=jdbc:derby://dbserver:1527/sample
+karaf.lock.jdbc.driver=org.apache.derby.jdbc.ClientDriver
+karaf.lock.jdbc.user=user
+karaf.lock.jdbc.password=password
+karaf.lock.jdbc.table=KARAF_LOCK
+karaf.lock.jdbc.clustername=karaf
+karaf.lock.jdbc.timeout=30
+----
+
+* `karaf.lock` property enabled the HA/failover mechanism
+* `karaf.lock.class` property contains the class name providing the lock implementation. The `org.apache.karaf.main.DefaultJDBCLock`
+ is the most generic database lock system implementation. Apache Karaf supports lock system for specific databases (see later for details).
+* `karaf.lock.level` property is the container-level locking (see later for details).
+* `karaf.lock.delay` property is the interval period (in seconds) to check if the lock has been released or not.
+* `karaf.lock.jdbc.url` property contains the JDBC URL to the database (derby in this example).
+* `karaf.lock.jdbc.driver` property contains the class name of the JDBC driver to use (derby in this example).
+* `karaf.lock.jdbc.user` property contains the username to use to connect to the database.
+* `karaf.lock.jdbc.password` property contains the password to use to connet to the database.
+* `karaf.lock.jdbc.table` property contains the database table to use for the lock.
+
+{warning}
+Apache Karaf won't start if the JDBC driver is not present in the `lib/ext` folder.
+{warning}
+
+{warning}
+The `sample` database will be created automatically if it does not exist.
+{warning}
+
+{warning}
+If the connection to the database is lost, the master instance tries to gracefully shutdown, allowing a slave instance to
+become the master when the database is back. The former master instance will required a manual restart.
+{warning}
+
+h4. Lock on Oracle
+
+Apache Karaf supports Oracle database for locking. The lock implementation class name to use is `org.apache.karaf.main.lock.OracleJDBCLock`:
+
+----
+karaf.lock=true
+karaf.lock.class=org.apache.karaf.main.lock.OracleJDBCLock
+karaf.lock.jdbc.url=jdbc:oracle:thin:@hostname:1521:XE
+karaf.lock.jdbc.driver=oracle.jdbc.OracleDriver
+karaf.lock.jdbc.user=user
+karaf.lock.jdbc.password=password
+karaf.lock.jdbc.table=KARAF_LOCK
+karaf.lock.jdbc.clustername=karaf
+karaf.lock.jdbc.timeout=30
+----
+
+The Oracle JDBC driver file (`ojdbc*.jar`) has to be copied in the `lib/ext` folder.
+
+{warning}
+The `karaf.lock.jdbc.url` property contains a JDBC URL which requires an active SID. It means that you must manually create the Oracle
+database instance first before using the lock mechanism.
+{warning}
+
+h4. Lock on Derby
+
+Apache Karaf supports Apache Derby database for locking. The lock implementation class name to use is `org.apache.karaf.main.lock.DerbyJDBCLock`:
+
+----
+karaf.lock=true
+karaf.lock.class=org.apache.karaf.main.lock.DerbyJDBCLock
+karaf.lock.jdbc.url=jdbc:derby://127.0.0.1:1527/dbname
+karaf.lock.jdbc.driver=org.apache.derby.jdbc.ClientDriver
+karaf.lock.jdbc.user=user
+karaf.lock.jdbc.password=password
+karaf.lock.jdbc.table=KARAF_LOCK
+karaf.lock.jdbc.clustername=karaf
+karaf.lock.jdbc.timeout=30
+----
+
+The Derby JDBC driver file name has to be copied in the `lib/ext` folder.
+
+h4.Lock on MySQL
+
+Apache Karaf supports MySQL database for locking. The lock implementation class name to use is `org.apache.karaf.main.lock.MySQLJDBCLock`:
+
+----
+karaf.lock=true
+karaf.lock.class=org.apache.karaf.main.lock.MySQLJDBCLock
+karaf.lock.jdbc.url=jdbc:mysql://127.0.0.1:3306/dbname
+karaf.lock.jdbc.driver=com.mysql.jdbc.Driver
+karaf.lock.jdbc.user=user
+karaf.lock.jdbc.password=password
+karaf.lock.jdbc.table=KARAF_LOCK
+karaf.lock.jdbc.clustername=karaf
+karaf.lock.jdbc.timeout=30
+----
+
+The MySQL JDBC driver file name has to be copied in `lib/ext` folder.
+
+h4. Lock on PostgreSQL
+
+Apache Karaf supports PostgreSQL database for locking. The lock implementation class name to use is `org.apache.karaf.main.lock.PostgreSQLJDBCLock`:
+
+----
+karaf.lock=true
+karaf.lock.class=org.apache.karaf.main.lock.PostgreSQLJDBCLock
+karaf.lock.jdbc.url=jdbc:postgresql://127.0.0.1:1527/dbname
+karaf.lock.jdbc.driver=org.postgresql.Driver
+karaf.lock.jdbc.user=user
+karaf.lock.jdbc.password=password
+karaf.lock.jdbc.table=KARAF_LOCK
+karaf.lock.jdbc.clustername=karaf
+karaf.lock.jdbc.timeout=0
+----
+
+The PostgreSQL JDBC driver file has to be copied in the `lib/ext` folder.
+
+h4. Lock on Microsoft SQLServer
+
+Apache Karaf supports Microsoft SQLServer database for locking. The lock implementation class name to use is `org.apache.karaf.main.lock.SQLServerJDBCLock`:
+
+----
+karaf.lock=true
+karaf.lock.class=org.apache.karaf.main.lock.SQLServerJDBCLock
+karaf.lock.level=50
+karaf.lock.delay=10
+karaf.lock.jdbc.url=jdbc:jtds:sqlserver://127.0.0.1;databaseName=sample
+karaf.lock.jdbc.driver=net.sourceforge.jtds.jdbc.Driver
+karaf.lock.jdbc.user=user
+karaf.lock.jdbc.password=password
+karaf.lock.jdbc.table=KARAF_LOCK
+karaf.lock.jdbc.clustername=karaf
+karaf.lock.jdbc.timeout=30
+----
+
+The JTDS JDBC driver file has to be copied in the `lib/ext` folder.
+
+=== Container-level locking
+
+Apache Karaf supports container-level locking. It allows bundles to be preloaded into the slave instance.
+Thanks to that, switching to a slave instance is very fast as the slave instance already contains all required bundles.
+
+The container-level locking is supported in both filesystem and database lock mechanisms.
+
+The container-level locking uses the `karaf.lock.level` property:
+
+----
+karaf.lock.level=50
+----
+
+The `karaf.lock.level` property tells the Karaf instance how far up the boot process to bring the OSGi container.
+All bundles with an ID equals or lower to this start level will be started in that Karaf instance.
+
+As reminder, the bundles start levels are specified in `etc/startup.properties`, in the `url=level` format.
+
+|| Level || Behavior ||
+| 1 | A 'cold' standby instance. Core bundles are not loaded into container. Slaves will wait until lock acquired to start server. |
+| <50 | A 'hot' standby instance. Core bundles are loaded into the container. Slaves will wait until lock acquired to start user level bundles. The console will be accessible for each slave instance at this level. |
+| >50 | This setting is not recommended as user bundles will end up being started. |
+
+{warning}
+Using 'hot' standby means that the slave instances are running and bind some ports. So, if you use master and slave instances on the same machine, you have
+to update the slave configuration to bind the services (ssh, JMX, etc) on different port numbers.
+{warning}
+
+== Cluster (active/active)
+
+Apache Karaf doesn't natively support cluster. By cluster, we mean several active instances, synchronized with each other.
+
+However, [Apache Karaf Cellar|http://karaf.apache.org/index/subprojects/cellar.html] can be installed to provide cluster support.
+
+See the [Apache Karaf Cellar website|http://karaf.apache.org/index/subprojects/cellar.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/features.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/users-guide/features.adoc b/manual/src/main/asciidoc/users-guide/features.adoc
new file mode 100644
index 0000000..881e75f
--- /dev/null
+++ b/manual/src/main/asciidoc/users-guide/features.adoc
@@ -0,0 +1,50 @@
+= Features
+
+== Standard Features
+
+* *Hot deployment*: simply drop a file in the `deploy` directory, Apache Karaf will detect the type of the file and
+ try to deploy it.
+* *Complete Console*: Apache Karaf provides a complete Unix-like console where you can completely manage the container.
+* *Dynamic Configuration*: Apache Karaf provides a set of command dedicated for the management of the configuration files.
+ All configuration files are centralized in the `etc` folder. Any change in a configuration file is taken on the fly.
+* *Advanced Logging System*: Apache Karaf supports a large set of Logging framework (slf4j, log4j, etc). Whatever the
+ logging framework you use, Apache Karaf centralizes the configuration in one file.
+* *Provisioning*: Apache Karaf supports a large set of URL where you can install your application (Maven repository, HTTP,
+ file, etc). It also provides the concept of "Karaf Feature" which is a way to describe your application.
+* *Management*: Apache Karaf is an enterprise-ready container, providing a lot of management indicators and operations
+ via JMX.
+* *Remote*: Apache Karaf embeds an SSHd server allowing you to use the console remotely. The management layer is also
+ accessible remotely.
+* *Security*: Apache Karaf provides a complete security framework (based on JAAS), and providing RBAC (Role-Based Access
+ Control) mechanism for console and JMX.
+* *Instances*: multiple instances of Apache Karaf can be managed directly from a main instance (root).
+* *OSGi frameworks*: Apache Karaf is not tight to one OSGi framework. By default, Apache Karaf runs with Apache Felix
+ Framework, but you can easily switch to Equinox (just change on property in a configuration file).
+
+!/images/karaf.png!
+
+== Enterprise features
+
+* WebContainer (JSP/Servlet support, including WAR archive deployment support)
+* Naming (JNDI)
+* Transaction (JTA)
+* DataSources (JDBC)
+* MOM (JMS)
+* Persistence (JPA)
+* EJB
+* CDI
+* HA/failover and cluster
+
+== External Features
+
+As a very extend-able container, OpenSource and commercial projects provide "native" support of Apache Karaf.
+
+We can mention (this list is not exhaustive):
+
+* [Apache ActiveMQ|http://activemq.apache.org/osgi-integration.html]
+* [Apache Camel|http://camel.apache.org/karaf.html]
+* [Apache CXF|http://cxf.apache.org]
+* [JClouds|http://www.jclouds.org/documentation/userguide/karaf/]
+* [Apache Wicket|http://team.ops4j.org/wiki/display/paxwicket/Install+Pax+Wicket]
+* ...
+
http://git-wip-us.apache.org/repos/asf/karaf/blob/677c6d46/manual/src/main/asciidoc/users-guide/http.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/users-guide/http.adoc b/manual/src/main/asciidoc/users-guide/http.adoc
new file mode 100644
index 0000000..add8e8e
--- /dev/null
+++ b/manual/src/main/asciidoc/users-guide/http.adoc
@@ -0,0 +1,60 @@
+= Http Service
+
+The Karaf http feature enables the Pax Web implementation of the OSGi HTTPService.
+
+== Installing the HTTP feature
+
+----
+root@karaf> feature:install http
+----
+
+Test the HTTP service is up by pointing your browser to [http://localhost:8080/].
+
+== Configuring the HTTPService
+
+By default the HTTPService listens on port 8181 you can change the port by creating a file `etc/org.ops4j.pax.web.cfg` with the following content:
+
+----
+org.osgi.service.http.port=8080
+----
+
+or by typing:
+----
+root@karaf> config:property-set -p org.ops4j.pax.web org.osgi.service.http.port 8080
+----
+
+If the http feature is already installed the change will take effect immediately.
+
+== Registering a servlet with the HttpService manually
+
+See [Apache Felix HTTP Service|http://felix.apache.org/site/apache-felix-http-service.html].
+
+== Using the Pax Web whiteboard extender
+
+The Pax Web whiteboard extender is an enhancement of the http feature. So use the following command to install:
+
+----
+root@karaf> feature:install http-whiteboard
+----
+
+The [Pax Web whiteboard|http://team.ops4j.org/wiki/display/ops4j/Pax+Web+Extender+-+Whiteboard] extender listens to services
+of interface type HttpServlet and Filter.
+It will register each of these interfaces with the HttpService and remove them as soon as the service goes down.
+So it is much more convenient than registering with the HttpService directly.
+
+----
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
+ <service interface="javax.servlet.http.HttpServlet">
+ <service-properties>
+ <entry key="alias" value="/myservlet"/>
+ </service-properties>
+ <bean id="myServlet" class="com.example.MyServlet"/>
+ </service>
+</blueprint>
+----
+
+The above snippet publishes the Servlet MyServlet on http://localhost:8080/myServlet.
+
+Please keep in mind that the Whiteboard pattern for Servlets is not standardized and only works with Pax Web.
+
+For commands take a look at the command section in the [webcontainer|webcontainer] chapter.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/karaf/blob/677c6d46/manual/src/main/asciidoc/users-guide/index.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/users-guide/index.adoc b/manual/src/main/asciidoc/users-guide/index.adoc
new file mode 100644
index 0000000..a4d1aae
--- /dev/null
+++ b/manual/src/main/asciidoc/users-guide/index.adoc
@@ -0,0 +1,63 @@
+Users Guide
+===========
+Apache Software Foundation
+:doctype: book
+:toc: left
+:toclevels: 3
+:toc-position: left
+:toc-title: Apache Karaf
+:numbered:
+
+include::users-guide/installation.adoc[]
+
+include::users-guide/directory-structure.adoc[]
+
+include::users-guide/start-stop.adoc[]
+
+include::users-guide/wrapper.adoc[]
+
+include::users-guide/console.adoc[]
+
+include::users-guide/remote.adoc[]
+
+include::users-guide/log.adoc[]
+
+include::users-guide/configuration.adoc[]
+
+include::users-guide/urls.adoc[]
+
+include::users-guide/provisioning.adoc[]
+
+include::users-guide/deployers.adoc[]
+
+include::users-guide/kar.adoc[]
+
+include::users-guide/instances.adoc[]
+
+include::users-guide/security.adoc[]
+
+include::users-guide/obr.adoc[]
+
+include::users-guide/enterprise.adoc[]
+
+include::users-guide/webcontainer.adoc[]
+
+include::users-guide/jndi.adoc[]
+
+include::users-guide/jta.adoc[]
+
+include::users-guide/jms.adoc[]
+
+include::users-guide/jpa.adoc[]
+
+include::users-guide/ejb.adoc[]
+
+include::users-guide/cdi.adoc[]
+
+include::users-guide/failover.adoc[]
+
+include::users-guide/monitoring.adoc[]
+
+include::users-guide/webconsole.adoc[]
+
+include::users-guide/tuning.adoc[]
http://git-wip-us.apache.org/repos/asf/karaf/blob/677c6d46/manual/src/main/asciidoc/users-guide/installation.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/users-guide/installation.adoc b/manual/src/main/asciidoc/users-guide/installation.adoc
new file mode 100644
index 0000000..69e5e64
--- /dev/null
+++ b/manual/src/main/asciidoc/users-guide/installation.adoc
@@ -0,0 +1,144 @@
+= Installation
+
+:doctype: book
+:toc: left
+:toclevels: 3
+:toc-position: left
+:toc-title: Apache Karaf
+:numbered:
+
+
+Apache Karaf is a lightweight container, very easy to install and administrate, on both Unix and Windows platforms.
+
+== Requirements
+
+Hardware: ::
+
+* 50 MB of free disk space for the Apache Karaf binary distribution.
+
+Operating Systems: ::
+
+* Windows: Windows 8, Windows 7, Windows 2003, Windows Vista, Windows XP SP2, Windows 2000.
+* Unix: RedHat Enterprise Linux, Debian, SuSE/OpenSuSE, CentOS, Fedora, Ubuntu, MacOS, AIX, HP-UX, Solaris, any Unix platform that supports Java.
+
+Environment: ::
+
+* Java SE 1.7.x or greater ([http://www.oracle.com/technetwork/java/javase/]).
+* The JAVA_HOME environment variable must be set to the directory where the Java runtime is installed,
+
+== Using Apache Karaf binary distributions
+
+Apache Karaf is available in two distributions, both as a tar.gz and zip archives.
+
+
+The "default" distribution is a "ready to use" distribution.
+The "default" distribution provides the following features enabled.
+
+The "minimal" distribution is like the minimal distributions that you can find for most of Unix distributions.
+Only the core layer is packaged, most of the features and bundles are downloaded from Internet at bootstrap.
+It means that Apache Karaf minimal distribution requires an Internet connection to start correctly.
+The features provided by the "minimal" distribution are exactly the same as in the "default" distribution, the difference
+is that the minimal distribution will download the features from Internet.
+
+=== Installation on Windows platform
+
+NB: the JAVA_HOME environment variable has to be correctly defined. To accomplish that, press Windows key and Break key together, switch to "Advanced" tab and click on "Environment Variables".
+
+. From a browser, navigate to [http://karaf.apache.org/index/community/download.html].
+. Download Apache Karaf binary distribution in the zip format: `apache-karaf-3.0.0.zip`.
+. Extract the files from the zip file into a directory of your choice (it's the `KARAF_HOME`.
+NB: remember the restrictions concerning illegal characters in Java paths, e.g. \!, % etc.
+. Apache Karaf is now installed.
+
+[TIP]
+====
+Handy Hint::
+In case you have to install Karaf into a very deep path or a path containing illegal characters for Java paths, e.g. \!, % etc., you may add a bat file to _start \-> startup_ that executes
+{noformat}
+subst S: "C:\your very % problematic path!\KARAF"
+{noformat}
+so your Karaf root directory is S: --- which works for sure and is short to type.
+====
+
+=== Installation on Unix platforms
+
+NB: the JAVA_HOME environment variable has to be correctly defined. Check the current value using
+----
+echo $JAVA_HOME
+----
+If it's not correct, fix it using:
+----
+export JAVA_HOME=....
+----
+
+. From a browser, navigate to [http://karaf.apache.org/index/community/download.html].
+. Download Apache Karaf binary distribution in the tar.gz format: `apache-karaf-3.0.0.tar.gz`.
+. Extract the files from the tar.gz file into a directory of your choice (it's the `KARAF_HOME`). For example:
+----
+gunzip apache-karaf-3.0.0.tar.gz
+tar xvf apache-karaf-3.0.0.tar
+----
+NB: remember the restrictions concerning illegal characters in Java paths, e.g. \!, % etc.
+. Apache Karaf is now installed.
+
+== Post-Installation steps
+
+Thought it is not always required, it is strongly advised to set up the `JAVA_HOME` environment property to point to the JDK you want Apache Karaf to use before starting it.
+This property is used to locate the `java` executable and should be configured to point to the home directory of the Java SE 7 installation.
+
+By default, all Apache Karaf files are "gather" in one directory: the `KARAF_HOME`.
+
+You can define your own directory layout, by using some Karaf environment variables:
+
+* `KARAF_DATA` is the location of the data folder, where Karaf stores temporary files.
+* `KARAF_ETC` is the location of the etc folder, where Karaf stores configuration files.
+* `KARAF_BASE` is the Karaf base folder. By default `KARAF_BASE` is the same as `KARAF_HOME`.
+
+== Building from Sources
+
+If you intend to build Apache Karaf from the sources, the requirements are a bit different:
+
+Hardware: ::
+
+* 500 MB of free disk space for the Apache Karaf source distributions or SVN checkout, the Maven build and the dependencies Maven downloads.
+
+Environment: ::
+
+* Java SE Development Kit 1.7.x or greater ([http://www.oracle.com/technetwork/java/javase/]).
+* Apache Maven 3.0.4 ([http://maven.apache.org/download.html]).
+
+=== Building on Windows platform
+
+. You can get the Apache Karaf sources from:
+* the sources distribution `apache-karaf-3.0.0-src.zip` available at [http://karaf.apache.org/index/community/download.html]. Extract the files in the directory of your choice.
+* by checkout of the git repository:
+----
+git clone https://git-wip-us.apache.org/repos/asf/karaf.git karaf
+----
+. Use Apache Maven to build Apache Karaf:
+----
+mvn clean install
+----
+NB: you can speed up the build by bypassing the unit tests:
+----
+mvn clean install -DskipTests
+----
+. You can find the built binary distribution in `assemblies\apache-karaf\target\apache-karaf-3.0.0.zip`. You can install and use it as explained in the "Using Apache Karaf binary distributions" section.
+
+=== Building on Unix platforms
+
+. You can get the Apache Karaf sources from:
+* the sources distribution `apache-karaf-3.0.0-src.tar.gz` available at [http://karaf.apache.org/index/community/download.html]. Extract the files in the directory of your choice.
+* by checkout of the git repository:
+----
+git clone https://git-wip-us.apache.org/repos/asf/karaf.git karaf
+----
+. Use Apache Maven to build Apache Karaf:
+----
+mvn clean install
+----
+NB: you can speed up the build by bypassing the unit tests:
+----
+mvn clean install -DskipTests
+----
+. You can find the built binary distribution in `assemblies/apache-karaf/target/apache-karaf-3.0.0.tar.gz`. You can install and use it as explained in the "Using Apache Karaf binary distributions" section.
http://git-wip-us.apache.org/repos/asf/karaf/blob/677c6d46/manual/src/main/asciidoc/users-guide/instances.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/users-guide/instances.adoc b/manual/src/main/asciidoc/users-guide/instances.adoc
new file mode 100644
index 0000000..877ae59
--- /dev/null
+++ b/manual/src/main/asciidoc/users-guide/instances.adoc
@@ -0,0 +1,365 @@
+= Instances
+
+A instance is a complete new Apache Karaf runtime, isolated from the other ones.
+
+The purpose is to easily create and manage a new Apache Karaf runtime without installing a complete distribution.
+
+A instance is a new instance that you can launch separately from the root one, and deploy applications into. It means that each instance is run on a different JVM.
+
+A instance does not contain a full copy of the Apache Karaf distribution, but only a set of the configuration files and data folder which contains all the runtime information, logs and temporary files.
+
+== Using the instance commands
+
+The *instance* commands allow you to create and manage instances.
+
+=== Creating instances
+
+You create a new runtime instance by typing [`instance:create`|/commands/instance-create] in the Karaf console.
+
+As shown in the following example, `instance:create` causes the runtime to create a new runtime installation in the active runtime's `instances/[name]} directory. The new instance is a new Karaf instance and is assigned an SSH port number based on an incremental count starting at 8101 and a RMI registry port number based on an incremental count starting at 1099.
+
+----
+karaf@root()> instance:create test
+----
+
+The new instance is fresh Apache Karaf instance. It uses default configuration files set, as you install a fresh Karaf distribution.
+
+You can enable the verbose mode for the `instance:create` command using the `-v` option:
+
+----
+karaf@root()> instance:create -v test
+Creating new instance on SSH port 8103 and registry port 1101 / RMI server port 44446 at: /opt/karaf/instances/test
+Creating dir: /opt/karaf/instances/test/bin
+Creating dir: /opt/karaf/instances/test/etc
+Creating dir: /opt/karaf/instances/test/system
+Creating dir: /opt/karaf/instances/test/deploy
+Creating dir: /opt/karaf/instances/test/data
+Creating file: /opt/karaf/instances/test/etc/config.properties
+Creating file: /opt/karaf/instances/test/etc/jre.properties
+Creating file: /opt/karaf/instances/test/etc/custom.properties
+Creating file: /opt/karaf/instances/test/etc/java.util.logging.properties
+Creating file: /opt/karaf/instances/test/etc/org.apache.felix.fileinstall-deploy.cfg
+Creating file: /opt/karaf/instances/test/etc/org.apache.karaf.features.obr.cfg
+Creating file: /opt/karaf/instances/test/etc/org.apache.karaf.features.repos.cfg
+Creating file: /opt/karaf/instances/test/etc/org.apache.karaf.log.cfg
+Creating file: /opt/karaf/instances/test/etc/org.ops4j.pax.logging.cfg
+Creating file: /opt/karaf/instances/test/etc/org.ops4j.pax.url.mvn.cfg
+Creating file: /opt/karaf/instances/test/etc/users.properties
+Creating file: /opt/karaf/instances/test/etc/keys.properties
+Creating file: /opt/karaf/instances/test/etc/org.apache.karaf.features.cfg
+Creating file: /opt/karaf/instances/test/etc/system.properties
+Creating file: /opt/karaf/instances/test/etc/org.apache.karaf.shell.cfg
+Creating file: /opt/karaf/instances/test/etc/org.apache.karaf.management.cfg
+Creating file: /opt/karaf/instances/test/bin/karaf
+Creating file: /opt/karaf/instances/test/bin/start
+Creating file: /opt/karaf/instances/test/bin/stop
+----
+
+You can manually configure the different ports, the location of the instance, the Apache Karaf features URLs using different options of the `instance:create` command.
+You can have details about these options using the `--help` option.
+
+=== Cloning an instance
+
+Instead of creating a fresh instance, you can clone an existing instance using `instance:clone`.
+
+The `instance:clone` command reuse the files from the source instance:
+
+----
+karaf@root()> instance:clone root test
+----
+
+You can have details about the cloning options using the `--help` option.
+
+=== Changing the instance location
+
+By default, the new instances storage is in the `KARAF_HOME/instance` directory.
+You find a directory with the name of the instance storing the different instance files.
+
+You can change the location of the instance using the `-l` option to the `instance:create` and `instance:clone` commands:
+
+----
+karaf@root()> instance:create -v -l /tmp/test test
+Creating new instance on SSH port 8102 and registry port 1100 / RMI server port 44445 at: /tmp/test
+Creating dir: /tmp/test/bin
+Creating dir: /tmp/test/etc
+Creating dir: /tmp/test/system
+Creating dir: /tmp/test/deploy
+Creating dir: /tmp/test/data
+Creating file: /tmp/test/etc/config.properties
+Creating file: /tmp/test/etc/jre.properties
+Creating file: /tmp/test/etc/custom.properties
+Creating file: /tmp/test/etc/java.util.logging.properties
+Creating file: /tmp/test/etc/org.apache.felix.fileinstall-deploy.cfg
+Creating file: /tmp/test/etc/org.apache.karaf.features.obr.cfg
+Creating file: /tmp/test/etc/org.apache.karaf.features.repos.cfg
+Creating file: /tmp/test/etc/org.apache.karaf.log.cfg
+Creating file: /tmp/test/etc/org.ops4j.pax.logging.cfg
+Creating file: /tmp/test/etc/org.ops4j.pax.url.mvn.cfg
+Creating file: /tmp/test/etc/users.properties
+Creating file: /tmp/test/etc/keys.properties
+Creating file: /tmp/test/etc/org.apache.karaf.features.cfg
+Creating file: /tmp/test/etc/system.properties
+Creating file: /tmp/test/etc/org.apache.karaf.shell.cfg
+Creating file: /tmp/test/etc/org.apache.karaf.management.cfg
+Creating file: /tmp/test/bin/karaf
+Creating file: /tmp/test/bin/start
+Creating file: /tmp/test/bin/stop
+----
+
+Careful, it's not possible to change the location of an instance once it has been created.
+
+NB: `instance:destroy` will remove the instance location for you. You don't have to remove the instance location "by hand".
+
+=== Changing instance ports
+
+You can change the SSH port number assigned to an instance using the `instance:ssh-port-change` command:
+
+----
+karaf@root()> instance:ssh-port-change test 8104
+----
+
+where test is the instance name and 8104 is the new SSH port number to use for the test instance.
+
+You can change the RMI Registry port number (used by JMX) of an instance using the `instance:rmi-registry-port-change` command:
+
+----
+karaf@root()> instance:rmi-registry-port-change test 1102
+----
+
+where test is the instance name and 1102 is the new RMI Registry port number to use for the test instance.
+
+You can also change the RMI Server port number (used by JMX too) of an instance using the `instance:rmi-server-port-change` command:
+
+----
+karaf@root()> instance:rmi-server-port-change test 44447
+----
+
+where test is the instance name and 44447 is the new RMI Server port number to use for the test instance.
+
+NB: the instance has to be stopped to be able to change the port numbers.
+
+=== Starting instances
+
+New instances are created in a stopped state.
+
+To start an instance, you can use the `instance:start` command:
+
+----
+karaf@root()> instance:start test
+----
+
+where test is the instance name.
+
+=== Listing instances
+
+To list the instances and their current status, you can use the `instance:list` command:
+
+----
+karaf@root()> instance:list
+SSH Port | RMI Registry | RMI Server | State | PID | Name
+-------------------------------------------------------------
+ 8101 | 1099 | 44444 | Started | 19652 | root
+ 8104 | 1101 | 44446 | Stopped | 0 | test
+----
+
+An instance can be in the following status:
+
+- Stopped: the instance is stopped.
+- Starting: the instance is starting.
+- Started: the instance is up and running. You can connect and use it.
+
+=== Status of an instance
+
+You can get directly the status of a given instance using the `instance:status` command:
+
+----
+karaf@root()> instance:status test
+Started
+----
+
+where test is the instance name.
+
+=== Connecting to an instance
+
+You can connect to a running instance directly from the root one using the `instance:connect` command:
+
+----
+karaf@root()> instance:connect test
+----
+
+where 'test' is the instance name where to connect to.
+
+By default, this command will use the same username used on the root instance, and the password will be prompted.
+
+You can use a different username using the `-u` or `--username` option. You can also provide the password using the
+`-p` or `--password` option.
+
+If you don't provide any argument, you will logon on the instance:
+
+----
+karaf@test()>
+----
+
+Note the name of instance in the shell prompt (@test).
+
+You can logoff from the instance and return back to the root instance using the `logout` command or CTRL-D key binding:
+
+----
+karaf@test()> logout
+karaf@root()>
+----
+
+The `instance:connect` command accepts shell commands as argument. It allows you to directly execute commands or scripts on the instance:
+
+----
+karaf@root()> instance:connect test 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
+...
+----
+
+=== Stop an instance
+
+To stop an instance, you can connect to the instance (using `instance:connect`) and execute the `system:shutdown`
+command.
+
+You can also use the [`instance:stop`|/commands/instance-stop] command:
+
+----
+karaf@root()> instance:stop test
+----
+
+where test is the instance name.
+
+The instance will go to the "Stopped" state.
+
+=== Destroy an instance
+
+You can completely delete a stopped instance using the `instance:destroy` command:
+----
+karaf@root()> instance:destroy test
+----
+
+where test is the instance name.
+
+NB: the `instance:destroy` deletes the instance store (the location where the instance files are stored).
+
+=== Rename an instance
+
+You can change the name of a stopped instance using the `instance:rename` command:
+
+----
+karaf@root()> instance:rename test newTest
+----
+
+where test is the current instance name, and newTest the new instance name.
+
+== Instance script
+
+The `instance:*` commands require the root instance running.
+
+But, you can also administrate directly instances without the root instance, using the `bin/instance` Unix script
+(or `bin/instance.bat` script on Windows).
+
+You find the same actions that you can do with the `instance:*` commands in the `instance[.bat]` script:
+
+----
+bin/instance
+Available commands:
+ clone - Clones an existing container instance.
+ create - Creates a new container instance.
+ destroy - Destroys an existing container instance.
+ list - Lists all existing container instances.
+ opts-change - Changes the Java options of an existing container instance.
+ rename - Rename an existing container instance.
+ rmi-registry-port-change - Changes the RMI registry port (used by management layer) of an existing container instance.
+ rmi-server-port-change - Changes the RMI server port (used by management layer) of an existing instance.
+ ssh-port-change - Changes the secure shell port of an existing container instance.
+ start - Start an existing container instance.
+ status - Check the current status of an instance.
+ stop - Stop an existing container instance.
+Type 'command --help' for more help on the specified command.
+----
+
+For instance, to list all the instances, you can use the `instance` script with the `list` command:
+
+----
+bin/instance list
+SSH Port | RMI Registry | RMI Server | State | PID | Name
+-----------------------------------------------------------
+ 8101 | 1099 | 44444 | Stopped | 0 | root
+ 8102 | 1100 | 44445 | Stopped | 0 | test
+----
+
+It's exactly the same as executing `instance:list` in the root instance.
+
+You can obtain details about commands options and arguments using the `--help` option. For instance:
+
+----
+bin/instance rename --help
+DESCRIPTION
+ instance:rename
+
+ Rename an existing container instance.
+
+SYNTAX
+ instance:rename [options] name new-name
+
+ARGUMENTS
+ name
+ The name of the container instance to rename
+ new-name
+ The new name of the container instance
+
+OPTIONS
+ --help
+ Display this help message
+ -v, --verbose
+ Display actions performed by the command (disabled by default)
+
+----
+
+== JMX InstanceMBean
+
+On the JMX layer, you have a MBean dedicated to the management of the instances: the InstanceMBean.
+
+The ObjectName to use is `org.apache.karaf:type=instance,name=*`.
+
+=== Attributes
+
+The `Instances` attribute is a tabular data attribute providing details about the instances:
+
+* `Is Root` (boolean): if true, the instance is the root instance, false else.
+* `JavaOpts` (string): it contains the JVM arguments used by the instance.
+* `Location` (string): it's the path to the instance storage.
+* `Name` (string): it's the name of the instance.
+* `Pid` (long): it's the current system process ID (PID) of the instance process.
+* `RMI Registry Port` (int): it's the port number of the instance RMI Registry (JMX).
+* `RMI Server Port` (int): it's the port number of the instance RMI Server (JMX).
+* `SSH Port` (int): it's the port number of the instance SSH Server.
+* `State` (string): it's the current status of the instance (Stopped, Starting, Started).
+
+=== Operations
+
+The InstanceMBean provides the following operations, corresponding to the previous `instance:*` commands:
+* `createInstance(instanceName, sshPort, rmiRegistryPort, rmiServerPort, location, javaOpts, features, featuresUrls)`: create a new instance.
+* `changeSshPort(instanceName, port)`: change the SSH port of an instance.
+* `changeRmiServerPort(instanceName, port)`: change the RMI server port of an instance.
+* `changeRmiRegistry(instanceName, port)`: change the RMI registry port of an instance.
+* `changeJavaOpts(instanceName, javaOpts)`: change the Java options of an instance.
+* `destroyInstance(instanceName)`: destroy an instance.
+* `startInstance(instanceName)`: start an instance.
+* `startInstance(instanceName, options)`: start an instance with the given Java options.
+* `startInstance(instanceName, options, wait, debug)`: start an instance with the given Java options.
+ If wait is true, this operation is waiting for the instance is in "Started" state. If debug is true, the instance is started in debug mode.
+* `stopInstance(instanceName)`: stop an instance.
+* `renameInstance(instanceName, newInstanceName)`: rename an instance.
+* `renameInstance(instanceName, newInstanceName, verbose)`: rename an instance. If verbose is true, this operation provides details in the log.
+* `cloneInstance(instanceName, cloneName, sshPort, rmiRegistryPort, rmiServerPort, location, javaOpts)`: clone an existing instance.
http://git-wip-us.apache.org/repos/asf/karaf/blob/677c6d46/manual/src/main/asciidoc/users-guide/jdbc.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/users-guide/jdbc.adoc b/manual/src/main/asciidoc/users-guide/jdbc.adoc
new file mode 100644
index 0000000..798e3e9
--- /dev/null
+++ b/manual/src/main/asciidoc/users-guide/jdbc.adoc
@@ -0,0 +1,212 @@
+= DataSources (JDBC)
+
+The Apache Karaf DataSources (JDBC) is an optional enterprise feature.
+
+You have to install the `jdbc` feature first:
+
+----
+karaf@root()> feature:install jdbc
+----
+
+This feature provides an OSGi service to create/delete JDBC datasources in the container and perform database operations (SQL queries).
+
+This JDBC OSGi service can be manipulated programmatically (see the developer guide for details), using the `jdbc:*` commands, or using the JDBC MBean.
+
+== Commands
+
+=== `jdbc:create`
+
+The `jdbc:create` command automatically creates a datasource definition file in the Apache Karaf `deploy` folder.
+
+The `jdbc:create` accepts a set of options and the name argument:
+
+----
+karaf@root()> jdbc:create --help
+DESCRIPTION
+ jdbc:create
+
+ Create a JDBC datasource
+
+SYNTAX
+ jdbc:create [options] name
+
+ARGUMENTS
+ name
+ The JDBC datasource name
+
+OPTIONS
+ -u, --username
+ The database username
+ -v, --version
+ The version of the driver to use
+ -t, --type
+ The JDBC datasource type (generic, MySQL, Oracle, Postgres, H2, HSQL, Derby, MSSQL)
+ -url
+ The JDBC URL to use
+ -p, --password
+ The database password
+ -i, --install-bundles
+ Try to install the bundles providing the JDBC driver
+ -d, --driver
+ The classname of the JDBC driver to use. NB: this option is used only the type generic
+ --help
+ Display this help message
+
+----
+
+* the `name` argument is required. It's the name of the datasource. The name is used to identify the datasource, and to create the datasource definition file (`deploy/datasource-[name].xml`).
+* the `-u` option is optional. It defines the database username.
+* the `-v` option is optional. It "forces" a given JDBC driver version (only used with the `-i` option).
+* the `-t` option is required. It defines the JDBC datasource type. Accepted values are: MySQL, Oracle, Postgres, Derby, H2, HSQL, MSSQL, Generic. Generic is a generic configuration file using DBCP to create a pooled datasource. When using generic, it's up to you to install the JDBC driver and configure the `deploy/datasource-[name].xml` datasource file.
+* the `-url` option is optional. It defines the JDBC URL to access to the database.
+* the `-p` option is optional. It defines the database password.
+* the `-d` option is optional. It defines the JDBC driver classname to use (only used with the generic type).
+* the `-i` option is optional. If specified, the command will try to automatically install the OSGi bundles providing the JDBC driver (depending of the datasource type specified by the `-t` option).
+
+For instance, to create an embedded Apache Derby database in Apache Karaf, you can do:
+
+----
+karaf@root()> jdbc:create -t derby -u test -i test
+----
+
+We can note that the Derby bundle has been installed automatically, and the datasource has been created:
+
+----
+karaf@root()> la
+...
+87 | Active | 80 | 10.8.2000002.1181258 | Apache Derby 10.8
+88 | Active | 80 | 0.0.0 | datasource-test.xml
+----
+
+We can see the `deploy/datasource-test.xml` datasource file.
+
+== `jdbc:delete`
+
+The `jdbc:delete` command deletes a datasource by removing the `deploy/datasource-[name].xml` datasource file:
+
+----
+karaf@root()> jdbc:delete test
+----
+
+{warning}
+The `jdbc:delete` does not uninstall the JDBC driver bundles and does not remove the files created by the JDBC driver (or the database in case of embedded database).
+It's up to you to remove it.
+{warning}
+
+== `jdbc:datasources`
+
+The `jdbc:datasources` command lists the JDBC datasources:
+
+----
+karaf@root()> jdbc:datasources
+Name | Product | Version | URL
+------------------------------------------------------------------
+/jdbc/test | Apache Derby | 10.8.2.2 - (1181258) | jdbc:derby:test
+----
+
+== `jdbc:info`
+
+The `jdbc:info` command provides details about a JDBC datasource:
+
+----
+karaf@root()> jdbc:info /jdbc/test
+Property | Value
+--------------------------------------------------
+driver.version | 10.8.2.2 - (1181258)
+username | APP
+db.version | 10.8.2.2 - (1181258)
+db.product | Apache Derby
+driver.name | Apache Derby Embedded JDBC Driver
+url | jdbc:derby:test
+----
+
+== `jdbc:execute`
+
+The `jdbc:execute` command executes a SQL query that doesn't return any result on a given JDBC datasource.
+
+Typically, you can use the `jdbc:execute` command to create tables, insert values into tables, etc.
+
+For instance, we can create a `person` table on our `test` datasource:
+
+----
+karaf@root()> jdbc:execute /jdbc/test "create table person(name varchar(100), nick varchar(100))"
+----
+
+And we can insert some records in the `person` table:
+
+----
+karaf@root()> jdbc:execute /jdbc/test "insert into person(name, nick) values('foo','bar')"
+karaf@root()> jdbc:execute /jdbc/test "insert into person(name, nick) values('test','test')"
+----
+
+== `jdbc:query`
+
+The `jdbc:query` command is similar to the `jdbc:execute` one but it displays the query result.
+
+For instance, to display the content of the `person` table, we can do:
+
+----
+karaf@root()> jdbc:query /jdbc/test "select * from person"
+NICK | NAME
+--------------------------------
+bar | foo
+test | test
+----
+
+== `jdbc:tables`
+
+The `jdbc:tables` command displays all tables available on a given JDBC datasource:
+
+----
+karaf@root()> jdbc:tables /jdbc/test
+REF_GENERATION | TYPE_NAME | TABLE_NAME | TYPE_CAT | REMARKS | TYPE_SCHEM | TABLE_TYPE | TABLE_SCHEM | TABLE_CAT | SELF_REFERENCING_COL_NAME
+----------------------------------------------------------------------------------------------------------------------------------------------------
+ | | SYSALIASES | | | | SYSTEM TABLE | SYS | |
+ | | SYSCHECKS | | | | SYSTEM TABLE | SYS | |
+ | | SYSCOLPERMS | | | | SYSTEM TABLE | SYS | |
+ | | SYSCOLUMNS | | | | SYSTEM TABLE | SYS | |
+ | | SYSCONGLOMERATES | | | | SYSTEM TABLE | SYS | |
+ | | SYSCONSTRAINTS | | | | SYSTEM TABLE | SYS | |
+ | | SYSDEPENDS | | | | SYSTEM TABLE | SYS | |
+ | | SYSFILES | | | | SYSTEM TABLE | SYS | |
+ | | SYSFOREIGNKEYS | | | | SYSTEM TABLE | SYS | |
+ | | SYSKEYS | | | | SYSTEM TABLE | SYS | |
+ | | SYSPERMS | | | | SYSTEM TABLE | SYS | |
+ | | SYSROLES | | | | SYSTEM TABLE | SYS | |
+ | | SYSROUTINEPERMS | | | | SYSTEM TABLE | SYS | |
+ | | SYSSCHEMAS | | | | SYSTEM TABLE | SYS | |
+ | | SYSSEQUENCES | | | | SYSTEM TABLE | SYS | |
+ | | SYSSTATEMENTS | | | | SYSTEM TABLE | SYS | |
+ | | SYSSTATISTICS | | | | SYSTEM TABLE | SYS | |
+ | | SYSTABLEPERMS | | | | SYSTEM TABLE | SYS | |
+ | | SYSTABLES | | | | SYSTEM TABLE | SYS | |
+ | | SYSTRIGGERS | | | | SYSTEM TABLE | SYS | |
+ | | SYSVIEWS | | | | SYSTEM TABLE | SYS | |
+ | | SYSDUMMY1 | | | | SYSTEM TABLE | SYSIBM | |
+ | | PERSON | | | | TABLE | APP | |
+----
+
+== JMX JDBC MBean
+
+The JMX JDBC MBean provides the JDBC datasources, and the operations to manipulate datasources and database.
+
+The object name to use is `org.apache.karaf:type=jdbc,name=*`.
+
+=== Attributes
+
+The `Datasources` attribute provides a tabular data of all JDBC datasource, containing:
+
+* `name` is the JDBC datasource name
+* `product` is the database product backend
+* `url` is the JDBC URL used by the datasource
+* `version` is the database version backend.
+
+=== Operations
+
+* `create(name, type, jdbcDriverClassName, version, url, user, password, installBundles)` creates a JDBC datasource (the arguments correspond to the options of the `jdbc:create` command).
+* `delete(name)` deletes a JDBC datasource.
+* `info(datasource)` returns a Map (String/String) of details about a JDBC `datasource`.
+* `tables(datasource)` returns a tabular data containing the tables available on a JDBC `datasource`.
+* `execute(datasource, command` executes a SQL command on the given JDBC `datasource`.
+* `query(datasource, query` executes a SQL query on the given JDBC `datasource` and return the execution result as tabular data.
+
http://git-wip-us.apache.org/repos/asf/karaf/blob/677c6d46/manual/src/main/asciidoc/users-guide/jms.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/users-guide/jms.adoc b/manual/src/main/asciidoc/users-guide/jms.adoc
new file mode 100644
index 0000000..587bd44
--- /dev/null
+++ b/manual/src/main/asciidoc/users-guide/jms.adoc
@@ -0,0 +1,290 @@
+= MOM (JMS)
+
+The Apache Karaf MOM (Messaging Oriented Middleware/JMS) is an optional enterprise feature.
+
+You have to install the `jms` feature first:
+
+----
+karaf@root()> feature:install jms
+----
+
+The `jms` feature doesn't install a JMS broker: it just installs the OSGi service, commands, and MBean to interact with
+a JMS broker (not the broker itself).
+
+It means that you have to install a JMS broker itself.
+
+This JMS broker can be available:
+
+* outside of Apache Karaf, as a standalone broker. In that case, Apache Karaf JMS will remotely connect to the JMS broker.
+ For instance, you can use this topology with Apache ActiveMQ or IBM WebsphereMQ.
+* embedded in Apache Karaf. With this topology, Apache Karaf itself provides a JMS broker service. Apache ActiveMQ provides
+ a native support in Apache Karaf.
+
+For instance, you can install Apache ActiveMQ directly in Apache Karaf:
+
+----
+karaf@root()> feature:repo-add activemq
+Adding feature url mvn:org.apache.activemq/activemq-karaf/LATEST/xml/features
+karaf@root()> feature:install activemq-broker
+----
+
+The `activemq-broker` feature installs:
+
+* a Apache ActiveMQ broker directly in Apache Karaf, bind to the `61616` port number by default.
+* the Apache ActiveMQ WebConsole bound to `http://0.0.0.0:8181/activemqweb` by default.
+
+The Apache Karaf `jms` feature provides an OSGi service to create/delete JMS connection factories in the container
+and perform JMS operations (send or consume messages, get information about a JMS broker, list the destinations, ...).
+
+This JMS OSGi service can be manipulated programmatically (see the developer guide for details), using the `jms:*` commands, or using the JMS MBean.
+
+== Commands
+
+=== `jms:create`
+
+The `jms:create` command creates a JMS connection factory in the Apache Karaf container. It automatically creates a
+blueprint XML file in the `deploy` folder containing the JMS connection factory definition corresponding
+to the type that you mentioned.
+
+The `jms:create` command accepts different arguments and options:
+
+----
+karaf@root()> jms:create --help
+DESCRIPTION
+ jms:create
+
+ Create a JMS connection factory.
+
+SYNTAX
+ jms:create [options] name
+
+ARGUMENTS
+ name
+ The JMS connection factory name
+
+OPTIONS
+ -u, --url
+ The JMS URL. NB: for WebsphereMQ type, the URL is hostname/port/queuemanager/channel
+ --help
+ Display this help message
+ -t, --type
+ The JMS connection factory type (ActiveMQ or WebsphereMQ)
+
+----
+
+* the `name` argument is required. It's the name of the JMS connection factory. The name is used to identify the connection factory, and to create the connection factory definition file (`deploy/connectionfactory-[name].xml`).
+* the `-t` (`--type`) option is required. It's the type of the JMS connection factory. Currently on `activemq` and `webspheremq` type are supported. If you want to use another type of JMS connection factory, you can create the `deploy/connectionfactory-[name].xml` file by hand (using one as template).
+* the `-u` (`--url`) option is required. It's the URL used by the JMS connection factory to connect to the broker. If the type is `activemq`, the URL looks like `tcp://localhost:61616`. If the type is `webspheremq`, the URL looks like `host/port/queuemanager/channel`.
+
+For instance, to create a JMS connection factory for a Apache ActiveMQ broker, you can do:
+
+----
+karaf@root()> jms:create -t activemq -u tcp://localhost:61616 test
+----
+
+{warning}
+The `jms:create` command doesn't install any feature or bundle providing the JMS connection factory classes (and dependencies).
+You have to install the required features (for instance `activemq-broker` feature for Apache ActiveMQ), or bundles (for IBM WebsphereMQ) providing the JMS connection factory packages and classes.
+{warning}
+
+In the previous example, we assume that you previously installed the `activemq-broker` feature.
+
+We can see the created JMS connection factory:
+
+----
+karaf@root()> la
+...
+151 | Active | 80 | 0.0.0 | connectionfactory-test.xml
+----
+
+The `connectionfactory-test.xml` file has been created in the `deploy` folder.
+
+By default, the `jms:create` command constructs a JNDI name for the connection factory: `/jms/[name]`.
+
+It means that the connection factory name to use for the other `jms:*` commands is `/jms/[name]`.
+
+=== `jms:delete`
+
+The `jms:delete` command deletes a JMS connection factory. The `name` argument is the name that you used at creation time:
+
+----
+karaf@root()> jms:delete test
+----
+
+=== `jms:connectionfactories`
+
+The `jms:connectionfactories` command lists the JMS connection factories:
+
+----
+karaf@root()> jms:connectionfactories
+JMS Connection Factory
+----------------------
+/jms/test
+----
+
+=== `jms:info`
+
+The `jms:info` command provides details about the JMS connection factory:
+
+----
+karaf@root()> jms:info /jms/test
+Property | Value
+-------------------
+product | ActiveMQ
+version | 5.9.0
+----
+
+You can see the JMS broker product and version.
+
+If the JMS broker requires an authentication, you can use the `-u` (`--username`) and `-p` (`--password`) options.
+
+=== `jms:queues`
+
+The `jms:queues` command lists the JMS queues available on a JMS broker. For instance:
+
+----
+karaf@root()> jms:queues /jms/test
+JMS Queues
+----------
+MyQueue
+----
+
+where `/jms/test` is the name of the JMS connection factory.
+
+If the JMS broker requires an authentication, you can use the `-u` (`--username`) and `-p` (`--password`) options.
+
+{warning}
+Depending of the JMS connection factory type, this command may not work.
+For now, the command works only with Apache ActiveMQ.
+{warning}
+
+=== `jms:topics`
+
+The `jms:topics` command lists the JMS topics available on a JMS broker. For instance:
+
+----
+karaf@root()> jms:topics /jms/test
+JMS Topics
+----------
+MyTopic
+----
+
+where `/jms/test` is the name of the JMS connection factory.
+
+If the JMS broker requires an authentication, you can use the `-u` (`--username`) and `-p` (`--password`) options.
+
+{warning}
+Depending of the JMS connection factory type, this command may not work.
+For now, the command works only with Apache ActiveMQ.
+{warning}
+
+=== `jms:send`
+
+The `jms:send` command sends a message to a given JMS queue.
+
+For instance, to send a message containing `Hello World` in the `MyQueue` queue, you can do:
+
+----
+karaf@root()> jms:send /jms/test MyQueue "Hello World"
+----
+
+If the JMS broker requires an authentication, you can use the `-u` (`--username`) and `-p` (`--password`) options.
+
+=== `jms:consume`
+
+The `jms:consume` command consumes messages from a JMS queue.
+
+For instance, to consume all messages from `MyQueue`, you can do:
+
+----
+karaf@root()> jms:consume /jms/test MyQueue
+2 message(s) consumed
+----
+
+If you want to consume only some messages, you can define a selector using the `-s` (`--selector`) option.
+
+If the JMS broker requires an authentication, you can use the `-u` (`--username`) and `-p` (`--password`) options.
+
+{warning}
+The `jms:consume` command just consumes (so removes) messages from a JMS queue. It doesn't display the messages.
+If you want to see the details of messages, you can use the `jms:browse` command.
+{warning}
+
+=== `jms:count`
+
+The `jms:count` command counts the number of pending messages into a JMS queue.
+
+For instance, if you want to know the number of messages on `MyQueue`, you can do:
+
+----
+karaf@root()> jms:count /jms/test MyQueue
+Messages Count
+--------------
+8
+----
+
+If the JMS broker requires an authentication, you can use the `-u` (`--username`) and `-p` (`--password`) options.
+
+=== `jms:browse`
+
+The `jms:browse` command browses a JMS queue and display details about messages.
+
+For instance, to browse the `MyQueue` queue:
+
+----
+karaf@root()> jms:browse /jms/test MyQueue
+Message ID | Content | Charset | Type | Correlation ID | Delivery Mode | Destination | Expiration | Priority | Redelivered | ReplyTo | Timestamp
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ID:vostro-59602-1387462183019-3:1:1:1:1 | Hello World | UTF-8 | | | Persistent | queue://MyQueue | Never | 4 | false | | Thu Dec 19 15:10:12 CET 2013
+ID:vostro-59602-1387462183019-3:2:1:1:1 | Hello ActiveMQ | UTF-8 | | | Persistent | queue://MyQueue | Never | 4 | false | | Thu Dec 19 15:10:16 CET 2013
+ID:vostro-59602-1387462183019-3:3:1:1:1 | Hello Karaf | UTF-8 | | | Persistent | queue://MyQueue | Never | 4 | false | | Thu Dec 19 15:10:19 CET 2013
+----
+
+By default, the messages properties are not displayed. You can use the `-v` (`--verbose`) option to display the properties:
+
+----
+karaf@root()> jms:browse -v /jms/test MyQueue
+Message ID | Content | Charset | Type | Correlation ID | Delivery Mode | Destination | Expiration | Priority | Redelivered | ReplyTo | Timestamp | Properties
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ID:vostro-59602-1387462183019-3:1:1:1:1 | Hello World | UTF-8 | | | Persistent | queue://MyQueue | Never | 4 | false | | Thu Dec 19 15:10:12 CET 2013 |
+ID:vostro-59602-1387462183019-3:2:1:1:1 | Hello ActiveMQ | UTF-8 | | | Persistent | queue://MyQueue | Never | 4 | false | | Thu Dec 19 15:10:16 CET 2013 |
+ID:vostro-59602-1387462183019-3:3:1:1:1 | Hello Karaf | UTF-8 | | | Persistent | queue://MyQueue | Never | 4 | false | | Thu Dec 19 15:10:19 CET 2013 |
+----
+
+If you want to browse only some messages, you can define a selector using the `-s` (`--selector`) option.
+
+If the JMS broker requires an authentication, you can use the `-u` (`--username`) and `-p` (`--password`) options.
+
+=== `jms:move`
+
+The `jms:move` command consumes all messages from a JMS queue and send it to another one.
+
+For instance, to move all messages from `MyQueue` queue to `AnotherQueue` queue, you can do:
+
+----
+karaf@root()> jms:move /jms/test MyQueue AnotherQueue
+3 message(s) moved
+----
+
+== JMX JMS MBean
+
+The JMX JMS MBean provides the attributes and operations to manipulate the JMS connection factories and JMS messages.
+
+The object name to use is `org.apache.karaf:type=jms,name=*`.
+
+=== Attributes
+
+The `Connectionfactories` attribute provides the list of all JMS connection factories names.
+
+=== Operations
+
+* `create(name, type, url)` creates a JMS connection factory.
+* `delete(name)` deletes a JMS connection factory.
+* `Map<String, String> info(connectionFactory, username, password)` gets details about a JMS connection factory and broker.
+* `int count(connectionFactory, queue, username, password)` counts the number of pending messages on a JMS queue.
+* `List<String> queues(connectionFactory, username, password)` lists the JMS queues available on the JMS broker.
+* `List<String> topics(connectionFactory, username, password)` lists the JMS topics available on the JMS broker.
+* `TabularData browse(connectionFactory, queue, selector, username, password)` browses a JMS queue and provides a table of JMS messages.
+* `send(connectionFactory, queue, content, replyTo, username, password)` sends a JMS message to a target queue.
+* `int consume(connectionFactory, queue, selector, username, password)` consumes JMS messages from a JMS queue.
+* `int move(connectionFactory, source, destination, selector, username, password)` moves messages from a JMS queue to another.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/karaf/blob/677c6d46/manual/src/main/asciidoc/users-guide/jndi.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/users-guide/jndi.adoc b/manual/src/main/asciidoc/users-guide/jndi.adoc
new file mode 100644
index 0000000..33867d8
--- /dev/null
+++ b/manual/src/main/asciidoc/users-guide/jndi.adoc
@@ -0,0 +1,205 @@
+= Naming (JNDI)
+
+The Apache Karaf Naming (JNDI) is an optional enterprise feature.
+
+You have to install the `jndi` feature first:
+
+----
+karaf@root()> feature:install jndi
+----
+
+Apache Karaf provides a complete JNDI support.
+
+You have two parts in the Apache Karaf JNDI support:
+
+* a fully compliant implementation of the OSGi Alliance JNDI Service specification.
+* a more "regular" JNDI context, containing different names that you can administrate.
+
+== OSGi Services Registry and JNDI
+
+The OSGi Service Registry provides a centralized register/query capabilities for OSGi services.
+
+A common pattern outside of OSGi is to make use of JNDI API to access services from a directory system.
+The OSGi service registry can be viewed as an example of such a system.
+
+Apache Karaf supports the `osgi:service` lookup scheme as defined by the JNDI Service Specification.
+
+The schema is:
+
+----
+osgi:service/<interface>[/<filter>]
+----
+
+For instance, you can directly use JNDI to get a OSGi service:
+
+----
+Context ctx = new InitialContext();
+Runnable r = (Runnable) ctx.lookup("osgi:service/java.lang.Runnable");
+----
+
+== JNDI service
+
+Apache Karaf also supports regular JNDI, including a directoy system where you can register name bindings, sub-context, etc.
+
+It supports the standard JNDI API:
+
+----
+Context ctx = new InitialContext();
+Runnable r = (Runnable) ctx.lookup("this/is/the/name");
+----
+
+It also allows you to bind some OSGi services as "pure" JNDI name. In that case, you don't have to use the specific
+`osgi:service` scheme.
+
+== Commands
+
+Apache Karaf provides specific commands to manipulate the JNDI service.
+
+=== `jndi:names`
+
+The `jndi:names` command lists all JNDI names. It groups both the JNDI names from the `osgi:service` scheme and the
+regular JNDI names:
+
+----
+karaf@root()> jndi:names
+JNDI Name | Class Name
+------------------------------------------------------------------
+osgi:service/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl
+jndi/service | org.apache.karaf.jndi.internal.JndiServiceImpl
+----
+
+We can see here the `osgi:service/jndi` name (using the `osgi:service` scheme) and `jndi/service` name (using the
+regular JNDI service).
+
+The `jndi:names` command accepts an optional `context` argument to list names on the given context.
+
+For instance, you can list only names in the `jndi` sub-context:
+
+----
+karaf@root()> jndi:names jndi
+JNDI Name | Class Name
+----------------------------------------------------------
+service | org.apache.karaf.jndi.internal.JndiServiceImpl
+----
+
+{warning}
+The `jndi:names` lists only names (the full qualified name). It means that the empty JNDI sub-contexts are not displayed.
+To display all JNDI sub-contexts (empty or not), you can use the `jndi:contexts` command.
+{warning}
+
+=== `jndi:contexts`
+
+The `jndi:contexts` command lists all JNDI sub-contexts:
+
+----
+karaf@root()> jndi:contexts
+JNDI Sub-Context
+----------------
+other/context
+foo/bar
+----
+
+=== `jndi:create`
+
+The `jndi:create` command creates a new JNDI sub-context:
+
+----
+karaf@root()> jndi:create my/company
+----
+
+=== `jndi:delete`
+
+The `jndi:delete` command deletes a JNDI sub-context:
+
+----
+karaf@root()> jndi:delete my/company
+----
+
+=== `jndi:alias`
+
+The `jndi:alias` command creates a new JNDI name (alias) with an existing one.
+
+The existing JNDI name can be a regular one:
+
+----
+karaf@root()> jndi:alias bean/services/jndi aliases/services/jndi
+karaf@root()> jndi:names
+JNDI Name | Class Name
+----------------------------------------------------------------------
+osgi:service/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl
+bean/services/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl
+aliases/services/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl
+----
+
+or a name from the `osgi:service` schema:
+
+----
+karaf@root()> jndi:alias osgi:service/jndi alias/jndi/service
+karaf@root()> jndi:names
+JNDI Name | Class Name
+-------------------------------------------------------------------
+osgi:service/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl
+alias/jndi/service | org.apache.karaf.jndi.internal.JndiServiceImpl
+----
+
+NB: the `jndi:alias` automatically creates all required JNDI sub-contexts.
+
+=== `jndi:bind`
+
+The `jndi:bind` command binds an OSGi service with a JNDI name.
+
+The `jndi:bind` command requires an OSGi service ID and a JNDI name. The OSGi service ID can be found using the `service:list` command.
+
+For instance, we can bind the OSGi service with ID 344 with the JNDI name `services/kar`:
+
+----
+karaf@root()> jndi:bind 344 services/kar
+karaf@root()> jndi:names
+JNDI Name | Class Name
+-------------------------------------------------------------------------------
+osgi:service/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl
+services/kar | org.apache.karaf.kar.internal.KarServiceImpl
+----
+
+=== `jndi:unbind`
+
+The `jndi:unbind` command unbind a given JNDI name:
+
+----
+karaf@root()> jndi:names
+JNDI Name | Class Name
+-------------------------------------------------------------------------------
+osgi:service/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl
+services/kar | org.apache.karaf.kar.internal.KarServiceImpl
+karaf@root()> jndi:unbind services/kar
+karaf@root()> jndi:names
+JNDI Name | Class Name
+-------------------------------------------------------------------------------
+osgi:service/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl
+----
+
+{warning}
+It's not possible to unbind a name from the `osgi:service` schema, as it's linked to a OSGi service.
+{warning}
+
+== JMX JndiMBean
+
+The JMX JndiMBean provides the JNDI names, and the operations to manipulate the JNDI service.
+
+The object name to use is `org.apache.karaf:type=jndi,name=*`.
+
+=== Attributes
+
+The `Names` attribute provides a map containing all JNDI names and class names from both `osgi:service` scheme
+and the regular JNDI service.
+
+The `Contexts` attribute provides a list containing all JNDI sub-contexts.
+
+=== Operations
+
+* `getNames(context)` provides a map containing JNDI names and class names in a given JNDI sub-context.
+* `create(context)` creates a new JNDI sub-context.
+* `delete(context)` deletes a JNDI sub-context.
+* `alias(name, alias` creates a JNDI name (alias) for a given one.
+* `bind(serviceId, name` binds a JNDI name using an OSGi service (identified by its ID).
+* `unbind(name)` unbinds a JNDI name.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/karaf/blob/677c6d46/manual/src/main/asciidoc/users-guide/jpa.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/users-guide/jpa.adoc b/manual/src/main/asciidoc/users-guide/jpa.adoc
new file mode 100644
index 0000000..6baf4e7
--- /dev/null
+++ b/manual/src/main/asciidoc/users-guide/jpa.adoc
@@ -0,0 +1,26 @@
+= Persistence (JPA)
+
+Apache Karaf provides JPA persistence providers (such as Apache OpenJPA) to be easy to use (in a OSGi way) and provide
+container managed persistence for applications (using Blueprint).
+
+Apache Karaf embeds Aries JPA, providing a very easy way to develop applications that use JPA persistence.
+
+See the developer guide for details about developing applications that use JPA.
+
+== Persistence engine features
+
+Apache Karaf provides a set of ready to use persistence engine features:
+
+* Apache OpenJPA. The `openjpa` feature installs the `jpa` feature with the Apache OpenJPA as persistence engine:
+
+----
+karaf@root()> feature:install openjpa
+----
+
+* Hibernate. The `hibernate` feature installs the `jpa` feature with the Hibernate persistence engine:
+
+----
+karaf@root()> feature:install hibernate
+----
+
+* EclipseLink. The `eclipselink` feature will be available in the next Apache Karaf release.
\ No newline at end of file