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 2014/05/19 17:35:00 UTC
svn commit: r1595933 [3/3] - in /karaf/site/production/manual/latest: ./
commands/ developers-guide/ users-guide/
Modified: karaf/site/production/manual/latest/manual.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/manual.html?rev=1595933&r1=1595932&r2=1595933&view=diff
==============================================================================
--- karaf/site/production/manual/latest/manual.html (original)
+++ karaf/site/production/manual/latest/manual.html Mon May 19 15:34:59 2014
@@ -3528,7 +3528,7 @@ package: com.mycompany.package
[INFO] Finished at: Mon Dec 19 13:30:15 CET 2011
[INFO] Final Memory: 8M/157M
[INFO] ------------------------------------------------------------------------
-</pre><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<br/>includes the remote console login, which uses the <tt>karaf</tt> realm, but which is configured with a dummy login module<br/>by default. These realms can also be used by the NMR, JBI components or the JMX server to authenticate users logging in<br/>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 W
S-Security.</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"><div class="highlight"><pre><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span>
<span class="c"><!--</span>

<span class="c"> Licensed to the Apache Software Foundation (ASF) under one or more</span>
<span class="c"> contributor license agreements. See the NOTICE file distributed with</span>
<span class="c"> this work for additional information regarding copyright ownership.</span>
<span class="c"> The ASF licenses this file to You under the Apache License,
Version 2.0</span>
<span class="c"> (the "License"); you may not use this file except in compliance with</span>
<span class="c"> the License. You may obtain a copy of the License at</span>

<span class="c"> http://www.apache.org/licenses/LICENSE-2.0</span>

<span class="c"> Unless required by applicable law or agreed to in writing, software</span>
<span class="c"> distributed under the License is distributed on an "AS IS" BASIS,</span>
<span class="c"> WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.</span>
<span class="c"> See the License for the specific language governing permissions and</span>
<span class="c"> limitations under the License.</span>

<span class="c">--></span>
<span class="nt"><xs:schema</span> <span class="na">elementFormDefault=</span><span class="s">'qualified'</span>

<span class="na">targetNamespace=</span><span class="s">'http://karaf.apache.org/xmlns/jaas/v1.1.0'</span>
 <span class="na">xmlns:xs=</span><span class="s">'http://www.w3.org/2001/XMLSchema'</span>
 <span class="na">xmlns:bp=</span><span class="s">"http://www.osgi.org/xmlns/blueprint/v1.0.0"</span>
 <span class="na">xmlns:tns=</span><span class="s">'http://karaf.apache.org/xmlns/jaas/v1.1.0'</span><span class="nt">></span>

 <span class="nt"><xs:import</span> <span class="na">namespace=</span><span class="s">"http://www.osgi.org/xmlns/blueprint/v1.0.0"</span><span class="nt">/></span>

 <span class="nt"><xs:element</span> <span class="na">name=</span><span class="s">"config"</span><span class="nt">></span>
 <span class="nt"><xs:complexType></span>
 <span class="nt"><xs:sequence></span>&#
x000A; <span class="nt"><xs:element</span> <span class="na">name=</span><span class="s">"module"</span> <span class="na">minOccurs=</span><span class="s">"0"</span> <span class="na">maxOccurs=</span><span class="s">"unbounded"</span><span class="nt">></span>
 <span class="nt"><xs:complexType</span> <span class="na">mixed=</span><span class="s">"true"</span><span class="nt">></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"name"</span> <span class="na">use=</span><span class="s">"optional"</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"className"</span> <span class="na">use=</span><span class="s">"require
d"</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"flags"</span> <span class="na">default=</span><span class="s">"required"</span><span class="nt">></span>
 <span class="nt"><xs:simpleType></span>
 <span class="nt"><xs:restriction</span> <span class="na">base=</span><span class="s">"xs:NMTOKEN"</span><span class="nt">></span>
 <span class="nt"><xs:enumeration</span> <span class="na">value=</span><span class="s">"required"</span><span class="nt">/></span>
 <span class="nt"><xs:enumeration</span> <span class="na">value=</span><span class="s">"requisite"</span><span class="nt">/
></span>
 <span class="nt"><xs:enumeration</span> <span class="na">value=</span><span class="s">"sufficient"</span><span class="nt">/></span>
 <span class="nt"><xs:enumeration</span> <span class="na">value=</span><span class="s">"optional"</span><span class="nt">/></span>
 <span class="nt"></xs:restriction></span>
 <span class="nt"></xs:simpleType></span>
 <span class="nt"></xs:attribute></span>
 <span class="nt"></xs:complexType></span>
 <span class="nt"></xs:element></span>
 <span class="nt"></xs:sequence></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"name"</span> <span class="na">use=</s
