karaf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jbono...@apache.org
Subject [14/19] karaf git commit: KARAF-3679 - Switch documentation to asciidoc, close #65
Date Mon, 04 Jan 2016 09:57:41 GMT
http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/user-guide/monitoring.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/user-guide/monitoring.adoc b/manual/src/main/asciidoc/user-guide/monitoring.adoc
new file mode 100644
index 0000000..5f8f809
--- /dev/null
+++ b/manual/src/main/asciidoc/user-guide/monitoring.adoc
@@ -0,0 +1,287 @@
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+== 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
+----
+
+If don't need the remote JMX at all, users can remove
+
+----
+-Dcom.sun.management.jmxremote
+----
+
+from bin/karaf|bin/karaf.bat to avoid opening the RMI listening port.
+
+You have to provide an username and password to access to the JMX layer.
+The JMX layer user the security framework, and so, by default, it uses the users defined in `etc/users.properties`.
+
+You can change the port numbers of the JMX layer in the `etc/org.apache.karaf.management.cfg` configuration file.
+
+=== 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:
+
+. Specific match for the invocation, e.g. `test(int)["17"] = role1`
+
+. 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.
+
+. Signature match for the invocation, e.g. `test(int) = role3`
+ If matched, the search stops and the associated roles are used.
+
+. Method name match for the invocation, e.g. `test = role4`
+ If matched, the search stops and the associated roles are used.
+
+. 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.
+
+http://www.jolokia.org/[Jolokia] 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 link:webcontainer[WebContainer (JSP/Servlet)] 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 http://www.jolokia.org[Jolokia website] and in the http://www.jolokia.org/reference/html/[documentation].
+
+=== Decanter
+
+Apache Karaf Decanter provides a complete monitoring solution including data history, turnkey dashboards, SLA and alerting support.

http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/user-guide/obr.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/user-guide/obr.adoc b/manual/src/main/asciidoc/user-guide/obr.adoc
new file mode 100644
index 0000000..c725a24
--- /dev/null
+++ b/manual/src/main/asciidoc/user-guide/obr.adoc
@@ -0,0 +1,373 @@
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+== OBR
+
+The goal of OBR (OSGi Bundle Repository) is:
+
+. to simplify deploying and using bundles
+. 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.12.0.SNAPSHOT
+activemq-camel                                                               | org.apache.activemq.activemq-camel                                        | 5.12.0.SNAPSHOT
+activemq-karaf                                                               | activemq-karaf                                                            | 5.12.0.SNAPSHOT
+activemq-osgi                                                                | org.apache.activemq.activemq-osgi                                         | 5.12.0.SNAPSHOT
+Apache Aries Application API                                                 | org.apache.aries.application.api                                          | 1.0.1.SNAPSHOT
+...
+----
+
+==== `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/4.0.0
+description: Core implementation and integration of the Java Service Wrapper.        It provides a complete integration of Karaf with your Operating System.
+documentation: http://www.apache.org/
+symbolicname: org.apache.karaf.wrapper.core
+presentationname: Apache Karaf :: Wrapper :: Core
+license: http://www.apache.org/licenses/LICENSE-2.0.txt
+uri: file:/user/.m2/repository/org/apache/karaf/wrapper/org.apache.karaf.wrapper.core/4.0.0/org.apache.karaf.wrapper.core-4.0.0.jar
+size: 1281352
+version: 4.0.0
+Requires:
+   service:(&(service=org.apache.aries.blueprint.NamespaceHandler)(osgi.service.blueprint.namespace=http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0))
+   package:(&(package=javax.management))
+   package:(&(package=org.apache.karaf.wrapper))
+   package:(&(package=org.apache.karaf.wrapper.management))
+   package:(&(package=org.fusesource.jansi)(version>=1.11.0)(!(version>=2.0.0)))
+   package:(&(package=org.osgi.framework)(version>=1.7.0)(!(version>=2.0.0)))
+   package:(&(package=org.osgi.framework.launch)(version>=1.1.0)(!(version>=2.0.0)))
+   package:(&(package=org.osgi.framework.startlevel)(version>=1.0.0)(!(version>=2.0.0)))
+   package:(&(package=org.osgi.service.blueprint)(version>=1.0.0)(!(version>=2.0.0)))
+   package:(&(package=org.slf4j)(version>=1.7.0)(!(version>=2.0.0)))
+Capabilities:
+   bundle:{manifestversion=2, symbolicname=org.apache.karaf.wrapper.core, presentationname=Apache Karaf :: Wrapper :: Core, version=4.0.0}
+   service:{service=org.apache.karaf.wrapper.WrapperService}
+   package:{package=org.apache.karaf.wrapper, version=4.0.0}
+   package:{package=org.apache.karaf.wrapper.management, uses:=javax.management, version=4.0.0}
+----
+
+The `obr:info` command uses the following syntax to identify the bundles: `symbolic_name,version` where `version` is optional.
+It means that you have to use the following command to see the info about the wrapper core bundle with version 4.0.0:
+
+----
+karaf@root()> obr:info org.apache.karaf.wrapper.core,4.0.0
+...
+----
+
+You can specific multiple bundles separated by space:
+
+----
+karaf@root()> obr:info org.apache.karaf.wrapper.core,4.0.0 org.apache.karaf.wrapper.command,4.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 4.0.0:
+
+----
+karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core,4.0.0
+----
+
+You can specify multiple bundles separated by space:
+
+----
+karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core,4.0.0 org.apache.karaf.wrapper.command,4.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 (4.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/4.0.0
+description: Core implementation and integration of the Java Service Wrapper.        It provides a complete integration of Karaf with your Operating System.
+documentation: http://www.apache.org/
+symbolicname: org.apache.karaf.wrapper.core
+presentationname: Apache Karaf :: Wrapper :: Core
+license: http://www.apache.org/licenses/LICENSE-2.0.txt
+uri: file:/user/.m2/repository/org/apache/karaf/wrapper/org.apache.karaf.wrapper.core/4.0.0/org.apache.karaf.wrapper.core-4.0.0.jar
+size: 1281352
+version: 4.0.0
+Requirements:
+   service:(&(service=org.apache.aries.blueprint.NamespaceHandler)(osgi.service.blueprint.namespace=http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0))
+   package:(&(package=javax.management))
+   package:(&(package=org.apache.karaf.wrapper))
+   package:(&(package=org.apache.karaf.wrapper.management))
+   package:(&(package=org.fusesource.jansi)(version>=1.11.0)(!(version>=2.0.0)))
+   package:(&(package=org.osgi.framework)(version>=1.7.0)(!(version>=2.0.0)))
+   package:(&(package=org.osgi.framework.launch)(version>=1.1.0)(!(version>=2.0.0)))
+   package:(&(package=org.osgi.framework.startlevel)(version>=1.0.0)(!(version>=2.0.0)))
+   package:(&(package=org.osgi.service.blueprint)(version>=1.0.0)(!(version>=2.0.0)))
+   package:(&(package=org.slf4j)(version>=1.7.0)(!(version>=2.0.0)))
+Capabilities:
+   bundle:{manifestversion=2, symbolicname=org.apache.karaf.wrapper.core, presentationname=Apache Karaf :: Wrapper :: Core, version=4.0.0}
+   service:{service=org.apache.karaf.wrapper.WrapperService}
+   package:{package=org.apache.karaf.wrapper, version=4.0.0}
+   package:{package=org.apache.karaf.wrapper.management, uses:=javax.management, version=4.0.0}
+----
+
+==== `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 4.0.0:
+
+----
+karaf@root()> obr:deploy org.apache.karaf.wrapper.core,4.0.0
+----
+
+You can specify multiple bundles separated by space:
+
+----
+karaf@root()> obr:deploy org.apache.karaf.wrapper.core,4.0.0 org.apache.karaf.wrapper.command,4.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 4.0.0:
+
+----
+karaf@root()> obr:start org.apache.karaf.wrapper.core,4.0.0
+----
+
+You can specify multiple bundles separated by space:
+
+----
+karaf@root()> obr:start org.apache.karaf.wrapper.core,4.0.0 org.apache.karaf.wrapper.command,4.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 http://karaf.apache.org/index/subprojects/cave.html for details.

