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/08/05 17:46:57 UTC
svn commit: r1615948 [7/7] - in /karaf/site/production/manual/latest-2.3.x:
./ commands/ developers-guide/ users-guide/
Modified: karaf/site/production/manual/latest-2.3.x/users-guide/logging-system.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/users-guide/logging-system.html?rev=1615948&r1=1615947&r2=1615948&view=diff
==============================================================================
--- karaf/site/production/manual/latest-2.3.x/users-guide/logging-system.html (original)
+++ karaf/site/production/manual/latest-2.3.x/users-guide/logging-system.html Tue Aug 5 15:46:54 2014
@@ -8,7 +8,7 @@
<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 Guides
+ Apache Karaf 2.3.7-SNAPSHOT Guides
</title>
</head>
<body>
@@ -103,49 +103,13 @@
<div class="wiki-content">
<h1 id="Loggingsystem">Logging system</h1><p>Karaf provides a powerful logging system based on <a href="http://team.ops4j.org/wiki/display/paxlogging/Pax+Logging">OPS4j Pax Logging</a>. </p><p>In addition to being a standard OSGi Log service, it supports the following APIs:</p><ul><li>Apache Commons Logging</li><li>SLF4J</li><li>Apache Log4j</li><li>Java Util Logging</li></ul><p>Karaf also comes with a set of console commands that can be used to display, view and change the log levels.</p><h2 id="Configuration">Configuration</h2><h3 id="Configurationfile">Configuration file</h3><p>The configuration of the logging system uses a <a href="http://logging.apache.org/log4j/1.2/manual.html">standard Log4j configuration file</a> at the following location:</p><pre>
[karaf_install_dir]/etc/org.ops4j.pax.logging.cfg
-</pre><p>You can edit this file at runtime and any change will be reloaded and be effective immediately.</p><h3 id="Configuringtheappenders">Configuring the appenders</h3><p>The default logging configuration defines three appenders:</p><ul><li>the <tt>stdout</tt> console appender is disabled by default. If you plan to run Karaf in server mode only (i.e. with the locale console disabled), you can turn on this appender on by adding it to the list of configured appenders using the <tt>log4j.rootLogger</tt> property</li><li>the <tt>out</tt> appender is the one enabled by default. It logs events to a number of rotating log files of a fixed size. You can easily change the parameters to control the number of files using <tt>maxBackupIndex</tt> and their size size <tt>maxFileSize</tt></li><li>the <tt>sift</tt> appender can be used instead to provide a per-bundle log file. The default configuration uses the bundle symbolic name as the file name to log to</li></ul><h3 id="Changingtheloglev
els">Changing the log levels</h3><p>The default logging configuration sets the logging levels so that the log file will provide enough information to monitor the behavior of the runtime and provide clues about what caused a problem. However, the default configuration will not provide enough information to debug most problems.</p><p>The most useful logger to change when trying to debug an issue with Karaf is the root logger. You will want to set its logging level to <tt>DEBUG</tt> in the <tt>org.ops4j.pax.logging.cfg</tt> file.</p><div class="syntax"><pre name='code' class='brush: text; gutter: false;'><code>
-log4j.rootLogger=DEBUG, out, osgi:VmLogAppender
-...</code></pre></div><p>When debugging a problem in Karaf you may want to change the level of logging information that is displayed on the console. The example below shows how to set the root logger to <tt>DEBUG</tt> but limiting the information displayed on the console to WARN.</p><div class="syntax"><pre name='code' class='brush: text; gutter: false;'><code>
-log4j.rootLogger=DEBUG, out, stdout, osgi:VmLogAppender
-log4j.appender.stdout.threshold=WARN
-...</code></pre></div><h2 id="ConsoleLogCommands">Console Log Commands</h2><p>The log subshell comes with the following commands:</p><ul><li><a href="../commands/log-clear.html"><tt>log:clear</tt></a>: clear the log</li><li><a href="../commands/log-display.html"><tt>log:display</tt></a>: display the last log entries</li><li><a href="../commands/log-display-exception.html"><tt>log:display-exception</tt></a>: display the last exception from the log</li><li><a href="../commands/log-get.html"><tt>log:get</tt></a>: show the log levels</li><li><a href="../commands/log-set.html"><tt>log:set</tt></a>: set the log levels</li><li><a href="../commands/log-tail.html"><tt>log:tail</tt></a>: continuous display of the log entries</li></ul><p>For example, if you want to debug something, you might want to run the following commands:</p><pre>
+</pre><p>You can edit this file at runtime and any change will be reloaded and be effective immediately.</p><h3 id="Configuringtheappenders">Configuring the appenders</h3><p>The default logging configuration defines three appenders:</p><ul><li>the <tt>stdout</tt> console appender is disabled by default. If you plan to run Karaf in server mode only (i.e. with the locale console disabled), you can turn on this appender on by adding it to the list of configured appenders using the <tt>log4j.rootLogger</tt> property</li><li>the <tt>out</tt> appender is the one enabled by default. It logs events to a number of rotating log files of a fixed size. You can easily change the parameters to control the number of files using <tt>maxBackupIndex</tt> and their size size <tt>maxFileSize</tt></li><li>the <tt>sift</tt> appender can be used instead to provide a per-bundle log file. The default configuration uses the bundle symbolic name as the file name to log to</li></ul><h3 id="Changingtheloglev
els">Changing the log levels</h3><p>The default logging configuration sets the logging levels so that the log file will provide enough information to monitor the behavior of the runtime and provide clues about what caused a problem. However, the default configuration will not provide enough information to debug most problems.</p><p>The most useful logger to change when trying to debug an issue with Karaf is the root logger. You will want to set its logging level to <tt>DEBUG</tt> in the <tt>org.ops4j.pax.logging.cfg</tt> file.</p><div class="syntax"><div class="highlight"><pre>log4j.rootLogger=DEBUG, out, osgi:VmLogAppender
...
</pre></div>
</div><p>When debugging a problem in Karaf you may want to change the level of logging information that is displayed on the console. The example below shows how to set the root logger to <tt>DEBUG</tt> but limiting the information displayed on the console to WARN.</p><div class="syntax"><div class="highlight"><pre>log4j.rootL
ogger=DEBUG, out, stdout, osgi:VmLogAppender
log4j.appender.stdout.threshold=WARN
...
</pre></div>
</div><h2 id="ConsoleLogCommands">Console Log Commands</h2><p>The log subshell comes with the following commands:</p><ul><li><a href="../commands/log-clear.html"><tt>log:clear</tt></a>: clear the log</li><li><a href="../commands/log-display.html"><tt>log:display</tt></a>: display the last log entries</li><li><a href="../commands/log-display-exception.html"><tt>log:display-exception</tt></a>: display the last exception from the log</li><li><a href="../commands/log-get.html"><tt>log:get</tt></a>: show the log levels. <tt>log:get ALL</tt> displays the level of all loggers.</li><li><tt>log:list</tt>: is an alias to <tt>log:get ALL</tt>.</li><li><a href="../commands/log-set.html"><tt>log:set</tt></a>: set the log levels. NB: this command doesn't update <tt>etc/org.ops4j.pax.logging.cfg</tt> file. You have to use <tt>config:edit</tt> to do so. It's possible to rel
oad the log level from the configuration file using <tt>log:set DEFAULT</tt>.</li><li><a href="../commands/log-tail.html"><tt>log:tail</tt></a>: continuous display of the log entries</li></ul><p>For example, if you want to debug something, you might want to run the following commands:</p><pre>
> log:set DEBUG
... do something ...
> log:display
</pre><p>Note that the log levels set using the <tt>log:set</tt> commands are not persistent and will be lost upon restart.<br/>To configure those in a persistent way, you should edit the configuration file mentioned above using the config commands or directly using a text editor of your choice.</p><p>The log commands has a separate configure file:</p><pre>
[karaf_install_dir]/etc/org.apache.karaf.log.cfg
-</pre><h2 id="Advancedconfiguration">Advanced configuration</h2><p>The logging backend uses Log4j, but offer a number of additional features.</p><h3 id="Nestedfiltersappendersanderrorhandlers">Nested filters, appenders and error handlers</h3><h4 id="Filters">Filters</h4><p>Appender filters can be added using the following syntax:</p><div class="syntax"><pre name='code' class='brush: text; gutter: false;'><code>
-log4j.appender.[appender-name].filter.[filter-name]=[filter-class]
-log4j.appender.[appender-name].filter.[filter-name].[option]=[value]</code></pre></div><p>Below is a real example:</p><div class="syntax"><pre name='code' class='brush: text; gutter: false;'><code>
-log4j.appender.out.filter.f1=org.apache.log4j.varia.LevelRangeFilter
-log4j.appender.out.filter.f1.LevelMax=FATAL
-log4j.appender.out.filter.f1.LevelMin=DEBUG</code></pre></div><h4 id="Nestedappenders">Nested appenders</h4><p>Nested appenders can be added using the following syntax:</p><div class="syntax"><pre name='code' class='brush: text; gutter: false;'><code>
-log4j.appender.[appender-name].appenders=[comma-separated-list-of-appender-names]</code></pre></div><p>Below is a real example:</p><div class="syntax"><pre name='code' class='brush: text; gutter: false;'><code>
-log4j.appender.async=org.apache.log4j.AsyncAppender
-log4j.appender.async.appenders=jms
-
-log4j.appender.jms=org.apache.log4j.net.JMSAppender
-...</code></pre></div><h4 id="Errorhandlers">Error handlers</h4><p>Error handlers can be added using the following syntax:</p><div class="syntax"><pre name='code' class='brush: text; gutter: false;'><code>
-log4j.appender.[appender-name].errorhandler=[error-handler-class]
-log4j.appender.[appender-name].errorhandler.root-ref=[true|false]
-log4j.appender.[appender-name].errorhandler.logger-ref=[logger-ref]
-log4j.appender.[appender-name].errorhandler.appender-ref=[appender-ref]</code></pre></div><h3 id="OSGispecificMDCattributes">OSGi specific MDC attributes</h3><p>Pax-Logging provides the following attributes by default:</p><ul><li><tt>bundle.id</tt>: the id of the bundle from which the class is loaded</li><li><tt>bundle.name</tt>: the symbolic-name of the bundle</li><li><tt>bundle.version</tt>: the version of the bundle</li></ul><p>An MDC sifting appender is available to split the log events based on MDC attributes. Below is a configuration example for this appender:</p><div class="syntax"><pre name='code' class='brush: text; gutter: false;'><code>
-log4j.appender.sift=org.apache.log4j.sift.MDCSiftingAppender
-log4j.appender.sift.key=bundle.name
-log4j.appender.sift.default=karaf
-log4j.appender.sift.appender=org.apache.log4j.FileAppender
-log4j.appender.sift.appender.layout=org.apache.log4j.PatternLayout
-log4j.appender.sift.appender.layout.ConversionPattern=%d{ABSOLUTE} | %-5.5p | %-16.16t | %-32.32c{1} | %-32.32C %4L | %m%n
-log4j.appender.sift.appender.file=${karaf.data}/log/$\\{bundle.name\\}.log
-log4j.appender.sift.appender.append=true</code></pre></div><h3 id="EnhancedOSGistacktracerenderer">Enhanced OSGi stack trace renderer</h3><p>This renderer is configured by default in Karaf and will give additional informations when printing stack traces.<br/>For each line of the stack trace, it will display OSGi specific informations related to the class on that line: the bundle id, the bundle symbolic name and the bundle version. This information can greatly help diagnosing problems in some cases.<br/>The information is appended at the end of each line in the following format <tt><a href="id:name:version">id:name:version</a></tt> as shown below</p><div class="syntax"><pre name='code' class='brush: text; gutter: false;'><code>
-java.lang.IllegalArgumentException: Command not found: *:foo
- at org.apache.felix.gogo.runtime.shell.Closure.execute(Closure.java:225)[21:org.apache.karaf.shell.console:2.1.0]
- at org.apache.felix.gogo.runtime.shell.Closure.executeStatement(Closure.java:162)[21:org.apache.karaf.shell.console:2.1.0]
- at org.apache.felix.gogo.runtime.shell.Pipe.run(Pipe.java:101)[21:org.apache.karaf.shell.console:2.1.0]
- at org.apache.felix.gogo.runtime.shell.Closure.execute(Closure.java:79)[21:org.apache.karaf.shell.console:2.1.0]
- at org.apache.felix.gogo.runtime.shell.CommandSessionImpl.execute(CommandSessionImpl.java:71)[21:org.apache.karaf.shell.console:2.1.0]
- at org.apache.karaf.shell.console.jline.Console.run(Console.java:169)[21:org.apache.karaf.shell.console:2.1.0]
- at java.lang.Thread.run(Thread.java:637)[:1.6.0_20]</code></pre></div><h3 id="Usingyourownappenders">Using your own appenders</h3><p>If you plan to use your own appenders, you need to create an OSGi bundle and attach it as a fragment to the bundle with a symbolic name of <br/><tt>org.ops4j.pax.logging.pax-logging-service</tt>. This way, the underlying logging system will be able to see and use your appenders.</p><p>So for example you write a log4j appender:<br/>class MyAppender extends AppenderSkeleton {<br/>...<br/>}</p><p>Then you need to package the appender in a jar with a Manifest like this:</p><p>Manifest:<br/>Bundle-SymbolicName: org.mydomain.myappender <br/>Fragment-Host: org.ops4j.pax.logging.pax-logging-service<br/>...</p><p>Copy the new appender fragment into the ${karaf.home}/system directory. Karaf uses a virtual maven repository to access resources in the system<br/>directory, so the jar path should use the standard maven groupId/artifactId/version/ convention,
where the groupId is a directory structure.</p><p>Edit ${karaf.home}/etc/startup.properties and add the new fragment bundle to the list before the pax-logging-service bundle.</p><p>Restart karaf with a clean run to reload the system bundles, and now you can use the appender in your log4j config file like shown in the config<br/>examples above.</p>
+</pre><h2 id="Advancedconfiguration">Advanced configuration</h2><p>The logging backend uses Log4j, but offer a number of additional features.</p><h3 id="Nestedfiltersappendersanderrorhandlers">Nested filters, appenders and error handlers</h3><h4 id="Filters">Filters</h4><p>Appender filters can be added using the following syntax:</p><div class="syntax"><div class="highlight"><pre>log4j.appender.[appender-name].filter.[filter-name]=[filter-class]
log4j.appender.[appender-name].filter.[filter-name].[option]=[value]
</pre></div>
</div><p>Below is a real example:</p><div class="syntax"><div class="highlight"><pre>log4j.appender.out.filter.f1=org.apache.log4j.varia.LevelRangeFilter
log4j.appender.out.filter.f1.LevelMax=FATAL
log4j.appender.out.filter.f1.LevelMin=DEBUG
</pre></div>
</div><h4 id="Nestedappenders">Nested appenders</h4><p>Nested appenders can be added using the following syntax:</p><div class="syntax"><div class="highlight"><p
re>log4j.appender.[appender-name].appenders=[comma-separated-list-of-appender-names]
</pre></div>
</div><p>Below is a real example:</p><div class="syntax"><div class="highlight"><pre>log4j.appender.async=org.apache.log4j.AsyncAppender
log4j.appender.async.appenders=jms