pan><span class="s">"required"</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"rank"</span> <span class="na">use=</span><span class="s">"optional"</span> <span class="na">default=</span><span class="s">"0"</span> <span class="na">type=</span><span class="s">"xs:int"</span><span class="nt">/></span>
 <span class="nt"></xs:complexType></span>
 <span class="nt"></xs:element></span>

 <span class="nt"><xs:element</span> <span class="na">name=</span><span class="s">"keystore"</span><span class="nt">></span>
 <span class="nt"><xs:complexType></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"name"</span> <span cl
ass="na">use=</span><span class="s">"required"</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"rank"</span> <span class="na">use=</span><span class="s">"optional"</span> <span class="na">default=</span><span class="s">"0"</span> <span class="na">type=</span><span class="s">"xs:int"</span><span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"path"</span> <span class="na">use=</span><span class="s">"required"</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"keystorePassword"</span> <span class="na
">use=</span><span class="s">"optional"</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"keyPasswords"</span> <span class="na">use=</span><span class="s">"optional"</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">/></span>
 <span class="nt"></xs:complexType></span>
 <span class="nt"></xs:element></span>

<span class="nt"></xs:schema></span>
</pre></div>
</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"><div class="highlight"><pre><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span> 
<span class
="nt"><blueprint</span> <span class="na">xmlns=</span><span class="s">"http://www.osgi.org/xmlns/blueprint/v1.0.0"</span>
 <span class="na">xmlns:jaas=</span><span class="s">"http://karaf.apache.org/xmlns/jaas/v1.0.0"</span>
 <span class="na">xmlns:ext=</span><span class="s">"http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0"</span><span class="nt">></span>

 <span class="c"><!-- Bean to allow the $[karaf.base] property to be correctly resolved --></span>
 <span class="nt"><ext:property-placeholder</span> <span class="na">placeholder-prefix=</span><span class="s">"$["</span> <span class="na">placeholder-suffix=</span><span class="s">"]"</span><span class="nt">/></span>

 <span class="nt"><type-converters></span>
 <span class="nt"><bean</span> <span class="na">class=</span><span class="s">"org.apache.k
araf.jaas.modules.properties.PropertiesConverter"</span><span class="nt">/></span>
 <span class="nt"></type-converters></span> 

 <span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"myrealm"</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.properties.PropertiesLoginModule"</span> 
 <span class="na">flags=</span><span class="s">"required"</span><span class="nt">></span>
 users = $[karaf.base]/etc/users.properties
 <span class="nt"></jaas:module></span>
 <span class="nt"></jaas:config></span>

<span class="nt"></blueprint></span>
</pre></div>
</div><div class="syntax"><div class="highlight"><pre><span class="nt"><jaas:keystore</span> <span cla
ss="na">xmlns:jaas=</span><span class="s">"http://karaf.apache.org/xmlns/jaas/v1.1.0"</span>
 <span class="na">name=</span><span class="s">"ks"</span>
 <span class="na">rank=</span><span class="s">"1"</span>
 <span class="na">path=</span><span class="s">"classpath:privatestore.jks"</span>
 <span class="na">keystorePassword=</span><span class="s">"keyStorePassword"</span>
 <span class="na">keyPasswords=</span><span class="s">"myalias=myAliasPassword"</span><span class="nt">></span>
<span class="nt"></jaas:keystore></span>
</pre></div>
</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<br/><tt>name</tt> attribute is specified. Additional attributes on the <tt>config</tt> elements are a <tt>rank</tt>, which is an int
eger.<br/>When the LoginContext looks for a realm for authenticating a given user, the realms registered in the OSGi registry are<br/>matched against the required name. If more than one realm is found, the one with the highest rank will be used, thus<br/>allowing the override of some realms with new values. The last attribute is <tt>publish</tt> which can be set to false to<br/>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><br/>attribute must be set to the class name of the login module to use. Note that this login module must be available from<br/>the bundle classloader, so either it has to be defined in the bundle itself, or the needed package needs to be correctly<br/>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<br/>framework performs an authentication, it will use the realm name to find a matching JAAS configuration. If multiple<br/>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<br/>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"><div class="highlight"><pre><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span>
<span class="nt"><blueprint</span> <span class="na">xmlns=</span><span class="s">"http://www.osgi.org/xmlns/blueprint/v1.0.0"</span>
 <span class="na">xmlns:jaas=</span><span class="s">"http://karaf.apache.org/xmlns/jaas/v1.1.0"</span>
 <span class="na">xmlns:ext=</span><span class="s">"http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0"</span><span class="nt">></span>

 <span class="c"><!-- Bean to allow the $[karaf.base] property to be correctly resolved --></span>
 <span class="nt"><ext:property-plac