http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/user-guide/provisioning.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/user-guide/provisioning.adoc b/manual/src/main/asciidoc/user-guide/provisioning.adoc
new file mode 100644
index 0000000..aef345b
--- /dev/null
+++ b/manual/src/main/asciidoc/user-guide/provisioning.adoc
@@ -0,0 +1,685 @@
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+== Provisioning
+
+Apache Karaf supports the provisioning of applications and modules using the concept of Karaf Features.
+
+=== Application
+
+By provisioning application, it means install all modules, configuration, and transitive applications.
+
+=== OSGi
+
+It natively supports the deployment of OSGi applications.
+
+An OSGi application is a set of OSGi bundles. An OSGi bundles is a regular jar file, with additional metadata in the jar MANIFEST.
+
+In OSGi, a bundle can depend to other bundles. So, it means that to deploy an OSGi application, most of the time, you have
+to firstly deploy a lot of other bundles required by the application.
+
+So, you have to find these bundles first, install the bundles. Again, these "dependency" bundles may require other bundles
+to satisfy their own dependencies.
+
+More over, typically, an application requires configuration (see the [Configuration section|configuration] of the user guide).
+So, before being able to start your application, in addition of the dependency bundles, you have to create or deploy the
+configuration.
+
+As we can see, the provisioning of an application can be very long and fastidious.
+
+=== Feature and resolver
+
+Apache Karaf provides a simple and flexible way to provision applications.
+
+In Apache Karaf, the application provisioning is an Apache Karaf "feature".
+
+A feature describes an application as:
+
+* a name
+* a version
+* a optional description (eventually with a long description)
+* a set of bundles
+* optionally a set configurations or configuration files
+* optionally a set of dependency features
+
+When you install a feature, Apache Karaf installs all resources described in the feature. It means that it will
+automatically resolves and installs all bundles, configurations, and dependency features described in the feature.
+
+The feature resolver checks the service requirements, and install the bundles providing the services matching the requirements.
+The default mode enables this behavior only for "new style" features repositories (basically, the features repositories XML with
+schema equal or greater to 1.3.0). It doesn't apply for "old style" features repositories (coming from Karaf 2 or 3).
+
+You can change the service requirements enforcement mode in `etc/org.apache.karaf.features.cfg` file, using the `serviceRequirements` property.
+
+----
+serviceRequirements=default
+----
+
+The possible values are:
+
+* disable: service requirements are completely ignored, for both "old style" and "new style" features repositories
+* default: service requirements are ignored for "old style" features repositories, and enabled for "new style" features repositories.
+* enforce: service requirements are always verified, for "old style" and "new style" features repositories.
+
+Additionally, a feature can also define requirements. In that case, Karaf can automatically additional bundles or features
+providing the capabilities to satisfy the requirements.
+
+A feature has a complete lifecycle: install, start, stop, update, uninstall.
+
+=== Features repositories
+
+The features are described in a features XML descriptor. This XML file contains the description of a set of features.
+
+A features XML descriptor is named a "features repository". Before being able to install a feature, you have to register
+the features repository that provides the feature (using `feature:repo-add` command or FeatureMBean as described later).
+
+For instance, the following XML file (or "features repository") describes the `feature1` and `feature2` features:
+
+----
+<features xmlns="http://karaf.apache.org/xmlns/features/v1.3.0">
+  <feature name="feature1" version="1.0.0">
+    <bundle>...</bundle>
+    <bundle>...</bundle>
+  </feature>
+  <feature name="feature2" version="1.1.0">
+    <feature>feature1</feature>
+    <bundle>...</bundle>
+  </feature>
+</features>
+----
+
+We can note that the features XML has a schema. Take a look on [Features XML Schema section|provisioning-schema] of the user guide
+for details.
+The `feature1` feature is available in version `1.0.0`, and contains two bundles. The `<bundle/>` element contains a URL
+to the bundle artifact (see [Artifacts repositories and URLs section|urls] for details). If you install the `feature1` feature
+(using `feature:install` or the FeatureMBean as described later), Apache Karaf will automatically installs the two bundles
+described.
+The `feature2` feature is available in version `1.1.0`, and contains a reference to the `feature1` feature and a bundle.
+The `<feature/>` element contains the name of a feature. A specific feature version can be defined using the `version`
+attribute to the `<feature/>` element (`<feature version="1.0.0">feature1</feature>`). If the `version` attribute is
+not specified, Apache Karaf will install the latest version available. If you install the `feature2` feature (using `feature:install`
+or the FeatureMBean as described later), Apache Karaf will automatically installs `feature1` (if it's not already installed)
+and the bundle.
+
+A feature repository is registered using the URL to the features XML file.
+
+The features state is stored in the Apache Karaf cache (in the `KARAF_DATA` folder). You can restart Apache Karaf, the
+previously installed features remain installed and available after restart.
+If you do a clean restart or you delete the Apache Karaf cache (delete the `KARAF_DATA` folder), all previously features
+repositories registered and features installed will be lost: you will have to register the features repositories and install
+features by hand again.
+To prevent this behaviour, you can specify features as boot features.
+
+=== Boot features
+
+You can describe some features as boot features. A boot feature will be automatically install by Apache Karaf, even if it has
+not been previously installed using `feature:install` or FeatureMBean.
+
+Apache Karaf features configuration is located in the `etc/org.apache.karaf.features.cfg` configuration file.
+
+This configuration file contains the two properties to use to define boot features:
+
+* `featuresRepositories` contains a list (coma separated) of features repositories (features XML) URLs.
+* `featuresBoot` contains a list (come separated) of features to install at boot.
+
+=== Features upgrade
+
+You can update a release by installing the same feature (with the same SNAPSHOT version or a different version).
+
+Thanks to the features lifecycle, you can control the status of the feature (started, stopped, etc).
+
+You can also use a simulation to see what the update will do.
+
+=== Feature bundles
+
+==== Start Level
+
+By default, the bundles deployed by a feature will have a start-level equals to the value defined in the `etc/config.properties`
+configuration file, in the `karaf.startlevel.bundle` property.
+
+This value can be "overrided" by the `start-level` attribute of the `<bundle/>` element, in the features XML.
+
+----
+  <feature name="my-project" version="1.0.0">
+    <bundle start-level="80">mvn:com.mycompany.myproject/myproject-dao</bundle>
+    <bundle start-level="85">mvn:com.mycompany.myproject/myproject-service</bundle>
+  </feature>
+----
+
+The start-level attribute insure that the `myproject-dao` bundle is started before the bundles that use it.
+
+Instead of using start-level, a better solution is to simply let the OSGi framework know what your dependencies are by
+defining the packages or services you need. It is more robust than setting start levels.
+
+==== Simulate, Start and stop
+
+You can simulate the installation of a feature using the `-t` option to `feature:install` command.
+
+You can install a bundle without starting it. By default, the bundles in a feature are automatically started.
+
+A feature can specify that a bundle should not be started automatically (the bundle stays in resolved state).
+To do so, a feature can specify the `start` attribute to false in the `<bundle/>` element:
+
+----
+  <feature name="my-project" version="1.0.0">
+    <bundle start-level="80" start="false">mvn:com.mycompany.myproject/myproject-dao</bundle>
+    <bundle start-level="85" start="false">mvn:com.mycompany.myproject/myproject-service</bundle>
+  </feature>
+----
+
+==== Dependency
+
+A bundle can be flagged as being a dependency, using the `dependency` attribute set to true on the `<bundle/>` element.
+
+This information can be used by resolvers to compute the full list of bundles to be installed.
+
+=== Dependent features
+
+A feature can depend to a set of other features:
+
+----
+  <feature name="my-project" version="1.0.0">
+    <feature>other</feature>
+    <bundle start-level="80" start="false">mvn:com.mycompany.myproject/myproject-dao</bundle>
+    <bundle start-level="85" start="false">mvn:com.mycompany.myproject/myproject-service</bundle>
+  </feature>
+----
+
+When the `my-project` feature will be installed, the `other` feature will be automatically installed as well.
+
+It's possible to define a version range for a dependent feature:
+
+----
+<feature name="spring-dm">
+  <feature version="[2.5.6,4)">spring</feature>
+  ...
+</feature>
+----
+
+The feature with the highest version available in the range will be installed.
+
+If a single version is specified, this version will be chosen.
+
+If nothing is specified, the highest available will be installed.
+
+=== Feature configurations
+
+The `<config/>` element in a feature XML allows a feature to create and/or populate a configuration (identified by a configuration PID).
+
+----
+<config name="com.foo.bar">
+  myProperty = myValue
+</config>
+----
+
+The `name` attribute of the `<config/>` element corresponds to the configuration PID (see the [Configuration section|configuration] for details).
+
+The installation of the feature will have the same effect as dropping a file named `com.foo.bar.cfg` in the `etc` folder.
+
+The content of the `<config/>` element is a set of properties, following the key=value standard.
+
+=== Feature configuration files
+
+Instead of using the `<config/>` element, a feature can specify `<configfile/>` elements.
+
+----
+<configfile finalname="/etc/myfile.cfg" override="false">URL</configfile>
+----
+
+Instead of directly manipulating the Apache Karaf configuration layer (as when using the `<config/>` element), the
+`<configfile/>` element takes directly a file specified by a URL, and copy the file in the location specified by the
+`finalname` attribute.
+
+If not specified, the location is relative from the `KARAF_BASE` variable. It's also possible to use variable like
+${karaf.home}, ${karaf.base}, ${karaf.etc}, or even system properties.
+
+For instance:
+
+----
+<configfile finalname="${karaf.etc}/myfile.cfg" override="false">URL</configfile>
+----
+
+If the file is already present at the desired location it is kept and the deployment of the configuration file is skipped,
+as a already existing file might contain customization. This behaviour can be overriden by `override` set to true.
+
+The file URL is any URL supported by Apache Karaf (see the [Artifacts repositories and URLs|urls] of the user guide for details).
+
+==== Requirements
+
+A feature can also specify expected requirements. The feature resolver will try to satisfy the requirements. For that, it checks
+the features and bundles capabilities and will automatically install the bundles to satisfy the requirements.
+
+For instance, a feature can contain:
+
+----
+<requirement>osgi.ee;filter:=&quot;(&amp;(osgi.ee=JavaSE)(!(version&gt;=1.8)))&quot;</requirement>
+----
+
+The requirement specifies that the feature will work by only if the JDK version is not 1.8 (so basically 1.7).
+
+The features resolver is also able to refresh the bundles when an optional dependency is satisfy, rewiring the optional import.
+
+=== Commands
+
+==== `feature:repo-list`
+
+The `feature:repo-list` command lists all registered features repository:
+
+----
+karaf@root()> feature:repo-list
+Repository               | URL
+--------------------------------------------------------------------------------------
+org.ops4j.pax.cdi-0.12.0 | mvn:org.ops4j.pax.cdi/pax-cdi-features/0.12.0/xml/features
+org.ops4j.pax.web-4.1.4  | mvn:org.ops4j.pax.web/pax-web-features/4.1.4/xml/features
+standard-4.0.0           | mvn:org.apache.karaf.features/standard/4.0.0/xml/features
+enterprise-4.0.0         | mvn:org.apache.karaf.features/enterprise/4.0.0/xml/features
+spring-4.0.0             | mvn:org.apache.karaf.features/spring/4.0.0/xml/features
+----
+
+Each repository has a name and the URL to the features XML.
+
+Apache Karaf parses the features XML when you register the features repository URL (using `feature:repo-add` command
+or the FeatureMBean as described later). If you want to force Apache Karaf to reload the features repository URL (and
+so update the features definition), you can use the `-r` option:
+
+----
+karaf@root()> feature:repo-list -r
+Reloading all repositories from their urls
+
+Repository               | URL
+--------------------------------------------------------------------------------------
+org.ops4j.pax.cdi-0.12.0 | mvn:org.ops4j.pax.cdi/pax-cdi-features/0.12.0/xml/features
+org.ops4j.pax.web-4.1.4  | mvn:org.ops4j.pax.web/pax-web-features/4.1.4/xml/features
+standard-4.0.0           | mvn:org.apache.karaf.features/standard/4.0.0/xml/features
+enterprise-4.0.0         | mvn:org.apache.karaf.features/enterprise/4.0.0/xml/features
+spring-4.0.0             | mvn:org.apache.karaf.features/spring/4.0.0/xml/features
+----
+
+==== `feature:repo-add`
+
+To register a features repository (and so having new features available in Apache Karaf), you have to use the
+`feature:repo-add` command.
+
+The `feature:repo-add` command requires the `name/url` argument. This argument accepts:
+
+* a feature repository URL. It's an URL directly to the features XML file. Any URL described in the [Artifacts repositories and URLs section|urls]
+ of the user guide is supported.
+* a feature repository name defined in the `etc/org.apache.karaf.features.repos.cfg` configuration file.
+
+The `etc/org.apache.karaf.features.repos.cfg` defines a list of "pre-installed/available" features repositories:
+
+----
+################################################################################
+#
+#    Licensed to the Apache Software Foundation (ASF) under one or more
+#    contributor license agreements.  See the NOTICE file distributed with
+#    this work for additional information regarding copyright ownership.
+#    The ASF licenses this file to You under the Apache License, Version 2.0
+#    (the "License"); you may not use this file except in compliance with
+#    the License.  You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+#
+################################################################################
+
+#
+# This file describes the features repository URL
+# It could be directly installed using feature:repo-add command
+#
+enterprise=mvn:org.apache.karaf.features/enterprise/LATEST/xml/features
+spring=mvn:org.apache.karaf.features/spring/LATEST/xml/features
+cellar=mvn:org.apache.karaf.cellar/apache-karaf-cellar/LATEST/xml/features
+cave=mvn:org.apache.karaf.cave/apache-karaf-cave/LATEST/xml/features
+camel=mvn:org.apache.camel.karaf/apache-camel/LATEST/xml/features
+camel-extras=mvn:org.apache-extras.camel-extra.karaf/camel-extra/LATEST/xml/features
+cxf=mvn:org.apache.cxf.karaf/apache-cxf/LATEST/xml/features
+cxf-dosgi=mvn:org.apache.cxf.dosgi/cxf-dosgi/LATEST/xml/features
+cxf-xkms=mvn:org.apache.cxf.services.xkms/cxf-services-xkms-features/LATEST/xml
+activemq=mvn:org.apache.activemq/activemq-karaf/LATEST/xml/features
+jclouds=mvn:org.apache.jclouds.karaf/jclouds-karaf/LATEST/xml/features
+openejb=mvn:org.apache.openejb/openejb-feature/LATEST/xml/features
+wicket=mvn:org.ops4j.pax.wicket/features/LATEST/xml/features
+hawtio=mvn:io.hawt/hawtio-karaf/LATEST/xml/features
+pax-cdi=mvn:org.ops4j.pax.cdi/pax-cdi-features/LATEST/xml/features
+pax-jdbc=mvn:org.ops4j.pax.jdbc/pax-jdbc-features/LATEST/xml/features
+pax-jpa=mvn:org.ops4j.pax.jpa/pax-jpa-features/LATEST/xml/features
+pax-web=mvn:org.ops4j.pax.web/pax-web-features/LATEST/xml/features
+pax-wicket=mvn:org.ops4j.pax.wicket/pax-wicket-features/LATEST/xml/features
+ecf=http://download.eclipse.org/rt/ecf/latest/site.p2/karaf-features.xml
+decanter=mvn:org.apache.karaf.decanter/apache-karaf-decanter/LATEST/xml/features
+----
+
+You can directly provide a features repository name to the `feature:repo-add` command. For install, to install Apache Karaf Cellar, you can do:
+
+----
+karaf@root()> feature:repo-add cellar
+Adding feature url mvn:org.apache.karaf.cellar/apache-karaf-cellar/LATEST/xml/features
+----
+
+When you don't provide the optional `version` argument, Apache Karaf installs the latest version of the features repository available.
+You can specify a target version with the `version` argument:
+
+----
+karaf@root()> feature:repo-add cellar 4.0.0.RC1
+Adding feature url mvn:org.apache.karaf.cellar/apache-karaf-cellar/4.0.0.RC1/xml/features
+----
+
+Instead of providing a features repository name defined in the `etc/org.apache.karaf.features.repos.cfg` configuration file,
+you can directly provide the features repository URL to the `feature:repo-add` command:
+
+----
+karaf@root()> feature:repo-add mvn:org.apache.karaf.cellar/apache-karaf-cellar/4.0.0.RC1/xml/features
+Adding feature url mvn:org.apache.karaf.cellar/apache-karaf-cellar/4.0.0.RC1/xml/features
+----
+
+By default, the `feature:repo-add` command just registers the features repository, it doesn't install any feature.
+If you specify the `-i` option, the `feature:repo-add` command registers the features repository and installs all
+features described in this features repository:
+
+----
+karaf@root()> feature:repo-add -i cellar
+----
+
+==== `feature:repo-refresh`
+
+Apache Karaf parses the features repository XML when you register it (using `feature:repo-add` command or the FeatureMBean).
+If the features repository XML changes, you have to indicate to Apache Karaf to refresh the features repository to load the changes.
+
+The `feature:repo-refresh` command refreshes the features repository.
+
+Without argument, the command refreshes all features repository:
+
+----
+karaf@root()> feature:repo-refresh
+Refreshing feature url mvn:org.ops4j.pax.cdi/pax-cdi-features/0.12.0/xml/features
+Refreshing feature url mvn:org.ops4j.pax.web/pax-web-features/4.1.4/xml/features
+Refreshing feature url mvn:org.apache.karaf.features/standard/4.0.0/xml/features
+Refreshing feature url mvn:org.apache.karaf.features/enterprise/4.0.0/xml/features
+Refreshing feature url mvn:org.apache.karaf.features/spring/4.0.0/xml/features
+----
+
+Instead of refreshing all features repositories, you can specify the features repository to refresh, by providing the URL
+or the features repository name (and optionally version):
+
+----
+karaf@root()> feature:repo-refresh mvn:org.apache.karaf.features/standard/4.0.0/xml/features
+Refreshing feature url mvn:org.apache.karaf.features/standard/4.0.0/xml/features
+----
+
+----
+karaf@root()> feature:repo-refresh cellar
+Refreshing feature url mvn:org.apache.karaf.cellar/apache-karaf-cellar/LATEST/xml/features
+----
+
+==== `feature:repo-remove`
+
+The `feature:repo-remove` command removes a features repository from the registered ones.
+
+The `feature:repo-remove` command requires a argument:
+
+* the features repository name (as displayed in the repository column of the `feature:repo-list` command output)
+* the features repository URL (as displayed in the URL column of the `feature:repo-list` command output)
+
+----
+karaf@root()> feature:repo-remove karaf-cellar-4.0.0.RC1
+----
+
+----
+karaf@root()> feature:repo-remove mvn:org.apache.karaf.cellar/apache-karaf-cellar/LATEST/xml/features
+----
+
+By default, the `feature:repo-remove` command just removes the features repository from the registered ones: it doesn't
+uninstall the features provided by the features repository.
+
+If you use `-u` option, the `feature:repo-remove` command uninstalls all features described by the features repository:
+
+----
+karaf@root()> feature:repo-remove -u karaf-cellar-4.0.0.RC1
+----
+
+==== `feature:list`
+
+The `feature:list` command lists all available features (provided by the different registered features repositories):
+
+----
+Name                          | Version                          | Required | State       | Repository               | Description
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+pax-cdi                       | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI support
+pax-cdi-1.1                   | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI 1.1 support
+pax-cdi-1.2                   | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI 1.2 support
+pax-cdi-weld                  | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld CDI support
+pax-cdi-1.1-weld              | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld CDI 1.1 support
+pax-cdi-1.2-weld              | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld CDI 1.2 support
+pax-cdi-openwebbeans          | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | OpenWebBeans CDI support
+pax-cdi-web                   | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Web CDI support
+pax-cdi-1.1-web               | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Web CDI 1.1 support
+...
+----
+
+If you want to order the features by alphabetical name, you can use the `-o` option:
+
+----
+karaf@root()> feature:list -o
+Name                          | Version                          | Required | State       | Repository               | Description
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+deltaspike-core               | 1.2.1                            |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Apache Deltaspike core support
+deltaspike-data               | 1.2.1                            |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Apache Deltaspike data support
+deltaspike-jpa                | 1.2.1                            |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Apache Deltaspike jpa support
+deltaspike-partial-bean       | 1.2.1                            |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Apache Deltaspike partial bean support
+pax-cdi                       | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI support
+pax-cdi-1.1                   | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI 1.1 support
+pax-cdi-1.1-web               | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Web CDI 1.1 support
+pax-cdi-1.1-web-weld          | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld Web CDI 1.1 support
+pax-cdi-1.1-weld              | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld CDI 1.1 support
+pax-cdi-1.2                   | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI 1.2 support
+...
+----
+
+By default, the `feature:list` command displays all features, whatever their current state (installed or not installed).
+
+Using the `-i` option displays only installed features:
+
+----
+karaf@root()> feature:list -i
+Name            | Version | Required | State   | Repository     | Description
+-------------------------------------------------------------------------------------------------------------------
+aries-proxy     | 4.0.0   |          | Started | standard-4.0.0 | Aries Proxy
+aries-blueprint | 4.0.0   | x        | Started | standard-4.0.0 | Aries Blueprint
+feature         | 4.0.0   | x        | Started | standard-4.0.0 | Features Support
+shell           | 4.0.0   | x        | Started | standard-4.0.0 | Karaf Shell
+shell-compat    | 4.0.0   | x        | Started | standard-4.0.0 | Karaf Shell Compatibility
+deployer        | 4.0.0   | x        | Started | standard-4.0.0 | Karaf Deployer
+bundle          | 4.0.0   | x        | Started | standard-4.0.0 | Provide Bundle support
+config          | 4.0.0   | x        | Started | standard-4.0.0 | Provide OSGi ConfigAdmin support
+diagnostic      | 4.0.0   | x        | Started | standard-4.0.0 | Provide Diagnostic support
+instance        | 4.0.0   | x        | Started | standard-4.0.0 | Provide Instance support
+jaas            | 4.0.0   | x        | Started | standard-4.0.0 | Provide JAAS support
+log             | 4.0.0   | x        | Started | standard-4.0.0 | Provide Log support
+package         | 4.0.0   | x        | Started | standard-4.0.0 | Package commands and mbeans
+service         | 4.0.0   | x        | Started | standard-4.0.0 | Provide Service support
+system          | 4.0.0   | x        | Started | standard-4.0.0 | Provide System support
+kar             | 4.0.0   | x        | Started | standard-4.0.0 | Provide KAR (KARaf archive) support
+ssh             | 4.0.0   | x        | Started | standard-4.0.0 | Provide a SSHd server on Karaf
+management      | 4.0.0   | x        | Started | standard-4.0.0 | Provide a JMX MBeanServer and a set of MBeans in
+wrap            | 0.0.0   | x        | Started | standard-4.0.0 | Wrap URL handler
+----
+
+==== `feature:install`
+
+The `feature:install` command installs a feature.
+
+It requires the `feature` argument. The `feature` argument is the name of the feature, or the name/version of the feature.
+If only the name of the feature is provided (not the version), the latest version available will be installed.
+
+----
+karaf@root()> feature:install eventadmin
+----
+
+We can simulate an installation using `-t` or `--simulate` option: it just displays what it would do, but it doesn't do it:
+
+----
+karaf@root()> feature:install -t -v eventadmin
+Adding features: eventadmin/[4.0.0,4.0.0]
+No deployment change.
+  Managing bundle:
+    org.apache.felix.metatype / 1.0.12
+----
+
+You can specify a feature version to install:
+
+----
+karaf@root()> feature:install eventadmin/4.0.0
+----
+
+By default, the `feature:install` command is not verbose. If you want to have some details about actions performed by the `feature:install`
+command, you can use the `-v` option:
+
+----
+karaf@root()> feature:install -v eventadmin
+Adding features: eventadmin/[4.0.0,4.0.0]
+No deployment change.
+Done.
+----
+
+If a feature contains a bundle which is already installed, by default, Apache Karaf will refresh this bundle.
+Sometime, this refresh can cause issue to other running applications. If you want to disable the auto-refresh of installed
+bundles, you can use the `-r` option:
+
+----
+karaf@root()> feature:install -v -r eventadmin
+Adding features: eventadmin/[4.0.0,4.0.0]
+No deployment change.
+Done.
+----
+
+You can decide to not start the bundles installed by a feature using the `-s` or `--no-auto-start` option:
+
+----
+karaf@root()> feature:install -s eventadmin
+----
+
+==== `feature:start`
+
+By default, when you install a feature, it's automatically installed. However, you can specify the `-s` option to the `feature:install` command.
+
+As soon as you install a feature (started or not), all packages provided by the bundles defined in the feature will be available, and can be used for
+the wiring in other bundles.
+
+When starting a feature, all bundles are started, and so, the feature also exposes the services.
+
+==== `feature:stop`
+
+You can also stop a feature: it means that all services provided by the feature will be stop and removed from the service registry. However, the packages
+are still available for the wiring (the bundles are in resolved state).
+
+==== `feature:uninstall`
+
+The `feature:uninstall` command uninstalls a feature. As the `feature:install` command, the `feature:uninstall` command
+requires the `feature` argument. The `feature` argument is the name of the feature, or the name/version of the feature.
+If only the name of the feature is provided (not the version), the latest version available will be installed.
+
+----
+karaf@root()> feature:uninstall eventadmin
+----
+
+The features resolver is involved during feature uninstallation: transitive features installed by the uninstalled feature can be uninstalled
+themselves if not used by other feature.
+
+=== Deployer
+
+You can "hot deploy" a features XML by dropping the file directly in the `deploy` folder.
+
+Apache Karaf provides a features deployer.
+
+When you drop a features XML in the deploy folder, the features deployer does:
+* register the features XML as a features repository
+* the features with `install` attribute set to "auto" will be automatically installed by the features deployer.
+
+For instance, dropping the following XML in the deploy folder will automatically install feature1 and feature2, whereas
+feature3 won't be installed:
+
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<features name="my-features" xmlns="http://karaf.apache.org/xmlns/features/v1.3.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="http://karaf.apache.org/xmlns/features/v1.3.0 http://karaf.apache.org/xmlns/features/v1.3.0">
+
+    <feature name="feature1" version="1.0" install="auto">
+        ...
+    </feature>
+
+    <feature name="feature2" version="1.0" install="auto">
+        ...
+    </feature>
+
+    <feature name="feature3" version="1.0">
+        ...
+    </feature>
+
+</features>
+----
+
+=== JMX FeatureMBean
+
+On the JMX layer, you have a MBean dedicated to the management of the features and features repositories: the FeatureMBean.
+
+The FeatureMBean object name is: `org.apache.karaf:type=feature,name=*`.
+
+==== Attributes
+
+The FeatureMBean provides two attributes:
+
+* `Features` is a tabular data set of all features available.
+* `Repositories` is a tabular data set of all registered features repositories.
+
+The `Repositories` attribute provides the following information:
+
+* `Name` is the name of the features repository.
+* `Uri` is the URI to the features XML for this repository.
+* `Features` is a tabular data set of all features (name and version) provided by this features repository.
+* `Repositories` is a tabular data set of features repositories "imported" in this features repository.
+
+The `Features` attribute provides the following information:
+
+* `Name` is the name of the feature.
+* `Version` is the version of the feature.
+* `Installed` is a boolean. If true, it means that the feature is currently installed.
+* `Bundles` is a tabular data set of all bundles (bundles URL) described in the feature.
+* `Configurations` is a tabular data set of all configurations described in the feature.
+* `Configuration Files` is a tabular data set of all configuration files described in the feature.
+* `Dependencies` is a tabular data set of all dependent features described in the feature.
+
+==== Operations
+
+* `addRepository(url)` adds the features repository with the `url`. The `url` can be a `name` as in the `feature:repo-add` command.
+* `addRepository(url, install)` adds the features repository with the `url` and automatically installs all bundles if `install` is true. The `url` can be a `name` like in the `feature:repo-add` command.
+* `removeRepository(url)` removes the features repository with the `url`. The `url` can be a `name` as in the `feature:repo-remove` command.
+* `installFeature(name)` installs the feature with the `name`.
+* `installFeature(name, version)` installs the feature with the `name` and `version`.
+* `installFeature(name, noClean, noRefresh)` installs the feature with the `name` without cleaning the bundles in case of failure, and without refreshing already installed bundles.
+* `installFeature(name, version, noClean, noRefresh) ` installs the feature with the `name` and `version` without cleaning the bundles in case of failure, and without refreshing already installed bundles.
+* `uninstallFeature(name)` uninstalls the feature with the `name`.
+* `uninstallFeature(name, version)` uninstalls the feature with the `name` and `version`.
+
+==== Notifications
+
+The FeatureMBean sends two kind of notifications (on which you can subscribe and react):
+
+* When a feature repository changes (added or removed).
+* When a feature changes (installed or uninstalled).

http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/user-guide/remote.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/user-guide/remote.adoc b/manual/src/main/asciidoc/user-guide/remote.adoc
new file mode 100644
index 0000000..35d551e
--- /dev/null
+++ b/manual/src/main/asciidoc/user-guide/remote.adoc
@@ -0,0 +1,424 @@
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+== Remote
+
+Apache Karaf supports a complete remote mechanism allowing you to remotely connect to a running Apache Karaf instance.
+More over, you can also browse, download, and upload files remotely to a running Apache Karaf instance.
+
+Apache Karaf embeds a complete SSHd server.
+
+=== SSHd server
+
+When you start Apache Karaf, it enables a remote console that can be accessed over SSH.
+
+This remote console provides all the features of the "local" console, and gives a remote user complete control over the
+container and services running inside of it. As the "local" console, the remote console is secured by a RBAC mechanism
+(see the link:security[Security section] of the user guide for details).
+
+In addition of the remote console, Apache Karaf also provides a remote filesystem. This remote filesystem can be accessed
+using a SCP/SFTP client.
+
+==== Configuration
+
+The configuration of the SSHd server is stored in the `etc/org.apache.karaf.shell.cfg` 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.
+#
+################################################################################
+
+#
+# These properties are used to configure Karaf's ssh shell.
+#
+
+#
+# Via sshPort and sshHost you define the address you can login into Karaf.
+#
+sshPort = 8101
+sshHost = 0.0.0.0
+
+#
+# The sshIdleTimeout defines the inactivity timeout to logout the SSH session.
+# The sshIdleTimeout is in milliseconds, and the default is set to 30 minutes.
+#
+sshIdleTimeout = 1800000
+
+#
+# sshRealm defines which JAAS domain to use for password authentication.
+#
+sshRealm = karaf
+
+#
+# The location of the hostKey file defines where the private/public key of the server
+# is located. If no file is at the defined location it will be ignored.
+#
+hostKey = ${karaf.etc}/host.key
+
+#
+# Role name used for SSH access authorization
+# If not set, this defaults to the ${karaf.admin.role} configured in etc/system.properties
+#
+# sshRole = admin
+
+#
+# Self defined key size in 1024, 2048, 3072, or 4096
+# If not set, this defaults to 4096.
+#
+# keySize = 4096
+
+#
+# Specify host key algorithm, defaults to RSA
+#
+# algorithm = RSA
+
+#
+# Defines the completion mode on the Karaf shell console. The possible values are:
+# - GLOBAL: it's the same behavior as in previous Karaf releases. The completion displays all commands and all aliases
+#           ignoring if you are in a subshell or not.
+# - FIRST: the completion displays all commands and all aliases only when you are not in a subshell. When you are
+#          in a subshell, the completion displays only the commands local to the subshell.
+# - SUBSHELL: the completion displays only the subshells on the root level. When you are in a subshell, the completion
+#             displays only the commands local to the subshell.
+# This property define the default value when you use the Karaf shell console.
+# You can change the completion mode directly in the shell console, using shell:completion command.
+#
+completionMode = GLOBAL
+----
+
+The `etc/org.apache.karaf.shell.cfg` configuration file contains different properties to configure the SSHd server:
+
+* `sshPort` is the port number where the SSHd server is bound (by default, it's 8101).
+* `sshHost` is the address of the network interface where the SSHd server is bound. The default value is 0.0.0.0,
+ meaning that the SSHd server is bound on all network interfaces. You can bind on a target interface providing the IP
+ address of the network interface.
+* `hostKey` is the location of the `host.key` file. By defaut, it uses `etc/host.key`. This file stores the public
+ and private key pair of the SSHd server.
+* `sshRole` is the default role used for SSH access. The default value is the value of `karaf.admin.role` property
+ defined in `etc/system.properties`. See the [Security section|security] of this user guide for details.
+* `keySize` is the key size used by the SSHd server. The possible values are 1024, 2048, 3072, or 4096. The default
+ value is 1024.
+* `algorithm` is the host key algorithm used by the SSHd server. The possible values are DSA or RSA. The default
+ value is DSA.
+
+The SSHd server configuration can be changed at runtime:
+
+* by editing the `etc/org.apache.karaf.shell.cfg` configuration file
+* by using the `config:*` commands
+
+At runtime, when you change the SSHd server configuration, you have to restart the SSHd server to load the changes.
+You can do it with:
+
+----
+karaf@root()> bundle:restart -f org.apache.karaf.shell.ssh
+----
+
+The Apache Karaf SSHd server supports key/agent authentication and password authentication.
+
+==== Console clients
+
+===== System native clients
+
+The Apache Karaf SSHd server is a pure SSHd server, similar to OpenSSH daemon.
+
+It means that you can use directly a SSH client from your system.
+
+For instance, on Unix, you can directly use OpenSSH:
+
+----
+~$ ssh -p 8101 karaf@localhost
+Authenticated with partial success.
+Authenticated with partial success.
+Authenticated with partial success.
+Password authentication
+Password:
+        __ __                  ____
+       / //_/____ __________ _/ __/
+      / ,<  / __ `/ ___/ __ `/ /_
+     / /| |/ /_/ / /  / /_/ / __/
+    /_/ |_|\__,_/_/   \__,_/_/
+
+  Apache Karaf (4.0.0)
+
+Hit '<tab>' for a list of available commands
+and '[cmd] --help' for help on a specific command.
+Hit 'system:shutdown' to shutdown Karaf.
+Hit '<ctrl-d>' or type 'logout' to disconnect shell from current session.
+
+karaf@root()>
+----
+
+On Windows, you can use Putty, Kitty, etc.
+
+If you don't have SSH client installed on your machine, you can use Apache Karaf client.
+
+===== `ssh:ssh` command
+
+Apache Karaf itself provides a SSH client. When you are on the Apache Karaf console, you have the `ssh:ssh` command:
+
+----
+karaf@root()> ssh:ssh --help
+DESCRIPTION
+        ssh:ssh
+
+        Connects to a remote SSH server
+
+SYNTAX
+        ssh:ssh [options] hostname [command]
+
+ARGUMENTS
+        hostname
+                The host name to connect to via SSH
+        command
+                Optional command to execute
+
+OPTIONS
+        --help
+                Display this help message
+        -p, --port
+                The port to use for SSH connection
+                (defaults to 22)
+        -P, --password
+                The password for remote login
+        -q
+                Quiet Mode. Do not ask for confirmations
+        -l, --username
+                The user name for remote login
+
+----
+
+Thanks to the `ssh:ssh` command, you can connect to another running Apache Karaf instance:
+
+----
+karaf@root()> ssh:ssh -p 8101 karaf@192.168.134.2
+Connecting to host 192.168.134.2 on port 8101
+Connecting to unknown server. Add this server to known hosts ? (y/n)
+Storing the server key in known_hosts.
+Connected
+        __ __                  ____
+       / //_/____ __________ _/ __/
+      / ,<  / __ `/ ___/ __ `/ /_
+     / /| |/ /_/ / /  / /_/ / __/
+    /_/ |_|\__,_/_/   \__,_/_/
+
+  Apache Karaf (4.0.0)
+
+Hit '<tab>' for a list of available commands
+and '[cmd] --help' for help on a specific command.
+Hit 'system:shutdown' to shutdown Karaf.
+Hit '<ctrl-d>' or type 'logout' to disconnect shell from current session.
+
+karaf@root()>
+----
+
+When you don't provide the `command` argument to the `ssh:ssh` command, you are in the interactive mode: you have
+a complete remote console available, where you can type commands, etc.
+
+You can also provide directly a command to execute using the `command` argument. For instance, to remotely shutdown
+a Apache Karaf instance:
+
+----
+karaf@root()> ssh:ssh -p 8101 karaf@localhost system:shutdown -f
+Connecting to host localhost on port 8101
+Connected
+----
+
+As the `ssh:ssh` command is a pure SSH client, so it means that you can connect to a Unix OpenSSH daemon:
+
+----
+karaf@root()> ssh:ssh user@localhost
+Connecting to host localhost on port 22
+Connecting to unknown server. Add this server to known hosts ? (y/n)
+Storing the server key in known_hosts.
+Agent authentication failed, falling back to password authentication.
+Password: Connected
+Last login: Sun Sep  8 19:21:12 2013
+user@server:~$
+----
+
+===== Apache Karaf client
+
+The `ssh:ssh` command requires to be run into a running Apache Karaf console.
+
+For commodity, the `ssh:ssh` command is "wrapped" as a standalone client: the `bin/client` Unix script (`bin\client.bat` on Windows).
+
+----
+bin/client --help
+Apache Karaf client
+  -a [port]     specify the port to connect to
+  -h [host]     specify the host to connect to
+  -u [user]     specify the user name
+  --help        shows this help message
+  -v            raise verbosity
+  -r [attempts] retry connection establishment (up to attempts times)
+  -d [delay]    intra-retry delay (defaults to 2 seconds)
+  -b            batch mode, specify multiple commands via standard input
+  -f [file]     read commands from the specified file
+  [commands]    commands to run
+If no commands are specified, the client will be put in an interactive mode
+----
+
+For instance, to connect to local Apache Karaf instance (on the default SSHd server 8101 port), you can directly use
+`bin/client` Unix script (`bin\client.bat` on Windows) without any argument or option:
+
+----
+bin/client
+Logging in as karaf
+343 [pool-2-thread-4] WARN org.apache.sshd.client.keyverifier.AcceptAllServerKeyVerifier - Server at /0.0.0.0:8101 presented unverified key:
+        __ __                  ____
+       / //_/____ __________ _/ __/
+      / ,<  / __ `/ ___/ __ `/ /_
+     / /| |/ /_/ / /  / /_/ / __/
+    /_/ |_|\__,_/_/   \__,_/_/
+
+  Apache Karaf (4.0.0)
+
+Hit '<tab>' for a list of available commands
+and '[cmd] --help' for help on a specific command.
+Hit 'system:shutdown' to shutdown Karaf.
+Hit '<ctrl-d>' or type 'logout' to disconnect shell from current session.
+
+karaf@root()>
+----
+
+When you don't provide the `command` argument to the `bin/client` Unix script (`bin\client.bat` on Windows), you are
+in the interactive mode: you have a complete remote console available, where you can type commands, etc.
+
+You can also provide directly a command to execute using the `command` argument. For instance, to remotely shutdown
+a Apache Karaf instance:
+
+----
+bin/client "system:shutdown -f"
+Logging in as karaf
+330 [pool-2-thread-3] WARN org.apache.sshd.client.keyverifier.AcceptAllServerKeyVerifier - Server at /0.0.0.0:8101 presented unverified key:
+----
+
+As the Apache Karaf client is a pure SSH client, you can use to connect to any SSHd daemon (like Unix OpenSSH daemon):
+
+----
+bin/client -a 22 -h localhost -u user
+Logging in as user
+353 [pool-2-thread-2] WARN org.apache.sshd.client.keyverifier.AcceptAllServerKeyVerifier - Server at localhost/127.0.0.1:22 presented unverified key:
+Password:
+Welcome to Ubuntu 13.10 (GNU/Linux 3.11.0-13-generic x86_64)
+
+ * Documentation:  https://help.ubuntu.com/
+
+Last login: Tue Dec  3 18:18:31 2013 from localhost
+----
+
+===== Logout
+
+When you are connected to a remote Apache Karaf console, you can logout using:
+
+* using CTRL-D key binding. Note that CTRL-D just logout from the remote console in this case, it doesn't shutdown
+ the Apache Karaf instance (as CTRL-D does when used on a local console).
+* using `shell:logout` command (or simply `logout`)
+
+==== Filsystem clients
+
+Apache Karaf SSHd server also provides complete fileystem access via SSH. For security reason, the available filesystem
+is limited to `KARAF_BASE` directory.
+
+You can use this remote filesystem with any SCP/SFTP compliant clients.
+
+===== Native SCP/SFTP clients
+
+On Unix, you can directly use `scp` command to download/upload files to the Apache Karaf filesystem. For instance,
+to retrieve the `karaf.log` file remotely:
+
+----
+~$ scp -P 8101 karaf@localhost:/data/log/karaf.log .
+Authenticated with partial success.
+Authenticated with partial success.
+Authenticated with partial success.
+Password authentication
+Password:
+karaf.log
+----
+
+As you have access to the complete `KARAF_BASE` directory, you can remotely change the configuration file in the `etc`
+folder, retrieve log files, populate the `system` folder.
+
+On Windows, you can use WinSCP to access the Apache Karaf filesystem.
+
+It's probably easier to use a SFTP complient client.
+
+For instance, on Unix system, you can use `lftp` or `ncftp`:
+
+----
+$ lftp
+lftp :~> open -u karaf sftp://localhost:8101
+Password:
+lftp karaf@localhost:~> ls
+-rw-r--r--   1 jbonofre jbonofre    27754 Oct 26 10:50 LICENSE
+-rw-r--r--   1 jbonofre jbonofre     1919 Dec  3 05:34 NOTICE
+-rw-r--r--   1 jbonofre jbonofre     3933 Aug 18  2012 README
+-rw-r--r--   1 jbonofre jbonofre   101041 Dec  3 05:34 RELEASE-NOTES
+drwxr-xr-x   1 jbonofre jbonofre     4096 Dec  3 12:51 bin
+drwxr-xr-x   1 jbonofre jbonofre     4096 Dec  3 18:57 data
+drwxr-xr-x   1 jbonofre jbonofre     4096 Dec  3 12:51 demos
+drwxr-xr-x   1 jbonofre jbonofre     4096 Dec  3 13:02 deploy
+drwxr-xr-x   1 jbonofre jbonofre     4096 Dec  3 17:59 etc
+drwxr-xr-x   1 jbonofre jbonofre     4096 Dec  3 13:02 instances
+drwxr-xr-x   1 jbonofre jbonofre     4096 Dec  3 13:02 lib
+-rw-r--r--   1 jbonofre jbonofre        0 Dec  3 13:02 lock
+drwxr-xr-x   1 jbonofre jbonofre     4096 Dec  3 12:51 system
+lftp karaf@localhost:/>
+----
+
+You can also use graphic client like `filezilla`, `gftp`, `nautilus`, etc.
+
+On Windows, you can use `filezilla`, `WinSCP`, etc.
+
+===== Apache Maven
+
+Apache Karaf `system` folder is the Karaf repository, that use a Maven directory structure. It's where Apache Karaf
+looks for the artifacts (bundles, features, kars, etc).
+
+Using Apache Maven, you can populate the `system` folder using the `deploy:deploy-file` goal.
+
+For instance, you want to add the Apache ServiceMix facebook4j OSGi bundle, you can do:
+
+----
+mvn deploy:deploy-file -Dfile=org.apache.servicemix.bundles.facebook4j-2.0.2_1.jar -DgroupId=org.apache.servicemix.bundles -DartifactId=org.apache.servicemix.bundles.facebook4j -Dversion=2.0.2_1 -Dpackaging=jar -Durl=scp://localhost:8101/system
+----
+
+[NOTE]
+====
+If you want to turn Apache Karaf as a simple Maven repository, you can use link:http://karaf.apache.org/index/subprojects/cave.html[Apache Karaf Cave].
+====
+
+=== JMX MBeanServer
+
+Apache Karaf provides a JMX MBeanServer.
+
+This MBeanServer is available remotely, using any JMX client like `jconsole`.
+
+You can find details on the [Monitoring section|monitoring] of the user guide.


Mime
View raw message