log4j.appender.jms=org.apache.log4j.net.JMSAppender
...
</pre></div>
</div><h4 id="Errorhandlers">Error handlers</h4><p>Error handlers can be added using the following syntax:</p><div class="syntax"><div class="highlight"><pre>log4j.appender.[appender-name].errorhandler=[error-handler-class]
log4j.appender.[appender-name].errorhandler.root-ref=[true|false]
log4j.appender.[appender-name].errorhandler.logger-ref=[logger-ref]
log4j.appender.[appender-name].errorhandler.appender-ref=[appender-ref]
</pre></div>
</div><h3 id="OSGispecificMDCattributes">OSGi specific MDC attributes</h3><p>Pax-Logging provides the following attributes
by default:</p><ul><li><tt>bundle.id</tt>: the id of the bundle from which the class is loaded</li><li><tt>bundle.name</tt>: the symbolic-name of the bundle</li><li><tt>bundle.version</tt>: the version of the bundle</li></ul><p>An MDC sifting appender is available to split the log events based on MDC attributes. Below is a configuration example for this appender:</p><div class="syntax"><div class="highlight"><pre>log4j.appender.sift=org.apache.log4j.sift.MDCSiftingAppender
log4j.appender.sift.key=bundle.name
log4j.appender.sift.default=karaf
log4j.appender.sift.appender=org.apache.log4j.FileAppender
log4j.appender.sift.appender.layout=org.apache.log4j.PatternLayout
log4j.appender.sift.appender.layout.ConversionPattern=%d{ABSOLUTE} | %-5.5p | %-16.16t | %-32.32c{1} | %-32.32C %4L | %m%n
log4j.appender.sift.appender.file=${karaf.data}/log/$\\{bundle.name\\}.log
log4j.appender.sift.appender.append=true
</pre></div>
</div><
h3 id="EnhancedOSGistacktracerenderer">Enhanced OSGi stack trace renderer</h3><p>This renderer is configured by default in Karaf and will give additional informations when printing stack traces.<br/>For each line of the stack trace, it will display OSGi specific informations related to the class on that line: the bundle id, the bundle symbolic name and the bundle version. This information can greatly help diagnosing problems in some cases.<br/>The information is appended at the end of each line in the following format <tt><a href="id:name:version">id:name:version</a></tt> as shown below</p><div class="syntax"><div class="highlight"><pre>java.lang.IllegalArgumentException: Command not found: *:foo
 at org.apache.felix.gogo.runtime.shell.Closure.execute(Closure.java:225)[21:org.apache.karaf.shell.console:2.1.0]
 at org.apache.felix.gogo.runtime.shell.Closure.executeStatement(Closure.java:162)[21:org.apache.karaf.shell.console:2.1.0]
 at org.apache.felix.gogo.run
