You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@karaf.apache.org by jb...@apache.org on 2013/03/15 10:00:54 UTC
svn commit: r1456813 [16/20] - in
/karaf/site/production/manual/latest-2.3.x: ./ commands/ css/ css/scalate/
developers-guide/ images/ users-guide/
Added: karaf/site/production/manual/latest-2.3.x/developers-guide/index.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/developers-guide/index.html?rev=1456813&view=auto
==============================================================================
--- karaf/site/production/manual/latest-2.3.x/developers-guide/index.html (added)
+++ karaf/site/production/manual/latest-2.3.x/developers-guide/index.html Fri Mar 15 09:00:51 2013
@@ -0,0 +1,150 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd">
+<html lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+ <meta name="description" content="description goes here"/>
+ <meta name="keywords" content="keywords,goes,here"/>
+ <meta name="author" content="The Apache Karaf Team"/>
+ <link href="../css/style.css" rel="stylesheet" type="text/css"/>
+ <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
+ <title>
+ Apache Karaf 2.3.2-SNAPSHOT Guides
+ </title>
+ </head>
+ <body>
+ <table width="100%" cellpadding="0" cellspacing="0">
+ <tr width="100%">
+ <td id="cell-0-0" colspan="2">
+
+ </td>
+ <td id="cell-0-1">
+
+ </td>
+ <td id="cell-0-2" colspan="2">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-1-0">
+
+ </td>
+ <td id="cell-1-1">
+
+ </td>
+ <td id="cell-1-2">
+ <div style="padding: 5px;">
+ <div id="banner">
+ <table border="0" cellpadding="0" cellspacing="0" width="100%">
+ <tr>
+ <td align="left" class="topbardiv" nowrap="">
+<a href="http://karaf.apache.org/" title="A server side OSGi distribution">
+ <img border="0" src="../images/karaf-logo.png" width="400px"></img>
+</a>
+ </td>
+ <td align="right" nowrap="">
+<a href="http://www.apache.org/" title="The Apache Sofware Foundation">
+ <img border="0" src="../images/asf-logo.png">
+</a>
+ </td>
+ </tr>
+ </table>
+
+ </div>
+ <div id="top-menu">
+ <table border="0" cellpadding="1" cellspacing="0" width="100%">
+ <tr>
+ <td>
+ <div align="left"></div>
+ </td>
+ <td>
+ <div align="right">
+ <p>
+<a href="../index.html" title="Home">Home</a>
+|
+<a href="../users-guide/index.html" title="Users Guide">Users Guide</a>
+|
+<a href="index.html" title="Developers Guide">Developers Guide</a>
+</p>
+
+
+ </div>
+ </td>
+ </tr>
+ </table>
+ </div>
+ </div>
+ </td>
+ <td id="cell-1-3">
+
+ </td>
+ <td id="cell-1-4">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-2-0" colspan="2">
+
+ </td>
+ <td id="cell-2-1">
+ <table>
+ <tr height="100%" valign="top">
+ <td height="100%">
+ <div id="wrapper-menu-page-right">
+ <div id="wrapper-menu-page-top">
+ <div id="wrapper-menu-page-bottom">
+ <div id="menu-page">
+ <h3 id="Homeindex"><a href="../index.html">Home</a></h3><ul style="list-style: square"><li><a href="../overview.html">Overview</a></li><li><a href="../quick-start.html">Quick Start</a></li></ul><h3 id="UsersGuideusersguideindex"><a href="../users-guide/index.html">Users Guide</a></h3><ul style="list-style: square"><li><a href="../users-guide/installation.html">Installing Karaf</a></li><li><a href="../users-guide/directory-structure.html">Directory Structure</a></li><li><a href="../users-guide/start-stop.html">Starting and stopping Karaf</a></li><li><a href="../users-guide/wrapper.html">OS integration</a></li><li><a href="../users-guide/using-console.html">Using the console</a></li><li><a href="../users-guide/remote-console.html">Remote console</a></li><li><a href="../users-guide/web-console.html">Web console</a></li><li><a href="../users-guide/child-instances.html">Child instances</a></li><li><a href="../users-guide/security.html">Security</a></li><li
><a href="../users-guide/failover.html">Failover Deployments</a></li><li><a href="../users-guide/logging-system.html">Logging system</a></li><li><a href="../users-guide/deployer.html">Deployer</a></li><li><a href="../users-guide/provisioning.html">Provisioning</a></li><li><a href="../users-guide/kar.html">KAR archive</a></li><li><a href="../users-guide/configuration.html">Configuration</a></li><li><a href="../users-guide/http.html">HTTP service</a></li><li><a href="../users-guide/web-applications.html">Web applications</a></li><li><a href="../users-guide/jre-tuning.html">JRE tuning</a></li><li><a href="../users-guide/jmx.html">JMX for administration and monitoring</a></li></ul><h3 id="DevelopersGuidedevelopersguideindex"><a href="index.html">Developers Guide</a></h3><ul style="list-style: square"><li><a href="archetypes.html">Maven Archetypes</a></li><li><a href="branding-console.html">Branding the Console</a></li><li><a href="extending-console.html">Extending the Console</a
></li><li><a href="custom-distribution.html">Custom Distribution</a></li><li><a href="security-framework.html">Security Framework</a></li><li><a href="features-maven-plugin.html">Using the features-maven-plugin</a></li><li><a href="debugging.html">Troubleshooting, Debugging and Profiling</a></li><li><a href="connect-console.html">Programmatically connect to the console</a></li><li><a href="writing-tests.html">Writing integration tests</a></li><li><a href="creating-bundles.html">Creating bundles</a></li><li><a href="shell-syntax.html">Shell syntax</a></li><li><a href="github-contributions.html">Github Contributions</a></li></ul><h3 id="Commandscommandscommands"><a href="../commands/commands.html">Commands</a></h3>
+ </div>
+ </div>
+ </div>
+ </div>
+ </td>
+ <td height="100%" width="100%">
+ <div class="wiki-content">
+<h1 id="DevelopersGuide">Developers Guide</h1><ul><li><a href="archetypes.html">Maven Archetypes</a></li><li><a href="branding-console.html">Branding the Console</a></li><li><a href="extending-console.html">Extending the Console</a></li><li><a href="custom-distribution.html">Custom Distribution</a></li><li><a href="security-framework.html">Security Framework</a></li><li><a href="features-maven-plugin.html">Using the features-maven-plugin</a></li><li><a href="debugging.html">Troubleshooting, Debugging, Profiling, and Monitoring</a></li><li><a href="developer-commands.html">Developer Commands</a></li><li><a href="connect-console.html">Programmatically connect to the console</a></li><li><a href="writing-tests.html">Writing integration tests</a></li><li><a href="creating-bundles.html">Creating bundles</a></li><li><a href="shell-syntax.html">Shell syntax</a></li><li><a href="github-contributions.html">Github Contributions</a></li></ul>
+ </div>
+ </td>
+ </tr>
+ </table>
+ </td>
+ <td id="cell-2-2" colspan="2">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-3-0">
+
+ </td>
+ <td id="cell-3-1">
+
+ </td>
+ <td id="cell-3-2">
+ <div id="footer">
+ <div id="site-footer">
+ © 2008-2011 The Apache Software Foundation
+ <br/>
+ Apache Karaf, Karaf, Apache, the Apache feather logo, and the Apache Karaf project logo are trademarks of The Apache Software Foundation.
+ </div>
+ </div>
+ </td>
+ <td id="cell-3-3">
+
+ </td>
+ <td id="cell-3-4">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-4-0" colspan="2">
+
+ </td>
+ <td id="cell-4-1">
+
+ </td>
+ <td id="cell-4-2" colspan="2">
+
+ </td>
+ </tr>
+ </table>
+ </body>
+</html>
\ No newline at end of file
Added: karaf/site/production/manual/latest-2.3.x/developers-guide/security-framework.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/developers-guide/security-framework.html?rev=1456813&view=auto
==============================================================================
--- karaf/site/production/manual/latest-2.3.x/developers-guide/security-framework.html (added)
+++ karaf/site/production/manual/latest-2.3.x/developers-guide/security-framework.html Fri Mar 15 09:00:51 2013
@@ -0,0 +1,392 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd">
+<html lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+ <meta name="description" content="description goes here"/>
+ <meta name="keywords" content="keywords,goes,here"/>
+ <meta name="author" content="The Apache Karaf Team"/>
+ <link href="../css/style.css" rel="stylesheet" type="text/css"/>
+ <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
+ <title>
+ Apache Karaf 2.3.2-SNAPSHOT Guides
+ </title>
+ </head>
+ <body>
+ <table width="100%" cellpadding="0" cellspacing="0">
+ <tr width="100%">
+ <td id="cell-0-0" colspan="2">
+
+ </td>
+ <td id="cell-0-1">
+
+ </td>
+ <td id="cell-0-2" colspan="2">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-1-0">
+
+ </td>
+ <td id="cell-1-1">
+
+ </td>
+ <td id="cell-1-2">
+ <div style="padding: 5px;">
+ <div id="banner">
+ <table border="0" cellpadding="0" cellspacing="0" width="100%">
+ <tr>
+ <td align="left" class="topbardiv" nowrap="">
+<a href="http://karaf.apache.org/" title="A server side OSGi distribution">
+ <img border="0" src="../images/karaf-logo.png" width="400px"></img>
+</a>
+ </td>
+ <td align="right" nowrap="">
+<a href="http://www.apache.org/" title="The Apache Sofware Foundation">
+ <img border="0" src="../images/asf-logo.png">
+</a>
+ </td>
+ </tr>
+ </table>
+
+ </div>
+ <div id="top-menu">
+ <table border="0" cellpadding="1" cellspacing="0" width="100%">
+ <tr>
+ <td>
+ <div align="left"></div>
+ </td>
+ <td>
+ <div align="right">
+ <p>
+<a href="../index.html" title="Home">Home</a>
+|
+<a href="../users-guide/index.html" title="Users Guide">Users Guide</a>
+|
+<a href="index.html" title="Developers Guide">Developers Guide</a>
+</p>
+
+
+ </div>
+ </td>
+ </tr>
+ </table>
+ </div>
+ </div>
+ </td>
+ <td id="cell-1-3">
+
+ </td>
+ <td id="cell-1-4">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-2-0" colspan="2">
+
+ </td>
+ <td id="cell-2-1">
+ <table>
+ <tr height="100%" valign="top">
+ <td height="100%">
+ <div id="wrapper-menu-page-right">
+ <div id="wrapper-menu-page-top">
+ <div id="wrapper-menu-page-bottom">
+ <div id="menu-page">
+ <h3 id="Homeindex"><a href="../index.html">Home</a></h3><ul style="list-style: square"><li><a href="../overview.html">Overview</a></li><li><a href="../quick-start.html">Quick Start</a></li></ul><h3 id="UsersGuideusersguideindex"><a href="../users-guide/index.html">Users Guide</a></h3><ul style="list-style: square"><li><a href="../users-guide/installation.html">Installing Karaf</a></li><li><a href="../users-guide/directory-structure.html">Directory Structure</a></li><li><a href="../users-guide/start-stop.html">Starting and stopping Karaf</a></li><li><a href="../users-guide/wrapper.html">OS integration</a></li><li><a href="../users-guide/using-console.html">Using the console</a></li><li><a href="../users-guide/remote-console.html">Remote console</a></li><li><a href="../users-guide/web-console.html">Web console</a></li><li><a href="../users-guide/child-instances.html">Child instances</a></li><li><a href="../users-guide/security.html">Security</a></li><li
><a href="../users-guide/failover.html">Failover Deployments</a></li><li><a href="../users-guide/logging-system.html">Logging system</a></li><li><a href="../users-guide/deployer.html">Deployer</a></li><li><a href="../users-guide/provisioning.html">Provisioning</a></li><li><a href="../users-guide/kar.html">KAR archive</a></li><li><a href="../users-guide/configuration.html">Configuration</a></li><li><a href="../users-guide/http.html">HTTP service</a></li><li><a href="../users-guide/web-applications.html">Web applications</a></li><li><a href="../users-guide/jre-tuning.html">JRE tuning</a></li><li><a href="../users-guide/jmx.html">JMX for administration and monitoring</a></li></ul><h3 id="DevelopersGuidedevelopersguideindex"><a href="index.html">Developers Guide</a></h3><ul style="list-style: square"><li><a href="archetypes.html">Maven Archetypes</a></li><li><a href="branding-console.html">Branding the Console</a></li><li><a href="extending-console.html">Extending the Console</a
></li><li><a href="custom-distribution.html">Custom Distribution</a></li><li><a href="security-framework.html">Security Framework</a></li><li><a href="features-maven-plugin.html">Using the features-maven-plugin</a></li><li><a href="debugging.html">Troubleshooting, Debugging and Profiling</a></li><li><a href="connect-console.html">Programmatically connect to the console</a></li><li><a href="writing-tests.html">Writing integration tests</a></li><li><a href="creating-bundles.html">Creating bundles</a></li><li><a href="shell-syntax.html">Shell syntax</a></li><li><a href="github-contributions.html">Github Contributions</a></li></ul><h3 id="Commandscommandscommands"><a href="../commands/commands.html">Commands</a></h3>
+ </div>
+ </div>
+ </div>
+ </div>
+ </td>
+ <td height="100%" width="100%">
+ <div class="wiki-content">
+<h1 id="Securityframework">Security framework</h1><p>Karaf supports <a href="http://download.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html">JAAS</a> 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. </p><h2 id="Overview">Overview</h2><p>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 <tt>karaf</tt> 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.</p><p>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-Securit
y.</p><p>A very simple XML schema for spring has been defined, allowing the deployment of a new realm or a new keystore very easily.</p><h2 id="Schema">Schema</h2><p>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.</p><p>Following is the XML Schema to use when defining Karaf realms:</p><div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code><?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+ 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.
+
+-->
+<xs:schema elementFormDefault='qualified'
+ targetNamespace='http://karaf.apache.org/xmlns/jaas/v1.1.0'
+ xmlns:xs='http://www.w3.org/2001/XMLSchema'
+ xmlns:bp="http://www.osgi.org/xmlns/blueprint/v1.0.0"
+ xmlns:tns='http://karaf.apache.org/xmlns/jaas/v1.1.0'>
+
+ <xs:import namespace="http://www.osgi.org/xmlns/blueprint/v1.0.0"/>
+
+ <xs:element name="config">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="module" minOccurs="0" maxOccurs="unbounded">
+ <xs:complexType mixed="true">
+ <xs:attribute name="name" use="optional" type="xs:string"/>
+ <xs:attribute name="className" use="required" type="xs:string"/>
+ <xs:attribute name="flags" default="required">
+ <xs:simpleType>
+ <xs:restriction base="xs:NMTOKEN">
+ <xs:enumeration value="required"/>
+ <xs:enumeration value="requisite"/>
+ <xs:enumeration value="sufficient"/>
+ <xs:enumeration value="optional"/>
+ </xs:restriction>
+ </xs:simpleType>
+ </xs:attribute>
+ </xs:complexType>
+ </xs:element>
+ </xs:sequence>
+ <xs:attribute name="name" use="required" type="xs:string"/>
+ <xs:attribute name="rank" use="optional" default="0" type="xs:int"/>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:element name="keystore">
+ <xs:complexType>
+ <xs:attribute name="name" use="required" type="xs:string"/>
+ <xs:attribute name="rank" use="optional" default="0" type="xs:int"/>
+ <xs:attribute name="path" use="required" type="xs:string"/>
+ <xs:attribute name="keystorePassword" use="optional" type="xs:string"/>
+ <xs:attribute name="keyPasswords" use="optional" type="xs:string"/>
+ </xs:complexType>
+ </xs:element>
+
+</xs:schema></code></pre></div><p>You can find the schema at the following <a href="http://karaf.apache.org/xmlns/jaas/v1.1.0">location</a>.</p><p>Here are two examples using this schema:</p><div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code>
+<?xml version="1.0" encoding="UTF-8"?>
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
+ xmlns:jaas="http://karaf.apache.org/xmlns/jaas/v1.0.0"
+ xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0">
+
+ <!-- Bean to allow the $[karaf.base] property to be correctly resolved -->
+ <ext:property-placeholder placeholder-prefix="$[" placeholder-suffix="]"/>
+
+ <type-converters>
+ <bean class="org.apache.karaf.jaas.modules.properties.PropertiesConverter"/>
+ </type-converters>
+
+ <jaas:config name="myrealm">
+ <jaas:module className="org.apache.karaf.jaas.modules.properties.PropertiesLoginModule"
+ flags="required">
+ users = $[karaf.base]/etc/users.properties
+ </jaas:module>
+ </jaas:config>
+
+ <service interface="org.apache.karaf.jaas.modules.BackingEngineFactory">
+ <bean class="org.apache.karaf.jaas.modules.properties.PropertiesBackingEngineFactory"/>
+ </service>
+
+</blueprint></code></pre></div><p>NB: Don't forge to expose the BackingEngine as an OSGi service.</p><div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code>
+<jaas:keystore xmlns:jaas="http://karaf.apache.org/xmlns/jaas/v1.1.0"
+ name="ks"
+ rank="1"
+ path="classpath:privatestore.jks"
+ keystorePassword="keyStorePassword"
+ keyPasswords="myalias=myAliasPassword">
+</jaas:keystore></code></pre></div><p>The <tt>id</tt> attribute is the blueprint id of the bean, but it will be used by default as the name of the realm if no <tt>name</tt> attribute is specified. Additional attributes on the <tt>config</tt> elements are a <tt>rank</tt>, 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 <tt>publish</tt> which can be set to false to not publish the realm in the OSGi registry, thereby disabling the use of this realm.</p><p>Each realm can contain one or more module definitions. Each module identifies a LoginModule and the <tt>className</tt> 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 <tt>flags</tt> attribute can take one of four values that are explained on the <a href="http://svn.apache.org/repos/asf/karaf/tags/karaf-2.0.0/jaas/boot/src/main/java/org/apache/karaf/jaas/boot/ProxyLoginModule.java">JAAS documentation</a>.<br/>The content of the <tt>module</tt> element is parsed as a properties file and will be used to further configure the login module.</p><p>Deploying such a code will lead to a <a href="http://svn.apache.org/repos/asf/karaf/tags/karaf-2.0.0/jaas/config/src/main/java/org/apache/karaf/jaas/config/JaasRealm.java">JaasRealm</a> object in the OSGi registry, which will then be used when using the JAAS login module.</p><h3 id="Configurationoverrideanduseoftherankattribute">Configuration override and use of the <tt>rank</tt> attribute</h3><p>The <tt>rank</tt> attribute on the <tt>config</tt> 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 <tt>rank</tt> attribute will be used.<br/>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 <tt>name="karaf"</tt> and <tt>rank="1"</tt>.</p><div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code>
+<?xml version="1.0" encoding="UTF-8"?>
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
+ xmlns:jaas="http://karaf.apache.org/xmlns/jaas/v1.1.0"
+ xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0">
+
+ <!-- Bean to allow the $[karaf.base] property to be correctly resolved -->
+ <ext:property-placeholder placeholder-prefix="$[" placeholder-suffix="]"/>
+
+ <type-converters>
+ <bean class="org.apache.karaf.jaas.modules.properties.PropertiesConverter"/>
+ </type-converters>
+
+ <jaas:config name="karaf" rank="1">
+ <jaas:module className="org.apache.karaf.jaas.modules.properties.PropertiesLoginModule"
+ flags="required">
+ users = $[karaf.base]/etc/users.properties
+ ...
+ </jaas:module>
+ </jaas:config>
+
+</blueprint></code></pre></div><h2 id="Architecture">Architecture</h2><p>Due to constraints in the JAAS specification, one class has to be available for all bundles. This class is called <a href="http://svn.apache.org/repos/asf/karaf/tags/karaf-2.0.0/jaas/boot/src/main/java/org/apache/karaf/jaas/boot/ProxyLoginModule.java">ProxyLoginModule</a> 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).</p><p>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 <a href="http://svn.apache.org/repos/asf/karaf/tags/karaf-2.0.0/j
aas/config/src/main/java/org/apache/karaf/jaas/config/JaasRealm.java">JaasRealm</a> 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.</p><h2 id="Availablerealms">Available realms</h2><p>Karaf comes with several login modules to handle authentication needs for your environment.</p><h3 id="PropertiesLoginModule">PropertiesLoginModule</h3><div class="table-wrap"><table class="confluenceTable"><tr><td class="confluenceTd"> LoginModule </td><td class="confluenceTd"> org.apache.karaf.jaas.modules.properties.PropertiesLoginModule </td></tr><tr><td class="confluenceTd"> BackingEngineFactory </td><td class="confluenceTd"> org.apache.karaf.jaas.modules.properties.PropertiesBackingEngineFactory </td></tr></table></div><p>This login module is the one configured by default. It uses a pro
perties text file to load the users, passwords and roles. </p><div class="table-wrap"><table class="confluenceTable"><tr><th class="confluenceTh"> Name </th><th class="confluenceTh"> Description </th></tr><tr><td class="confluenceTd"> <tt>users</tt> </td><td class="confluenceTd"> location of the properties file </td></tr></table></div><p>This file uses the <a href="http://download.oracle.com/javase/6/docs/api/java/util/Properties.html#load(java.io.Reader)">properties file format</a>.<br/>The format of the properties is as follows, with each line defining a user, its password and associated roles:</p><pre>
+user=password[,role][,role]...
+</pre><div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code>
+<jaas:config name="karaf">
+ <jaas:module className="org.apache.karaf.jaas.modules.properties.PropertiesLoginModule"
+ flags="required">
+ users = $[karaf.base]/etc/users.properties
+ </jaas:module>
+</jaas:config></code></pre></div><p>Note for windows users: Do not forget the typeconverter from the first config snippet. It makes sure that windows paths are handled correctly.</p><h3 id="OsgiConfigLoginModule">OsgiConfigLoginModule</h3><div class="table-wrap"><table class="confluenceTable"><tr><td class="confluenceTd"> LoginModule </td><td class="confluenceTd"> org.apache.karaf.jaas.modules.osgi.OsgiConfigLoginModule </td></tr><tr><td class="confluenceTd"> BackingEngineFactory </td><td class="confluenceTd"> </td></tr></table></div><p>The OsgiConfigLoginModule uses the OSGi ConfigurationAdmin service to provide the users, passwords and roles.</p><div class="table-wrap"><table class="confluenceTable"><tr><th class="confluenceTh"> Name </th><th class="confluenceTh"> Description </th></tr><tr><td class="confluenceTd"> <tt>pid</tt> </td><td class="confluenceTd"> t
he PID of the configuration containing user definitions </td></tr></table></div><p>The format of the configuration is the same than for the <tt>PropertiesLoginModule</tt>.</p><h3 id="JDBCLoginModule">JDBCLoginModule</h3><div class="table-wrap"><table class="confluenceTable"><tr><td class="confluenceTd"> LoginModule </td><td class="confluenceTd"> org.apache.karaf.jaas.modules.jdbc.JDBCLoginModule </td></tr><tr><td class="confluenceTd"> BackingEngineFactory </td><td class="confluenceTd"> org.apache.karaf.jaas.modules.jdbc.JDBCBackingEngineFactory </td></tr></table></div><p>The JDBCLoginModule uses a database to load the users, passwords and roles from a provided data source <em>(normal or XA)</em>. The data source and the queries for password and role retrieval are configurable using the following parameters.</p><div class="table-wrap"><table class="confluenceTable"><tr><th class="confluenceTh"> Name </th><th class="confluenceTh"> Desc
ription </th></tr><tr><td class="confluenceTd"> <tt>datasource</tt> </td><td class="confluenceTd"> The datasource as on OSGi ldap filter or as JDNI name</td></tr><tr><td class="confluenceTd"> <tt>query.password</tt> </td><td class="confluenceTd"> The SQL query that retries the password of the user </td></tr><tr><td class="confluenceTd"> <tt>query.role</tt> </td><td class="confluenceTd"> The SQL query that retries the roles of the user </td></tr></table></div><p><u>Passing a data source as an OSGi ldap filter</u></p><p>To use an OSGi ldap filter, the prefix osgi: needs to be provided, as shown below:</p><div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code>
+<jaas:config name="karaf">
+ <jaas:module className="org.apache.karaf.jaas.modules.jdbc.JDBCLoginModule"
+ flags="required">
+ 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=?
+ </jaas:module>
+</jaas:config></code></pre></div><p><u>Passing a data source as a JNDI name</u></p><p>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.</p><div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code>
+<jaas:config name="karaf">
+ <jaas:module className="org.apache.karaf.jaas.modules.jdbc.JDBCLoginModule"
+ flags="required">
+ 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=?
+ </jaas:module>
+</jaas:config></code></pre></div><h3 id="LDAPLoginModule">LDAPLoginModule</h3><div class="table-wrap"><table class="confluenceTable"><tr><td class="confluenceTd"> LoginModule </td><td class="confluenceTd"> org.apache.karaf.jaas.modules.ldap.LDAPLoginModule </td></tr><tr><td class="confluenceTd"> BackingEngineFactory </td><td class="confluenceTd"> </td></tr></table></div><p>The LDAPLoginModule uses LDAP to load the users and roles and bind the users on the LDAP to check passwords.</p><p>The LDAPLoginModule supports the following parameters:</p><div class="table-wrap"><table class="confluenceTable"><tr><th class="confluenceTh"> Name </th><th class="confluenceTh"> Description </th></tr><tr><td class="confluenceTd"> <tt>connection.url</tt> </td><td class="confluenceTd"> The LDAP connection URL, e.g. ldap://hostname </td></tr><tr><td class="confluenceTd"> <tt>co
nnection.username</tt> </td><td class="confluenceTd"> Admin username to connect to the LDAP. This parameter is optional, if it's not provided, the LDAP connection will be anonymous. </td></tr><tr><td class="confluenceTd"> <tt>connection.password</tt> </td><td class="confluenceTd"> Admin password to connect to the LDAP. Only used if the <tt>connection.username</tt> is specified. </td></tr><tr><td class="confluenceTd"> <tt>user.base.dn</tt> </td><td class="confluenceTd"> The LDAP base DN used to looking for user, e.g. ou=user,dc=apache,dc=org </td></tr><tr><td class="confluenceTd"> <tt>user.filter</tt> </td><td class="confluenceTd"> The LDAP filter used to looking for user, e.g. (uid=%u) where %u will be replaced by the username. </td></tr><tr><td class="confluenceTd"> <tt>user.search.subtree</tt> </td><td class="confluenceTd"> If "true", the user lookup will be recursive (SUBTREE). If "false", the user lookup will be performed only at the fi
rst level (ONELEVEL). </td></tr><tr><td class="confluenceTd"> <tt>role.base.dn</tt> </td><td class="confluenceTd"> The LDAP base DN used to looking for roles, e.g. ou=role,dc=apache,dc=org </td></tr><tr><td class="confluenceTd"> <tt>role.filter</tt> </td><td class="confluenceTd"> The LDAP filter used to looking for user's role, e.g. (member:=uid=%u) </td></tr><tr><td class="confluenceTd"> <tt>role.name.attribute</tt> </td><td class="confluenceTd"> The LDAP role attribute containing the role string used by Karaf, e.g. cn </td></tr><tr><td class="confluenceTd"> <tt>role.search.subtree</tt> </td><td class="confluenceTd"> If "true", the role lookup will be recursive (SUBTREE). If "false", the role lookup will be performed only at the first level (ONELEVEL). </td></tr><tr><td class="confluenceTd"> <tt>authentication</tt> </td><td class="confluenceTd"> Define the authentication backend used on the LDAP server. The default is simple. </td></t
r><tr><td class="confluenceTd"> <tt>initial.context.factory</tt> </td><td class="confluenceTd"> Define the initial context factory used to connect to the LDAP server. The default is com.sun.jndi.ldap.LdapCtxFactory </td></tr><tr><td class="confluenceTd"> <tt>ssl</tt> </td><td class="confluenceTd"> If "true" or if the protocol on the <tt>connection.url</tt> is <tt>ldaps</tt>, an SSL connection will be used </td></tr><tr><td class="confluenceTd"> <tt>ssl.provider</tt> </td><td class="confluenceTd"> The provider name to use for SSL </td></tr><tr><td class="confluenceTd"> <tt>ssl.protocol</tt> </td><td class="confluenceTd"> The protocol name to use for SSL (SSL for example)</td></tr><tr><td class="confluenceTd"> <tt>ssl.algorithm</tt> </td><td class="confluenceTd"> The algorithm to use for the KeyManagerFactory and TrustManagerFactory (PKIX for example) </td></tr><tr><td class="confluenceTd"> <tt>ssl.keystore</tt> <
/td><td class="confluenceTd"> The key store name to use for SSL. The key store must be deployed using a <tt>jaas:keystore</tt> configuration. </td></tr><tr><td class="confluenceTd"> <tt>ssl.keyalias</tt> </td><td class="confluenceTd"> The key alias to use for SSL </td></tr><tr><td class="confluenceTd"> <tt>ssl.truststore</tt> </td><td class="confluenceTd"> The trust store name to use for SSL. The trust store must be deployed using a <tt>jaas:keystore</tt> configuration. </td></tr></table></div><p>A example of LDAPLoginModule usage follows:</p><div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code>
+<jaas:config name="karaf">
+ <jaas:module className="org.apache.karaf.jaas.modules.ldap.LDAPLoginModule" flags="required">
+ 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
+ </jaas:module>
+</jaas:config></code></pre></div><p>If you wish to use an SSL connection, the following configuration can be used as an example:</p><div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code>
+<ext:property-placeholder />
+
+<jaas:config name="karaf" rank="1">
+ <jaas:module className="org.apache.karaf.jaas.modules.ldap.LDAPLoginModule" flags="required">
+ 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
+ </jaas:module>
+</jaas:config>
+
+<jaas:keystore name="ks"
+ path="file:///${karaf.home}/etc/trusted.ks"
+ keystorePassword="secret" /></code></pre></div><h2 id="Encryptionservice">Encryption service</h2><p>The <a href="http://svn.apache.org/repos/asf/karaf/trunk/jaas/modules/src/main/java/org/apache/karaf/jaas/modules/EncryptionService.java">EncryptionService</a> is a service registered in the OSGi registry providing means to encrypt and check encrypted passwords. This service acts as a factory for <a href="http://svn.apache.org/repos/asf/karaf/trunk/jaas/modules/src/main/java/org/apache/karaf/jaas/modules/Encryption.java">Encryption</a> objects actually performing the encryption.</p><p>This service is used in all Karaf login modules to support encrypted passwords.</p><h3 id="Configuringproperties">Configuring properties</h3><p>Each login module supports the following additional set of properties:</p><div class="table-wrap"><table class="confluenceTable"><tr><th class="confluenceTh"> Name </th><th class="confluenceTh"> Description <
/th></tr><tr><td class="confluenceTd"> <tt>encryption.name</tt> </td><td class="confluenceTd"> Name of the encryption service registered in OSGi (cf. paragraph <a href="#Jasypt.html">below</a>) </td></tr><tr><td class="confluenceTd"> <tt>encryption.enabled</tt> </td><td class="confluenceTd"> Boolean used to turn on encryption </td></tr><tr><td class="confluenceTd"> <tt>encryption.prefix</tt> </td><td class="confluenceTd"> Prefix for encrypted passwords </td></tr><tr><td class="confluenceTd"> <tt>encryption.suffix</tt> </td><td class="confluenceTd"> Suffix for encrypted passwords </td></tr><tr><td class="confluenceTd"> <tt>encryption.algorithm</tt> </td><td class="confluenceTd"> Name of an algorithm to be used for hashing, like "MD5" or "SHA-1" </td></tr><tr><td class="confluenceTd"> <tt>encryption.encoding</tt> </td><td class="confluenceTd"> Encrypted passwords encoding (can be <tt>hexadecimal</tt> or <tt>base64</tt>) </td></tr><tr><td class="confluenceTd"> <tt
>role.policy</tt> </td><td class="confluenceTd"> A policy for identifying roles (can be <tt>prefix</tt> or <tt>group</tt>) <a href="#Rolediscoverypolicies.html">below</a>) </td></tr><tr><td class="confluenceTd"> <tt>role.discriminator</tt> </td><td class="confluenceTd"> A discriminator value to be used by the role policy </td></tr></table></div><p>A simple example follows:</p><div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code>
+<jaas:config name="karaf">
+ <jaas:module className="org.apache.karaf.jaas.modules.properties.PropertiesLoginModule"
+ flags="required">
+ users = $[karaf.base]/etc/users.properties
+ encryption.enabled = true
+ encryption.algorithm = MD5
+ encryption.encoding = hexadecimal
+ </jaas:module>
+</jaas:config></code></pre></div><h3 id="Prefixandsuffix">Prefix and suffix</h3><p>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.</p><h3 id="Jasypt">Jasypt</h3><p>Karaf default installation comes with a simple encryption service which usually fulfills simple needs. However, in some cases, you may need to install the <a href="http://www.jasypt.org/">Jasypt</a> library which provides stronger encryption algorithms and more control over them.</p><p>To install the Jasypt library, the easiest way is to install the available feature:</p><pre>
+karaf@root> features:install jasypt-encryption
+</pre><p>It will download and install the required bundles and also register an <tt>EncryptionService</tt> for Jasypt in the OSGi registry.</p><p>When configuring a login module to use Jasypt, you need to specify the <tt>encryption.name</tt> property and set it to a value of <tt>jasypt</tt> to make sure the Jasypt encryption service will be used. </p><p>In addition to the standard properties above, the Jasypt service provides the following parameters:</p><div class="table-wrap"><table class="confluenceTable"><tr><th class="confluenceTh"> Name </th><th class="confluenceTh"> Description </th></tr><tr><td class="confluenceTd"> <tt>providerName</tt> </td><td class="confluenceTd"> Name of the <tt>java.security.Provider</tt> name to use for obtaining the digest algorithm </td></tr><tr><td class="confluenceTd"> <tt>providerClassName</tt> </td><td class="confluenceTd"> Class name for the security provider to be used for obtaining the digest algorit
hm </td></tr><tr><td class="confluenceTd"> <tt>iterations</tt> </td><td class="confluenceTd"> Number of times the hash function will be applied recursively </td></tr><tr><td class="confluenceTd"> <tt>saltSizeBytes</tt> </td><td class="confluenceTd"> Size of the salt to be used to compute the digest </td></tr><tr><td class="confluenceTd"> <tt>saltGeneratorClassName</tt> </td><td class="confluenceTd"> Class name of the salt generator </td></tr></table></div><p>A typical realm definition using Jasypt encryption service would look like:</p><div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code>
+<jaas:config name="karaf">
+ <jaas:module className="org.apache.karaf.jaas.modules.properties.PropertiesLoginModule"
+ flags="required">
+ 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
+ </jaas:module>
+</jaas:config></code></pre></div><h2 id="Rolediscoverypolicies">Role discovery policies</h2><p>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.</p><p>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.</p><ol><li>Prefixed Roles</li><li>Grouped Roles</li></ol><p><u>Prefixed Roles</u><br/>When the prefixed role policy is used the login module applies a configurable prefix <em>(property role.discriminator)</em> to the role, so that the a
pplication can identify the role's principals by its prefix. Example:</p><div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code>
+<jaas:config name="karaf">
+ <jaas:module className="org.apache.karaf.jaas.modules.properties.PropertiesLoginModule"
+ flags="required">
+ users = $[karaf.base]/etc/users.properties
+ role.policy = prefix
+ role.discriminator = ROLE_
+ </jaas:module>
+</jaas:config></code></pre></div><p>The application can identify the role principals using a snippet like this:</p><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code>
+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())));
+ }
+}</code></pre></div><p><u>Grouped Roles</u><br/>When the group role policy is used the login module provides all roles as members of a group with a configurable name <em>(property role.discriminator)</em>. Example:</p><div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code>
+<jaas:config name="karaf">
+ <jaas:module className="org.apache.karaf.jaas.modules.properties.PropertiesLoginModule"
+ flags="required">
+ users = $[karaf.base]/etc/users.properties
+ role.policy = group
+ role.discriminator = ROLES
+ </jaas:module>
+</jaas:config></code></pre></div><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code>
+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<? extends Principal> members = g.members();
+ while (members.hasMoreElements()) {
+ Principal member = members.nextElement();
+ roles.add(member.getName());
+ }
+ }
+}</code></pre></div><h2 id="Defaultrolepolicies">Default role policies</h2><p>The previous section describes how to leverage role policies. However, Karaf provides a default role policy, based on the following class names:</p><ul><li>org.apache.karaf.jaas.modules.UserPrincipal</li><li>org.apache.karaf.jaas.modules.RolePrincipal</li><li>org.apache.karaf.jaas.modules.GroupPrincipal</li></ul><p>It allows you to directly handling the role class:</p><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code>
+String rolePrincipalClass = "org.apache.karaf.jaas.modules.RolePrincipal";
+
+for (Principal p : subject.getPrincipals()) {
+ if (p.getClass().getName().equals(rolePrincipalClass)) {
+ roles.add(p.getName());
+ }
+}</code></pre></div>
+ </div>
+ </td>
+ </tr>
+ </table>
+ </td>
+ <td id="cell-2-2" colspan="2">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-3-0">
+
+ </td>
+ <td id="cell-3-1">
+
+ </td>
+ <td id="cell-3-2">
+ <div id="footer">
+ <div id="site-footer">
+ © 2008-2011 The Apache Software Foundation
+ <br/>
+ Apache Karaf, Karaf, Apache, the Apache feather logo, and the Apache Karaf project logo are trademarks of The Apache Software Foundation.
+ </div>
+ </div>
+ </td>
+ <td id="cell-3-3">
+
+ </td>
+ <td id="cell-3-4">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-4-0" colspan="2">
+
+ </td>
+ <td id="cell-4-1">
+
+ </td>
+ <td id="cell-4-2" colspan="2">
+
+ </td>
+ </tr>
+ </table>
+ </body>
+</html>
\ No newline at end of file
Added: karaf/site/production/manual/latest-2.3.x/developers-guide/shell-syntax.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/developers-guide/shell-syntax.html?rev=1456813&view=auto
==============================================================================
--- karaf/site/production/manual/latest-2.3.x/developers-guide/shell-syntax.html (added)
+++ karaf/site/production/manual/latest-2.3.x/developers-guide/shell-syntax.html Fri Mar 15 09:00:51 2013
@@ -0,0 +1,229 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd">
+<html lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+ <meta name="description" content="description goes here"/>
+ <meta name="keywords" content="keywords,goes,here"/>
+ <meta name="author" content="The Apache Karaf Team"/>
+ <link href="../css/style.css" rel="stylesheet" type="text/css"/>
+ <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
+ <title>
+ Apache Karaf 2.3.2-SNAPSHOT Guides
+ </title>
+ </head>
+ <body>
+ <table width="100%" cellpadding="0" cellspacing="0">
+ <tr width="100%">
+ <td id="cell-0-0" colspan="2">
+
+ </td>
+ <td id="cell-0-1">
+
+ </td>
+ <td id="cell-0-2" colspan="2">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-1-0">
+
+ </td>
+ <td id="cell-1-1">
+
+ </td>
+ <td id="cell-1-2">
+ <div style="padding: 5px;">
+ <div id="banner">
+ <table border="0" cellpadding="0" cellspacing="0" width="100%">
+ <tr>
+ <td align="left" class="topbardiv" nowrap="">
+<a href="http://karaf.apache.org/" title="A server side OSGi distribution">
+ <img border="0" src="../images/karaf-logo.png" width="400px"></img>
+</a>
+ </td>
+ <td align="right" nowrap="">
+<a href="http://www.apache.org/" title="The Apache Sofware Foundation">
+ <img border="0" src="../images/asf-logo.png">
+</a>
+ </td>
+ </tr>
+ </table>
+
+ </div>
+ <div id="top-menu">
+ <table border="0" cellpadding="1" cellspacing="0" width="100%">
+ <tr>
+ <td>
+ <div align="left"></div>
+ </td>
+ <td>
+ <div align="right">
+ <p>
+<a href="../index.html" title="Home">Home</a>
+|
+<a href="../users-guide/index.html" title="Users Guide">Users Guide</a>
+|
+<a href="index.html" title="Developers Guide">Developers Guide</a>
+</p>
+
+
+ </div>
+ </td>
+ </tr>
+ </table>
+ </div>
+ </div>
+ </td>
+ <td id="cell-1-3">
+
+ </td>
+ <td id="cell-1-4">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-2-0" colspan="2">
+
+ </td>
+ <td id="cell-2-1">
+ <table>
+ <tr height="100%" valign="top">
+ <td height="100%">
+ <div id="wrapper-menu-page-right">
+ <div id="wrapper-menu-page-top">
+ <div id="wrapper-menu-page-bottom">
+ <div id="menu-page">
+ <h3 id="Homeindex"><a href="../index.html">Home</a></h3><ul style="list-style: square"><li><a href="../overview.html">Overview</a></li><li><a href="../quick-start.html">Quick Start</a></li></ul><h3 id="UsersGuideusersguideindex"><a href="../users-guide/index.html">Users Guide</a></h3><ul style="list-style: square"><li><a href="../users-guide/installation.html">Installing Karaf</a></li><li><a href="../users-guide/directory-structure.html">Directory Structure</a></li><li><a href="../users-guide/start-stop.html">Starting and stopping Karaf</a></li><li><a href="../users-guide/wrapper.html">OS integration</a></li><li><a href="../users-guide/using-console.html">Using the console</a></li><li><a href="../users-guide/remote-console.html">Remote console</a></li><li><a href="../users-guide/web-console.html">Web console</a></li><li><a href="../users-guide/child-instances.html">Child instances</a></li><li><a href="../users-guide/security.html">Security</a></li><li
><a href="../users-guide/failover.html">Failover Deployments</a></li><li><a href="../users-guide/logging-system.html">Logging system</a></li><li><a href="../users-guide/deployer.html">Deployer</a></li><li><a href="../users-guide/provisioning.html">Provisioning</a></li><li><a href="../users-guide/kar.html">KAR archive</a></li><li><a href="../users-guide/configuration.html">Configuration</a></li><li><a href="../users-guide/http.html">HTTP service</a></li><li><a href="../users-guide/web-applications.html">Web applications</a></li><li><a href="../users-guide/jre-tuning.html">JRE tuning</a></li><li><a href="../users-guide/jmx.html">JMX for administration and monitoring</a></li></ul><h3 id="DevelopersGuidedevelopersguideindex"><a href="index.html">Developers Guide</a></h3><ul style="list-style: square"><li><a href="archetypes.html">Maven Archetypes</a></li><li><a href="branding-console.html">Branding the Console</a></li><li><a href="extending-console.html">Extending the Console</a
></li><li><a href="custom-distribution.html">Custom Distribution</a></li><li><a href="security-framework.html">Security Framework</a></li><li><a href="features-maven-plugin.html">Using the features-maven-plugin</a></li><li><a href="debugging.html">Troubleshooting, Debugging and Profiling</a></li><li><a href="connect-console.html">Programmatically connect to the console</a></li><li><a href="writing-tests.html">Writing integration tests</a></li><li><a href="creating-bundles.html">Creating bundles</a></li><li><a href="shell-syntax.html">Shell syntax</a></li><li><a href="github-contributions.html">Github Contributions</a></li></ul><h3 id="Commandscommandscommands"><a href="../commands/commands.html">Commands</a></h3>
+ </div>
+ </div>
+ </div>
+ </div>
+ </td>
+ <td height="100%" width="100%">
+ <div class="wiki-content">
+<h1 id="Shellsyntax">Shell syntax</h1><h2 id="Easytouseinteractivelynounnecessarysyntax">Easy to use interactively - no unnecessary syntax</h2><pre>
+// simple command
+karaf@root> echo hello world
+hello world
+
+// session variables
+karaf@root> msg = "hello world"
+hello world
+karaf@root> echo $msg
+hello world
+
+// execution quotes () - similar to bash backquotes
+karaf@root> (bundle 1) location
+mvn:org.ops4j.pax.url/pax-url-mvn/1.1.3
+</pre><h2 id="Listmapspipesandclosures">List, maps, pipes and closures</h2><pre>
+// lists - []
+karaf@root> list = [1 2 a b]
+1
+2
+a
+b
+
+karaf@root> map = [Jan=1 Feb=2 Mar=3]
+Jan 1
+Feb 2
+Mar 3
+
+// pipes
+karaf@root> bundles | grep felix
+000000 ACT org.apache.felix.framework-3.0.2
+000005 ACT org.apache.felix.configadmin-1.2.4
+000006 ACT org.apache.felix.fileinstall-3.0.2
+
+// closures - {}
+karaf@root> echo2 = { echo xxx $args yyy }
+org.apache.felix.gogo.runtime.shell.Closure@2ffb36c2
+karaf@root> echo2 hello world
+xxx hello world yyy
+</pre><h2 id="LeveragesexistingJavacapabilitiesviareflection">Leverages existing Java capabilities, via reflection</h2><pre>
+// exception handling - console shows summary, but full context available
+karaf@root> start xxx
+Error executing command osgi:start: unable to convert argument ids with value '[xxx]' to type java.util.List<java.lang.Long>
+karaf@root> $karaf.lastException printStackTrace
+org.apache.felix.gogo.commands.CommandException: Unable to convert argument ids with value '[xxx]' to type java.util.List<java.lang.Long>
+ at org.apache.felix.gogo.commands.basic.DefaultActionPreparator.prepare(DefaultActionPreparator.java:347)
+ at org.apache.felix.gogo.commands.basic.AbstractCommand.execute(AbstractCommand.java:34)
+ at org.apache.felix.gogo.runtime.shell.CommandProxy.execute(CommandProxy.java:50)
+ at org.apache.felix.gogo.runtime.shell.Closure.execute(Closure.java:229)
+ at org.apache.felix.gogo.runtime.shell.Closure.executeStatement(Closure.java:162)
+ at org.apache.felix.gogo.runtime.shell.Pipe.run(Pipe.java:101)
+ at org.apache.felix.gogo.runtime.shell.Closure.execute(Closure.java:79)
+ at org.apache.felix.gogo.runtime.shell.CommandSessionImpl.execute(CommandSessionImpl.java:71)
+ at org.apache.karaf.shell.console.jline.Console.run(Console.java:169)
+ at java.lang.Thread.run(Thread.java:637)
+Caused by: java.lang.Exception: Unable to convert from [xxx] to java.util.List<java.lang.Long>(error converting collection entry)
+ at org.apache.aries.blueprint.container.AggregateConverter.convertToCollection(AggregateConverter.java:318)
+ at org.apache.aries.blueprint.container.AggregateConverter.convert(AggregateConverter.java:159)
+ at org.apache.karaf.shell.console.commands.BlueprintCommand$BlueprintActionPreparator.convert(BlueprintCommand.java:73)
+ at org.apache.felix.gogo.commands.basic.DefaultActionPreparator.prepare(DefaultActionPreparator.java:344)
+ ... 9 more
+Caused by: java.lang.NumberFormatException: For input string: "xxx"
+ at java.lang.NumberFormatException.forInputString(NumberFormatException.java:48)
+ at java.lang.Long.parseLong(Long.java:410)
+ at java.lang.Long.valueOf(Long.java:525)
+ at org.apache.aries.blueprint.container.AggregateConverter.convertFromString(AggregateConverter.java:261)
+ at org.apache.aries.blueprint.container.AggregateConverter.convert(AggregateConverter.java:151)
+ at org.apache.aries.blueprint.container.AggregateConverter.convertToCollection(AggregateConverter.java:316)
+ ... 12 more
+
+// add all public methods on java.lang.System as commands:
+karaf@root> addcommand system (loadClass java.lang.System)
+karaf@root> system:getproperty karaf.name
+root
+
+// create new objects
+karaf@root> map = (new java.util.HashMap)
+karaf@root> $map put 0 0
+karaf@root> $map
+0 0
+</pre>
+ </div>
+ </td>
+ </tr>
+ </table>
+ </td>
+ <td id="cell-2-2" colspan="2">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-3-0">
+
+ </td>
+ <td id="cell-3-1">
+
+ </td>
+ <td id="cell-3-2">
+ <div id="footer">
+ <div id="site-footer">
+ © 2008-2011 The Apache Software Foundation
+ <br/>
+ Apache Karaf, Karaf, Apache, the Apache feather logo, and the Apache Karaf project logo are trademarks of The Apache Software Foundation.
+ </div>
+ </div>
+ </td>
+ <td id="cell-3-3">
+
+ </td>
+ <td id="cell-3-4">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-4-0" colspan="2">
+
+ </td>
+ <td id="cell-4-1">
+
+ </td>
+ <td id="cell-4-2" colspan="2">
+
+ </td>
+ </tr>
+ </table>
+ </body>
+</html>
\ No newline at end of file
Added: karaf/site/production/manual/latest-2.3.x/developers-guide/writing-tests.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/developers-guide/writing-tests.html?rev=1456813&view=auto
==============================================================================
--- karaf/site/production/manual/latest-2.3.x/developers-guide/writing-tests.html (added)
+++ karaf/site/production/manual/latest-2.3.x/developers-guide/writing-tests.html Fri Mar 15 09:00:51 2013
@@ -0,0 +1,307 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd">
+<html lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+ <meta name="description" content="description goes here"/>
+ <meta name="keywords" content="keywords,goes,here"/>
+ <meta name="author" content="The Apache Karaf Team"/>
+ <link href="../css/style.css" rel="stylesheet" type="text/css"/>
+ <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
+ <title>
+ Apache Karaf 2.3.2-SNAPSHOT Guides
+ </title>
+ </head>
+ <body>
+ <table width="100%" cellpadding="0" cellspacing="0">
+ <tr width="100%">
+ <td id="cell-0-0" colspan="2">
+
+ </td>
+ <td id="cell-0-1">
+
+ </td>
+ <td id="cell-0-2" colspan="2">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-1-0">
+
+ </td>
+ <td id="cell-1-1">
+
+ </td>
+ <td id="cell-1-2">
+ <div style="padding: 5px;">
+ <div id="banner">
+ <table border="0" cellpadding="0" cellspacing="0" width="100%">
+ <tr>
+ <td align="left" class="topbardiv" nowrap="">
+<a href="http://karaf.apache.org/" title="A server side OSGi distribution">
+ <img border="0" src="../images/karaf-logo.png" width="400px"></img>
+</a>
+ </td>
+ <td align="right" nowrap="">
+<a href="http://www.apache.org/" title="The Apache Sofware Foundation">
+ <img border="0" src="../images/asf-logo.png">
+</a>
+ </td>
+ </tr>
+ </table>
+
+ </div>
+ <div id="top-menu">
+ <table border="0" cellpadding="1" cellspacing="0" width="100%">
+ <tr>
+ <td>
+ <div align="left"></div>
+ </td>
+ <td>
+ <div align="right">
+ <p>
+<a href="../index.html" title="Home">Home</a>
+|
+<a href="../users-guide/index.html" title="Users Guide">Users Guide</a>
+|
+<a href="index.html" title="Developers Guide">Developers Guide</a>
+</p>
+
+
+ </div>
+ </td>
+ </tr>
+ </table>
+ </div>
+ </div>
+ </td>
+ <td id="cell-1-3">
+
+ </td>
+ <td id="cell-1-4">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-2-0" colspan="2">
+
+ </td>
+ <td id="cell-2-1">
+ <table>
+ <tr height="100%" valign="top">
+ <td height="100%">
+ <div id="wrapper-menu-page-right">
+ <div id="wrapper-menu-page-top">
+ <div id="wrapper-menu-page-bottom">
+ <div id="menu-page">
+ <h3 id="Homeindex"><a href="../index.html">Home</a></h3><ul style="list-style: square"><li><a href="../overview.html">Overview</a></li><li><a href="../quick-start.html">Quick Start</a></li></ul><h3 id="UsersGuideusersguideindex"><a href="../users-guide/index.html">Users Guide</a></h3><ul style="list-style: square"><li><a href="../users-guide/installation.html">Installing Karaf</a></li><li><a href="../users-guide/directory-structure.html">Directory Structure</a></li><li><a href="../users-guide/start-stop.html">Starting and stopping Karaf</a></li><li><a href="../users-guide/wrapper.html">OS integration</a></li><li><a href="../users-guide/using-console.html">Using the console</a></li><li><a href="../users-guide/remote-console.html">Remote console</a></li><li><a href="../users-guide/web-console.html">Web console</a></li><li><a href="../users-guide/child-instances.html">Child instances</a></li><li><a href="../users-guide/security.html">Security</a></li><li
><a href="../users-guide/failover.html">Failover Deployments</a></li><li><a href="../users-guide/logging-system.html">Logging system</a></li><li><a href="../users-guide/deployer.html">Deployer</a></li><li><a href="../users-guide/provisioning.html">Provisioning</a></li><li><a href="../users-guide/kar.html">KAR archive</a></li><li><a href="../users-guide/configuration.html">Configuration</a></li><li><a href="../users-guide/http.html">HTTP service</a></li><li><a href="../users-guide/web-applications.html">Web applications</a></li><li><a href="../users-guide/jre-tuning.html">JRE tuning</a></li><li><a href="../users-guide/jmx.html">JMX for administration and monitoring</a></li></ul><h3 id="DevelopersGuidedevelopersguideindex"><a href="index.html">Developers Guide</a></h3><ul style="list-style: square"><li><a href="archetypes.html">Maven Archetypes</a></li><li><a href="branding-console.html">Branding the Console</a></li><li><a href="extending-console.html">Extending the Console</a
></li><li><a href="custom-distribution.html">Custom Distribution</a></li><li><a href="security-framework.html">Security Framework</a></li><li><a href="features-maven-plugin.html">Using the features-maven-plugin</a></li><li><a href="debugging.html">Troubleshooting, Debugging and Profiling</a></li><li><a href="connect-console.html">Programmatically connect to the console</a></li><li><a href="writing-tests.html">Writing integration tests</a></li><li><a href="creating-bundles.html">Creating bundles</a></li><li><a href="shell-syntax.html">Shell syntax</a></li><li><a href="github-contributions.html">Github Contributions</a></li></ul><h3 id="Commandscommandscommands"><a href="../commands/commands.html">Commands</a></h3>
+ </div>
+ </div>
+ </div>
+ </div>
+ </td>
+ <td height="100%" width="100%">
+ <div class="wiki-content">
+<h1 id="Writingintegrationtests">Writing integration tests</h1><p>We recommend using <a href="http://team.ops4j.org/wiki/display/paxexam/Pax+Exam">PAX Exam</a> to write integration tests when developing applications using Karaf.</p><p>Starting with Karaf 2.3.0 and 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 such as <a href="http://servicemix.apache.org">Servicemix</a> or <a href="http://geronimo.apache.org">Geronimo</a>.</p><h2 id="Introduction">Introduction</h2><p>To make use of this new framework simply add the following dependencies into your integration tests pom.xml:</p><div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code>
+<!-- Karaf Test Framework Version -->
+<dependency>
+ <groupId>org.apache.karaf.tooling.exam</groupId>
+ <artifactId>org.apache.karaf.tooling.exam.container</artifactId>
+ <version>2.3.2-SNAPSHOT</version>
+ <scope>test</scope>
+</dependency>
+<!-- Pax Exam version you would like to use. At least 2.2.x is required. -->
+<dependency>
+ <groupId>org.ops4j.pax.exam</groupId>
+ <artifactId>pax-exam-junit4</artifactId>
+ <version>2.6.0</version>
+ <scope>test</scope>
+</dependency></code></pre></div><p>As a next step you need to reference the distribution you want to run your tests on. For example, if you want to run your tests on Karaf the following section would be required in the integration tests pom.xml:</p><div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code>
+<dependency>
+ <groupId>org.apache.karaf</groupId>
+ <artifactId>apache-karaf</artifactId>
+ <version>2.3.2-SNAPSHOT</version>
+ <type>zip</type>
+ <scope>test</scope>
+</dependency></code></pre></div><p>If you want to make use of Exams "versionAsInProject" feature you also need to add the following section:</p><div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code>
+<build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.servicemix.tooling</groupId>
+ <artifactId>depends-maven-plugin</artifactId>
+ <version>${plugin.depends.version}</version>
+ <executions>
+ <execution>
+ <id>generate-depends-file</id>
+ <goals>
+ <goal>generate-depends-file</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build></code></pre></div><p>With this done we can start writing our first test case:</p><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code>
+import static junit.framework.Assert.assertTrue;
+import static org.apache.karaf.tooling.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("zip").versionAsInProject())
+ .karafVersion("2.2.4").name("Apache Karaf")};
+ }
+
+ @Test
+ public void test() throws Exception {
+ assertTrue(true);
+ }
+}</code></pre></div><h2 id="Commands">Commands</h2><p>Basically the Pax Exam - Karaf bridge introduced with 3.0 should support all commands you know from Pax Exam 2.x. In addition we've added various additional commands to make your life easier. Those commands are listed and explained in this sub section.</p><p>As a small remark: All of the Options explained here are also accessible via the static methods in the KarafDistributionOption class in the options package automatically on your classpath when you reference the container package.</p><h3 id="KarafDistributionConfigurationOption">KarafDistributionConfigurationOption</h3><p>The framework itself is non of the typical runtimes you define normally in PAXEXAM. 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.</p><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><c
ode>
+new KarafDistributionConfigurationOption(
+ "mvn:org.apache.karaf/apache-karaf/2.2.4/zip", // artifact to unpack and use
+ "karaf", // name; display only
+ "2.2.4") // the karaf version; this one is relevant since the startup script differs between versions</code></pre></div><p>or for Servicemix e.g.</p><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code>
+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</code></pre></div><p>As an alternative you can also use the maven url resolvers. Please keep in mind that this only works starting with karaf-3.0.0 since there will be problems with the pax-url version. In addition, if you want to make use of the versionAsInProject part you also need to define the following maven-plugin in the pom file of your integration tests:</p><div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code>
+...
+<dependency>
+ <groupId>org.apache.karaf</groupId>
+ <artifactId>apache-karaf</artifactId>
+ <type>zip</type>
+ <classifier>bin</classifier>
+ <scope>test</scope>
+</dependency>
+...
+<plugin>
+ <groupId>org.apache.servicemix.tooling</groupId>
+ <artifactId>depends-maven-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>generate-depends-file</id>
+ <goals>
+ <goal>generate-depends-file</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin></code></pre></div><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code>
+@Configuration
+ public Option[] config() {
+ return new Option[]{ karafDistributionConfiguration().frameworkUrl(
+ maven().groupId("org.apache.karaf").artifactId("apache-karaf").type("zip")
+ .classifier("bin").versionAsInProject()) };
+ }</code></pre></div><p>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.</p><h4 id="UnpackDirectory">Unpack Directory</h4><p>Paxexam-Karaf 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:</p><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code>
+@Configuration
+public Option[] config() {
+ return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/2.3.2-SNAPSHOT/zip")
+ .unpackDirectory(new File("target/paxexam/unpack/")) };
+}</code></pre></div><h4 id="UseDeployFolder">Use Deploy Folder</h4><p>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:</p><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code>
+@Configuration
+public Option[] config() {
+ return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/2.3.2-SNAPSHOT/zip")
+ .useDeployFolder(false)) };
+}</code></pre></div><h3 id="KarafDistributionKitConfigurationOption">KarafDistributionKitConfigurationOption</h3><p>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:</p><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code>
+@Configuration
+public Option[] config() {
+ return new Option[]{
+ new KarafDistributionKitConfigurationOption("mvn:org.apache.karaf/apache-karaf/2.3.2-SNAPSHOT/zip",
+ Platform.WINDOWS).executable("bin\\karaf.bat").filesToMakeExecutable("bin\\admin.bat"),
+ new KarafDistributionKitConfigurationOption("mvn:org.apache.karaf/apache-karaf/2.3.2-SNAPSHOT/tar.gz", "karaf",
+ Platform.NIX).executable("bin/karaf").filesToMakeExecutable("bin/admin") };
+}</code></pre></div><h3 id="KarafDistributionConfigurationFilePutOption">KarafDistributionConfigurationFilePutOption</h3><p>The option replaces or adds an option to one of Karaf's configuration files:</p><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code>
+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</code></pre></div><p>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.</p><h3 id="KarafDistributionConfigurationFileExtendOption">KarafDistributionConfigurationFileExtendOption</h3><p>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.</p><p>This option could also be extended in "batch-mode" v
ia 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.</p><h3 id="KarafDistributionConfigurationFileReplacementOption">KarafDistributionConfigurationFileReplacementOption</h3><p>The file replacement option allows you to simply replace a file in you Karaf distribution with a different file:</p><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code>
+new KarafDistributionConfigurationFileReplacementOption("etc/tests.cfg", new File(
+ "src/test/resources/BaseKarafDefaultFrameworkDuplicatedPropertyEntryTestSecondKey"));</code></pre></div><h3 id="ProvisionOption">ProvisionOption</h3><p>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.</p><h3 id="KarafDistributionConfigurationConsoleOption">KarafDistributionConfigurationConsoleOption</h3><p>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:</p><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code>
+@Configuration
+public Option[] config() {
+ return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/2.3.2-SNAPSHOT/zip"),
+ configureConsole().ignoreLocalConsole().startRemoteShell() };
+}</code></pre></div><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code>
+@Configuration
+public Option[] config() {
+ return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/2.3.2-SNAPSHOT/zip"),
+ configureConsole().startLocalConsole(), configureConsole().ignoreRemoteShell() };
+}</code></pre></div><h3 id="VMOption">VMOption</h3><p>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.</p><h3 id="LogLevelOption">LogLevelOption</h3><p>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:</p><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code>
+import static org.openengsb.labs.paxexam.karaf.options.KarafDistributionOption.logLevel;
+...
+@Configuration
+public Option[] config() {
+ return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/2.3.2-SNAPSHOT/zip"),
+ logLevel(LogLevel.TRACE) };
+}</code></pre></div><h3 id="DoNotModifyLogOption">DoNotModifyLogOption</h3><p>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:</p><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code>
+@Configuration
+public Option[] config() {
+ return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/2.3.2-SNAPSHOT/zip"),
+ doNotModifyLogConfiguration() };
+}</code></pre></div><h3 id="KeepRuntimeFolderOption">KeepRuntimeFolderOption</h3><p>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:</p><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code>
+@Configuration
+public Option[] config() {
+ return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/2.3.2-SNAPSHOT/zip"),
+ keepRuntimeFolder() };
+}</code></pre></div><h3 id="FeaturesScannerProvisionOption">FeaturesScannerProvisionOption</h3><p>The FeaturesScannerProvisionOption (e.g. CoreOption.scanFeature()) are directly supported by the Paxexam Karaf Testframework.</p><h3 id="BootDelegationOption">BootDelegationOption</h3><p>The BootDelegationOption as known from PaxExam is also supported added the boot delegation string directly into the correct property files.</p><h3 id="SystemPackageOption">SystemPackageOption</h3><p>The Standard Exam SystemPackageOption is implemented by adding those packages to "org.osgi.framework.system.packages.extra" of the config.properties file.</p><h3 id="BootClasspathLibraryOption">BootClasspathLibraryOption</h3><p>The BootClasspathLibraryOption is honored by copying the urls into the lib directory where they are automatically taken and worked on.</p><h3 id="ExamBundlesStartLevel">ExamBundlesStartLevel</h3><p>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:</p><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code>
+@Configuration
+public Option[] config() {
+ return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/2.3.2-SNAPSHOT/zip"),
+ useOwnExamBundlesStartLevel(4) };
+}</code></pre></div><h2 id="Driver">Driver</h2><p>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.</p><h3 id="JavaRunner">JavaRunner</h3><p>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.</p><h3 id="ScriptRunner">ScriptRunner</h3><p>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.</p>
+ </div>
+ </td>
+ </tr>
+ </table>
+ </td>
+ <td id="cell-2-2" colspan="2">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-3-0">
+
+ </td>
+ <td id="cell-3-1">
+
+ </td>
+ <td id="cell-3-2">
+ <div id="footer">
+ <div id="site-footer">
+ © 2008-2011 The Apache Software Foundation
+ <br/>
+ Apache Karaf, Karaf, Apache, the Apache feather logo, and the Apache Karaf project logo are trademarks of The Apache Software Foundation.
+ </div>
+ </div>
+ </td>
+ <td id="cell-3-3">
+
+ </td>
+ <td id="cell-3-4">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-4-0" colspan="2">
+
+ </td>
+ <td id="cell-4-1">
+
+ </td>
+ <td id="cell-4-2" colspan="2">
+
+ </td>
+ </tr>
+ </table>
+ </body>
+</html>
\ No newline at end of file
Added: karaf/site/production/manual/latest-2.3.x/images/asf-logo.png
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/images/asf-logo.png?rev=1456813&view=auto
==============================================================================
Binary file - no diff available.
Propchange: karaf/site/production/manual/latest-2.3.x/images/asf-logo.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: karaf/site/production/manual/latest-2.3.x/images/bg.png
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/images/bg.png?rev=1456813&view=auto
==============================================================================
Binary file - no diff available.
Propchange: karaf/site/production/manual/latest-2.3.x/images/bg.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: karaf/site/production/manual/latest-2.3.x/images/bg02-blue-left.png
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/images/bg02-blue-left.png?rev=1456813&view=auto
==============================================================================
Binary file - no diff available.
Propchange: karaf/site/production/manual/latest-2.3.x/images/bg02-blue-left.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: karaf/site/production/manual/latest-2.3.x/images/bg02-blue-right.png
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/images/bg02-blue-right.png?rev=1456813&view=auto
==============================================================================
Binary file - no diff available.
Propchange: karaf/site/production/manual/latest-2.3.x/images/bg02-blue-right.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream