karaf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jbono...@apache.org
Subject [12/15] karaf git commit: KARAF-3679 - Switch user guide to asciidoc
Date Tue, 05 Jan 2016 14:02:37 GMT
http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/user-guide/configuration.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/user-guide/configuration.adoc b/manual/src/main/asciidoc/user-guide/configuration.adoc
new file mode 100644
index 0000000..eba7dd3
--- /dev/null
+++ b/manual/src/main/asciidoc/user-guide/configuration.adoc
@@ -0,0 +1,366 @@
+//
+// 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.
+//
+
+=== Configuration
+
+==== Files
+
+Apache Karaf stores and loads all configuration in files located in the `etc` folder.
+
+By default, the `etc` folder is located relatively to the `KARAF_BASE` folder. You can define another location
+using the `KARAF_ETC` variable.
+
+Each configuration is identified by a ID (the ConfigAdmin PID). The configuration files name follows the `pid.cfg`
+name convention.
+
+For instance, `etc/org.apache.karaf.shell.cfg` means that this file is the file used by the configuration with
+`org.apache.karaf.shell` as PID.
+
+A configuration file is a properties file containing key/value pairs:
+
+----
+property=value
+----
+
+In Apache Karaf, a configuration is PID with a set of properties attached.
+
+Apache Karaf automatically loads all `*.cfg` files from the `etc` folder.
+
+You can configure the behaviour of the configuration files using some dedicated properties in the
+`etc/config.properties` configuration file:
+
+----
+...
+#
+# Configuration FileMonitor properties
+#
+felix.fileinstall.enableConfigSave = true
+felix.fileinstall.dir    = ${karaf.etc}
+felix.fileinstall.filter = .*\\.cfg
+felix.fileinstall.poll   = 1000
+felix.fileinstall.noInitialDelay = true
+felix.fileinstall.log.level = 3
+...
+----
+
+* `felix.fileinstall.enableConfigSave` flush back in the configuration file the changes performed directly on the
+configuration service (ConfigAdmin). If `true`, any change (using `config:*` commands, MBeans, OSGi service) is
+persisted back in the configuration false. Default is `true`.
+* `felix.fileinstall.dir` is the directory where Apache Karaf is looking for configuration files. Default is `${karaf.etc`}
+meaning the value of the `KARAF_ETC` variable.
+* `felix.fileinstall.filter` is the file name pattern used to load only some configuration files. Only files matching
+the pattern will be loaded. Default value is `.*\\.cfg` meaning *.cfg files.
+* `felix.fileinstall.poll` is the polling interval (in milliseconds). Default value is `1000` meaning that Apache
+Karaf "re-loads" the configuration files every second.
+* `felix.fileinstall.noInitialDelay` is a flag indicating if the configuration file polling starts as soon as Apache
+Karaf starts or wait for a certain time. If `true`, Apache Karaf polls the configuration files as soon as the configuration
+service starts.
+* `felix.fileinstall.log.level` is the log message verbosity level of the configuration polling service. More
+this value is high, more verbose the configuration service is.
+
+You can change the configuration at runtime by directly editiing the configuration file.
+
+You can also do the same using the `config:*` commands or the ConfigMBean.
+
+==== `config:*` commands
+
+Apache Karaf provides a set of commands to manage the configuration.
+
+===== `config:list`
+
+`config:list` displays the list of all configurations available, or the properties in a given configuration (PID).
+
+Without the `query` argument, the `config:list` command display all configurations, with PID, attached bundle and
+properties defined in the configuration:
+
+----
+karaf@root()> config:list
+----------------------------------------------------------------
+Pid:            org.apache.karaf.service.acl.command.system.start-level
+BundleLocation: mvn:org.apache.karaf.shell/org.apache.karaf.shell.console/3.0.0
+Properties:
+   service.guard = (&(osgi.command.scope=system)(osgi.command.function=start-level))
+   * = *
+   start-level = admin                           # admin can set any start level, including < 100
+   start-level[/[^0-9]*/] = viewer               # viewer can obtain the current start level
+   execute[/.*/,/[^0-9]*/] = viewer               # viewer can obtain the current start level
+   execute = admin                           # admin can set any start level, including < 100
+   service.pid = org.apache.karaf.service.acl.command.system.start-level
+   start-level[/.*[0-9][0-9][0-9]+.*/] = manager # manager can set startlevels above 100
+   execute[/.*/,/.*[0-9][0-9][0-9]+.*/] = manager # manager can set startlevels above 100
+----------------------------------------------------------------
+Pid:            org.apache.karaf.log
+BundleLocation: mvn:org.apache.karaf.log/org.apache.karaf.log.core/3.0.0
+Properties:
+   service.pid = org.apache.karaf.log
+   size = 500
+   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
+   felix.fileinstall.filename = file:/opt/apache-karaf-3.0.0/etc/org.apache.karaf.log.cfg
+...
+----
+
+The `query` argument accepts a query using a LDAP syntax.
+
+For instance, you can display details on one specific configuration using the following filter:
+
+----
+karaf@root()> config:list "(service.pid=org.apache.karaf.log)"
+----------------------------------------------------------------
+Pid:            org.apache.karaf.log
+BundleLocation: mvn:org.apache.karaf.log/org.apache.karaf.log.core/3.0.0
+Properties:
+   service.pid = org.apache.karaf.log
+   size = 500
+   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
+   felix.fileinstall.filename = file:/opt/apache-karaf-3.0.0/etc/org.apache.karaf.log.cfg
+----
+
+===== `config:edit`
+
+`config:edit` is the first command to do when you want to change a configuration. `config:edit` command put you
+in edition mode for a given configuration.
+
+For instance, you can edit the `org.apache.karaf.log` configuration:
+
+----
+karaf@root()> config:edit org.apache.karaf.log
+----
+
+The `config:edit` command doesn't display anything, it just puts you in configuration edit mode. You are now ready
+to use other config commands (like `config:property-append`, `config:property-delete`, `config:property-set`, ...).
+
+If you provide a configuration PID that doesn't exist yet, Apache Karaf will create a new configuration (and so a new
+configuration file) automatically.
+
+All changes that you do in configuration edit mode are store in your console session: the changes are not directly
+applied in the configuration. It allows you to "commit" the changes (see `config:update` command) or "rollback" and
+cancel your changes (see `config:cancel` command).
+
+===== `config:property-list`
+
+The `config:property-list` lists the properties for the currently edited configuration.
+
+Assuming that you edited the `org.apache.karaf.log` configuration, you can do:
+
+----
+karaf@root()> config:property-list
+   service.pid = org.apache.karaf.log
+   size = 500
+   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
+   felix.fileinstall.filename = file:/opt/apache-karaf-3.0.0/etc/org.apache.karaf.log.cfg
+----
+
+===== `config:property-set`
+
+The `config:property-set` command update the value of a given property in the currently edited configuration.
+
+For instance, to change the value of the `size` property of previously edited `org.apache.karaf.log` configuration,
+you can do:
+
+----
+karaf@root()> config:property-set size 1000
+karaf@root()> config:property-list
+   service.pid = org.apache.karaf.log
+   size = 1000
+   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
+   felix.fileinstall.filename = file:/opt/apache-karaf-3.0.0/etc/org.apache.karaf.log.cfg
+----
+
+If the property doesn't exist, the `config:property-set` command creates the property.
+
+You can use `config:property-set` command outside the configuration edit mode, by specifying the `-p` (for configuration pid) option:
+
+----
+karaf@root()> config:property-set -p org.apache.karaf.log size 1000
+karaf@root()> config:list "(service.pid=org.apache.karaf.log)"
+----------------------------------------------------------------
+Pid:            org.apache.karaf.log
+BundleLocation: mvn:org.apache.karaf.log/org.apache.karaf.log.core/3.0.0
+Properties:
+   service.pid = org.apache.karaf.log
+   size = 1000
+   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
+   felix.fileinstall.filename = file:/opt/apache-karaf-3.0.0/etc/org.apache.karaf.log.cfg
+----
+
+[NOTE]
+====
+Using the `pid` option, you bypass the configuration commit and rollback mechanism.
+====
+
+===== `config:property-append`
+
+The `config:property-append` is similar to `config:property-set` command, but instead of completely replacing the
+property value, it appends a string at the end of the property value.
+
+For instance, to add 1 at the end of the value of the `size` property in `org.apache.karaf.log` configuration
+(and so have 5001 for the value instead of 500), you can do:
+
+----
+karaf@root()> config:property-append size 1
+karaf@root()> config:property-list
+   service.pid = org.apache.karaf.log
+   size = 5001
+   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
+   felix.fileinstall.filename = file:/opt/apache-karaf-3.0.0/etc/org.apache.karaf.log.cfg
+----
+
+Like the `config:property-set` command, if the property doesn't exist, the `config:property-set` command creates
+the property.
+
+You can use the `config:property-append` command outside the configuration edit mode, by specifying the `-p` (for configuration pid) option:
+
+----
+karaf@root()> config:property-append -p org.apache.karaf.log size 1
+karaf@root()> config:list "(service.pid=org.apache.karaf.log)"
+----------------------------------------------------------------
+Pid:            org.apache.karaf.log
+BundleLocation: mvn:org.apache.karaf.log/org.apache.karaf.log.core/3.0.0
+Properties:
+   service.pid = org.apache.karaf.log
+   size = 5001
+   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
+   felix.fileinstall.filename = file:/opt/apache-karaf-3.0.0/etc/org.apache.karaf.log.cfg
+----
+
+[NOTE]
+====
+Using the `pid` option, you bypass the configuration commit and rollback mechanism.
+====
+
+===== `config:property-delete`
+
+The `config:property-delete` command delete a property in the currently edited configuration.
+
+For instance, you previously added a `test` property in `org.apache.karaf.log` configuration. To delete this `test`
+property, you do:
+
+----
+karaf@root()> config:property-set test test
+karaf@root()> config:property-list
+   service.pid = org.apache.karaf.log
+   size = 500
+   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
+   felix.fileinstall.filename = file:/opt/apache-karaf-3.0.0/etc/org.apache.karaf.log.cfg
+   test = test
+karaf@root()> config:property-delete test
+karaf@root()> config:property-list
+   service.pid = org.apache.karaf.log
+   size = 500
+   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
+   felix.fileinstall.filename = file:/opt/apache-karaf-3.0.0/etc/org.apache.karaf.log.cfg
+----
+
+You can use the `config:property-delete` command outside the configuration edit mode, by specifying the `-p` (for configuration pid) option:
+
+----
+karaf@root()> config:property-delete -p org.apache.karaf.log test
+----
+
+===== `config:update` and `config:cancel`
+
+When you are in the configuration edit mode, all changes that you do using `config:property*` commands are stored in "memory"
+(actually in the console session).
+
+Thanks to that, you can "commit" your changes using the `config:update` command. The `config:update` command will
+commit your changes, update the configuration, and (if possible) update the configuration files.
+
+For instance, after changing `org.apache.karaf.log` configuration with some `config:property*` commands, you have
+to commit your change like this:
+
+----
+karaf@root()> config:edit org.apache.karaf.log
+karaf@root()> config:property-set test test
+karaf@root()> config:update
+karaf@root()> config:list "(service.pid=org.apache.karaf.log)"
+----------------------------------------------------------------
+Pid:            org.apache.karaf.log
+BundleLocation: mvn:org.apache.karaf.log/org.apache.karaf.log.core/3.0.0
+Properties:
+   service.pid = org.apache.karaf.log
+   size = 500
+   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
+   felix.fileinstall.filename = file:/opt/apache-karaf-3.0.0/etc/org.apache.karaf.log.cfg
+   test = test
+----
+
+On the other hand, if you want to "rollback" your changes, you can use the `config:cancel` command. It will cancel all
+changes that you did, and return of the configuration state just before the `config:edit` command. The `config:cancel`
+exits from the edit mode.
+
+For instance, you added the test property in the `org.apache.karaf.log` configuration, but it was a mistake:
+
+----
+karaf@root()> config:edit org.apache.karaf.log
+karaf@root()> config:property-set test test
+karaf@root()> config:cancel
+karaf@root()> config:list "(service.pid=org.apache.karaf.log)"
+----------------------------------------------------------------
+Pid:            org.apache.karaf.log
+BundleLocation: mvn:org.apache.karaf.log/org.apache.karaf.log.core/3.0.0
+Properties:
+   service.pid = org.apache.karaf.log
+   size = 500
+   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
+   felix.fileinstall.filename = file:/opt/apache-karaf-3.0.0/etc/org.apache.karaf.log.cfg
+----
+
+===== `config:delete`
+
+The `config:delete` command completely delete an existing configuration. You don't have to be in edit mode to delete
+a configuration.
+
+For instance, you added `my.config` configuration:
+
+----
+karaf@root()> config:edit my.config
+karaf@root()> config:property-set test test
+karaf@root()> config:update
+karaf@root()> config:list "(service.pid=my.config)"
+----------------------------------------------------------------
+Pid:            my.config
+BundleLocation: null
+Properties:
+   service.pid = my.config
+   test = test
+----
+
+You can delete the `my.config` configuration (including all properties in the configuration) using the `config:delete`
+command:
+
+----
+karaf@root()> config:delete my.config
+karaf@root()> config:list "(service.pid=my.config)"
+karaf@root()>
+----
+
+==== JMX ConfigMBean
+
+On the JMX layer, you have a MBean dedicated to the management of the configurations: the ConfigMBean.
+
+The ConfigMBean object name is: `org.apache.karaf:type=config,name=*`.
+
+===== Attributes
+
+The `Configs` attribute is a list of all configuration PIDs.
+
+===== Operations
+
+* `listProperties(pid)` returns the list of properties (property=value formatted) for the configuration `pid`.
+* `deleteProperty(pid, property)` deletes the `property` from the configuration `pid`.
+* `appendProperty(pid, property, value)` appends `value` at the end of the value of the `property` of the configuration `pid`.
+* `setProperty(pid, property, value)` sets `value` for the value of the `property` of the configuration `pid`.
+* `delete(pid)` deletes the configuration identified by the `pid`.
+* `create(pid)` creates an empty (without any property) configuration with `pid`.
+* `update(pid, properties)` updates a configuration identified with `pid` with the provided `properties` map.