time.shell.Pipe.run(Pipe.java:101)[21:org.apache.karaf.shell.console:2.1.0]
 at org.apache.felix.gogo.runtime.shell.Closure.execute(Closure.java:79)[21:org.apache.karaf.shell.console:2.1.0]
 at org.apache.felix.gogo.runtime.shell.CommandSessionImpl.execute(CommandSessionImpl.java:71)[21:org.apache.karaf.shell.console:2.1.0]
 at org.apache.karaf.shell.console.jline.Console.run(Console.java:169)[21:org.apache.karaf.shell.console:2.1.0]
 at java.lang.Thread.run(Thread.java:637)[:1.6.0_20]
</pre></div>
</div><h3 id="Usingyourownappenders">Using your own appenders</h3><p>If you plan to use your own appenders, you need to create an OSGi bundle and attach it as a fragment to the bundle with a symbolic name of <br/><tt>org.ops4j.pax.logging.pax-logging-service</tt>. This way, the underlying logging system will be able to see and use your appenders.</p><p>So for example you write a log4j appender:<br/>class MyAppender extends AppenderSkeleton {<br/>
...<br/>}</p><p>Then you need to package the appender in a jar with a Manifest like this:</p><p>Manifest:<br/>Bundle-SymbolicName: org.mydomain.myappender <br/>Fragment-Host: org.ops4j.pax.logging.pax-logging-service<br/>...</p><p>Copy the new appender fragment into the ${karaf.home}/system directory. Karaf uses a virtual maven repository to access resources in the system<br/>directory, so the jar path should use the standard maven groupId/artifactId/version/ convention, where the groupId is a directory structure.</p><p>Edit ${karaf.home}/etc/startup.properties and add the new fragment bundle to the list before the pax-logging-service bundle.</p><p>Restart karaf with a clean run to reload the system bundles, and now you can use the appender in your log4j config file like shown in the config<br/>examples above.</p>
</div>
</td>
</tr>
Modified: karaf/site/production/manual/latest-2.3.x/users-guide/provisioning-schema.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/users-guide/provisioning-schema.html?rev=1615948&r1=1615947&r2=1615948&view=diff
==============================================================================
--- karaf/site/production/manual/latest-2.3.x/users-guide/provisioning-schema.html (original)
+++ karaf/site/production/manual/latest-2.3.x/users-guide/provisioning-schema.html Tue Aug 5 15:46:54 2014
@@ -8,7 +8,7 @@
<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 Guides
+ Apache Karaf 2.3.7-SNAPSHOT Guides
</title>
</head>
<body>
@@ -101,7 +101,7 @@
</td>
<td height="100%" width="100%">
<div class="wiki-content">
-<h1 id="XMLSchemaforprovisioning">XML Schema for provisioning</h1><p>The following schema can be found in Karaf sources. It is also available publicly at url http://karaf.apache.org/xmlns/features/v1.0.0.</p><div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code></code></pre></div>
+<h1 id="XMLSchemaforprovisioning">XML Schema for provisioning</h1><p>The following schema can be found in Karaf sources. It is also available publicly at url http://karaf.apache.org/xmlns/features/v1.0.0.</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>&#x
000A;
<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/features/v1.0.0"</span>
 <span class="na">xmlns:tns=</span><span class="s">"http://karaf.apache.org/xmlns/features/v