eholder</span> <span class="na">placeholder-prefix=</span><span class="s">"$["</span> <span class="na">placeholder-suffix=</span><span class="s">"]"</span><span class="nt">/></span>

 <span class="nt"><type-converters></span>
 <span class="nt"><bean</span> <span class="na">class=</span><span class="s">"org.apache.karaf.jaas.modules.properties.PropertiesConverter"</span><span class="nt">/></span>
 <span class="nt"></type-converters></span> 

 <span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"karaf"</span> <span class="na">rank=</span><span class="s">"1"</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.properties.PropertiesLoginModule"</span>
 <span class="na">flags=
</span><span class="s">"required"</span><span class="nt">></span>
 users = $[karaf.base]/etc/users.properties
 ...
 <span class="nt"></jaas:module></span>
 <span class="nt"></jaas:config></span>

<span class="nt"></blueprint></span>
</pre></div>
</div><h2 id="Architecture">Architecture</h2><p>Due to constraints in the JAAS specification, one class has to be available for all bundles.<br/>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<br/>register a JAAS configuration for a given realm. This configuration will be made available into the OSGi registry as a<br/><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> and the OSGi specific Configuration will look for such services.<br/>Then the proxy login module will be able to use the information provided by the realm to actually load the class from<br/>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><p>This login module is the one configured by default. It uses a properties text file to load the users, passwords and roles.</p><div cl
ass="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>
+</pre><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<br/>includes the remote console login, which uses the <tt>karaf</tt> realm, but which is configured with a dummy login module<br/>by default. These realms can also be used by the NMR, JBI components or the JMX server to authenticate users logging in<br/>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 W
S-Security.</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"><div class="highlight"><pre><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span>
<span class="c"><!--</span>

<span class="c"> Licensed to the Apache Software Foundation (ASF) under one or more</span>
<span class="c"> contributor license agreements. See the NOTICE file distributed with</span>
<span class="c"> this work for additional information regarding copyright ownership.</span>
<span class="c"> The ASF licenses this file to You under the Apache License,
Version 2.0</span>
<span class="c"> (the "License"); you may not use this file except in compliance with</span>
<span class="c"> the License. You may obtain a copy of the License at</span>

<span class="c"> http://www.apache.org/licenses/LICENSE-2.0</span>

<span class="c"> Unless required by applicable law or agreed to in writing, software</span>
<span class="c"> distributed under the License is distributed on an "AS IS" BASIS,</span>
<span class="c"> WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.</span>
<span class="c"> See the License for the specific language governing permissions and</span>
<span class="c"> limitations under the License.</span>

<span class="c">--></span>
<span class="nt"><xs:schema</span> <span class="na">elementFormDefault=</span><span class="s">'qualified'</span>

<span class="na">targetNamespace=</span><span class="s">'http://karaf.apache.org/xmlns/jaas/v1.1.0'</span>
 <span class="na">xmlns:xs=</span><span class="s">'http://www.w3.org/2001/XMLSchema'</span>
 <span class="na">xmlns:bp=</span><span class="s">"http://www.osgi.org/xmlns/blueprint/v1.0.0"</span>
 <span class="na">xmlns:tns=</span><span class="s">'http://karaf.apache.org/xmlns/jaas/v1.1.0'</span><span class="nt">></span>

 <span class="nt"><xs:import</span> <span class="na">namespace=</span><span class="s">"http://www.osgi.org/xmlns/blueprint/v1.0.0"</span><span class="nt">/></span>

 <span class="nt"><xs:element</span> <span class="na">name=</span><span class="s">"config"</span><span class="nt">></span>
 <span class="nt"><xs:complexType></span>
 <span class="nt"><xs:sequence></span>&#
x000A; <span class="nt"><xs:element</span> <span class="na">name=</span><span class="s">"module"</span> <span class="na">minOccurs=</span><span class="s">"0"</span> <span class="na">maxOccurs=</span><span class="s">"unbounded"</span><span class="nt">></span>
 <span class="nt"><xs:complexType</span> <span class="na">mixed=</span><span class="s">"true"</span><span class="nt">></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"name"</span> <span class="na">use=</span><span class="s">"optional"</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"className"</span> <span class="na">use=</span><span class="s">"require