http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/user-guide/console.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/user-guide/console.adoc b/manual/src/main/asciidoc/user-guide/console.adoc
new file mode 100644
index 0000000..c676fcf
--- /dev/null
+++ b/manual/src/main/asciidoc/user-guide/console.adoc
@@ -0,0 +1,428 @@
+//
+// 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.
+//
+
+=== Using the console
+
+==== Available commands
+
+To see a list of the available commands in the console, you can use the `help`:
+
+----
+karaf@root()> help
+COMMANDS
+bundle
+bundle:capabilities               Displays OSGi capabilities of a given bundles.
+bundle:classes                    Displays a list of classes contained in the bundle
+...
+----
+
+You have the list of all commands with a short description.
+
+You can use the tab key to get a quick list of all commands:
+
+----
+karaf@root()> Display all 280 possibilities? (y or n)
+...
+----
+
+==== Subshell and completion mode
+
+The commands have a scope and a name. For instance, the command `feature:list` has `feature` as scope, and `list` as name.
+
+Karaf "groups" the commands by scope. Each scope form a subshell.
+
+You can directly execute a command with its full qualified name (scope:name):
+
+----
+karaf@root()> feature:list
+...
+----
+
+or enter in a subshell and type the command contextual to the subshell:
+
+----
+karaf@root()> feature
+karaf@root(feature)> list
+----
+
+You can note that you enter in a subshell directly by typing the subshell name (here `feature`). You can "switch" directly from a subshell to another:
+
+----
+karaf@root()> feature
+karaf@root(feature)> bundle
+karaf@root(bundle)>
+----
+
+The prompt displays the current subshell between ().
+
+The `exit` command goes to the parent subshell:
+
+----
+karaf@root()> feature
+karaf@root(feature)> exit
+karaf@root()>
+----
+
+The completion mode defines the behaviour of the tab key and the help command.
+
+You have three different modes available:
+
+* GLOBAL
+* FIRST
+* SUBSHELL
+
+You can define your default completion mode using the completionMode property in `etc/org.apache.karaf.shell.cfg` file. By default, you have:
+
+----
+completionMode = GLOBAL
+----
+
+You can also change the completion mode “on the fly” (while using the Karaf shell console) using the `shell:completion` command:
+
+----
+karaf@root()> shell:completion
+GLOBAL
+karaf@root()> shell:completion FIRST
+karaf@root()> shell:completion
+FIRST
+----
+
+`shell:completion` can inform you about the current completion mode used. You can also provide the new completion mode that you want.
+
+GLOBAL completion mode is the default one in Karaf 3.0.0 (mostly for transition purpose).
+
+GLOBAL mode doesn’t really use subshell: it’s the same behavior as in previous Karaf versions.
+
+When you type the tab key, whatever in which subshell you are, the completion will display all commands and all aliases:
+
+----
+karaf@root()> <TAB>
+karaf@root()> Display all 273 possibilities? (y or n)
+...
+karaf@root()> feature
+karaf@root(feature)> <TAB>
+karaf@root(feature)> Display all 273 possibilities? (y or n)
+----
+
+FIRST completion mode is an alternative to the GLOBAL completion mode.
+
+If you type the tab key on the root level subshell, the completion will display the commands and the aliases from all subshells (as in GLOBAL mode).
+However, if you type the tab key when you are in a subshell, the completion will display only the commands of the current subshell:
+
+----
+karaf@root()> shell:completion FIRST
+karaf@root()> <TAB>
+karaf@root()> Display all 273 possibilities? (y or n)
+...
+karaf@root()> feature
+karaf@root(feature)> <TAB>
+karaf@root(feature)>
+info install list repo-add repo-list repo-remove uninstall version-list
+karaf@root(feature)> exit
+karaf@root()> log
+karaf@root(log)> <TAB>
+karaf@root(log)>
+clear display exception-display get log set tail
+----
+
+SUBSHELL completion mode is the real subshell mode.
+
+If you type the tab key on the root level, the completion displays the subshell commands (to go into a subshell), and the global aliases.
+Once you are in a subshell, if you type the TAB key, the completion displays the commands of the current subshell:
+
+----
+karaf@root()> shell:completion SUBSHELL
+karaf@root()> <TAB>
+karaf@root()>
+* bundle cl config dev feature help instance jaas kar la ld lde log log:list man package region service shell ssh system
+karaf@root()> bundle
+karaf@root(bundle)> <TAB>
+karaf@root(bundle)>
+capabilities classes diag dynamic-import find-class headers info install list refresh requirements resolve restart services start start-level stop
+uninstall update watch
+karaf@root(bundle)> exit
+karaf@root()> camel
+karaf@root(camel)> <TAB>
+karaf@root(camel)>
+backlog-tracer-dump backlog-tracer-info backlog-tracer-start backlog-tracer-stop context-info context-list context-start context-stop endpoint-list route-info route-list route-profile route-reset-stats
+route-resume route-show route-start route-stop route-suspend
+----
+
+==== Unix like environment
+
+Karaf console provides a full Unix like environment.
+
+===== Help or man
+
+We already saw the usage of the `help` command to display all commands available.
+
+But you can also use the `help` command to get details about a command or 
+the `man` command which is an alias to the `help` command.
+You can also use another form to get the command help, by using the `--help` option to the command.
+
+So these commands 
+
+----
+karaf@root()> help feature:list
+karaf@root()> man feature:list
+karaf@root()> feature:list --help
+----
+
+All produce the same help output:
+
+----
+DESCRIPTION
+        feature:list
+
+        Lists all existing features available from the defined repositories.
+
+SYNTAX
+        feature:list [options]
+
+OPTIONS
+        --help
+                Display this help message
+        -o, --ordered
+                Display a list using alphabetical order
+        -i, --installed
+                Display a list of all installed features only
+        --no-format
+                Disable table rendered output
+
+----
+
+===== Completion
+
+When you type the tab key, Karaf tries to complete:
+
+* subshell
+* commands
+* aliases
+* command arguments
+* command options
+
+===== Alias
+
+An alias is another name associated to a given command.
+
+The `shell:alias` command creates a new alias. For instance, to create the `list-installed-features` alias to the actual
+`feature:list -i` command, you can do:
+
+----
+karaf@root()> alias "list-features-installed = { feature:list -i }"
+karaf@root()> list-features-installed 
+Name       | Version  | Installed | Repository     | Description
+---------------------------------------------------------------------------------------------------------
+standard   | 3.0.0    | x         | standard-3.0.0 | Karaf standard feature
+config     | 3.0.0    | x         | standard-3.0.0 | Provide OSGi ConfigAdmin support
+region     | 3.0.0    | x         | standard-3.0.0 | Provide Region Support
+package    | 3.0.0    | x         | standard-3.0.0 | Package commands and mbeans
+kar        | 3.0.0    | x         | standard-3.0.0 | Provide KAR (KARaf archive) support
+ssh        | 3.0.0    | x         | standard-3.0.0 | Provide a SSHd server on Karaf
+management | 3.0.0    | x         | standard-3.0.0 | Provide a JMX MBeanServer and a set of MBeans in K
+----
+
+At login, the Apache Karaf console reads the `etc/shell.init.script` file where you can create your aliases.
+It's similar to a bashrc or profile file on Unix.
+
+----
+ld = { log:display $args } ;
+lde = { log:exception-display $args } ;
+la = { bundle:list -t 0 $args } ;
+ls = { service:list $args } ;
+cl = { config:list "(service.pid=$args)" } ;
+halt = { system:shutdown -h -f $args } ;
+help = { *:help $args | more } ;
+man = { help $args } ;
+log:list = { log:get ALL } ;
+----
+
+You can see here the aliases available by default:
+
+* `ld` is a short form to display log (alias to `log:display` command)
+* `lde` is a short form to display exceptions (alias to `log:exception-display` command)
+* `la` is a short form to list all bundles (alias to `bundle:list -t 0` command)
+* `ls` is a short form to list all services (alias to `service:list` command)
+* `cl` is a short form to list all configurations (alias to `config:list` command)
+* `halt` is a short form to shutdown Apache Karaf (alias to `system:shutdown -h -f` command)
+* `help` is a short form to display help (alias to `*:help` command)
+* `man` is the same as help (alias to `help` command)
+* `log:list` displays all loggers and level (alias to `log:get ALL` command)
+
+You can create your own aliases in the `etc/shell.init.script` file.
+
+===== Key binding
+
+Like on most Unix environment, Karaf console support some key bindings:
+
+* the arrows key to navigate in the commands history
+* CTRL-D to logout/shutdown Karaf
+* CTRL-R to search previously executed command
+* CTRL-U to remove the current line
+
+===== Pipe
+
+You can pipe the output of one command as input to another one. It's a pipe, using the | character:
+
+----
+karaf@root()> feature:list | grep -i war
+war                           | 3.0.0  |           | standard-3.0.0          | Turn Karaf as a full WebContainer
+----
+
+===== Grep, more, find, ...
+
+Karaf console provides some core commands similar to Unix environment:
+
+* `shell:head` displays the first line of the input
+* `shell:source` executes commands contained in a script
+* `shell:alias` creates an alias to an existing command
+* `shell:history` prints the commands history
+* `shell:cat` displays the content of a file or URL
+* `shell:if` allows you to use conditions (if, then, else blocks) in script
+* `shell:tac` captures stdin and returns it as a string
+* `shell:clear` clears the current console display
+* `shell:info` prints various information about the current Karaf instance
+* `shell:tail` displays the last lines of the input
+* `shell:completion` displays or change the current completion mode
+* `shell:java` executes a Java application
+* `shell:threads` prints the current thread
+* `shell:date` displays the current date (optionally using a format)
+* `shell:watch` periodically executes a command and refresh the output
+* `shell:each` executes a closure on a list of arguments
+* `shell:more` is a file pager
+* `shell:wc` prints newline, words, and byte counts for each file
+* `shell:env` gets/sets the value of a shell session variable
+* `shell:echo` echoes and prints arguments to stdout
+* `shell:new` creates a new Java object
+* `shell:edit` calls a text editor on the current file or URL
+* `shell:printf` formats and prints arguments
+* `shell:exec` executes a system command
+* `shell:sleep` sleeps for a bit then wakes up
+* `shell:grep` prints lines matching the given pattern
+* `shell:sort` writes sorted concatenation of all files to stdout
+
+You don't have to use the fully qualified name of the command, you can directly use the command name as long as it is unique.
+So you can use 'head' instead of 'shell:head'
+
+Again, you can find details and all options of these commands using `help` command or `--help` option.
+
+===== Scripting
+
+The Apache Karaf Console supports a complete scripting language, similar to bash or csh on Unix.
+
+The `each` (`shell:each`) command can iterate in a list:
+
+----
+karaf@root()> list = [1 2 3]; each ($list) { echo $it }
+1
+2
+3
+----
+
+You can create the list yourself (as in the previous example), or some commands can return a list too.
+
+We can note that the console created a "session" variable with the name `list` that you can access with `$list`.
+
+The `$it` variable is an implicit one corresponding to the current object (here the current iterated value from the
+list).
+
+When you create a list with `[]`, Apache Karaf console creates a Java ArrayList. It means that you can use methods
+available in the ArrayList objects (like get or size for instance):
+
+----
+karaf@root()> list = ["Hello" world]; echo ($list get 0) ($list get 1)
+Hello world
+----
+
+We can note here that calling a method on an object is directly using `(object method argument)`.
+Here `($list get 0)` means `$list.get(0)` where `$list` is the ArrayList.
+
+The `class` notation will display details about the object:
+
+----
+karaf@root()> $list class
+...
+ProtectionDomain     ProtectionDomain  null
+ null
+ <no principals>
+ java.security.Permissions@6521c24e (
+ ("java.security.AllPermission" "<all permissions>" "<all actions>")
+)
+
+
+Signers              null
+SimpleName           ArrayList
+TypeParameters       [E]
+----
+
+You can "cast" a variable to a given type.
+
+----
+karaf@root()> ("hello world" toCharArray)
+[h, e, l, l, o,  , w, o, r, l, d]
+----
+
+If it fails, you will see the casting exception:
+
+----
+karaf@root()> ("hello world" toCharArray)[0]
+Error executing command: [C cannot be cast to [Ljava.lang.Object;
+----
+
+You can "call" a script using the `shell:source` command:
+
+----
+karaf@root> shell:source script.txt
+True!
+----
+
+where `script.txt` contains:
+
+----
+foo = "foo"
+if { $foo equals "foo" } {
+  echo "True!"
+}
+----
+
+{warning}
+The spaces are important when writing script.
+For instance, the following script is not correct:
+
+----
+if{ $foo equals "foo" } ...
+----
+
+and will fail with:
+
+----
+karaf@root> shell:source script.txt
+Error executing command: Cannot coerce echo "true!"() to any of []
+----
+
+because a space is missing after the `if` statement.
+{warning}
+
+As for the aliases, you can create init scripts in the `etc/shell.init.script` file.
+You can also named you script with an alias. Actually, the aliases are just scripts.
+
+See the Scripting section of the developers guide for details.
+
+==== Security
+
+The Apache Karaf console supports a Role Based Access Control (RBAC) security mechanism. It means that depending of
+the user connected to the console, you can define, depending of the user's groups and roles, the permission to execute
+some commands, or limit the values allowed for the arguments.
+
+Console security is detailed in the link:security[Security section] of this guide.

http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/user-guide/deployers.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/user-guide/deployers.adoc b/manual/src/main/asciidoc/user-guide/deployers.adoc
new file mode 100644
index 0000000..a82ea14
--- /dev/null
+++ b/manual/src/main/asciidoc/user-guide/deployers.adoc
@@ -0,0 +1,286 @@
+//
+// 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.
+//
+
+=== Deployers
+
+The following picture describes the architecture of the deployers.
+
+image::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:
+
+----
+<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:
+
+----
+<spring:beans ...>
+  <manifest xmlns="http://karaf.apache.org/xmlns/deployer/spring/v1.0.0">
+    Require-Bundle= my-bundle
+  </manifest>
+----
+
+==== Features deployer
+
+See the link:provisioning[Provisioning section] for details.
+
+==== KAR deployer
+
+See the link:kar[KAR section] 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:
+
+----
+<bundle>wrap:mvn:jboss/jbossall-client/4.3.2.GA/$Bundle-SymbolicName=jbossall-client&amp;Bundle-Version=4.3.2.GA&amp;Export-Package=org.jboss.remoting;version=&quot;4.3.2.GA&quot;,!*</bundle>
+----
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/user-guide/directory-structure.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/user-guide/directory-structure.adoc b/manual/src/main/asciidoc/user-guide/directory-structure.adoc
new file mode 100644
index 0000000..988a4fe
--- /dev/null
+++ b/manual/src/main/asciidoc/user-guide/directory-structure.adoc
@@ -0,0 +1,38 @@
+//
+// 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.
+//
+
+=== 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
+
+----
+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
+link:start-stop[using the clean option].
+----
+
+	

http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/user-guide/ejb.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/user-guide/ejb.adoc b/manual/src/main/asciidoc/user-guide/ejb.adoc
new file mode 100644
index 0000000..be19943
--- /dev/null
+++ b/manual/src/main/asciidoc/user-guide/ejb.adoc
@@ -0,0 +1,92 @@
+//
+// 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.
+//
+
+==== 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/9f08eb9e/manual/src/main/asciidoc/user-guide/failover.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/user-guide/failover.adoc b/manual/src/main/asciidoc/user-guide/failover.adoc
new file mode 100644
index 0000000..f8d3708
--- /dev/null
+++ b/manual/src/main/asciidoc/user-guide/failover.adoc
@@ -0,0 +1,255 @@
+//
+// 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.
+//
+
+==== 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), http://karaf.apache.org/index/subprojects/cellar.html[Apache Karaf Cellar] 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=10000
+----
+
+* `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 milliseconds) 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=10000
+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 milliseconds) 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. Karaf will first try to find the table as specified in this property,
+  and if not found, it will try the table name in lower and upper case.
+
+[NOTE]
+====
+Apache Karaf won't start if the JDBC driver is not present in the `lib/ext` folder.
+====
+
+[NOTE]
+====
+The `sample` database will be created automatically if it does not exist.
+====
+
+[NOTE]
+====
+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.
+====
+
+*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.
+
+[NOTE]
+====
+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.
+====
+
+*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.
+
+*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.
+
+*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.
+
+*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=10000
+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.
+|===
+
+[NOTE]
+====
+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.
+====
+
+===== Cluster (active/active)
+
+Apache Karaf doesn't natively support cluster. By cluster, we mean several active instances, synchronized with each other.
+
+However, http://karaf.apache.org/index/subprojects/cellar.html[Apache Karaf Cellar] can be installed to provide cluster support.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/user-guide/installation.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/user-guide/installation.adoc b/manual/src/main/asciidoc/user-guide/installation.adoc
new file mode 100644
index 0000000..3440fc7
--- /dev/null
+++ b/manual/src/main/asciidoc/user-guide/installation.adoc
@@ -0,0 +1,187 @@
+//
+// 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.
+//
+
+=== Installation
+
+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
+
+[NOTE]
+====
+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`)
+
+[NOTE]
+====
+Remember the restrictions concerning illegal characters in Java paths, e.g. \!, % etc.
+====
+
+[NOTE]
+====
+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
+
+----
+subst S: "C:\your very % problematic path!\KARAF"
+----
+
+so your Karaf root directory is S: --- which works for sure and is short to type.
+====
+
+===== Installation on Unix platforms
+
+[NOTE]
+====
+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
+----
+
+[NOTE]
+====
+Remember the restrictions concerning illegal characters in Java paths, e.g. \!, % etc.
+====
+
+==== 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
+----
+
+[NOTE]
+====
+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
+----
+
+[NOTE]
+====
+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.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/user-guide/instances.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/user-guide/instances.adoc b/manual/src/main/asciidoc/user-guide/instances.adoc
new file mode 100644
index 0000000..4dca20f
--- /dev/null
+++ b/manual/src/main/asciidoc/user-guide/instances.adoc
@@ -0,0 +1,391 @@
+//
+// 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.
+//
+
+=== 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` 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.
+
+[NOTE]
+====
+`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.
+
+[NOTE]
+====
+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.
+
+[NOTE]
+====
+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.


Mime
View raw message