1.0.0"</span>
 <span class="na">xmlns:xs=</span><span class="s">"http://www.w3.org/2001/XMLSchema"</span><span class="nt">></span>

 <span class="nt"><xs:annotation></span>
 <span class="nt"><xs:documentation></span><span class="cp"><![CDATA[</span>
<span class="cp">Karaf features mechanism. For documentation please visit the</span>
<span class="cp"><a href="http://karaf.apache.org/">Karaf website</a>.</span>
<span class="cp"> ]]></span><span class="nt"></xs:documentation></span>
 <span class="nt"></xs:annotation></span>

 <span class="nt"><xs:complexType</span> <span class="na">name=</span><span class="s">"features"</span><span class="nt">></span>
 <span class="nt"><xs:annotation></span>
 <span class="nt"><xs:documentation></span><span class="cp"><![CDATA[<
/span>
<span class="cp">Root element of Feature definition. It contains optional attribute for</span>
<span class="cp">designating from which repository this feature should be loaded. The Karaf</span>
<span class="cp">shell will show the repository name when displaying information about the feature.</span>
<span class="cp"> ]]></span><span class="nt"></xs:documentation></span>
 <span class="nt"></xs:annotation></span>
 <span class="nt"><xs:choice</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:element</span> <span class="na">name=</span><span class="s">"repository"</span> <span class="na">type=</span><span class="s">"xs:anyURI"</span><span class="nt">></span>
 <span class="nt">&
lt;xs:annotation></span>
 <span class="nt"><xs:documentation></span><span class="cp"><![CDATA[</span>
<span class="cp">Additional repositories where dependencies are stored.</span>
<span class="cp"> ]]></span><span class="nt"></xs:documentation></span>
 <span class="nt"></xs:annotation></span>
 <span class="nt"></xs:element></span>
 <span class="nt"><xs:element</span> <span class="na">name=</span><span class="s">"feature"</span> <span class="na">type=</span><span class="s">"tns:feature"</span><span class="nt">></span>
 <span class="nt"><xs:annotation></span>
 <span class="nt"><xs:documentation></span><span class="cp"><![CDATA[</span>
<span class="cp">Feature definition.</span>
<span class="cp"> ]]></span><span cl
ass="nt"></xs:documentation></span>
 <span class="nt"></xs:annotation></span>
 <span class="nt"></xs:element></span>
 <span class="nt"></xs:choice></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"name"</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:complexType</span> <span class="na">name=</span><span class="s">"feature"</span><span class="nt">></span>
 <span class="nt"><xs:annotation></span>
 <span class="nt"><xs:documentation></span><span class="cp"><![CDATA[</span>
<span class="cp">Definition of the Feature.</span>
<span class="cp"> ]]></span><span class="nt"></xs:documentation>
</span>
 <span class="nt"></xs:annotation></span>
 <span class="nt"><xs:choice</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:element</span> <span class="na">name=</span><span class="s">"details"</span> <span class="na">minOccurs=</span><span class="s">"0"</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">></span>
 <span class="nt"><xs:annotation></span>
 <span class="nt"><xs:documentation></span><span class="cp"><![CDATA[</span>
<span class="cp">The help shown for this feature when using the feature:info console command.</span>
<span class="cp"> ]]></span>
 <span class="nt">&l
t;/xs:documentation></span>
 <span class="nt"></xs:annotation></span>
 <span class="nt"></xs:element></span>
 <span class="nt"><xs:element</span> <span class="na">name=</span><span class="s">"config"</span> <span class="na">type=</span><span class="s">"tns:config"</span> <span class="nt">/></span>
 <span class="nt"><xs:element</span> <span class="na">name=</span><span class="s">"configfile"</span> <span class="na">type=</span><span class="s">"tns:configFile"</span> <span class="nt">/></span>
 <span class="nt"><xs:element</span> <span class="na">name=</span><span class="s">"feature"</span> <span class="na">type=</span><span class="s">"tns:dependency"</span> <span class="nt">/></span>
 <span class="nt"><xs:element</span> <span class="na">name=</span><span class="s">"bundle&qu
ot;</span> <span class="na">type=</span><span class="s">"tns:bundle"</span> <span class="nt">/></span>
 <span class="nt"></xs:choice></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"name"</span> <span class="na">type=</span><span class="s">"tns:featureName"</span> <span class="na">use=</span><span class="s">"required"</span> <span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"version"</span> <span class="na">type=</span><span class="s">"xs:string"</span> <span class="na">default=</span><span class="s">"0.0.0"</span> <span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"description"</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">"resolver"</span> <span class="na">type=</span><span class="s">"tns:resolver"</span><span class="nt">></span>
 <span class="nt"><xs:annotation></span>
 <span class="nt"><xs:documentation></span><span class="cp"><![CDATA[</span>
<span class="cp">Optional alternative resolver to use for determining the list of bundles to install for a given feature.</span>
<span class="cp"> ]]></span>
 <span class="nt"></xs:documentation></span>
 <span class="nt"></xs:annotation></span>
 <span class="nt"></xs:attribute></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"install"</span> <span class="na">type=</span><span class="s">&q
uot;tns:install"</span><span class="nt">></span>
 <span class="nt"><xs:annotation></span>
 <span class="nt"><xs:documentation></span><span class="cp"><![CDATA[</span>
<span class="cp">If true, marks that the feature should start automatically when placed in the deploy folder.</span>
<span class="cp"> ]]></span>
 <span class="nt"></xs:documentation></span>
 <span class="nt"></xs:annotation></span>
 <span class="nt"></xs:attribute></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"start-level"</span> <span class="na">type=</span><span class="s">"xs:int"</span><span class="nt">></span>
 <span class="nt"><xs:annotation></span>
 <span class="nt"><xs:documentation></span><span class="cp"><
![CDATA[</span>
<span class="cp">Set this attribute to have an OSGi start level for this feature different</span>
<span class="cp">from the default start level defined in Karaf's config.properties.</span>
<span class="cp"> ]]></span>
 <span class="nt"></xs:documentation></span>
 <span class="nt"></xs:annotation></span>
 <span class="nt"></xs:attribute></span>
 <span class="nt"></xs:complexType></span>

 <span class="nt"><xs:complexType</span> <span class="na">name=</span><span class="s">"bundle"</span><span class="nt">></span>
 <span class="nt"><xs:annotation></span>
 <span class="nt"><xs:documentation></span><span class="cp"><![CDATA[</span>
<span class="cp">Deployable element to install.</span>
<span class="cp"> ]]></span><span class="nt"></
xs:documentation></span>
 <span class="nt"></xs:annotation></span>
 <span class="nt"><xs:simpleContent></span>
 <span class="nt"><xs:extension</span> <span class="na">base=</span><span class="s">"xs:anyURI"</span><span class="nt">></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"start-level"</span> <span class="na">type=</span><span class="s">"xs:int"</span><span class="nt">></span>
 <span class="nt"><xs:annotation></span>
 <span class="nt"><xs:documentation></span><span class="cp"><![CDATA[</span>
<span class="cp">Set this attribute to have an OSGi start level for this bundle different</span>
<span class="cp">from the default start level defined in Karaf's config.properties.</span>
<span class="cp">
]]></span>
 <span class="nt"></xs:documentation></span>
 <span class="nt"></xs:annotation></span>
 <span class="nt"></xs:attribute></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"start"</span> <span class="na">type=</span><span class="s">"xs:boolean"</span><span class="nt">></span>
 <span class="nt"><xs:annotation></span>
 <span class="nt"><xs:documentation></span><span class="cp"><![CDATA[</span>
<span class="cp">If false, leaves bundle in resolved start rather than the default active state.</span>
<span class="cp"> ]]></span>
 <span class="nt"></xs:documentation></span>
 <span class="nt"></xs:annotation></span>�
0A; <span class="nt"></xs:attribute></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"dependency"</span> <span class="na">type=</span><span class="s">"xs:boolean"</span><span class="nt">></span>
 <span class="nt"><xs:annotation></span>
 <span class="nt"><xs:documentation></span><span class="cp"><![CDATA[</span>
<span class="cp">Mark bundle as a dependency for the resolver.</span>
<span class="cp"> ]]></span>
 <span class="nt"></xs:documentation></span>
 <span class="nt"></xs:annotation></span>
 <span class="nt"></xs:attribute></span>
 <span class="nt"></xs:extension></span>
 <span class="nt"></xs:simpleContent></span>

<span class="nt"></xs:complexType></span>

 <span class="nt"><xs:complexType</span> <span class="na">name=</span><span class="s">"dependency"</span><span class="nt">></span>
 <span class="nt"><xs:annotation></span>
 <span class="nt"><xs:documentation></span><span class="cp"><![CDATA[</span>
<span class="cp">Dependency of feature.</span>
<span class="cp"> ]]></span><span class="nt"></xs:documentation></span>
 <span class="nt"></xs:annotation></span>
 <span class="nt"><xs:simpleContent></span>
 <span class="nt"><xs:extension</span> <span class="na">base=</span><span class="s">"tns:featureName"</span><span class="nt">></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"version"</span> <span class="na">type=</span><spa
n class="s">"xs:string"</span> <span class="na">default=</span><span class="s">"0.0.0"</span> <span class="nt">/></span>
 <span class="nt"></xs:extension></span>
 <span class="nt"></xs:simpleContent></span>
 <span class="nt"></xs:complexType></span>

 <span class="nt"><xs:complexType</span> <span class="na">name=</span><span class="s">"config"</span><span class="nt">></span>
 <span class="nt"><xs:annotation></span>
 <span class="nt"><xs:documentation></span><span class="cp"><![CDATA[</span>
<span class="cp">Configuration entries which should be created during feature installation. This</span>
<span class="cp">configuration may be used with OSGi Configuration Admin. The element content is</span>
<span class="cp">read in as a properties file.</span>
<span class="cp"> ]]></span><span
class="nt"></xs:documentation></span>
 <span class="nt"></xs:annotation></span>
 <span class="nt"><xs:simpleContent></span>
 <span class="nt"><xs:extension</span> <span class="na">base=</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">"name"</span> <span class="na">type=</span><span class="s">"xs:string"</span> <span class="na">use=</span><span class="s">"required"</span> <span class="nt">/></span>
 <span class="nt"></xs:extension></span>
 <span class="nt"></xs:simpleContent></span>
 <span class="nt"></xs:complexType></span>

 <span class="nt"><xs:complexType</span> <span class="na">name=</span><span class="s">"configFile"</span><span class="nt">></span>&#x
000A; <span class="nt"><xs:annotation></span>
 <span class="nt"><xs:documentation></span><span class="cp"><![CDATA[</span>
<span class="cp">Additional configuration files which should be created during feature installation.</span>
<span class="cp"> ]]></span><span class="nt"></xs:documentation></span>
 <span class="nt"></xs:annotation></span>
 <span class="nt"><xs:simpleContent></span>
 <span class="nt"><xs:extension</span> <span class="na">base=</span><span class="s">"xs:anyURI"</span><span class="nt">></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"finalname"</span> <span class="na">type=</span><span class="s">"xs:string"</span> <span class="na">use=</span><span class="s">"required"</span><span class="nt">></span>

<span class="nt"><xs:annotation></span>
 <span class="nt"><xs:documentation></span><span class="cp"><![CDATA[</span>
<span class="cp">The final destination path and name for the configuration file.</span>
<span class="cp"> ]]></span><span class="nt"></xs:documentation></span>
 <span class="nt"></xs:annotation></span>
 <span class="nt"></xs:attribute></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"override"</span> <span class="na">type=</span><span class="s">"xs:boolean"</span><span class="nt">></span>
 <span class="nt"><xs:annotation></span>
 <span class="nt"><xs:documentation></span><span class="cp"><![CDATA[</span>
<span class="cp">If the configFile already
exists at the finalname location, whether or not to replace it.</span>
<span class="cp"> ]]></span><span class="nt"></xs:documentation></span>
 <span class="nt"></xs:annotation></span>
 <span class="nt"></xs:attribute></span>

 <span class="nt"></xs:extension></span>
 <span class="nt"></xs:simpleContent></span>
 <span class="nt"></xs:complexType></span>

 <span class="nt"><xs:simpleType</span> <span class="na">name=</span><span class="s">"featureName"</span><span class="nt">></span>
 <span class="nt"><xs:annotation></span>
 <span class="nt"><xs:documentation></span><span class="cp"><![CDATA[</span>
<span class="cp">Feature name should be non empty string.</span>
<span class="cp"> ]]></span><span class="nt"></xs
:documentation></span>
 <span class="nt"></xs:annotation></span>
 <span class="nt"><xs:restriction</span> <span class="na">base=</span><span class="s">"xs:string"</span><span class="nt">></span>
 <span class="nt"><xs:minLength</span> <span class="na">value=</span><span class="s">"1"</span> <span class="nt">/></span>
 <span class="nt"></xs:restriction></span>
 <span class="nt"></xs:simpleType></span>

 <span class="nt"><xs:simpleType</span> <span class="na">name=</span><span class="s">"resolver"</span><span class="nt">></span>
 <span class="nt"><xs:annotation></span>
 <span class="nt"><xs:documentation></span><span class="cp"><![CDATA[</span>
<span class="cp">Resolver to use. Karaf will look for OSGi service which have following properties:</span>
<span class="cp">object
Class: org.apache.karaf.features.Resolver</span>
<span class="cp">name: the value</span>
<span class="cp"> ]]></span><span class="nt"></xs:documentation></span>
 <span class="nt"></xs:annotation></span>
 <span class="nt"><xs:restriction</span> <span class="na">base=</span><span class="s">"xs:string"</span><span class="nt">></span>
 <span class="nt"><xs:minLength</span> <span class="na">value=</span><span class="s">"1"</span> <span class="nt">/></span>
 <span class="nt"></xs:restriction></span>
 <span class="nt"></xs:simpleType></span>
 <span class="nt"><xs:simpleType</span> <span class="na">name=</span><span class="s">"install"</span><span class="nt">></span>
 <span class="nt"><xs:annotation></span>
 <span class="nt"><xs:documentation></span><span class="cp"><