d"</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"flags"</span> <span class="na">default=</span><span class="s">"required"</span><span class="nt">></span>
 <span class="nt"><xs:simpleType></span>
 <span class="nt"><xs:restriction</span> <span class="na">base=</span><span class="s">"xs:NMTOKEN"</span><span class="nt">></span>
 <span class="nt"><xs:enumeration</span> <span class="na">value=</span><span class="s">"required"</span><span class="nt">/></span>
 <span class="nt"><xs:enumeration</span> <span class="na">value=</span><span class="s">"requisite"</span><span class="nt">/
></span>
 <span class="nt"><xs:enumeration</span> <span class="na">value=</span><span class="s">"sufficient"</span><span class="nt">/></span>
 <span class="nt"><xs:enumeration</span> <span class="na">value=</span><span class="s">"optional"</span><span class="nt">/></span>
 <span class="nt"></xs:restriction></span>
 <span class="nt"></xs:simpleType></span>
 <span class="nt"></xs:attribute></span>
 <span class="nt"></xs:complexType></span>
 <span class="nt"></xs:element></span>
 <span class="nt"></xs:sequence></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"name"</span> <span class="na">use=</s
pan><span class="s">"required"</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"rank"</span> <span class="na">use=</span><span class="s">"optional"</span> <span class="na">default=</span><span class="s">"0"</span> <span class="na">type=</span><span class="s">"xs:int"</span><span class="nt">/></span>
 <span class="nt"></xs:complexType></span>
 <span class="nt"></xs:element></span>

 <span class="nt"><xs:element</span> <span class="na">name=</span><span class="s">"keystore"</span><span class="nt">></span>
 <span class="nt"><xs:complexType></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"name"</span> <span cl
ass="na">use=</span><span class="s">"required"</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"rank"</span> <span class="na">use=</span><span class="s">"optional"</span> <span class="na">default=</span><span class="s">"0"</span> <span class="na">type=</span><span class="s">"xs:int"</span><span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"path"</span> <span class="na">use=</span><span class="s">"required"</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"keystorePassword"</span> <span class="na
">use=</span><span class="s">"optional"</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"keyPasswords"</span> <span class="na">use=</span><span class="s">"optional"</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">/></span>
 <span class="nt"></xs:complexType></span>
 <span class="nt"></xs:element></span>

<span class="nt"></xs:schema></span>
</pre></div>
</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"><div class="highlight"><pre><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span> 
<span class
="nt"><blueprint</span> <span class="na">xmlns=</span><span class="s">"http://www.osgi.org/xmlns/blueprint/v1.0.0"</span>
 <span class="na">xmlns:jaas=</span><span class="s">"http://karaf.apache.org/xmlns/jaas/v1.0.0"</span>
 <span class="na">xmlns:ext=</span><span class="s">"http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0"</span><span class="nt">></span>

 <span class="nt"><type-converters></span>
 <span class="nt"><bean</span> <span class="na">class=</span><span class="s">"org.apache.karaf.jaas.modules.properties.PropertiesConverter"</span><span class="nt">/></span>
 <span class="nt"></type-converters></span> 

 <span class="c"><!-- Bean to allow the $[karaf.base] property to be correctly resolved --></span>
 <span class="nt"><ext:property-placeholder</span> <span class="na">placeholder-prefix=</
span><span class="s">"$["</span> <span class="na">placeholder-suffix=</span><span class="s">"]"</span><span class="nt">/></span>

 <span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"myrealm"</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.properties.PropertiesLoginModule"</span> 
 <span class="na">flags=</span><span class="s">"required"</span><span class="nt">></span>
 users = $[karaf.base]/etc/users.properties
 <span class="nt"></jaas:module></span>
 <span class="nt"></jaas:config></span>

<span class="nt"></blueprint></span>
</pre></div>
</div><div class="syntax"><div class="highlight"><pre><span class="nt"><jaas:keystore</span> <span cla
ss="na">xmlns:jaas=</span><span class="s">"http://karaf.apache.org/xmlns/jaas/v1.1.0"</span>
 <span class="na">name=</span><span class="s">"ks"</span>
 <span class="na">rank=</span><span class="s">"1"</span>
 <span class="na">path=</span><span class="s">"classpath:privatestore.jks"</span>
 <span class="na">keystorePassword=</span><span class="s">"keyStorePassword"</span>
 <span class="na">keyPasswords=</span><span class="s">"myalias=myAliasPassword"</span><span class="nt">></span>
