Return-Path: X-Original-To: apmail-karaf-commits-archive@minotaur.apache.org Delivered-To: apmail-karaf-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id DBDA3184C4 for ; Mon, 4 Jan 2016 09:57:31 +0000 (UTC) Received: (qmail 86981 invoked by uid 500); 4 Jan 2016 09:57:28 -0000 Delivered-To: apmail-karaf-commits-archive@karaf.apache.org Received: (qmail 86955 invoked by uid 500); 4 Jan 2016 09:57:28 -0000 Mailing-List: contact commits-help@karaf.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@karaf.apache.org Delivered-To: mailing list commits@karaf.apache.org Received: (qmail 86502 invoked by uid 99); 4 Jan 2016 09:57:28 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 04 Jan 2016 09:57:28 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 7BBEFE0255; Mon, 4 Jan 2016 09:57:28 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: jbonofre@apache.org To: commits@karaf.apache.org Date: Mon, 04 Jan 2016 09:57:41 -0000 Message-Id: <5ed6e20090184314bc0b288677c1ec68@git.apache.org> In-Reply-To: <6921824a1322475cbb8e4b2849b9210e@git.apache.org> References: <6921824a1322475cbb8e4b2849b9210e@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [14/19] karaf git commit: KARAF-3679 - Switch documentation to asciidoc, close #65 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: + +---- + + + ... + ... + + + feature1 + ... + + +---- + +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 `` 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 `` element contains the name of a feature. A specific feature version can be defined using the `version` +attribute to the `` element (`feature1`). 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 `` element, in the features XML. + +---- + + mvn:com.mycompany.myproject/myproject-dao + mvn:com.mycompany.myproject/myproject-service + +---- + +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 `` element: + +---- + + mvn:com.mycompany.myproject/myproject-dao + mvn:com.mycompany.myproject/myproject-service + +---- + +==== Dependency + +A bundle can be flagged as being a dependency, using the `dependency` attribute set to true on the `` 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: + +---- + + other + mvn:com.mycompany.myproject/myproject-dao + mvn:com.mycompany.myproject/myproject-service + +---- + +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: + +---- + + spring + ... + +---- + +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 `` element in a feature XML allows a feature to create and/or populate a configuration (identified by a configuration PID). + +---- + + myProperty = myValue + +---- + +The `name` attribute of the `` 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 `` element is a set of properties, following the key=value standard. + +=== Feature configuration files + +Instead of using the `` element, a feature can specify `` elements. + +---- +URL +---- + +Instead of directly manipulating the Apache Karaf configuration layer (as when using the `` element), the +`` 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: + +---- +URL +---- + +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: + +---- +osgi.ee;filter:="(&(osgi.ee=JavaSE)(!(version>=1.8)))" +---- + +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: + +---- + + + + + ... + + + + ... + + + + ... + + + +---- + +=== 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 '' for a list of available commands +and '[cmd] --help' for help on a specific command. +Hit 'system:shutdown' to shutdown Karaf. +Hit '' 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 '' for a list of available commands +and '[cmd] --help' for help on a specific command. +Hit 'system:shutdown' to shutdown Karaf. +Hit '' 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 '' for a list of available commands +and '[cmd] --help' for help on a specific command. +Hit 'system:shutdown' to shutdown Karaf. +Hit '' 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.