![CDATA[</span>
<span class="cp">Installation mode. Can be either manual or auto. Specifies whether the feature should be automatically installed when</span>
<span class="cp">dropped inside the deploy folder. Note: This attribute doesn't affect feature descriptors that are installed from the</span>
<span class="cp">command line or as part of the org.apache.karaf.features.cfg.</span>
<span class="cp"> ]]></span><span class="nt"></xs:documentation></span>
 <span class="nt"></xs:annotation></span>
 <span class="nt"><xs:restriction</span> <span class="na">base=</span><span class="s">"xs:string"</span><span class="nt">></span>
 <span class="nt"><xs:minLength</span> <span class="na">value=</span><span class="s">"1"</span> <span class="nt">/></span>
 <span class="nt"></xs:restriction></span>
 <span class="nt"></xs:simpleTyp
e></span>

 <span class="nt"><xs:element</span> <span class="na">name=</span><span class="s">"features"</span> <span class="na">type=</span><span class="s">"tns:features"</span> <span class="nt">/></span>

<span class="nt"></xs:schema></span>
</pre></div>
</div>
</div>
</td>
</tr>
Modified: karaf/site/production/manual/latest-2.3.x/users-guide/provisioning.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/users-guide/provisioning.html?rev=1615948&r1=1615947&r2=1615948&view=diff
==============================================================================
--- karaf/site/production/manual/latest-2.3.x/users-guide/provisioning.html (original)
+++ karaf/site/production/manual/latest-2.3.x/users-guide/provisioning.html Tue Aug 5 15:46:54 2014
@@ -8,7 +8,7 @@
<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 Guides
+ Apache Karaf 2.3.7-SNAPSHOT Guides
</title>
</head>
<body>
@@ -160,7 +160,7 @@ http://www.example.org/repo@snapshots
<bundle start-level='85' start='false'>mvn:com.mycompany.myproject/myproject-service</bundle>
<bundle start-level='85' start='false'>mvn:com.mycompany.myproject/myproject-camel-routing</bundle>
</feature>
-</pre><div class="warning" style="border: 1px solid #c00;background-color: #fcc;margin: 20px;padding: 0px 6px 0px 6px;"><p>Before Karaf 3.0 the start-level was NOT considered during the feature startup, but only the order in which bundles are defined in your feature.xml. Starting with 3.0 the start-level is no considered correctly. If you need to use the old behavior you can uncomment and change the respectStartLvlDuringFeatureStartup variable in org.apache.karaf.features.xml to false. But please be aware that it will be removed in 4.0 and should therefore be used only temporarily.</p></div><h4 id="Bundledependency">Bundle 'dependency'</h4><p>A bundle can be flagged as being a dependency. Such information can be used by resolvers to compute the full list of bundles to be installed.</p><h3 id="Dependentfeatures">Dependent features</h3><p>Dependent features are useful when a given feature depends on another feature to be installed. Such a dependency can be expressed easily in the fe
ature definition:</p><pre>
+</pre><div class="warning" style="border: 1px solid #c00;background-color: #fcc;margin: 20px;padding: 0px 6px 0px 6px;"><p>On Karaf 2.x, the start-level was not considered during the feature startup, but only the order in which bundles<br/>are defined in your feature.xml.<br/>Starting with Karaf 3.x, the start-level is considered correctly.<br/>If you need to use the old behavior you can uncomment and change the respectStartLvlDuringFeatureStartup variable<br/>in org.apache.karaf.features.xml to false. But please be aware that it will be removed in 4.0 and should therefore<br/>be used only temporarily.</p></div><h4 id="Bundledependency">Bundle 'dependency'</h4><p>A bundle can be flagged as being a dependency. Such information can be used by resolvers to compute the full list of bundles to be installed.</p><h3 id="Dependentfeatures">Dependent features</h3><p>Dependent features are useful when a given feature depends on another feature to be installed. Such a dependency can be expre
ssed easily in the feature definition:</p><pre>
<feature name="jbi">
<feature>nmr</feature>
...
@@ -193,7 +193,7 @@ http://www.example.org/repo@snapshots
</beans:property>
</beans:bean>
</pre><p>In this example, we are using SpringDM with osgi as the primary namespace. Instead of using ctx:context-placeholder we are using the "PropertyPlaceholderConfig"<br/>class. Then we are passing in a beans array and inside of that array is where we set our osgix:cm-properties elements. This element "returns" a properties bean.</p><p>For more information about using the Configuration Admin service in Spring-DM, see the <a href="http://static.springframework.org/osgi/docs/1.2.0-m2/reference/html/compendium.html#compendium:cm:props">Spring-DM documentation</a>.</p><h3 id="Configurationfiles">Configuration files</h3><p>In certain cases it is needed not only to provide configurations for the configuration admin service but to add additional<br/>configuration files e.g. a configuration file for jetty (jetty.xml). It even might be helpful to deploy a configuration<br/>file instead of a configuration for the config admin service since. To achieve this the attribute <tt>finalname</tt>
shows the<br/>final destination of the <tt>configfile</tt>, while the value references the Maven artifact to deploy.</p><pre>
-<configfile finalname="/etc/jetty.xml">mvn:org.apache.karaf/apache-karaf/2.3.2/xml/jettyconfig</configfile>
+<configfile finalname="/etc/jetty.xml">mvn:org.apache.karaf/apache-karaf/2.3.7-SNAPSHOT/xml/jettyconfig</configfile>
</pre><h3 id="Featureresolver">Feature resolver</h3><p>The resolver attribute on a feature can be set to force the use of a given resolver instead of the default resolution process. A resolver will be use to obtain the list of bundles to actually install for a given feature.<br/>The default resolver will simply return the list of bundles provided in the feature description.<br/>The OBR resolver can be installed and used instead of the standard one. In that case, the resolver will use the OBR service<br/>to determine the list of bundles to install (bundles flagged as dependency will only be used as possible candidates to solve<br/>various constraints).</p><h2 id="Commands">Commands</h2><h3 id="Repositorymanagement">Repository management</h3><p>The following commands can be used to manage the list of descriptors known by Karaf. They use URLs pointing to features descriptors. These URLs can use any protocol known to the Apache Karaf, the most common ones being http, file and mvn.</
p><pre>
features:addUrl Add a list of repository URLs to the features service
features:removeUrl Remove a list of repository URLs from the features service
@@ -214,7 +214,7 @@ features:addUrl file:base/features/featu
<bundle>file:base/bundles/spring-web-2.5.6.SEC01.jar</bundle>
</feature>
</features>
-</pre><p>Note: The path is relative to the Apache Karaf installation directory</p><h2 id="Serviceconfiguration">Service configuration</h2><p>A simple configuration file located in <tt>etc/org.apache.karaf.features.cfg</tt> can be modified to customize the behavior when starting the Kernel for the first time.<br/>This configuration file contains two properties:</p><ul><li><tt>featuresBoot</tt>: a comma separated list of features to install at startup</li><li><tt>featuresRepositories</tt>: a comma separated list of feature repositories to load at startup</li></ul><p>This configuration file is of interest if you plan to distribute a customized Karaf distribution having pre-installed features. Such a process is detailed in the <a href="customer-distribution.html">building custom distributions</a> section.</p>
+</pre><p>Note: The path is relative to the Apache Karaf installation directory</p><h2 id="Serviceconfiguration">Service configuration</h2><p>A simple configuration file located in <tt>etc/org.apache.karaf.features.cfg</tt> can be modified to customize the behavior when starting the Kernel for the first time.<br/>This configuration file contains two properties:</p><ul><li><tt>featuresBoot</tt>: a comma separated list of features to install at startup</li><li><tt>featuresRepositories</tt>: a comma separated list of feature repositories to load at startup</li></ul><p>This configuration file is of interest if you plan to distribute a customized Karaf distribution having pre-installed features. Such a process is detailed in the <a href="../developers-guide/custom-distribution.html">building custom distributions</a> section.</p>
</div>
</td>
</tr>
Modified: karaf/site/production/manual/latest-2.3.x/users-guide/remote-console.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/users-guide/remote-console.html?rev=1615948&r1=1615947&r2=1615948&view=diff
==============================================================================
--- karaf/site/production/manual/latest-2.3.x/users-guide/remote-console.html (original)
+++ karaf/site/production/manual/latest-2.3.x/users-guide/remote-console.html Tue Aug 5 15:46:54 2014
@@ -8,7 +8,7 @@
<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 Guides
+ Apache Karaf 2.3.7-SNAPSHOT Guides
</title>
</head>
<body>
Modified: karaf/site/production/manual/latest-2.3.x/users-guide/security.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/users-guide/security.html?rev=1615948&r1=1615947&r2=1615948&view=diff
==============================================================================
--- karaf/site/production/manual/latest-2.3.x/users-guide/security.html (original)
+++ karaf/site/production/manual/latest-2.3.x/users-guide/security.html Tue Aug 5 15:46:54 2014
@@ -8,7 +8,7 @@
<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 Guides
+ Apache Karaf 2.3.7-SNAPSHOT Guides
</title>
</head>
<body>
@@ -101,9 +101,24 @@
</td>
<td height="100%" width="100%">
<div class="wiki-content">
-<h1 id="Security">Security</h1><h2 id="Managingusersandpasswords">Managing users and passwords</h2><p>The default security configuration uses a property file located at <tt>etc/users.properties</tt> to store authorized users and their passwords.</p><p>The default user name is <tt>karaf</tt> and the associated password is <tt>karaf</tt> too. We strongly encourage you to change the default password by editing the above file before moving Karaf into production.</p><p>The users are currently used in three different places in Karaf:</p><ul><li>access to the SSH console</li><li>access to the JMX management layer</li><li>access to the Web console<p>Those three ways all delegate to the same JAAS based security authentication.</p><p>The <tt>users.properties</tt> file contains one or more lines, each line defining a user, its password and the associated roles.</p><pre>
+<h1 id="Security">Security</h1><h2 id="Managingauthenticationbyusersandpasswords">Managing authentication by users and passwords</h2><p>The default security configuration uses a property file located at <tt>etc/users.properties</tt> to store authorized users and their passwords.</p><p>The default user name is <tt>karaf</tt> and the associated password is <tt>karaf</tt> too. We strongly encourage you to change the default password by editing the above file before moving Karaf into production.</p><p>The users are currently used in three different places in Karaf:</p><ul><li>access to the SSH console</li><li>access to the JMX management layer</li><li>access to the Web console<p>Those three ways all delegate to the same JAAS based security authentication.</p><p>The <tt>users.properties</tt> file contains one or more lines, each line defining a user, its password and the associated roles.</p><pre>
user=password[,role][,role]...
-</pre></li></ul><h2 id="Managingroles">Managing roles</h2><p>JAAS roles can be used by various components. The three management layers (SSH, JMX and WebConsole) all use a global role based authorization system. The default role name is configured in the <tt>etc/system.properties</tt> using the <tt>karaf.admin.role</tt> system property and the default value is <tt>admin</tt>. All users authenticating for the management layer must have this role defined.</p><p>The syntax for this value is the following:</p><pre>
+</pre></li></ul><h2 id="Managingauthenticationbykey">Managing authentication by key</h2><p>For the SSH layer, Karaf supports the authentication by key, allowing to login without providing the password.</p><p>The SSH client (so bin/client provided by Karaf itself, or any ssh client like OpenSSH) uses a public/private keys pair that<br/>will identify himself on Karaf SSHD (server side).</p><p>The keys allowed to connect are stored in <tt>etc/keys.properties</tt> file, following the format:</p><pre>
+user=key,role
+</pre><p>By default, Karaf allows a key for the karaf user:</p><pre>
+# karaf=AAAAB3NzaC1kc3MAAACBAP1/U4EddRIpUt9KnC7s5Of2EbdSPO9EAMMeP4C2USZpRV1AIlH7WT2NWPq/xfW6MPbLm1Vs14E7gB00b/JmYLdrmVClpJ+f6AR7ECLCT7up1/63xhv4O1fnxqimFQ8E+4P208UewwI1VBNaFpEy9nXzrith1yrv8iIDGZ3RSAHHAAAAFQCXYFCPFSMLzLKSuYKi64QL8Fgc9QAAAIEA9+GghdabPd7LvKtcNrhXuXmUr7v6OuqC+VdMCz0HgmdRWVeOutRZT+ZxBxCBgLRJFnEj6EwoFhO3zwkyjMim4TwWeotUfI0o4KOuHiuzpnWRbqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog9/hWuWfBpKLZl6Ae1UlZAFMO/7PSSoAAACBAKKSU2PFl/qOLxIwmBZPPIcJshVe7bVUpFvyl3BbJDow8rXfskl8wO63OzP/qLmcJM0+JbcRU/53JjTuyk31drV2qxhIOsLDC9dGCWj47Y7TyhPdXh/0dthTRBy6bqGtRPxGa7gJov1xm/UuYYXPIUR/3x9MAZvZ5xvE0kYXO+rx,admin
+</pre><div class="warning" style="border: 1px solid #c00;background-color: #fcc;margin: 20px;padding: 0px 6px 0px 6px;"><p>For security reason, this key is disabled. We encourage to create the keys pair per client and update the <tt>etc/keys.properties</tt> file.</p></div><p>The easiest way to create key pair is to use OpenSSH.</p><p>You can create a key pair using:</p><pre>
+ssh-keygen -t dsa -f karaf.id_dsa -N karaf
+</pre><p>You have now the public and private keys:</p><pre>
+-rw------- 1 jbonofre jbonofre 771 Jul 25 22:05 karaf.id_dsa
+-rw-r--r-- 1 jbonofre jbonofre 607 Jul 25 22:05 karaf.id_dsa.pub
+</pre><p>You can copy in the content of the <tt>karaf.id_dsa.pub</tt> file in the <tt>etc/keys.properties</tt>:</p><pre>
+karaf=AAAAB3NzaC1kc3MAAACBAJLj9vnEhu3/Q9Cvym2jRDaNWkATgQiHZxmErCmiLRuD5Klfv+HT/+8WoYdnvj0YaXFP80phYhzZ7fbIO2LRFhYhPmGLa9nSeOsQlFuX5A9kY1120yB2kxSIZI0fU2hy1UCgmTxdTQPSYtdWBJyvO/vczoX/8I3FziEfss07Hj1NAAAAFQD1dKEzkt4e7rBPDokPOMZigBh4kwAAAIEAiLnpbGNbKm8SNLUEc/fJFswg4G4VjjngjbPZAjhkYe4+H2uYmynry6V+GOTS2kaFQGZRf9XhSpSwfdxKtx7vCCaoH9bZ6S5Pe0voWmeBhJXi/Sww8f2stpitW2Oq7V7lDdDG81+N/D7/rKDD5PjUyMsVqc1n9wCTmfqmi6XPEw8AAACAHAGwPn/Mv7P9Q9+JZRWtGq+i4pL1zs1OluiStCN9e/Ok96t3gRVKPheQ6IwLacNjC9KkSKrLtsVyepGA+V5j/N+Cmsl6csZilnLvMUTvL/cmHDEEhTIQnPNrDDv+tED2BFqkajQqYLgMWeGVqXsBU6IT66itZlYtrq4v6uDQG/o=,admin
+</pre><p>and specify to the client to use the <tt>karaf.id_dsa</tt> private key:</p><pre>
+bin/client -k ~/karaf.id_dsa
+</pre><p>or to ssh</p><pre>
+ssh -p 8101 -i ~/karaf.id_dsa karaf@localhost
+</pre><h2 id="Managingroles">Managing roles</h2><p>JAAS roles can be used by various components. The three management layers (SSH, JMX and WebConsole) all use a global role based authorization system. The default role name is configured in the <tt>etc/system.properties</tt> using the <tt>karaf.admin.role</tt> system property and the default value is <tt>admin</tt>. All users authenticating for the management layer must have this role defined.</p><p>The syntax for this value is the following:</p><pre>
[classname:]principal
</pre><p>where classname is the class name of the principal object (defaults to org.apache.karaf.jaas.modules.RolePrincipal) and principal is the name of the principal of that class (defaults to admin).</p><p>Note that roles can be changed for a given layer using ConfigAdmin in the following configurations:</p><div class="table-wrap"><table class="confluenceTable"><tr><th class="confluenceTh"> Layer </th><th class="confluenceTh"> PID </th><th class="confluenceTh"> Value </th></tr><tr><td class="confluenceTd"> SSH </td><td class="confluenceTd"> org.apache.karaf.shell </td><td class="confluenceTd"> sshRole </td></tr><tr><td class="confluenceTd"> JMX </td><td class="confluenceTd"> org.apache.karaf.management </td><td class="confluenceTd"> jmxRole </td></tr><tr><td class="confluenceTd"> Web </td><td class="confluenceTd"> org.apache.karaf.webconsole </td><td class="confluenceTd"> role </td></tr></table></div><h2 id="Enablingpasswordencryption">
Enabling password encryption</h2><p>In order to not keep the passwords in plain text, the passwords can be stored encrypted in the configuration file.<br/>This can be easily enabled using the following commands:</p><pre>
# edit config
Modified: karaf/site/production/manual/latest-2.3.x/users-guide/start-stop.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/users-guide/start-stop.html?rev=1615948&r1=1615947&r2=1615948&view=diff
==============================================================================
--- karaf/site/production/manual/latest-2.3.x/users-guide/start-stop.html (original)
+++ karaf/site/production/manual/latest-2.3.x/users-guide/start-stop.html Tue Aug 5 15:46:54 2014
@@ -8,7 +8,7 @@
<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 Guides
+ Apache Karaf 2.3.7-SNAPSHOT Guides
</title>
</head>
<body>
Modified: karaf/site/production/manual/latest-2.3.x/users-guide/using-console.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/users-guide/using-console.html?rev=1615948&r1=1615947&r2=1615948&view=diff
==============================================================================
--- karaf/site/production/manual/latest-2.3.x/users-guide/using-console.html (original)
+++ karaf/site/production/manual/latest-2.3.x/users-guide/using-console.html Tue Aug 5 15:46:54 2014
@@ -8,7 +8,7 @@
<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 Guides
+ Apache Karaf 2.3.7-SNAPSHOT Guides
</title>
</head>
<body>
Modified: karaf/site/production/manual/latest-2.3.x/users-guide/web-applications.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/users-guide/web-applications.html?rev=1615948&r1=1615947&r2=1615948&view=diff
==============================================================================
--- karaf/site/production/manual/latest-2.3.x/users-guide/web-applications.html (original)
+++ karaf/site/production/manual/latest-2.3.x/users-guide/web-applications.html Tue Aug 5 15:46:54 2014
@@ -8,7 +8,7 @@
<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 Guides
+ Apache Karaf 2.3.7-SNAPSHOT Guides
</title>
</head>
<body>
Modified: karaf/site/production/manual/latest-2.3.x/users-guide/web-console.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/users-guide/web-console.html?rev=1615948&r1=1615947&r2=1615948&view=diff
==============================================================================
--- karaf/site/production/manual/latest-2.3.x/users-guide/web-console.html (original)
+++ karaf/site/production/manual/latest-2.3.x/users-guide/web-console.html Tue Aug 5 15:46:54 2014
@@ -8,7 +8,7 @@
<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 Guides
+ Apache Karaf 2.3.7-SNAPSHOT Guides
</title>
</head>
<body>
Modified: karaf/site/production/manual/latest-2.3.x/users-guide/wrapper.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/users-guide/wrapper.html?rev=1615948&r1=1615947&r2=1615948&view=diff
==============================================================================
--- karaf/site/production/manual/latest-2.3.x/users-guide/wrapper.html (original)
+++ karaf/site/production/manual/latest-2.3.x/users-guide/wrapper.html Tue Aug 5 15:46:54 2014
@@ -8,7 +8,7 @@
<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 Guides
+ Apache Karaf 2.3.7-SNAPSHOT Guides
</title>
</head>
<body>
@@ -183,12 +183,7 @@ On Ubuntu/Debian Systems:
To uninstall the service :
$ rm /etc/init.d/KARAF-service
-
-h2. Configuration Hints
-
-If you need to append parameters to the "java" invoke (like memory configurations) you add those in the KARAF-wrapper file using "wrapper.java.additional.n=PARAMETER" where "n" is the number of the additional config (typically you simply look for the last entry and use n+1) and PARAMTER is any JVM parameter you would like to append, such as "-XX:MaxPermSize=1024m".
-
-</pre>
+</pre><h2 id="ConfigurationHints">Configuration Hints</h2><p>By default, the wrapper sets the JAVA_HOME in etc/karaf-wrapper.conf file. However, the bin/karaf-service script uses java. If required, you have to define the JAVA_HOME in this bin/karaf-service script.</p><p>If you need to append parameters to the "java" invoke (like memory configurations) you add those in the KARAF-wrapper file using "wrapper.java.additional.n=PARAMETER" where "n" is the number of the additional config (typically you simply look for the last entry and use n+1) and PARAMETER is any JVM parameter you would like to append, such as "-XX:MaxPermSize=1024m".</p>
</div>
</td>
</tr>