<span class="nt"></jaas:keystore></span>
</pre></div>
</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<br/><tt>name</tt> attribute is specified. Additional attributes on the <tt>config</tt> elements are a <tt>rank</tt>, which is an int
eger.<br/>When the LoginContext looks for a realm for authenticating a given user, the realms registered in the OSGi registry are<br/>matched against the required name. If more than one realm is found, the one with the highest rank will be used, thus<br/>allowing the override of some realms with new values. The last attribute is <tt>publish</tt> which can be set to false to<br/>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><br/>attribute must be set to the class name of the login module to use. Note that this login module must be available from<br/>the bundle classloader, so either it has to be defined in the bundle itself, or the needed package needs to be correctly<br/>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<br/>framework performs an authentication, it will use the realm name to find a matching JAAS configuration. If multiple<br/>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<br/>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"><div class="highlight"><pre><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span>
<span class="nt"><blueprint</span> <span class="na">xmlns=</span><span class="s">"http://www.osgi.org/xmlns/blueprint/v1.0.0"</span>
 <span class="na">xmlns:jaas=</span><span class="s">"http://karaf.apache.org/xmlns/jaas/v1.1.0"</span>
 <span class="na">xmlns:ext=</span><span class="s">"http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0"</span><span class="nt">></span>

 <span class="c"><!-- Bean to allow the $[karaf.base] property to be correctly resolved --></span>
 <span class="nt"><ext:property-plac
eholder</span> <span class="na">placeholder-prefix=</span><span class="s">"$["</span> <span class="na">placeholder-suffix=</span><span class="s">"]"</span><span class="nt">/></span>

 <span class="nt"><type-converters></span>
 <span class="nt"><bean</span> <span class="na">class=</span><span class="s">"org.apache.karaf.jaas.modules.properties.PropertiesConverter"</span><span class="nt">/></span>
 <span class="nt"></type-converters></span> 

 <span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"karaf"</span> <span class="na">rank=</span><span class="s">"1"</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.properties.PropertiesLoginModule"</span>
 <span class="na">flags=
</span><span class="s">"required"</span><span class="nt">></span>
 users = $[karaf.base]/etc/users.properties
 ...
 <span class="nt"></jaas:module></span>
 <span class="nt"></jaas:config></span>

<span class="nt"></blueprint></span>
</pre></div>
</div><h2 id="Architecture">Architecture</h2><p>Due to constraints in the JAAS specification, one class has to be available for all bundles.<br/>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<br/>register a JAAS configuration for a given realm. This configuration will be made available into the OSGi registry as a<br/><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> and the OSGi specific Configuration will look for such services.<br/>Then the proxy login module will be able to use the information provided by the realm to actually load the class from<br/>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><p>This login module is the one configured by default. It uses a properties text file to load the users, passwords and roles.</p><div cl
ass="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"><div class="highlight"><pre><span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"karaf"</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.properties.PropertiesLoginModule"</span> 
 <span class="na">flags=</span><span class="s">"required"</span><span class="nt">></span>
 users = $[karaf.base]/etc/users.properties
 <span class="nt"></jaas:module></span>
<span class="nt"></jaas:config></span>
</pre></div>
</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><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"> the 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><p>The JDBCLoginModule uses a database to load the users, passwords and roles from a provided data source <em>(normal or XA)</em>.<br/>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"> Description </th></tr><tr><td class="confluenceTd"> <tt>datasource</tt> </td><td class="confluenceTd"> The datasou
rce 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"><div class="highlight"><pre><span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"karaf"</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.jdbc.JDBCLoginModule"</span> 
 <span class="na">flags=</span><span class="s">"required"</span><span class="nt">></spa
n>
 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=?
 <span class="nt"></jaas:module></span>
<span class="nt"></jaas:config></span>
</pre></div>
</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<br/>services via JNDI.</p><div class="syntax"><div class="highlight"><pre><span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"karaf"</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.jdbc.JDBCLoginModule"</span> 
 <span class="na">flags=</span><span cl
ass="s">"required"</span><span class="nt">></span>
 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=?
 <span class="nt"></jaas:module></span>
<span class="nt"></jaas:config></span>
</pre></div>
</div><h3 id="LDAPLoginModule">LDAPLoginModule</h3><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><t
d class="confluenceTd"> <tt>connection.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 pe
rformed only at the first 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 si
mple. </td></tr><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"><div class="highlight"><pre><span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"karaf"</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.ldap.LDAPLoginModule"</span> <span class="na">flags=</span><span class="s">"required&qu
ot;</span><span class="nt">></span>
 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
 <span class="nt"></jaas:module></span>
<span class="nt"></jaas:config></span>
</pre></div>
</div><p>If you wish to use an SSL connection, the following configuration can be used as an example:</p><div class="syntax"><div class="highlight"><pre><span class="nt"><ext:property-placeholder</span> <span class="nt">/></span>

