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 F3DEB184BF for ; Mon, 4 Jan 2016 09:57:28 +0000 (UTC) Received: (qmail 87153 invoked by uid 500); 4 Jan 2016 09:57:28 -0000 Delivered-To: apmail-karaf-commits-archive@karaf.apache.org Received: (qmail 87094 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 86680 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 8FB05E0249; Mon, 4 Jan 2016 09:57:28 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit From: jbonofre@apache.org To: commits@karaf.apache.org Date: Mon, 04 Jan 2016 09:57:44 -0000 Message-Id: <991e968c570a4ec6b2da60601aa4cd2c@git.apache.org> In-Reply-To: <6921824a1322475cbb8e4b2849b9210e@git.apache.org> References: <6921824a1322475cbb8e4b2849b9210e@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [17/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/developer-guide/security-framework.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/security-framework.adoc b/manual/src/main/asciidoc/developer-guide/security-framework.adoc new file mode 100644 index 0000000..62c6ba4 --- /dev/null +++ b/manual/src/main/asciidoc/developer-guide/security-framework.adoc @@ -0,0 +1,842 @@ +// +// 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. +// + +== Security framework + +Karaf supports http://download.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html[JAAS] with +some enhancements to allow JAAS to work nicely in an OSGi environment. + +This framework also features an OSGi keystore manager with the ability to deploy new keystores or truststores at runtime. + +=== Overview + +This feature allows runtime deployment of JAAS based configuration for use in various parts of the application. This +includes the remote console login, which uses the `karaf` realm, but which is configured with a dummy login module +by default. These realms can also be used by the NMR, JBI components or the JMX server to authenticate users logging in +or sending messages into the bus. + +In addition to JAAS realms, you can also deploy keystores and truststores to secure the remote shell console, setting +up HTTPS connectors or using certificates for WS-Security. + +A very simple XML schema for spring has been defined, allowing the deployment of a new realm or a new keystore very easily. + +=== Schema + +To override or deploy a new realm, you can use the following XSD which is supported by a Spring namespace handler and +can thus be defined in a Spring xml configuration file. + +You can find the schema at the following http://karaf.apache.org/xmlns/jaas/v1.1.0 + +Here are two examples using this schema: + +---- + + + + + + + + + users = $[karaf.base]/etc/users.properties + + + + +---- + +---- + + +---- + +The `id` attribute is the blueprint id of the bean, but it will be used by default as the name of the realm if no +`name` attribute is specified. Additional attributes on the `config` elements are a `rank`, which is an integer. +When the LoginContext looks for a realm for authenticating a given user, the realms registered in the OSGi registry are +matched against the required name. If more than one realm is found, the one with the highest rank will be used, thus +allowing the override of some realms with new values. The last attribute is `publish` which can be set to false to +not publish the realm in the OSGi registry, thereby disabling the use of this realm. + +Each realm can contain one or more module definitions. Each module identifies a LoginModule and the `className` +attribute must be set to the class name of the login module to use. Note that this login module must be available from +the bundle classloader, so either it has to be defined in the bundle itself, or the needed package needs to be correctly +imported. The `flags` attribute can take one of four values. +The content of the `module` element is parsed as a properties file and will be used to further configure the login module. + +Deploying such a code will lead to a JaasRealm object in the OSGi registry, which will then be used when using the JAAS login module. + +==== Configuration override and use of the `rank` attribute + +The `rank` attribute on the `config` element is tied to the ranking of the underlying OSGi service. When the JAAS +framework performs an authentication, it will use the realm name to find a matching JAAS configuration. If multiple +configurations are used, the one with the highest `rank` attribute will be used. +So if you want to override the default security configuration in Karaf (which is used by the ssh shell, web console and +JMX layer), you need to deploy a JAAS configuration with the name `name="karaf"` and `rank="1"`. + +---- + + + + + + + + + users = $[karaf.base]/etc/users.properties + ... + + + + +---- + +=== Architecture + +Due to constraints in the JAAS specification, one class has to be available for all bundles. +This class is called ProxyLoginModule and is a LoginModule that acts as a proxy for an OSGi defines LoginModule. +If you plan to integrate this feature into another OSGi runtime, this class must be made available from the system +classloader and the related package be part of the boot delegation classpath (or be deployed as a fragment attached to +the system bundle). + +The xml schema defined above allows the use of a simple xml (leveraging spring xml extensibility) to configure and +register a JAAS configuration for a given realm. This configuration will be made available into the OSGi registry as a +JaasRealm and the OSGi specific Configuration will look for such services. +Then the proxy login module will be able to use the information provided by the realm to actually load the class from +the bundle containing the real login module. + +Karaf itself provides a set of login modules ready to use, depending of the authentication backend that you need. + +In addition of the login modules, Karaf also support backend engine. The backend engine is coupled to a login module and +allows you to manipulate users and roles directly from Karaf (adding a new user, delete an existing user, etc). +The backend engine is constructed by a backend engine factory, registered as an OSGi service. +Some login modules (for security reason for instance) don't provide backend engine. + +=== Available realm and login modules + +Karaf comes with a default realm named "karaf" using login modules. + +Karaf also provides a set of login modules and backend engines to handle authentication needs for your environment. + +==== PropertiesLoginModule + +|=== +|LoginModule |BackendEngineFactory + +| org.apache.karaf.jaas.modules.properties.PropertiesLoginModule +| org.apache.karaf.jaas.modules.properties.PropertiesBackendEngineFactory +|=== + +This login module is the one configured by default. It uses a properties text file to load the users, passwords and roles. + +|=== +|Name |Description + +|`users` +| location of the properties file +|=== + +This file uses the http://download.oracle.com/javase/6/docs/api/java/util/Properties.html#load(java.io.Reader)[properties file format]. +The format of the properties is as follows, with each line defining a user, its password and associated roles: + +---- +user=password[,role][,role]... +---- + +---- + + + users = ${karaf.etc}/users.properties + + +---- + +The PropertiesLoginModule provides a backend engine allowing: + +* add a new user +* delete an existing user +* list the users, groups, and roles +* add a new role to an user +* delete a role from an user +* add an user into a group +* remove an user from a group +* add a role to a group +* delete a role from a group + +To enable the backend engine, you have to register the corresponding OSGi service. For instance, the following blueprint +shows how to register the PropertiesLoginModule and the corresponding backend engine: + +---- + + + + + + users = ${karaf.etc}/users.properties + + + + + + + + +---- + +==== OsgiConfigLoginModule + +|=== +|LoginModule |BackendEngineFactory + +|org.apache.karaf.jaas.modules.osgi.OsgiConfigLoginModule +|N/A +|=== + +The OsgiConfigLoginModule uses the OSGi ConfigurationAdmin service to provide the users, passwords and roles. + +|=== +|Name |Description + +|`pid` +|the PID of the configuration containing user definitions +|=== + +The format of the configuration is the same than for the `PropertiesLoginModule` with properties prefixed with `user.`. + +For instance, in the Karaf etc folder, we create a file `org.apache.karaf.authentication.cfg` containing: + +---- +user.karaf=karaf,admin +user.user=password,role +---- + +The following blueprint shows how to use this configuration: + +---- + + + + + + pid = org.apache.karaf.authentication + + + + +---- + +[NOTE] +==== +The OsgiConfigLoginModule doesn't provide a backend engine. +==== + +==== JDBCLoginModule + +|=== +|LoginModule |BackendEngineFactory + +|org.apache.karaf.jaas.modules.jdbc.JDBCLoginModule +|org.apache.karaf.jaas.modules.jdbc.JDBCBackendEngineFactory +|=== + +The JDBCLoginModule uses a database to load the users, passwords and roles from a provided data source (normal or XA). +The data source and the queries for password and role retrieval are configurable using the following parameters. + +|=== +|Name |Description + +|`datasource` +|The datasource as on OSGi ldap filter or as JDNI name + +|`query.password` +|The SQL query that retries the password of the user + +|`query.role` +|The SQL query that retries the roles of the user +|=== + +To use an OSGi ldap filter, the prefix osgi: needs to be provided, as shown below: + +---- + + + datasource = osgi:javax.sql.DataSource/(osgi.jndi.service.name=jdbc/karafdb) + query.password = SELECT PASSWORD FROM USERS WHERE USERNAME=? + query.role = SELECT ROLE FROM ROLES WHERE USERNAME=? + + +---- + +To use an JNDI name, the prefix jndi: needs to be provided. The example below assumes the use of Aries jndi to expose +services via JNDI. + +---- + + + datasource = jndi:aries:services/javax.sql.DataSource/(osgi.jndi.service.name=jdbc/karafdb) + query.password = SELECT PASSWORD FROM USERS WHERE USERNAME=? + query.role = SELECT ROLE FROM ROLES WHERE USERNAME=? + + +---- + +The JDBCLoginModule provides a backend engine allowing: + +* add a new user +* delete an user +* list users, roles +* add a new role to an user +* remove a role from an user + +[NOTE] +==== +The groups are not fully supported by the JDBCBackingEngine. +==== + +The following blueprint shows how to define the JDBCLoginModule with the corresponding backend engine: + +---- + + + + + + datasource = jndi:aries:services/javax.sql.DataSource/(osgi.jndi.service.name=jdbc/karafdb) + query.password = SELECT PASSWORD FROM USERS WHERE USERNAME=? + query.role = SELECT ROLE FROM ROLES WHERE USERNAME=? + insert.user = INSERT INTO USERS(USERNAME,PASSWORD) VALUES(?,?) + insert.role = INSERT INTO ROLES(ROLE,USERNAME) VALUES(?,?) + delete.user = DELETE FROM USERS WHERE USERNAME=? + + + + + + + + +---- + +==== LDAPLoginModule + +|=== +|LoginModule |BackendEngineFactory + +|org.apache.karaf.jaas.modules.ldap.LDAPLoginModule +|N/A +|=== + +The LDAPLoginModule uses LDAP to load the users and roles and bind the users on the LDAP to check passwords. + +The LDAPLoginModule supports the following parameters: + +|=== +|Name |Description + +|`connection.url` +|The LDAP connection URL, e.g. ldap://hostname + +|`connection.username` +|Admin username to connect to the LDAP. This parameter is optional, if it's not provided, the LDAP connection will be anonymous. + +|`connection.password` +|Admin password to connect to the LDAP. Only used if the `connection.username` is specified. + +|`user.base.dn` +|The LDAP base DN used to looking for user, e.g. ou=user,dc=apache,dc=org + +|`user.filter` +|The LDAP filter used to looking for user, e.g. (uid=%u) where %u will be replaced by the username. + +|`user.search.subtree` +|If "true", the user lookup will be recursive (SUBTREE). If "false", the user lookup will be performed only at the first level (ONELEVEL). + +|`role.base.dn` +|The LDAP base DN used to looking for roles, e.g. ou=role,dc=apache,dc=org + +|`role.filter` +|The LDAP filter used to looking for user's role, e.g. (member:=uid=%u) + +|`role.name.attribute` +|The LDAP role attribute containing the role string used by Karaf, e.g. cn + +|`role.search.subtree` +|If "true", the role lookup will be recursive (SUBTREE). If "false", the role lookup will be performed only at the first level (ONELEVEL). + +|`role.mapping` +|Define a mapping between roles defined in the LDAP directory for the user, and corresponding roles in Karaf. The format is ldapRole1=karafRole1,karafRole2;ldapRole2=karafRole3,karafRole4. + +|`authentication` +|Define the authentication backend used on the LDAP server. The default is simple. + +|`initial.context.factory` +|Define the initial context factory used to connect to the LDAP server. The default is com.sun.jndi.ldap.LdapCtxFactory + +|`ssl` +|If "true" or if the protocol on the `connection.url` is `ldaps`, an SSL connection will be used + +|`ssl.provider` +|The provider name to use for SSL + +|`ssl.protocol` +|The protocol name to use for SSL (SSL for example) + +|`ssl.algorithm` +|The algorithm to use for the KeyManagerFactory and TrustManagerFactory (PKIX for example) + +|`ssl.keystore` +|The key store name to use for SSL. The key store must be deployed using a `jaas:keystore` configuration. + +|`ssl.keyalias` +|The key alias to use for SSL + +|`ssl.truststore` +|The trust store name to use for SSL. The trust store must be deployed using a `jaas:keystore` configuration. +|=== + +A example of LDAPLoginModule usage follows: + +---- + + + connection.url = ldap://localhost:389 + user.base.dn = ou=user,dc=apache,dc=org + user.filter = (cn=%u) + user.search.subtree = true + role.base.dn = ou=group,dc=apache,dc=org + role.filter = (member:=uid=%u) + role.name.attribute = cn + role.search.subtree = true + authentication = simple + + +---- + +If you wish to use an SSL connection, the following configuration can be used as an example: + +---- + + + + + connection.url = ldaps://localhost:10636 + user.base.dn = ou=users,ou=system + user.filter = (uid=%u) + user.search.subtree = true + role.base.dn = ou=groups,ou=system + role.filter = (uniqueMember=uid=%u) + role.name.attribute = cn + role.search.subtree = true + authentication = simple + ssl.protocol=SSL + ssl.truststore=ks + ssl.algorithm=PKIX + + + + +---- + +The LDAPLoginModule supports the following patterns that you can use in the filter (user and role filters): + +* `%u` is replaced by the user +* `%dn` is replaced by the user DN +* `%fqdn` is replaced by the user full qualified DN (`userDNNamespace`). + +For instance, the following configuration will work properly with ActiveDirectory (adding the ActiveDirectory to the +default `karaf` realm): + +---- + + + initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory + connection.username=admin + connection.password=xxxxxxx + connection.protocol= + connection.url=ldap://activedirectory_host:389 + user.base.dn=ou=Users,ou=there,DC=local + user.filter=(sAMAccountName=%u) + user.search.subtree=true + role.base.dn=ou=Groups,ou=there,DC=local + role.name.attribute=cn + role.filter=(member=%fqdn) + role.search.subtree=true + authentication=simple + + +---- + +[NOTE] +==== +The LDAPLoginModule doesn't provide backend engine. It means that the administration of the users and roles should be +performed directly on the LDAP backend. +==== + +==== SyncopeLoginModule + +|=== +|LoginModule |BackendEngineFactory + +|org.apache.karaf.jaas.modules.syncope.SyncopeLoginModule +|org.apache.karaf.jaas.modules.syncope.SyncopeBackendEngineFactory +|=== + +The Syncope login module uses the Syncope REST API to authenticate users and retrieve the roles. + +The Syncope login module just requires one parameter: + +|=== +|Name |Description + +|`address` +|Location of the Syncope REST API + +|`admin.user` +|Admin username to administrate Syncope (only required by the backend engine) + +|`admin.password` +|Admin password to administrate Syncope (only required by the backend engine) +|=== + +The following snippet shows how to use Syncope with the karaf realm: + +---- + + + address=http://localhost:9080/syncope/cxf + admin.user=admin + admin.password=password + + +---- + +SyncopeLoginModule comes with a backend engine allowing to manipulate users and roles. You have to register the +SyncopeBackendEngineFactory service. + +For security reason, the SyncopeLoginModule backend engine allows only to list users and roles. You can't create or delete +users and roles directly from Karaf. To do it, you have to use the Syncope web console. + +For instance, the following blueprint descriptor enables the SyncopeLoginModule and the backend engine factory: + +---- + + + + + + address=http://localhost:9080/syncope/cxf + admin.user=admin + admin.password=password + + + + + + + + +---- + +=== Encryption service + +The EncryptionService is a service registered in the OSGi registry providing means to encrypt and check encrypted passwords. +This service acts as a factory for Encryption objects actually performing the encryption. + +This service is used in all Karaf login modules to support encrypted passwords. + +==== Configuring properties + +Each login module supports the following additional set of properties: + +|=== +|Name |Description + +|`encryption.name` +|Name of the encryption service registered in OSGi (cf. Jasypt section) + +|`encryption.enabled` +|Boolean used to turn on encryption + +|`encryption.prefix` +|Prefix for encrypted passwords + +|`encryption.suffix` +|Suffix for encrypted passwords + +|`encryption.algorithm` +|Name of an algorithm to be used for hashing, like "MD5" or "SHA-1" + +|`encryption.encoding` +|Encrypted passwords encoding (can be `hexadecimal` or `base64`) + +|`role.policy` +|A policy for identifying roles (can be `prefix` or `group`) (see Role discovery policies section) + +|`role.discriminator` +|A discriminator value to be used by the role policy +|=== + +A simple example follows: + +---- + + + users = $[karaf.base]/etc/users.properties + encryption.enabled = true + encryption.algorithm = MD5 + encryption.encoding = hexadecimal + + +---- + +==== Prefix and suffix + +The login modules have the ability to support both encrypted and plain passwords at the same time. +In some cases, some login modules may be able to encrypt the passwords on the fly and save them back in an encrypted form. + +==== Jasypt + +Karaf default installation comes with a simple encryption service which usually fullfill simple needs. However, in some +cases, you may want to install the Jasypt (http://www.jasypt.org/) library which provides stronger encryption algorithms +and more control over them. + +To install the Jasypt library, the easiest way is to install the available feature: + +---- +karaf@root> features:install jasypt-encryption +---- + +It will download and install the required bundles and also register an `EncryptionService` for Jasypt in the OSGi registry. + +When configuring a login module to use Jasypt, you need to specify the `encryption.name` property and set it to a value of `jasypt` to make sure the Jasypt encryption service will be used. + +In addition to the standard properties above, the Jasypt service provides the following parameters: + +|=== +|Name |Description + +|`providerName` +|Name of the `java.security.Provider` name to use for obtaining the digest algorithm + +|`providerClassName` +|Class name for the security provider to be used for obtaining the digest algorithm + +|`iterations` +|Number of times the hash function will be applied recursively + +|`saltSizeBytes` +|Size of the salt to be used to compute the digest + +|`saltGeneratorClassName` +|Class name of the salt generator +|=== + +A typical realm definition using Jasypt encryption service would look like: + +---- + + + users = $[karaf.base]/etc/users.properties + encryption.enabled = true + encryption.name = jasypt + encryption.algorithm = SHA-256 + encryption.encoding = base64 + encryption.iterations = 100000 + encryption.saltSizeBytes = 16 + + +---- + +==== Using encrypted property placeholders + +When using blueprint framework for OSGi for configuring devices that requires passwords like JDBC datasources, +it is undesirable to use plain text passwords in configuration files. To avoid this problem it is good to store database +passwords in encrypted format and use encrypted property placeholders when ever possible. + +Encrypted properties can be stored in plain properties files. The encrypted content is wrapped by an ENC() function. + +---- +#db.cfg / db.properties +db.url=localhost:9999 +db.username=admin +db.password=ENC(zRM7Pb/NiKyCalroBz8CKw==) +---- + +The encrypted property placeholders can be used either by defining Apache Aries ConfigAdmin `property-placeholder` +or by directly using the Apache Karaf `property-placeholder`. It has one child element `encryptor` that contains +the actual Jasypt configuration. For detailed information on how to configure the different Jasypt encryptors, see the +Jasypt documentation (http://www.jasypt.org/general-usage.html). + +A typical definition using Jasypt encryption would look like: + +---- + + + + + + + + + + + + + + + file:etc/db.properties + + + + + + + + + + + + + + + + +---- + +Don't forget to install the jasypt feature to add the support of the enc namespace: + +---- +karaf@root()> feature:install jasypt-encryption +---- + +=== Role discovery policies + +The JAAS specification does not provide means to distinguish between User and Role Principals without referring to the +specification classes. In order to provide means to the application developer to decouple the application from Karaf +JAAS implementation role policies have been created. + +A role policy is a convention that can be adopted by the application in order to identify Roles, without depending from the implementation. +Each role policy can be cofigured by setting a "role.policy" and "role.discriminator" property to the login module configuration. +Currently, Karaf provides two policies that can be applied to all Karaf Login Modules. + +. Prefixed Roles +. Grouped Roles + +When the prefixed role policy is used the login module applies a configurable prefix _(property role.discriminator)_ to +the role, so that the application can identify the role's principals by its prefix. Example: + +---- + + + users = $[karaf.base]/etc/users.properties + role.policy = prefix + role.discriminator = ROLE_ + + +---- + +The application can identify the role principals using a snippet like this: + +---- +LoginContext ctx = new LoginContext("karaf", handler); +ctx.login(); +authenticated = true; +subject = ctx.getSubject(); +for (Principal p : subject.getPrincipals()) { + if (p.getName().startsWith("ROLE_")) { + roles.add((p.getName().substring("ROLE_".length()))); + } +} +---- + +When the group role policy is used the login module provides all roles as members of a group with a configurable name _(property role.discriminator)_. Example: + +---- + + + users = $[karaf.base]/etc/users.properties + role.policy = group + role.discriminator = ROLES + + +---- + +---- +LoginContext ctx = new LoginContext("karaf", handler); +ctx.login(); +authenticated = true; +subject = ctx.getSubject(); +for (Principal p : subject.getPrincipals()) { + if ((p instanceof Group) && ("ROLES".equalsIgnoreCase(p.getName()))) { + Group g = (Group) p; + Enumeration members = g.members(); + while (members.hasMoreElements()) { + Principal member = members.nextElement(); + roles.add(member.getName()); + } + } +} +---- + +=== Default role policies + +The previous section describes how to leverage role policies. However, Karaf provides a default role policy, based on the following class names: + +* org.apache.karaf.jaas.modules.UserPrincipal +* org.apache.karaf.jaas.modules.RolePrincipal +* org.apache.karaf.jaas.modules.GroupPrincipal + +It allows you to directly handling the role class: + +---- +String rolePrincipalClass = "org.apache.karaf.jaas.modules.RolePrincipal"; + +for (Principal p : subject.getPrincipals()) { + if (p.getClass().getName().equals(rolePrincipalClass)) { + roles.add(p.getName()); + } +} +---- http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/developer-guide/services.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/services.adoc b/manual/src/main/asciidoc/developer-guide/services.adoc new file mode 100644 index 0000000..f724270 --- /dev/null +++ b/manual/src/main/asciidoc/developer-guide/services.adoc @@ -0,0 +1,15 @@ +// +// 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. +// + +== OSGi Services \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/developer-guide/writing-tests.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/writing-tests.adoc b/manual/src/main/asciidoc/developer-guide/writing-tests.adoc new file mode 100644 index 0000000..d3f95a7 --- /dev/null +++ b/manual/src/main/asciidoc/developer-guide/writing-tests.adoc @@ -0,0 +1,370 @@ +// +// 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. +// + +== Writing integration tests + +We recommend using http://team.ops4j.org/wiki/display/paxexam/Pax+Exam[PAX Exam] to write integration tests when developing applications using Karaf. + +Starting with Karaf 3.0 we've also included a component briding between Karaf and Pax Exam making it easier to write integration tests +for Karaf or Karaf based distributions. + +=== Introduction + +Pax Exam directly supports Karaf as a test container. + +To make use of this new framework simply add the following dependencies into your integration tests pom.xml: + +---- + + org.ops4j.pax.exam + pax-exam-container-karaf + 4.7.0 + test + + + org.ops4j.pax.exam + pax-exam-junit4 + 4.7.0 + test + + + org.apache.geronimo.specs + geronimo-atinject-1.0_spec + 1.0 + test + +---- + +As a next step you need to reference the distribution you want to run your tests on. +For instance, if you want to run your tests on Karaf the following section would be required in the integration tests pom.xml: + +---- + + org.apache.karaf + apache-karaf + 4.0.0 + tar.gz + test + +---- + +If you want to make use of Exams "versionAsInProject" feature you also need to add the following section: + +---- + + + + org.apache.servicemix.tooling + depends-maven-plugin + 1.2 + + + generate-depends-file + + generate-depends-file + + + + + + +---- + +With this done we can start writing our first test case: + +---- +import static junit.framework.Assert.assertTrue; +import static org.ops4j.pax.exam.options.KarafDistributionOption.karafDistributionConfiguration; +import static org.ops4j.pax.exam.CoreOptions.maven; + +import org.junit.Test; +import org.junit.runner.RunWith; +import org.ops4j.pax.exam.Option; +import org.ops4j.pax.exam.junit.Configuration; +import org.ops4j.pax.exam.junit.ExamReactorStrategy; +import org.ops4j.pax.exam.junit.JUnit4TestRunner; +import org.ops4j.pax.exam.spi.reactors.AllConfinedStagedReactorFactory; + +@RunWith(JUnit4TestRunner.class) +@ExamReactorStrategy(AllConfinedStagedReactorFactory.class) +public class VersionAsInProjectKarafTest { + + @Configuration + public Option[] config() { + return new Option[]{ karafDistributionConfiguration().frameworkUrl( + maven().groupId("org.apache.karaf").artifactId("apache-karaf").type("tar.gz").versionAsInProject()) + .karafVersion("4.0.0").name("Apache Karaf")}; + } + + @Test + public void test() throws Exception { + assertTrue(true); + } +} +---- + +=== Commands + +==== KarafDistributionConfigurationOption + +The framework itself is non of the typical runtimes you define normally in Pax-Exam. + +Instead you define a packed distribution as zip or tar.gz. Those distributions have to follow the Karaf packaging style. +Therefore instead of Karaf you can also enter Servicemix or Geronimo. + +---- +new KarafDistributionConfigurationOption( + "mvn:org.apache.karaf/apache-karaf/4.0.0/zip", // artifact to unpack and use + "karaf", // name; display only + "4.0.0") // the karaf version; this one is relevant since the startup script differs between versions +---- + +or for Servicemix e.g. + +---- +new KarafDistributionConfigurationOption( + "mvn:org.apache.servicemix/apache-servicemix/4.4.0/zip", // artifact to unpack and use + "servicemix", // name; display only + "2.2.4") // the karaf version; this one is relevant since the startup script differs between versions +---- + +As an alternative you can also use the maven url resolvers. + +---- +... + + org.apache.karaf + apache-karaf + zip + bin + test + +... + + org.apache.servicemix.tooling + depends-maven-plugin + + + generate-depends-file + + generate-depends-file + + + + +---- + +---- +@Configuration + public Option[] config() { + return new Option[]{ karafDistributionConfiguration().frameworkUrl( + maven().groupId("org.apache.karaf").artifactId("apache-karaf").type("zip") + .classifier("bin").versionAsInProject()) }; + } +---- + +In addition to the framework specification options this option also includes various additional configuration options. +Those options are used to configure the internal properties of the runtime environment. + +===== Unpack Directory + +Pax-Exam Testframework extracts the distribution you specify by default into the paxexam config directory. +If you would like to unpack them into your target directory simply extend the KarafDistributionConfigurationOption with the unpackDirectoryFile like shown in the next example: + +---- +@Configuration +public Option[] config() { + return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/4.0.0/zip") + .unpackDirectory(new File("target/paxexam/unpack/")) }; +} +---- + +===== Use Deploy Folder + +Karaf distributions come by default with a deploy folder where you can simply drop artifacts to be deployed. +In some distributions this folder might have been removed. To still be able to deploy your additional artifacts using +default Pax Exam ProvisionOptions you can configure PaxExam Karaf to use a features.xml (which is directly added to +your `etc/org.apache.karaf.features.cfg`) for those deploys. To use it instead of the deploy folder simply do the following: + +---- +@Configuration +public Option[] config() { + return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/4.0.0/zip") + .useDeployFolder(false)) }; +} +---- + +==== KarafDistributionKitConfigurationOption + +The KarafDistributionKitConfigurationOption is almost equal to all variations of the KarafDistributionConfigurationOption +with the exception that it requires to have set a platform and optionally the executable and the files which should be +made executable additionally. By default it is bin/karaf for nix platforms and bin\karaf.bat for windows platforms. +The executable option comes in handy if you like to e.g. embed an own java runtime. You should add a windows AND a +linux Kit definition. The framework automatically takes the correct one then. The following shows a simple example for Karaf: + +---- +@Configuration +public Option[] config() { + return new Option[]{ + new KarafDistributionKitConfigurationOption("mvn:org.apache.karaf/apache-karaf/4.0.0/zip", + Platform.WINDOWS).executable("bin\\karaf.bat").filesToMakeExecutable("bin\\admin.bat"), + new KarafDistributionKitConfigurationOption("mvn:org.apache.karaf/apache-karaf/4.0.0/tar.gz", "karaf", + Platform.NIX).executable("bin/karaf").filesToMakeExecutable("bin/admin") }; +} +---- + +==== KarafDistributionConfigurationFilePutOption + +The option replaces or adds an option to one of Karaf's configuration files: + +---- +new KarafDistributionConfigurationFilePutOption( + "etc/config.properties", // config file to modify based on karaf.base + "karaf.framework", // key to add or change + "equinox") // value to add or change +---- + +This option could also be used in "batch-mode" via a property file. Therefore use the +KarafDistributionOption#editConfigurationFilePut(final String configurationFilePath, File source, String... keysToUseFromSource) method. +This option allows you to add all properties found in the file as KarafDistributionConfigurationFilePutOption. If you configure the "keysToUseFromSource" array only the keys specified there will be used. That way you can easily put an entire range of properties. + +==== KarafDistributionConfigurationFileExtendOption + +This one does the same as the KarafDistributionConfigurationFilePutOption option with the one difference that it either +adds or appends a specific property. This is especially useful if you do not want to store the entire configuration in the line in your code. + +This option could also be extended in "batch-mode" via a property file. Therefore use the +KarafDistributionOption#editConfigurationFileExtend(final String configurationFilePath, File source, String... keysToUseFromSource) method. This option allows you to extend all properties found in the file as KarafDistributionConfigurationFileExtendOption. If you configure the "keysToUseFromSource" array only the keys specified there will be used. That way you can easily extend an entire range of properties. + +==== KarafDistributionConfigurationFileReplacementOption + +The file replacement option allows you to simply replace a file in you Karaf distribution with a different file: + +---- +new KarafDistributionConfigurationFileReplacementOption("etc/tests.cfg", new File( + "src/test/resources/BaseKarafDefaultFrameworkDuplicatedPropertyEntryTestSecondKey")); +---- + +==== ProvisionOption + +The new test container fully supports the provision option. Feel free to use any option provided here by paxexam itself (e.g. Maven resolver). +All those artifacts are copied into the deploy folder of your Karaf distribution before it is started. Therefore they all will be available after startup. + +==== KarafDistributionConfigurationConsoleOption + +The test container supports options to configure if the localConsole and/or the remote shell should be started. Possible options to do so are shown in the following two examples: + +---- +@Configuration +public Option[] config() { + return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/4.0.0/zip"), + configureConsole().ignoreLocalConsole().startRemoteShell() }; +} +---- + +---- +@Configuration +public Option[] config() { + return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/4.0.0/zip"), + configureConsole().startLocalConsole(), configureConsole().ignoreRemoteShell() }; +} +---- + +==== VMOption + +The Karaf container passes the vmOptions now through to the Karaf environment. They are directly passed to the startup of the container. +In addition the KarafDistributionOption helper has two methods (debugConfiguration() and debugConfiguration(String port, boolean hold)) to activate debugging quickly. + +==== LogLevelOption + +The Paxexam-Karaf specific log-level option allows an easy way to set a specific log-level for the Karaf based distribution. For example simply add the following to your Option[] array to get TRACE logging: + +---- +import static org.openengsb.labs.paxexam.karaf.options.KarafDistributionOption.logLevel; +... +@Configuration +public Option[] config() { + return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/4.0.0/zip"), + logLevel(LogLevel.TRACE) }; +} +---- + +==== DoNotModifyLogOption + +The option to modify the logging behavior requires that the container automatically modifies the logging configuration file. +If you would like to suppress this behavior simply set the doNotModifyLogConfiguration option as shown in the next example: + +---- +@Configuration +public Option[] config() { + return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/4.0.0/zip"), + doNotModifyLogConfiguration() }; +} +---- + +==== KeepRuntimeFolderOption + +Per default the test container removes all test runner folders. If you want to keep them for any reasons (e.g. check why a test fails) set the following option: + +---- +@Configuration +public Option[] config() { + return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/4.0.0/zip"), + keepRuntimeFolder() }; +} +---- + +==== FeaturesScannerProvisionOption + +The FeaturesScannerProvisionOption (e.g. CoreOption.scanFeature()) are directly supported by the Paxexam Karaf Testframework. + +==== BootDelegationOption + +The BootDelegationOption as known from PaxExam is also supported added the boot delegation string directly into the correct property files. + +==== SystemPackageOption + +The Standard Exam SystemPackageOption is implemented by adding those packages to "org.osgi.framework.system.packages.extra" of the config.properties file. + +==== BootClasspathLibraryOption + +The BootClasspathLibraryOption is honored by copying the urls into the lib directory where they are automatically taken and worked on. + +==== ExamBundlesStartLevel + +The ExamBundlesStartLevel can be used to configure the start lvl of the bundles provided by the test-frameworks features.xml. Simply use it as a new option like: + +---- +@Configuration +public Option[] config() { + return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/4.0.0/zip"), + useOwnExamBundlesStartLevel(4) }; +} +---- + +=== Driver + +Drivers are the parts of the framework responsible for running the Karaf Based Distribution. By default the already in +the overview explained KarafDistributionConfigurationOption uses a JavaRunner starting the distribution platform independent +but not using the scripts in the distribution. If you like to test those scripts too an option is to to use the ScriptRunner via the KarafDistributionKitConfigurationOption instead. + +==== JavaRunner + +The JavaRunner builds the entire command itself and executes Karaf in a new JVM. This behavior is more or less exactly +what the default runner does. Simply use the KarafDistributionConfigurationOption as explained in the Commands section to use this. + +==== ScriptRunner + +The script runner has the disadvantage over the java runner that it is also platform dependent. +The advantage though is that you can also test your specific scripts. To use it follow the explanation of the KarafDistributionKitConfigurationOption in the Commands section. http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/images/asf-logo.png ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/images/asf-logo.png b/manual/src/main/asciidoc/images/asf-logo.png new file mode 100644 index 0000000..d824fab Binary files /dev/null and b/manual/src/main/asciidoc/images/asf-logo.png differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/images/bg.png ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/images/bg.png b/manual/src/main/asciidoc/images/bg.png new file mode 100644 index 0000000..878a84f Binary files /dev/null and b/manual/src/main/asciidoc/images/bg.png differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/images/bg02-blue-left.png ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/images/bg02-blue-left.png b/manual/src/main/asciidoc/images/bg02-blue-left.png new file mode 100644 index 0000000..057efdf Binary files /dev/null and b/manual/src/main/asciidoc/images/bg02-blue-left.png differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/images/bg02-blue-right.png ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/images/bg02-blue-right.png b/manual/src/main/asciidoc/images/bg02-blue-right.png new file mode 100644 index 0000000..edf9a9d Binary files /dev/null and b/manual/src/main/asciidoc/images/bg02-blue-right.png differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/images/bg02-white-left-nogr.png ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/images/bg02-white-left-nogr.png b/manual/src/main/asciidoc/images/bg02-white-left-nogr.png new file mode 100644 index 0000000..1c5186c Binary files /dev/null and b/manual/src/main/asciidoc/images/bg02-white-left-nogr.png differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/images/bg02-white-right-nogr.png ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/images/bg02-white-right-nogr.png b/manual/src/main/asciidoc/images/bg02-white-right-nogr.png new file mode 100644 index 0000000..9734def Binary files /dev/null and b/manual/src/main/asciidoc/images/bg02-white-right-nogr.png differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/images/big-bullet.png ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/images/big-bullet.png b/manual/src/main/asciidoc/images/big-bullet.png new file mode 100644 index 0000000..f036db5 Binary files /dev/null and b/manual/src/main/asciidoc/images/big-bullet.png differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/images/deployer.png ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/images/deployer.png b/manual/src/main/asciidoc/images/deployer.png new file mode 100644 index 0000000..505eb3c Binary files /dev/null and b/manual/src/main/asciidoc/images/deployer.png differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/images/jconsole_admin.jpg ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/images/jconsole_admin.jpg b/manual/src/main/asciidoc/images/jconsole_admin.jpg new file mode 100644 index 0000000..93e8d0e Binary files /dev/null and b/manual/src/main/asciidoc/images/jconsole_admin.jpg differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/images/jconsole_connect.jpg ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/images/jconsole_connect.jpg b/manual/src/main/asciidoc/images/jconsole_connect.jpg new file mode 100644 index 0000000..6041ee1 Binary files /dev/null and b/manual/src/main/asciidoc/images/jconsole_connect.jpg differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/images/jconsole_features.jpg ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/images/jconsole_features.jpg b/manual/src/main/asciidoc/images/jconsole_features.jpg new file mode 100644 index 0000000..233e5fa Binary files /dev/null and b/manual/src/main/asciidoc/images/jconsole_features.jpg differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/images/jconsole_memory.jpg ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/images/jconsole_memory.jpg b/manual/src/main/asciidoc/images/jconsole_memory.jpg new file mode 100644 index 0000000..c9fbb29 Binary files /dev/null and b/manual/src/main/asciidoc/images/jconsole_memory.jpg differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/images/jconsole_overview.jpg ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/images/jconsole_overview.jpg b/manual/src/main/asciidoc/images/jconsole_overview.jpg new file mode 100644 index 0000000..b41a72b Binary files /dev/null and b/manual/src/main/asciidoc/images/jconsole_overview.jpg differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/images/jconsole_summary.jpg ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/images/jconsole_summary.jpg b/manual/src/main/asciidoc/images/jconsole_summary.jpg new file mode 100644 index 0000000..7245d12 Binary files /dev/null and b/manual/src/main/asciidoc/images/jconsole_summary.jpg differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/images/jconsole_threads.jpg ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/images/jconsole_threads.jpg b/manual/src/main/asciidoc/images/jconsole_threads.jpg new file mode 100644 index 0000000..b4c0cb2 Binary files /dev/null and b/manual/src/main/asciidoc/images/jconsole_threads.jpg differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/images/karaf-logo.png ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/images/karaf-logo.png b/manual/src/main/asciidoc/images/karaf-logo.png new file mode 100644 index 0000000..066ab86 Binary files /dev/null and b/manual/src/main/asciidoc/images/karaf-logo.png differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/images/karaf.png ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/images/karaf.png b/manual/src/main/asciidoc/images/karaf.png new file mode 100644 index 0000000..f9fb4a4 Binary files /dev/null and b/manual/src/main/asciidoc/images/karaf.png differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/images/karaf2.png ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/images/karaf2.png b/manual/src/main/asciidoc/images/karaf2.png new file mode 100644 index 0000000..f9fb4a4 Binary files /dev/null and b/manual/src/main/asciidoc/images/karaf2.png differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/images/left-box-bottom.png ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/images/left-box-bottom.png b/manual/src/main/asciidoc/images/left-box-bottom.png new file mode 100644 index 0000000..0495248 Binary files /dev/null and b/manual/src/main/asciidoc/images/left-box-bottom.png differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/images/left-box-right.png ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/images/left-box-right.png b/manual/src/main/asciidoc/images/left-box-right.png new file mode 100644 index 0000000..2698074 Binary files /dev/null and b/manual/src/main/asciidoc/images/left-box-right.png differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/images/left-box-top.png ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/images/left-box-top.png b/manual/src/main/asciidoc/images/left-box-top.png new file mode 100644 index 0000000..e1fc26e Binary files /dev/null and b/manual/src/main/asciidoc/images/left-box-top.png differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/index.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/index.adoc b/manual/src/main/asciidoc/index.adoc new file mode 100644 index 0000000..7f7a57f --- /dev/null +++ b/manual/src/main/asciidoc/index.adoc @@ -0,0 +1,137 @@ +// +// 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. +// + +Apache Karaf Container 4.x - Documentation +========================================= +Apache Software Foundation +:doctype: book +:toc: left +:toclevels: 3 +:toc-position: left +:toc-title: Apache Karaf Container 4.x - Documentation +:numbered: + += Overview + +include::overview.adoc[] + += Quick Start + +include::quick-start.adoc[] + += Update Notes (from Karaf 3.x to 4.x versions) + +include::update-notes.adoc[] + += User Guide + +include::user-guide/installation.adoc[] + +include::user-guide/directory-structure.adoc[] + +include::user-guide/start-stop.adoc[] + +include::user-guide/wrapper.adoc[] + +include::user-guide/console.adoc[] + +include::user-guide/remote.adoc[] + +include::user-guide/log.adoc[] + +include::user-guide/configugration.adoc[] + +include::user-guide/urls.adoc[] + +include::user-guide/provisioning.adoc[] + +include::user-guide/deployers.adoc[] + +include::user-guide/kar.adoc[] + +include::user-guide/instances.adoc[] + +include::user-guide/security.adoc[] + +include::user-guide/obr.adoc[] + +== Enterprise + +include::user-guide/http.adoc[] + +include::user-guide/webcontainer.adoc[] + +include::user-guide/jndi.adoc[] + +include::user-guide/jta.adoc[] + +include::user-guide/jdbc.adoc[] + +include::user-guide/jms.adoc[] + +include::user-guide/jpa.adoc[] + +include::user-guide/ejb.adoc[] + +include::user-guide/cdi.adoc[] + +include::user-guide/failover.adoc[] + +include::user-guide/monitoring.adoc[] + +include::user-guide/webconsole.adoc[] + +include::user-guide/tuning.adoc[] + += Developer Guide + +[NOTE] +==== +The developer guide is currently under a refactoring. The "new" developer guide will document samples providing +in the Karaf Container distribution, in order to have more practical recipes. +==== + +include::developer-guide/developer-commands.adoc[] + +include::developer-guide/scripting.adoc[] + +include::developer-guide/connect.adoc[] + +include::developer-guide/branding.adoc[] + +include::developer-guide/extending.adoc[] + +include::developer-guide/karaf-maven-plugin.adoc[] + +include::developer-guide/custom-distribution.adoc[] + +include::developer-guide/services.adoc[] + +include::developer-guide/creating-bundles.adoc[] + +include::developer-guide/blueprint.adoc[] + +include::developer-guide/ds.adoc[] + +include::developer-guide/dev-cdi.adoc[] + +include::developer-guide/archetypes.adoc[] + +include::developer-guide/security-framework.adoc[] + +include::developer-guide/debugging.adoc[] + +include::developer-guide/writing-tests.adoc[] + +include::developer-guide/github-contributions.adoc[] \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/overview.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/overview.adoc b/manual/src/main/asciidoc/overview.adoc new file mode 100644 index 0000000..6b87e57 --- /dev/null +++ b/manual/src/main/asciidoc/overview.adoc @@ -0,0 +1,51 @@ +// +// 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. +// + +Apache Karaf is a modern and polymorphic container. + +Karaf can be used standalone as a container, supporting a wide range of applications and technologies. +It also supports the "run anywhere" (on any machine with Java, cloud, docker images, ...) using the embedded mode. + +It's a lightweight, powerful, and enterprise ready platform. + +With this flexibility, Karaf is the perfect solution for microservices, systems integration, big data, and much more. + +Apache Karaf is powered by OSGi (but you don't need to know what OSGi is to use Karaf). + +Apache Karaf uses either the Apache Felix or Eclipse Equinox OSGi frameworks, providing additional features on top of the framework. + +Apache Karaf can be scaled from a very lightweight container to a fully featured enterprise service: it's a very flexible and extensible container, covering all the major needs. + +Here is a short list of provided features: + +* *Hot deployment*: simply drop a file in the `deploy` directory, Apache Karaf will detect the type of the file and + try to deploy it. +* *Complete Console*: Apache Karaf provides a complete Unix-like console where you can completely manage the container. +* *Dynamic Configuration*: Apache Karaf provides a set of commands focused on managing its own configuration. + All configuration files are centralized in the `etc` folder. Any change in a configuration file is noticed and reloaded. +* *Advanced Logging System*: Apache Karaf supports all the popular logging frameworks (slf4j, log4j, etc). Whichever + logging framework you use, Apache Karaf centralizes the configuration in one file. +* *Provisioning*: Apache Karaf supports a large set of URLs where you can install your applications (Maven repository, HTTP, + file, etc). It also provides the concept of "Karaf Features" which is a way to describe your application. +* *Management*: Apache Karaf is an enterprise-ready container, providing many management indicators and operations + via JMX. +* *Remote*: Apache Karaf embeds an SSHd server allowing you to use the console remotely. The management layer is also + accessible remotely. +* *Security*: Apache Karaf provides a complete security framework (based on JAAS), and provides a RBAC (Role-Based Access + Control) mechanism for console and JMX access. +* *Instances*: multiple instances of Apache Karaf can be managed directly from a main instance (root). +* *OSGi frameworks*: Apache Karaf is not tightly coupled to one OSGi framework. By default, Apache Karaf runs with the Apache Felix + Framework, but you can easily switch to Equinox (just change one property in a configuration file). + +image::karaf.png[] http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/quick-start.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/quick-start.adoc b/manual/src/main/asciidoc/quick-start.adoc new file mode 100644 index 0000000..5a9b55a --- /dev/null +++ b/manual/src/main/asciidoc/quick-start.adoc @@ -0,0 +1,181 @@ +// +// 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. +// + +These instructions should help you get Apache Karaf up and running in 5 to 15 minutes. + +== Prerequisites + +Karaf requires a Java SE 7 or Java SE 8 environment to run. Refer to http://www.oracle.com/technetwork/java/javase/ for details on how to download and install Java SE 1.7 or greater. + +* Open a Web browser and access the following URL: http://karaf.apache.org/index/community/download.html +* Download the binary distribution that matches your system (zip for windows, tar.gz for unixes) +* Extract the archive to a new folder on your hard drive; for example in c:\karaf - from now on this directory will be referenced as . + +== Start the server + +Open a command line console and change the directory to . + +To start the server, run the following command in Windows: + +---- +bin\karaf.bat +---- + +respectively on Unix: + +---- +bin/karaf +---- + +You should see the following information on the command line console: + +---- + __ __ ____ + / //_/____ __________ _/ __/ + / ,< / __ `/ ___/ __ `/ /_ + / /| |/ /_/ / / / /_/ / __/ + /_/ |_|\__,_/_/ \__,_/_/ + + Apache Karaf (4.0.0) + +Hit '' for a list of available commands +and '[cmd] --help' for help on a specific command. +Hit '' or type 'system:shutdown' or 'logout' to shutdown Karaf. + +karaf@root()> + +---- + +== Shell console basics + +You can now run your first command. Simply type the `` key in the console. + +---- +karaf@root()> Display all 294 possibilities? (y or n) +... +shell:logout shell:more shell:new shell:printf shell:sleep shell:sort shell:source +shell:stack-traces-print shell:tac shell:tail shell:threads shell:watch shell:wc shell:while +shutdown sleep sort source ssh ssh ssh-host-change +ssh-port-change ssh:ssh stack-traces-print start start-level status stop +su sudo system system:framework system:name system:property system:shutdown +system:start-level system:version tac tail threads tree-show uninstall +update user-add user-delete user-list version version-list wait +watch wc while +---- + +You can then grab more specific help for a given command using the `--help` option for this command: + +---- +karaf@root()> bundle:list --help +DESCRIPTION + bundle:list + + Lists all installed bundles. + +SYNTAX + bundle:list [options] [ids] + +ARGUMENTS + ids + The list of bundle (identified by IDs or name or name/version) separated by whitespaces + +OPTIONS + -t + Specifies the bundle threshold; bundles with a start-level less than this value will not get printed out. + --no-format + Disable table rendered output + -s + Shows the symbolic name + -l + Show the locations + --no-ellipsis + + --help + Display this help message + -u + Shows the update locations + --context, -c + Use the given bundle context + (defaults to 0) + -r + Shows the bundle revisions +---- + +Note that the console supports tab completion so if you start typing a command it will show all possible completions and also auto complete if there is only one completion. + +== Deploy a sample application + +While you will learn in the Karaf user's guide how to fully use and leverage Apache Karaf, let's install a sample http://camel.apache.org[Apache Camel] application for now: + +In the console, run the following commands: + +---- +karaf@root()> feature:repo-add camel 2.15.2 +Adding feature url mvn:org.apache.camel.karaf/apache-camel/2.15.2/xml/features +karaf@root()> feature:install camel-spring +karaf@root()> bundle:install -s mvn:org.apache.camel/camel-example-osgi/2.15.2 +Bundle ID: 82 +---- + +The example installed is using Camel to start a timer every 2 seconds and output a message in the log. +The previous commands download the Camel features descriptor and install the example feature. + +You can display the log in the shell: + +---- +karaf@root()> log:display +... +2015-06-30 13:39:44,731 | INFO | timer://myTimer | ExampleRouter | 53 - org.apache.camel.camel-core - 2.15.2 | Exchange[ExchangePattern: InOnly, BodyType: String, Body: SpringDSL set body: Tue Jun 30 13:39:44 CEST 2015] +2015-06-30 13:39:46,730 | INFO | timer://myTimer | MyTransform | 82 - camel-example-osgi - 2.15.2 | >>>> SpringDSL set body: Tue Jun 30 13:39:46 CEST 2015 +2015-06-30 13:39:46,731 | INFO | timer://myTimer | ExampleRouter | 53 - org.apache.camel.camel-core - 2.15.2 | Exchange[ExchangePattern: InOnly, BodyType: String, Body: SpringDSL set body: Tue Jun 30 13:39:46 CEST 2015] +2015-06-30 13:39:48,730 | INFO | timer://myTimer | MyTransform | 82 - camel-example-osgi - 2.15.2 | >>>> SpringDSL set body: Tue Jun 30 13:39:48 CEST 2015 +2015-06-30 13:39:48,730 | INFO | timer://myTimer | ExampleRouter | 53 - org.apache.camel.camel-core - 2.15.2 | Exchange[ExchangePattern: InOnly, BodyType: String, Body: SpringDSL set body: Tue Jun 30 13:39:48 CEST 2015] +---- + +== Stopping and uninstalling the sample application + +To stop and uninstall the demo, run the following command: + +---- +karaf@root()> bundle:stop camel-example-osgi +karaf@root()> bundle:uninstall camel-example-osgi +---- + +== Stopping Karaf + +To stop Karaf from the console, enter `^D` in the console: + +---- +^D +---- + +Alternatively, you can also run the following command: + +---- +karaf@root()> system:shutdown +---- + +halt is also an alias for system:shutdown: + +---- +karaf@root()> halt +---- + +== Cleaning the Karaf state + +Normally Karaf remembers the features and bundles you installed and started. To reset Karaf into a clean state, just delete the data directory when Karaf is not running. + +== Summary + +This document shows how simple it is to get Apache Karaf up and running and install a simple Apache Camel application. http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/update-notes.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/update-notes.adoc b/manual/src/main/asciidoc/update-notes.adoc new file mode 100644 index 0000000..0c5176f --- /dev/null +++ b/manual/src/main/asciidoc/update-notes.adoc @@ -0,0 +1,171 @@ +// +// 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. +// + +This section is dedicated to users of previous Apache Karaf version. + +NB: for the users upgrading from Karaf 2.x, please see the "Update Notes (from 2.x to 3.x)" in the Karaf 3.x +documentation first. + +NB: Karaf 4.x supports Java8. + +== Distributions + +Apache Karaf 4.x is available as tar.gz and zip archives. The content is the same and works on either Unix or Windows +platforms. +The `bin` folder contains both sh and bat scripts. + +== Commands + +Karaf 4 commands are close to the ones provided in Karaf 3. + +The sub-shell modes are the same (in `etc/org.apache.karaf.shell.cfg` or using `shell:completion` command). + +However, some minor changes have been introduced and new commands available: + +|=== +|Apache Karaf 4.x + +|feature:requirement-list + +|feature:requirement-add + +|feature:requirement-remove + +|feature:regions + +|feature:start + +|feature:stop + +|jaas:group-create + +|jaas:group-add + +|jaas:group-delete + +|jaas:group-list + +|jaas:group-role-add + +|jaas:group-role-delete + +|jaas:su + +|jaas:sudo + +|shell:edit + +|shell:env + +|shell:less + +|shell:stack-traces-print + +|shell:threads + +|shell:while + +|log:list + +|bundle:capabilities + +|bundle:diag + +|bundle:id + +|bundle:load-test + +|bundle:requirements + +|bundle:resolve + +|system:name +|=== + +We encourage the users to use the `--help` option to check the name and type of arguments and options. + +In term of development, you can still use the blueprint definition as you do in Karaf 2.x & 3.x (with the corresponding annotations). + +However, in Karaf 4.x, you can use DS and new annotations and avoid the usage of a blueprint XML. + +The new annotations are available: @Service, @Completion, @Parsing, @Reference. It allows you to complete define the command +in the command class directly. + +To simplify the generation of the code and OSGi headers, Karaf 4.x provides the karaf-services-maven-plugin (in org.apache.karaf.tooling Maven groupId). + +Take a look in the developer guide for the command development "new style" details. + +== Features repositories + +Karaf 4.x provides: + +* `mvn:org.apache.karaf.features/enterprise/4.0.x/xml/features` +* `mvn:org.apache.karaf.features/framework/4.0.x/xml/features` +* `mvn:org.apache.karaf.features/spring/4.0.x/xml/features` +* `mvn:org.apache.karaf.features/standard/4.0.x/xml/features` +* `mvn:org.apache.karaf.features/static/4.0.x/xml/features` + +== Features resolver + +Apache Karaf 4.x brings a complete new feature resolver. The purpose is to simplify the features installation and +lifecycle. +The new resolver now checks the feature requirements (defined directly in the features XML), and check which bundles +provides the capabilities to satisfy these requirements. +It allows Karaf to automatically install bundles required by features. + +For "old style" feature (features XML using namespace from Karaf 2.x or 3.x), this feature is not enabled. +As soon as you use a "new style" feature (with namespace 1.3.0 used by Karaf 4.x), this feature is enabled. + +== Namespaces + +Apache Karaf 4.x brings updated version of the namespaces: + +* Supported features namespaces: +** `karaf-features-1.0.0.xsd` +** `karaf-features-1.1.0.xsd` +** `karaf-features-1.2.0.xsd` +** `karaf-features-1.2.1.xsd` +** `karaf-features-1.3.0.xsd` +* Supported jaas namespaces: +** `karaf-jaas-1.0.0.xsd` +** `karaf-jaas-1.1.0.xsd` +* Supported shell namespaces: +** `karaf-shell-1.0.0.xsd` +** `karaf-shell-1.1.0.xsd` + +== Maven plugin + +A cleanup of the goals provided by {{karaf-maven-plugin}} has been done. + +Now the provided goals are: + +* `karaf:archive` to create a tar.gz or zip of a Karaf distribution +* `karaf:assembly` to create a custom Karaf distribution assembly +* `karaf:kar` to create a kar file +* `karaf:verify` to verify and validate Karaf features +* `karaf:features-add-to-repository` to recursively copy features XML and content into a folder (repository) +* `karaf:features-export-meta-data` to extract the metadata from a features XML +* `karaf:features-generate-descriptor` to generate a features XML +* `karaf:commands-generate-help` to generate help/documentation on the commands +* `karaf:run` to run a Karaf container directly from Maven +* `karaf:client` to interact with a remote Karaf instance +* `karaf:deploy` to deploy an application to a remote Karaf instance + +== Update guide + +We encourage users to start a fresh Apache Karaf 4.x container. + +If you upgrade an existing container, `lib` and `system` folder have to be updated (just an override copy). + +For the `etc` folder, a diff is required as some properties changed and new configurations are available. http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/user-guide/cdi.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/cdi.adoc b/manual/src/main/asciidoc/user-guide/cdi.adoc new file mode 100644 index 0000000..3ddd253 --- /dev/null +++ b/manual/src/main/asciidoc/user-guide/cdi.adoc @@ -0,0 +1,75 @@ +// +// 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. +// + +=== CDI + +This section described how to add support of CDI, and embed a CDI container in Apache Karaf. It doesn't describe +how to develop CDI applications. See the developer guide for that. + +==== Pax CDI + +Apache Karaf supports different CDI containers by using Pax CDI. + +Pax CDI is pre-loaded in Apache Karaf. + +You can see now a set of new CDI features available: + +---- +karaf@root()> feature:list|grep -i cdi +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 +pax-cdi-1.2-web | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Web CDI 1.2 support +pax-cdi-web-weld | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld Web CDI 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.2-web-weld | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld Web CDI 1.2 support +pax-cdi-web-openwebbeans | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | OpenWebBeans Web CDI support +deltaspike-core | 1.2.1 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Apache Deltaspike core 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 +deltaspike-data | 1.2.1 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Apache Deltaspike data support +---- + +==== CDI Containers + +Thanks to Pax CDI, Apache Karaf supports multiple CDI implementation versions, and different CDI containers. + +You just have to install the feature corresponding to the CDI container and version that you want to use. + +===== Apache OpenWebBeans + +Apache Karaf provides a ready to use feature for Apache OpenWebBeans. + +The `openwebbeans` feature automatically install the Pax CDI features and the Apache OpenWebBeans bundles: + +---- +karaf@root()> feature:install http +karaf@root()> feature:install pax-cdi-openwebbeans +---- + +===== JBoss Weld CDI container + +Apache Karaf provides a ready to use feature for JBoss Weld. + +The `weld` feature automatically install the Pax CDI features and the JBoss Weld bundles: + +---- +karaf@root()> feature:install pax-cdi-weld +----