<span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"karaf"</span> <span class="na">rank=</span><span class="s">"1&q
uot;</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.ldap.LDAPLoginModule"</span> <span class="na">flags=</span><span class="s">"required"</span><span class="nt">></span>
 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
 <span class="nt"></jaas:module></span>
<span class="nt"></jaas:config></span>

<span class="nt"><jaas:keystore</span> <span class="
na">name=</span><span class="s">"ks"</span>
 <span class="na">path=</span><span class="s">"file:///${karaf.home}/etc/trusted.ks"</span>
 <span class="na">keystorePassword=</span><span class="s">"secret"</span> <span class="nt">/></span>
</pre></div>
</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="Configuringproper
ties">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"><div class="highlight"><pre><span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"karaf"</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.properties.PropertiesLoginModu
le"</span> 
 <span class="na">flags=</span><span class="s">"required"</span><span class="nt">></span>
 users = $[karaf.base]/etc/users.properties
 encryption.enabled = true
 encryption.algorithm = MD5
 encryption.encoding = hexadecimal
 <span class="nt"></jaas:module></span>
<span class="nt"></jaas:config></span>
</pre></div>
</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 fullfill simple needs. However, in some<br/>cases, you may want to install the <a href="http://www.jasypt.org/">Jasypt</a> library which
provides stronger encryption algorithms<br/>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
Modified: karaf/site/production/manual/latest/users-guide/instances.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/users-guide/instances.html?rev=1595933&r1=1595932&r2=1595933&view=diff
==============================================================================
--- karaf/site/production/manual/latest/users-guide/instances.html (original)
+++ karaf/site/production/manual/latest/users-guide/instances.html Mon May 19 15:34:59 2014
@@ -101,7 +101,7 @@
</td>
<td height="100%" width="100%">
<div class="wiki-content">
-<h1 id="Instances">Instances</h1><p>A instance is a complete new Apache Karaf runtime, isolated from the other ones.</p><p>The purpose is to easily create and manage a new Apache Karaf runtime without installing a complete distribution.<br/>A instance</p><p>A instance is a new instance that you can launch separately from the root one, and deploy applications into.</p><p>An instance does not contain a full copy of the Apache Karaf distribution, but only a set of the configuration files and data folder which contains all the runtime information, logs and temporary files.</p><h2 id="Usingtheinstancecommands">Using the instance commands</h2><p>The <strong>instance</strong> commands allow you to create and manage instances.</p> <h3 id="Creatinginstances">Creating instances</h3><p>You create a new runtime instance by typing <a href="../commands/instance-create.html"><tt>instance:create</tt></a> in the Karaf console.</p><p>As shown in the following example, <tt>instance:create</tt> causes
the runtime to create a new runtime installation in the active runtime's {{instances/<a href="name.html">name</a>} directory. The new instance is a new Karaf instance and is assigned an SSH port number based on an incremental count starting at 8101 and a RMI registry port number based on an incremental count starting at 1099.</p><pre>
+<h1 id="Instances">Instances</h1><p>A instance is a complete new Apache Karaf runtime, isolated from the other ones.</p><p>The purpose is to easily create and manage a new Apache Karaf runtime without installing a complete distribution.</p><p>A instance is a new instance that you can launch separately from the root one, and deploy applications into. It means that each instance is run on a different JVM.</p><p>A instance does not contain a full copy of the Apache Karaf distribution, but only a set of the configuration files and data folder which contains all the runtime information, logs and temporary files.</p><h2 id="Usingtheinstancecommands">Using the instance commands</h2><p>The <strong>instance</strong> commands allow you to create and manage instances.</p> <h3 id="Creatinginstances">Creating instances</h3><p>You create a new runtime instance by typing <a href="../commands/instance-create.html"><tt>instance:create</tt></a> in the Karaf console.</p><p>As shown in the following ex
ample, <tt>instance:create</tt> causes the runtime to create a new runtime installation in the active runtime's {{instances/<a href="name.html">name</a>} directory. The new instance is a new Karaf instance and is assigned an SSH port number based on an incremental count starting at 8101 and a RMI registry port number based on an incremental count starting at 1099.</p><pre>
karaf@root()> instance:create test
</pre><p>The new instance is fresh Apache Karaf instance. It uses default configuration files set, as you install a fresh Karaf distribution.</p><p>You can enable the verbose mode for the <tt>instance:create</tt> command using the <tt>-v</tt> option:</p><pre>
karaf@root()> instance:create -v test
Modified: karaf/site/production/manual/latest/users-guide/obr.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/users-guide/obr.html?rev=1595933&r1=1595932&r2=1595933&view=diff
==============================================================================
--- karaf/site/production/manual/latest/users-guide/obr.html (original)
+++ karaf/site/production/manual/latest/users-guide/obr.html Mon May 19 15:34:59 2014
@@ -160,8 +160,19 @@ Capabilities:
service:{service=org.apache.karaf.wrapper.WrapperService}
package:{package=org.apache.karaf.wrapper, version=3.0.0}
package:{package=org.apache.karaf.wrapper.management, uses:=javax.management, version=3.0.0}
+</pre><p>The <tt>obr:info</tt> command uses the following syntax to identify the bundles: <tt>symbolic_name,version</tt> where <tt>version</tt> is optional.<br/>It means that you have to use the following command to see the info about the wrapper core bundle with version 3.0.0:</p><pre>
+karaf@root()> obr:info org.apache.karaf.wrapper.core,3.0.0
+...
+</pre><p>You can specific multiple bundles separated by space:</p><pre>
+karaf@root()> obr:info org.apache.karaf.wrapper.core,3.0.0 org.apache.karaf.wrapper.command,3.0.0
+...
</pre><h3 id="obrsource"><tt>obr:source</tt></h3><p>In addition of the bundles executable, the OBR service can also store the bundles sources.</p><p>The <tt>obr:source</tt> command check the source URL in the OBR metadata for a given bundle, and download the sources on a target folder:</p><pre>
karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core
+</pre><p>The <tt>obr:source</tt> command uses the following syntax to identify the bundles: <tt>symbolic_name,version</tt> where <tt>version</tt> is optional.<br/>It means that you have to use the following command to download the source of wrapper core bundle with version 3.0.0:</p><pre>
+karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core,3.0.0
+</pre><p>You can specify multiple bundles separated by space:</p><pre>
+karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core,3.0.0 org.apache.karaf.wrapper.command,3.0.0
+...
</pre><h3 id="obrresolve"><tt>obr:resolve</tt></h3><p>The <tt>obr:resolve</tt> command displays the resolution output for a given set of requirements. Actually, it show the bundles providing<br/>the capabilities to match the requirements. It's what the OBR service does when executing <tt>obr:deploy</tt>.</p><p>Optionally, the <tt>obr:resolve</tt> command can deploy the bundles as the <tt>obr:deploy</tt> command does.</p><p>For instance, to know the OBR bundle resolving the <tt>org.apache.karaf.wrapper</tt> package requirement, you can do:</p><pre>
karaf@root()> obr:resolve package=org.apache.karaf.wrapper
Required resource(s):
@@ -209,7 +220,29 @@ Required resource(s):
OPS4J Pax Web - Jetty Bundle (4.0.0.SNAPSHOT)
Deploying...done.
-</pre><p>By default, the bundles are just installed, not started. You can use the <tt>-s</tt> option to start the bundles.</p><h2 id="obrstart"><tt>obr:start</tt></h2><p>The <tt>obr:start</tt> command does the same as <tt>obr:deploy -s</tt> command. It installs the bundle (and all required bundles to<br/>satisfy the requirements) and starts all installed bundles.</p><h2 id="JMXObrMBean">JMX ObrMBean</h2><p>On the JMX layer, Apache Karaf provides a MBean dedicated to the management of the OBR service: the ObrMBean.</p><p>The ObjectName to use is <tt>org.apache.karaf:type=obr,name=*</tt>.</p><h3 id="Attributes">Attributes</h3><p>The <tt>Urls</tt> attribute provides the list of registered OBR repositories URLs.</p><p>The <tt>Bundles</tt> attribute provides a tabular data containing all bundles available on the registered OBR repositories.</p><h3 id="Operations">Operations</h3><ul><li><tt>addUrl(url)</tt> registers the OBR repository using the <tt>url</tt> to the <tt>repository.xml</tt>
.</li><li><tt>removeUrl(url)</tt> removes the OBR repository at the given <tt>url</tt>.</li><li><tt>refreshUrl(url)</tt> refreshes the OBR repository at the given <tt>url</tt>.</li><li><tt>deployBundle(name)</tt> deploys a bundle (and all bundles required to satisfy the requirements) using the OBR service. The bundles are not automatically started.</li><li><tt>deployBundle(name, start, deployOptional)</tt> deploys a bundle (and all bundles required to satisfy the requirements) using the OBR service.<p> If <tt>start</tt> is <tt>true</tt>, the bundles are automatically started. If <tt>deployOptional</tt> is <tt>true</tt>, even the optional requirements will be resolved<br/> by the OBR service (meaning installing more bundles to satisfy the optional requirements).</p><h2 id="ApacheKarafCave">Apache Karaf Cave</h2><p>In addition of being an OBR client, Apache Karaf can act as an OBR repositories server, thanks to Apache Karaf Cave.</p><p>See the <a href="http://karaf.apache.org/index/su
bprojects/cave.html">Apache Karaf Cave sub-project</a> for details.</p></li></ul>
+</pre><p>By default, the bundles are just installed, not started. You can use the <tt>-s</tt> option to start the bundles.</p><p>The <tt>obr:deploy</tt> command uses the following syntax to identify the bundles: <tt>symbolic_name,version</tt> where <tt>version</tt> is optional.<br/>It means that you have to use the following command to deploy the wrapper core bundle with version 3.0.0:</p><pre>
+karaf@root()> obr:deploy org.apache.karaf.wrapper.core,3.0.0
+</pre><p>You can specify multiple bundles separated by space:</p><pre>
+karaf@root()> obr:deploy org.apache.karaf.wrapper.core,3.0.0 org.apache.karaf.wrapper.command,3.0.0
+...
+</pre><h2 id="obrstart"><tt>obr:start</tt></h2><p>The <tt>obr:start</tt> command does the same as <tt>obr:deploy -s</tt> command. It installs the bundle (and all required bundles to<br/>satisfy the requirements) and starts all installed bundles.</p><pre>
+karaf@root()> obr:start org.ops4j.pax.web.samples.helloworld-hs
+Target resource(s):
+-------------------
+ OPS4J Pax Web - Samples - Hello World - HttpService (4.0.0.SNAPSHOT)
+
+Required resource(s):
+---------------------
+ Apache ServiceMix :: Specs :: Activation API 1.4 (2.3.0.SNAPSHOT)
+ OPS4J Pax Web - Jetty Bundle (4.0.0.SNAPSHOT)
+
+Deploying...done.
+</pre><p>The <tt>obr:start</tt> command uses the following syntax to identify the bundles: <tt>symbolic_name,version</tt> where <tt>version</tt> is optional.<br/>It means that you have to use the following command to deploy and start the wrapper core bundle with version 3.0.0:</p><pre>
+karaf@root()> obr:start org.apache.karaf.wrapper.core,3.0.0
+</pre><p>You can specify multiple bundles separated by space:</p><pre>
+karaf@root()> obr:start org.apache.karaf.wrapper.core,3.0.0 org.apache.karaf.wrapper.command,3.0.0
+...
+</pre><h2 id="JMXObrMBean">JMX ObrMBean</h2><p>On the JMX layer, Apache Karaf provides a MBean dedicated to the management of the OBR service: the ObrMBean.</p><p>The ObjectName to use is <tt>org.apache.karaf:type=obr,name=*</tt>.</p><h3 id="Attributes">Attributes</h3><p>The <tt>Urls</tt> attribute provides the list of registered OBR repositories URLs.</p><p>The <tt>Bundles</tt> attribute provides a tabular data containing all bundles available on the registered OBR repositories.</p><h3 id="Operations">Operations</h3><ul><li><tt>addUrl(url)</tt> registers the OBR repository using the <tt>url</tt> to the <tt>repository.xml</tt>.</li><li><tt>removeUrl(url)</tt> removes the OBR repository at the given <tt>url</tt>.</li><li><tt>refreshUrl(url)</tt> refreshes the OBR repository at the given <tt>url</tt>.</li><li><tt>deployBundle(name)</tt> deploys a bundle (and all bundles required to satisfy the requirements) using the OBR service. The bundles are not automatically started.</li><li><tt>
deployBundle(name, start, deployOptional)</tt> deploys a bundle (and all bundles required to satisfy the requirements) using the OBR service.<p> If <tt>start</tt> is <tt>true</tt>, the bundles are automatically started. If <tt>deployOptional</tt> is <tt>true</tt>, even the optional requirements will be resolved<br/> by the OBR service (meaning installing more bundles to satisfy the optional requirements).</p><p>The name to identify a bundle uses the following syntax: <tt>symbolic_name,version</tt> where version is optional.</p><h2 id="ApacheKarafCave">Apache Karaf Cave</h2><p>In addition of being an OBR client, Apache Karaf can act as an OBR repositories server, thanks to Apache Karaf Cave.</p><p>See the <a href="http://karaf.apache.org/index/subprojects/cave.html">Apache Karaf Cave sub-project</a> for details.</p></li></ul>
</div>
</td>
</tr>