felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Felix > Karaf Users' Guide in one page
Date Mon, 12 Oct 2009 14:49:00 GMT
<html>
<head>
    <base href="http://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1519/1/1/_/styles/combined.css?spaceKey=FELIX&amp;forWysiwyg=true" type="text/css">
    </head>
<body style="background-color: white" bgcolor="white">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
     <h2><a href="http://cwiki.apache.org/confluence/display/FELIX/Karaf+Users%27+Guide+in+one+page">Karaf Users' Guide in one page</a></h2>
     <h4>Page <b>edited</b> by             <a href="http://cwiki.apache.org/confluence/display/~gnodet">Guillaume Nodet</a>
    </h4>
     
          <br/>
     <div class="notificationGreySide">
         <p><div align="center"><img src="/confluence/download/attachments/4587566/karafGuide.png" border="0" /></div>
<br clear="all" />
<br clear="all" />
<br clear="all" />
<br clear="all" />
<br clear="all" />
<br clear="all" />
<br clear="all" />
<br clear="all" />
<br clear="all" />
<br clear="all" />
<br clear="all" />
<br clear="all" />
<br clear="all" />
<br clear="all" />
Copyright 2009 The Apache Software Foundation</p>

<div>
<ul>
    <li><a href='#KarafUsers%27Guideinonepage-1.Quickstart'>1. Quick start</a></li>
<ul>
    <li><a href='#KarafUsers%27Guideinonepage-Background'>Background</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Gettingthesoftware'>Getting the software</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Starttheserver'>Start the server</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Deployasampleapplication'>Deploy a sample application</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-StoppingKaraf'>Stopping Karaf</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Summary'>Summary</a></li>
</ul>
    <li><a href='#KarafUsers%27Guideinonepage-1.1QuickStart%28Source%29'>1.1 Quick Start (Source)</a></li>
<ul>
    <li><a href='#KarafUsers%27Guideinonepage-Background'>Background</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Gettingthesoftware'>Getting the software</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Starttheserver'>Start the server</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Deployasampleapplication'>Deploy a sample application</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-StoppingKaraf'>Stopping Karaf</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Summary'>Summary</a></li>
</ul>
    <li><a href='#KarafUsers%27Guideinonepage-2.Overview'>2. Overview</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-3.Installation'>3. Installation</a></li>
<ul>
    <li><a href='#KarafUsers%27Guideinonepage-PreInstallationRequirements'>Pre-Installation Requirements</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-InstallationProcedureforWindows'>Installation Procedure for Windows</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-InstallationProcedureForUnix'>Installation Procedure For Unix</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-StartingKaraf'>Starting Karaf</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-TestingtheInstallation'>Testing the Installation</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-StoppingKaraf'>Stopping Karaf</a></li>
</ul>
    <li><a href='#KarafUsers%27Guideinonepage-4.UnderstandingKaraf'>4. Understanding Karaf</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-4.1.ConsoleandCommands'>4.1. Console and Commands</a></li>
<ul>
    <li><a href='#KarafUsers%27Guideinonepage-Overview'>Overview</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Adminshell'>Admin shell</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Configshell'>Config shell</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Featuresshell'>Features shell</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Logshell'>Log shell</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-OBRshell'>OBR shell</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-OSGishell'>OSGi shell</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Packageshell'>Package shell</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Shellshell'>Shell shell</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-SSHshell'>SSH shell</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Wrappershell'>Wrapper shell</a></li>
</ul>
    <li><a href='#KarafUsers%27Guideinonepage-4.2.RemoteConsole'>4.2. Remote Console</a></li>
<ul>
    <li><a href='#KarafUsers%27Guideinonepage-Launchoptions'>Launch options</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Usingtheclientjar'>Using the client jar</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-UsinganSSHclient'>Using an SSH client</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-UsinganotherKernelinstance'>Using another Kernel instance</a></li>
</ul>
    <li><a href='#KarafUsers%27Guideinonepage-4.3.Loggingsystem'>4.3. Logging system</a></li>
<ul>
    <li><a href='#KarafUsers%27Guideinonepage-Configuration'>Configuration</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Commands'>Commands</a></li>
</ul>
    <li><a href='#KarafUsers%27Guideinonepage-4.4.Deployer'>4.4. Deployer</a></li>
<ul>
    <li><a href='#KarafUsers%27Guideinonepage-Springdeployer'>Spring deployer</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Featuresdeployer'>Features deployer</a></li>
</ul>
    <li><a href='#KarafUsers%27Guideinonepage-4.5.Securityframework'>4.5. Security framework</a></li>
<ul>
    <li><a href='#KarafUsers%27Guideinonepage-Overview'>Overview</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Schema'>Schema</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Architecture'>Architecture</a></li>
</ul>
    <li><a href='#KarafUsers%27Guideinonepage-4.6.Provisioning'>4.6. Provisioning</a></li>
<ul>
    <li><a href='#KarafUsers%27Guideinonepage-Repositories'>Repositories</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Commands'>Commands</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Serviceconfiguration'>Service configuration</a></li>
</ul>
    <li><a href='#KarafUsers%27Guideinonepage-4.7.Administration'>4.7. Administration</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-5.UsingKaraf'>5. Using Karaf</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-5.1.Troubleshooting%2CDebuggingandProfiling'>5.1. Troubleshooting, Debugging and Profiling</a></li>
<ul>
    <li><a href='#KarafUsers%27Guideinonepage-Troubleshooting'>Troubleshooting</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Debugging'>Debugging</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Profiling'>Profiling</a></li>
</ul>
    <li><a href='#KarafUsers%27Guideinonepage-5.2.Developpingapplications'>5.2. Developping applications</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-5.3.Creatingbundlesforthirdpartydependencies'>5.3. Creating bundles for third party dependencies</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-6.Advanceduses'>6. Advanced uses</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-6.1.Extendingtheconsole'>6.1. Extending the console</a></li>
<ul>
    <li><a href='#KarafUsers%27Guideinonepage-Createtheprojectusingmaven'>Create the project using maven</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Dependencies'>Dependencies</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-AddtheSpringMilestoneRepository'>Add the Spring Milestone Repository</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-LoadingtheprojectinyourIDE'>Loading the project in your IDE</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Creatingabasiccommandclass'>Creating a basic command class</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Creatingtheassociatedspringconfigurationfiles'>Creating the associated spring configuration files</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-Compilingthejar'>Compiling the jar</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-TurningthejarintoanOSGibundle'>Turning the jar into an OSGi bundle</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-TestinServiceMixKernel'>Test in ServiceMix Kernel</a></li>
</ul>
    <li><a href='#KarafUsers%27Guideinonepage-6.2.Buildingcustomdistributions'>6.2. Building custom distributions</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-6.3.Programmaticallyconnecttotheconsole'>6.3. Programmatically connect to the console</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-6.4.EmbeddingKaraf'>6.4. Embedding Karaf</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-6.5.Deployingsecurityproviders'>6.5. Deploying security providers</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-7.OptionalFeatures'>7. Optional Features</a></li>
    <li><a href='#KarafUsers%27Guideinonepage-7.1.EnablingColorizedConsoleOutputOnWindows'>7.1. Enabling Colorized Console Output On Windows</a></li>
</ul></div>

<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td width='33%' class='ScrollbarPrevName'>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide">Karaf Users' Guide</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/2.+Overview">2. Overview</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/2.+Overview"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-1.Quickstart"></a>1. Quick start</h1>

<p>If you are in a hurry to have Apache Felix Karaf up and running right away, this section will provide you with some basic steps for downloading, building (when needed) and running the server in no time. This is clearly not a complete guide so you may want to check other sections of this guide for further information.</p>

<p>All you need is 5 to 10 minutes and to follow these basic steps.</p>
<ul>
	<li><a href="#KarafUsers%27Guideinonepage-Background">Background</a></li>
	<li><a href="#KarafUsers%27Guideinonepage-Gettingthesoftware">Getting the software</a></li>
	<li><a href="#KarafUsers%27Guideinonepage-Starttheserver">Start the server</a></li>
	<li><a href="#KarafUsers%27Guideinonepage-Deployasampleapplication">Deploy a sample application</a></li>
</ul>


<h2><a name="KarafUsers%27Guideinonepage-Background"></a>Background</h2>

<p>Apache Felix Karaf is a small and lightweight OSGi based runtime.  This provides a small lightweight container onto which various bundles can be deployed.</p>
<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><p>Apache Felix Karaf started life as the <a href="http://servicemix.apache.org" rel="nofollow">Apache ServiceMix </a> kernel.<br/>
Don't be surprised by any transitional references which remain. </p></td></tr></table></div>
<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>

<h2><a name="KarafUsers%27Guideinonepage-Gettingthesoftware"></a>Getting the software</h2>

<p>At this time you have one option to get the software. The fastest and easiest way is to get the binary directly from the Apache site. Since this article is intended to help you to have Apache Felix Karaf up and running in the fastest way only the binary download will be covered at this time.</p>

<h3><a name="KarafUsers%27Guideinonepage-Prerequisites"></a>Prerequisites</h3>

<p>Although this installation path is the fastest one, still you will need to install some software before installing Karaf.</p>

<p>Karaf requires a Java 5 environment to run. Refer to <a href="http://java.sun.com" rel="nofollow">http://java.sun.com</a> for details on how to download and install J2SE 1.5 or greater.</p>

<h3><a name="KarafUsers%27Guideinonepage-Downloadbinaries"></a>Download binaries</h3>

<p>Depending on the platform you plan to install and run Karaf you will select the appropriate installation image. Open a Web browser and access the following URL, there you will find the available packages for download (binaries and source code).</p>

<p><a href="http://felix.apache.org/site/downloads.cgi" rel="nofollow">http://felix.apache.org/site/downloads.cgi</a></p>

<p>Select the file compression format compatible with your system (zip for windows, tar.gz for unixes) by clicking directly on the link, download it and expand the binary to your hard drive in a new directory; for example in z:\servicemix - from now on this directory will be referenced as &lt;KARAF_HOME&gt;. Please remember the restrictions concerning illegal characters in Java paths, e.g. &#33;, % etc.</p>

<p>The installation of Karaf is as simple as uncompressing the .zip or .tar files. The next step is to start the server.</p>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>

<h2><a name="KarafUsers%27Guideinonepage-Starttheserver"></a>Start the server</h2>

<p>With Karaf already installed, open a command line console and change directory to &lt;SERVICEMIX_HOME&gt;. To start the server, run the following command in Windows:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
bin\karaf.bat
</pre>
</div></div>
<p>respectively on Unix:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
bin/karaf
</pre>
</div></div>
<p>You should see the following informations on the command line console:</p>
<div class="panel" style="background-color: #000000;border-width: 1px;"><div class="panelContent" style="background-color: #000000;">
<p><font color="#00ffff"><pre>        __ __                  ____      
       / //_/____ __________ _/ __/      
      / ,&lt;  / __ `/ ___/ __ `/ /_        
     / /| |/ /_/ / /  / /_/ / __/        
    /_/ |_|\__,_/_/   \__,_/_/         

</pre></font><font color="#c0c0c0"><pre>  Apache Felix Karaf (1.0.0)

Hit '&lt;tab&gt;' for a list of available commands
and '[cmd] --help' for help on a specific command.

karaf@root&gt; 
</pre></font></p>
</div></div>
<p>You can now run your first command.  Simply type the <tt>&lt;tab&gt;</tt> key in the console.</p>
<div class="panel" style="background-color: #000000;border-width: 1px;"><div class="panelContent" style="background-color: #000000;">
<p><font color="#c0c0c0">
<pre>karaf@root&gt; 

admin:change-port        admin:connect            admin:create             admin:destroy            admin:list               admin:start
admin:stop               config:cancel            config:edit              config:list              config:propappend        config:propdel
config:proplist          config:propset           config:update            features:addUrl          features:install         features:list
features:listUrl         features:refreshUrl      features:removeUrl       features:uninstall       log:display              log:display-exception
log:get                  log:set                  osgi:bundle-level        osgi:headers             osgi:install             osgi:list
osgi:ls                  osgi:refresh             osgi:resolve             osgi:restart             osgi:shutdown            osgi:start
osgi:start-level         osgi:stop                osgi:uninstall           osgi:update              packages:exports         packages:imports
shell:cat                shell:echo               shell:exec               shell:grep               shell:info               shell:java
shell:printf             shell:sleep              shell:sort               shell:tac                ssh:ssh                  ssh:sshd
karaf@root&gt; 
</pre></font></p>
</div></div>
<p>You can then grab more specific help for a given command using the <tt>--help</tt> option for this command:</p>
<div class="panel" style="background-color: #000000;border-width: 1px;"><div class="panelContent" style="background-color: #000000;">
<p><font color="#c0c0c0">
<pre>karaf@root&gt; admin:create --help
DESCRIPTION
	admin:create

	Create a new instance.

SYNTAX
	admin:create [options] [VAL]

ARGUMENTS
	VAL	Name of the new Karaf instance

OPTIONS
	-p, --port
		Port number for remote shell connection
	--help
		Display this help message
	-l, --location
		Location of the new instance on the file system

karaf@root&gt; 
</pre></font></p>
</div></div>
<p>Note that the console supports tab completion, so you just need to enter <tt>ad &lt;tab&gt; cr &lt;tab&gt;</tt> instead of <tt>admin:create</tt>.<br/>
<a href="#KarafUsers%27Guideinonepage-top">top</a></p>

<h2><a name="KarafUsers%27Guideinonepage-Deployasampleapplication"></a>Deploy a sample application</h2>

<p>While you will learn in the remainder of this guide how to use and leverage Apache Felix Karaf, we will just use the pre-built packaging for now.</p>

<p>In the console, run the following commands:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
features:install spring-dm
osgi:install -s mvn:org.apache.geronimo.specs/geronimo-activation_1.1_spec/1.0.2
osgi:install -s mvn:org.apache.servicemix.specs/org.apache.servicemix.specs.stax-api-1.0/1.1.0
osgi:install -s mvn:org.apache.servicemix.specs/org.apache.servicemix.specs.jaxb-api-2.1/1.1.0
osgi:install -s mvn:org.apache.servicemix.bundles/org.apache.servicemix.bundles.jaxb-impl/2.1.6_1
osgi:install -s mvn:org.apache.camel/camel-core/1.4.0
osgi:install -s mvn:org.springframework/spring-tx/2.5.6.SEC01
osgi:install -s mvn:org.apache.camel/camel-spring/1.4.0
osgi:install -s mvn:org.apache.camel/camel-osgi/1.4.0
osgi:install -s mvn:org.apache.camel/camel-example-osgi/1.4.0
</pre>
</div></div>
<p>This commands will download, install and start the specified jars.</p>

<p>The example installed is using <a href="http://activemq.apache.org/camel" rel="nofollow">Camel</a> to start a timer every 2 seconds and output a message on the console.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&gt;&gt;&gt;&gt; MyTransform set body:  Wed Jan 02 23:34:19 CET 2008
&gt;&gt;&gt;&gt; MyTransform set body:  Wed Jan 02 23:34:21 CET 2008
</pre>
</div></div>

<h3><a name="KarafUsers%27Guideinonepage-Stoppinganduninstallingthesampleapplication"></a>Stopping and uninstalling the sample application</h3>

<p>To stop this demo, run the following command:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
osgi:list | grep example
</pre>
</div></div>
<p>In the output, locate the line containing <tt>camel-example-osgi</tt> and note the id of the bundle in the first column.  Then launch the following command:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
osgi:stop [id]
</pre>
</div></div>
<p>If you wish, you can start again the sample by using the following command:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
osgi:start [id]
</pre>
</div></div>
<p>To uninstall the demo, run the following command:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
osgi:uninstall [id]
</pre>
</div></div>

<h3><a name="KarafUsers%27Guideinonepage-CommonProblems"></a>Common Problems</h3>

<ol>
	<li>Launching Karaf can result in a deadlock in Felix during module dependency resolution.  This is often a result of sending a SIGINT (control-C) to the process when it will not cleanly exit.  This can corrupt the caches and cause startup problems in the very next launch. It is fixed by emptying the component cache:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
rm -rf data/cache/*
</pre>
</div></div></li>
</ol>


<h2><a name="KarafUsers%27Guideinonepage-StoppingKaraf"></a>Stopping Karaf</h2>

<p>To stop Karaf from the console, enter <tt>^D</tt> in the console:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
^D
</pre>
</div></div>
<p>Alternatively, you can also run the following command:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
osgi:shutdown
</pre>
</div></div>

<h2><a name="KarafUsers%27Guideinonepage-Summary"></a>Summary</h2>

<p>This document showed you how simple it is to have Apache Felix Karaf up and running. The overall time for getting the server running should be less than five minutes if you have the prerequisite (Java 1.5) already installed. Additionally, this article also showed you how to deploy and test a simple Apache Camel application in less than five minutes.</p>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td width='33%' class='ScrollbarPrevName'>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide">Karaf Users' Guide</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/2.+Overview">2. Overview</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/2.+Overview"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td width='33%' class='ScrollbarPrevName'>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/1.+Quick+Start"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/1.+Quick+Start">1. Quick Start</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;</td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-1.1QuickStart%28Source%29"></a>1.1 Quick Start (Source)</h1>

<p>If you are in a hurry to have Apache Felix Karaf up and running right away, this section will provide you with some basic steps for checking out, building and running the server in no time. This is clearly not a complete guide so you may want to check other sections of this guide for further information.</p>

<p>All you need is 15 minutes and to follow these basic steps.</p>
<ul>
	<li><a href="#KarafUsers%27Guideinonepage-Background">Background</a></li>
	<li><a href="#KarafUsers%27Guideinonepage-Gettingthesoftware">Getting the software</a></li>
	<li><a href="#KarafUsers%27Guideinonepage-Starttheserver">Start the server</a></li>
	<li><a href="#KarafUsers%27Guideinonepage-Deployasampleapplication">Deploy a sample application</a></li>
</ul>


<h2><a name="KarafUsers%27Guideinonepage-Background"></a>Background</h2>

<p>Apache Felix Karaf is a small and lightweight OSGi based runtime.  This provides a small lightweight container onto which various bundles can be deployed.</p>
<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><p>Apache Felix Karaf started life as the <a href="http://servicemix.apache.org" rel="nofollow">Apache ServiceMix </a> kernel.<br/>
Don't be surprised by any transitional references which remain. </p></td></tr></table></div>
<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>

<h2><a name="KarafUsers%27Guideinonepage-Gettingthesoftware"></a>Getting the software</h2>

<p>This document describes how to build the server from the latest Karaf source. </p>

<h3><a name="KarafUsers%27Guideinonepage-Prerequisites"></a>Prerequisites</h3>

<p>Although this installation path is the fastest one, still you will need to install some software before installing Karaf.</p>

<p>Karaf requires a Java 5 environment to run. Refer to <a href="http://java.sun.com" rel="nofollow">http://java.sun.com</a> for details on how to download and install J2SE 1.5 or greater.</p>

<p><a href="http://subversion.tigris.org" rel="nofollow">Subversion </a> is required to checkout the source.</p>

<p><a href="http://maven.apache.org" rel="nofollow">Maven 2</a> is required to build Karaf.</p>

<h3><a name="KarafUsers%27Guideinonepage-CheckoutSource"></a>Checkout Source</h3>

<p>The Karaf source is found at <a href="http://svn.apache.org/repos/asf/felix/trunk/karaf/" rel="nofollow">http://svn.apache.org/repos/asf/felix/trunk/karaf/</a>. To check out with a command line client:</p>

<div class="code panel" style="border-style: solid;border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
$ svn co http:<span class="code-comment">//svn.apache.org/repos/asf/felix/trunk/karaf/</span>
</pre>
</div></div> 

<h3><a name="KarafUsers%27Guideinonepage-Build"></a>Build</h3>

<p>Change directory to the top level of the source checkout. Build Karaf using Maven as follows:</p>

<div class="code panel" style="border-style: solid;border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
$ mvn -Pfastinstall
</pre>
</div></div>

<p>Distributions will be created in assembly/target. Select the file compression format compatible with your system (apache-felix-karaf-1.0.0.zip for windows, apache-felix-karaf-1.0.0.tar.gz for unixes) and expand the binary in a new directory; for example in z:\karaf - from now on this directory will be referenced as &lt;KARAF_HOME&gt;. Please remember the restrictions concerning illegal characters in Java paths, e.g. &#33;, % etc.</p>

<p>The installation of Karaf is as simple as uncompressing the .zip or .tar files. The next step is to start the server.</p>

<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><p>To generate Eclipse projects for all modules, in KARAF_HOME type:</p>

<p>mvn -Psetup.eclipse </p>

<p>Then add each module location, prefixing each name with <em>org.apache.felix.karaf</em> (for example <em>org.apache.felix.karaf.shell.core</em>)</p></td></tr></table></div>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>

<h2><a name="KarafUsers%27Guideinonepage-Starttheserver"></a>Start the server</h2>

<p>With Karaf already installed, open a command line console and change directory to &lt;KARAF_HOME&gt;. To start the server, run the following command in Windows:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
bin\karaf.bat
</pre>
</div></div>
<p>respectively on Unix:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
bin/karaf
</pre>
</div></div>
<p>You should see the following informations on the command line console:</p>
<div class="panel" style="background-color: #000000;border-width: 1px;"><div class="panelContent" style="background-color: #000000;">
<p><font color="#00ffff"><pre>        __ __                  ____      
       / //_/____ __________ _/ __/      
      / ,&lt;  / __ `/ ___/ __ `/ /_        
     / /| |/ /_/ / /  / /_/ / __/        
    /_/ |_|\__,_/_/   \__,_/_/         

</pre></font><font color="#c0c0c0"><pre>  Apache Felix Karaf (1.0.0)

Hit '&lt;tab&gt;' for a list of available commands
and '[cmd] --help' for help on a specific command.

karaf@root&gt; 
</pre></font></p>
</div></div>
<p>You can now run your first command.  Simply type the <tt>&lt;tab&gt;</tt> key in the console.</p>
<div class="panel" style="background-color: #000000;border-width: 1px;"><div class="panelContent" style="background-color: #000000;">
<p><font color="#c0c0c0">
<pre>karaf@root&gt; 

admin:change-port        admin:connect            admin:create             admin:destroy            admin:list               admin:start
admin:stop               config:cancel            config:edit              config:list              config:propappend        config:propdel
config:proplist          config:propset           config:update            features:addUrl          features:install         features:list
features:listUrl         features:refreshUrl      features:removeUrl       features:uninstall       log:display              log:display-exception
log:get                  log:set                  osgi:bundle-level        osgi:headers             osgi:install             osgi:list
osgi:ls                  osgi:refresh             osgi:resolve             osgi:restart             osgi:shutdown            osgi:start
osgi:start-level         osgi:stop                osgi:uninstall           osgi:update              packages:exports         packages:imports
shell:cat                shell:echo               shell:exec               shell:grep               shell:info               shell:java
shell:printf             shell:sleep              shell:sort               shell:tac                ssh:ssh                  ssh:sshd
karaf@root&gt; 
</pre></font></p>
</div></div>
<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>

<h2><a name="KarafUsers%27Guideinonepage-Deployasampleapplication"></a>Deploy a sample application</h2>

<p>While you will learn in the remainder of this guide how to use and leverage Apache Felix Karaf, we will just use the pre-built packaging for now.</p>

<p>In the console, run the following commands:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
features:install spring-dm
osgi:install -s mvn:org.apache.geronimo.specs/geronimo-activation_1.1_spec/1.0.2
osgi:install -s mvn:org.apache.servicemix.specs/org.apache.servicemix.specs.stax-api-1.0/1.1.0
osgi:install -s mvn:org.apache.servicemix.specs/org.apache.servicemix.specs.jaxb-api-2.1/1.1.0
osgi:install -s mvn:org.apache.servicemix.bundles/org.apache.servicemix.bundles.jaxb-impl/2.1.6_1
osgi:install -s mvn:org.apache.camel/camel-core/1.4.0
osgi:install -s mvn:org.springframework/spring-tx/2.5.6.SEC01
osgi:install -s mvn:org.apache.camel/camel-spring/1.4.0
osgi:install -s mvn:org.apache.camel/camel-osgi/1.4.0
osgi:install -s mvn:org.apache.camel/camel-example-osgi/1.4.0
</pre>
</div></div>
<p>This commands will download, install and start the specified jars.</p>

<p>The example installed is using <a href="http://activemq.apache.org/camel" rel="nofollow">Camel</a> to start a timer every 2 seconds and output a message on the console.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&gt;&gt;&gt;&gt; MyTransform set body:  Wed Jan 02 23:34:19 CET 2008
&gt;&gt;&gt;&gt; MyTransform set body:  Wed Jan 02 23:34:21 CET 2008
</pre>
</div></div>

<h3><a name="KarafUsers%27Guideinonepage-Stoppinganduninstallingthesampleapplication"></a>Stopping and uninstalling the sample application</h3>

<p>To stop this demo, run the following command:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
osgi:list | grep example
</pre>
</div></div>
<p>In the output, locate the line containing <tt>camel-example-osgi</tt> and note the id of the bundle in the first column.  Then launch the following command:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
osgi:stop [id]
</pre>
</div></div>
<p>If you wish, you can start again the sample by using the following command:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
osgi:start [id]
</pre>
</div></div>
<p>To uninstall the demo, run the following command:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
osgi:uninstall [id]
</pre>
</div></div>

<h3><a name="KarafUsers%27Guideinonepage-CommonProblems"></a>Common Problems</h3>

<ol>
	<li>Launching SMX4 can result in a deadlock in Felix during module dependency resolution.  This is often a result of sending a SIGINT (control-C) to the process when it will not cleanly exit.  This can corrupt the caches and cause startup problems in the very next launch. It is fixed by emptying the component cache:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
rm -rf data/cache/*
</pre>
</div></div></li>
</ol>


<h2><a name="KarafUsers%27Guideinonepage-StoppingKaraf"></a>Stopping Karaf</h2>

<p>To stop Karaf from the console, enter <tt>^D</tt> in the console:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
^D
</pre>
</div></div>
<p>Alternatively, you can also run the following command:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
osgi:shutdown
</pre>
</div></div>

<h2><a name="KarafUsers%27Guideinonepage-Summary"></a>Summary</h2>

<p>This document showed you how simple it is to have Apache Felix Karaf up and running. The overall time for getting the server running should be less than five minutes if you have the prerequisite (Java 1.5) already installed. Additionally, this article also showed you how to deploy and test a simple Apache Camel application in less than five minutes.</p>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td width='33%' class='ScrollbarPrevName'>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/1.+Quick+Start"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/1.+Quick+Start">1. Quick Start</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;</td></tr></table></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/1.+Quick+Start"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/1.+Quick+Start">1. Quick Start</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide">Karaf Users' Guide</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/3.+Installation">3. Installation</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/3.+Installation"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-2.Overview"></a>2. Overview</h1>

<p>Apache Felix Karaf is a small OSGi based runtime which provides a lightweight container onto which various components and applications can be deployed.</p>

<p>Here is a short list of features supported by the Karaf:</p>
<ul>
	<li><b>Hot deployment</b>: Karaf supports hot deployment of OSGi bundles by monitoring jar files inside the <tt>[home]/deploy</tt> directory.  Each time a jar is copied in this folder, it will be installed inside the runtime.  You can then update or delete it and changes will be handled automatically.  In addition, the Karaf also supports exploded bundles and custom deployers (blueprint and spring ones are included by default).</li>
	<li><b>Dynamic configuration</b>: Services are usually configured through the ConfigurationAdmin OSGi service.  Such configuration can be defined in Karaf using property files inside the <tt>[home]/etc</tt> directory.  These configurations are monitored and changes on the properties files will be propagated to the services.</li>
	<li><b>Logging System</b>: using a centralized logging back end supported by Log4J, Karaf supports a number of different APIs (JDK 1.4, JCL, SLF4J, Avalon, Tomcat, OSGi)</li>
	<li><b>Provisioning</b>: Provisioning of libraries or applications can be done through a number of different ways, by which they will be downloaded locally, installed and started.</li>
	<li><b>Native OS integration</b>: Karaf can be integrated into your own Operating System as a service so that the lifecycle will be bound to your Operating System.</li>
	<li><b>Extensible Shell console</b>: Karaf features a nice text console where you can manage the services, install new applications or libraries and manage their state.  This shell is easily extensible by deploying new commands dynamically along with new features or applications.</li>
	<li><b>Remote access</b>: use any SSH client to connect to Karaf and issue commands in the console</li>
	<li><b>Security framework</b> based on JAAS</li>
	<li><b>Managing instances</b>: Karaf provides simple commands for managing multiple instances. You can easily create, delete, start and stop instances of Karaf through the console.</li>
	<li>Supports the latest OSGi 4.2 containers: Apache Felix Framework 2.0.0 and Eclipse Equinox 3.5</li>
</ul>


<p><img src="/confluence/download/attachments/74929/karaf2.png" align="absmiddle" border="0" /></p>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/1.+Quick+Start"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/1.+Quick+Start">1. Quick Start</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide">Karaf Users' Guide</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/3.+Installation">3. Installation</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/3.+Installation"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/2.+Overview"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/2.+Overview">2. Overview</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide">Karaf Users' Guide</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/4.+Understanding+Karaf">4. Understanding Karaf</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/4.+Understanding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-3.Installation"></a>3. Installation</h1>

<p>This document describes how to install and configure Apache Felix Karaf for both Unix and Windows' platforms.<br/>
Here you will find information about what are pre requisite software, where to download Karaf from and how to customize the installation to use custom ports other than the defaults.</p>

<p>This article contains the following sections:</p>
<div>
<ul>
    <li><a href='#3.Installation-PreInstallationRequirements'>Pre-Installation Requirements</a></li>
    <li><a href='#3.Installation-InstallationProcedureforWindows'>Installation Procedure for Windows</a></li>
<ul>
    <li><a href='#3.Installation-WindowsBinaryInstallation'>Windows Binary Installation</a></li>
    <li><a href='#3.Installation-WindowsSourceInstallation'>Windows Source Installation</a></li>
</ul>
    <li><a href='#3.Installation-InstallationProcedureForUnix'>Installation Procedure For Unix</a></li>
<ul>
    <li><a href='#3.Installation-UnixBinaryInstallation'>Unix Binary Installation</a></li>
    <li><a href='#3.Installation-UnixSourceInstallation'>Unix Source Installation</a></li>
</ul>
    <li><a href='#3.Installation-StartingKaraf'>Starting Karaf</a></li>
<ul>
    <li><a href='#3.Installation-OnWindows'>On Windows</a></li>
    <li><a href='#3.Installation-OnUnix'>On Unix</a></li>
</ul>
    <li><a href='#3.Installation-TestingtheInstallation'>Testing the Installation</a></li>
    <li><a href='#3.Installation-StoppingKaraf'>Stopping Karaf</a></li>
</ul></div>

<h2><a name="KarafUsers%27Guideinonepage-PreInstallationRequirements"></a>Pre-Installation Requirements</h2>

<p><b>Hardware:</b></p>
<ul>
	<li>5 MB of free disk space for the Apache Felix Karaf x.y binary distribution.</li>
	<li>3 MB of free disk space for the Apache Felix Karaf x.y source distributions or SVN checkout. The Maven build requires roughly 57 MB disk space and for the dependencies Maven downloads during building further 76 MB are required. As a lot of small files are produced, the exact space demands depend greatly on your cluster utilization ratio.</li>
</ul>


<p><b>Operating Systems:</b></p>
<ul>
	<li>Windows: Windows XP SP2, Windows 2000.</li>
	<li>Unix: Ubuntu Linux, Powerdog Linux, MacOS, AIX, HP-UX, Solaris, any Unix platform that supports Java.</li>
</ul>


<p><b>Environment:</b></p>
<ul>
	<li>Java Developer Kit (JDK) 1.5.x or greater (<a href="http://java.sun.com/" rel="nofollow">http://java.sun.com/</a>).</li>
	<li>The JAVA_HOME environment variable must be set to the directory where the JDK is installed, e.g., <tt>c:\Program Files\jdk.1.5.0_06</tt>. To accomplish that, press Windows key and Break key together, switch to "Advanced" tab and click on "Environment Variables". Here, check for the variable and, if necessary, add it.</li>
	<li>Apache Maven 2.0.8 (<a href="http://maven.apache.org/download.html" rel="nofollow">http://maven.apache.org/download.html</a>).</li>
</ul>


<h2><a name="KarafUsers%27Guideinonepage-InstallationProcedureforWindows"></a>Installation Procedure for Windows</h2>

<p>This section of the Getting Started guide explains how to install binary and source distributions of Karaf on a Windows system.</p>
<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Handy Hint</b><br /><p>In case you have to install Karaf into a very deep path or a path containing illegal characters for Java paths, e.g. &#33;, % etc., you may add a bat file to <em>start &#45;&gt; startup</em> that executes</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>subst S: "C:\your very % problematic path!\KARAF"
</pre>
</div></div>
<p>so your Karaf root directory is S: &#8212; which works for sure and is short to type.</p></td></tr></table></div>

<h3><a name="KarafUsers%27Guideinonepage-WindowsBinaryInstallation"></a>Windows Binary Installation</h3>

<p>This procedure explains how to download and install the binary distribution on a Windows system.</p>
<ol>
	<li>From a browser, navigate to <a href="http://felix.apache.org/site/downloads.cgi" rel="nofollow">http://felix.apache.org/site/downloads.cgi</a>.</li>
	<li>Scroll down to the "Apache Felix Karaf" section and select the desired distribution.<br/>
For a binary distribution, the filename will be similar to: <tt>apache-felix-karaf-x.y.zip</tt>.</li>
	<li>Extract the files from the ZIP file into a directory of your choice. Please remember the restrictions concerning illegal characters in Java paths, e.g. &#33;, % etc.</li>
	<li>Proceed to the <a href="#KarafUsers%27Guideinonepage-StartingKaraf">Starting Karaf</a> section of this document.</li>
	<li>Following start-up, go to the <a href="#KarafUsers%27Guideinonepage-TestingtheInstallation">Testing the Installation</a> section of this document.</li>
	<li>Optional: see <a href="/confluence/display/FELIX/7.1.+Enabling+Colorized+Console+Output+On+Windows" title="7.1. Enabling Colorized Console Output On Windows">7.1. Enabling Colorized Console Output On Windows</a></li>
</ol>


<h3><a name="KarafUsers%27Guideinonepage-WindowsSourceInstallation"></a>Windows Source Installation</h3>

<p>This procedure explains how to download and install the source distribution on a Windows system. <b>NOTE:</b> Karaf requires Java 5 is compile, build and run.</p>
<ol>
	<li>From a browser, navigate to <a href="http://felix.apache.org/site/downloads.cgi" rel="nofollow">http://felix.apache.org/site/downloads.cgi</a>.</li>
	<li>Scroll down to the "Apache Felix Karaf" section and select the desired distribution.<br/>
For a source distribution, the filename will be similar to: <tt>apache-felix-karaf-x.y-src.zip</tt>.</li>
	<li>Extract Karaf from the ZIP file into a directory of your choice. Please remember the restrictions concerning illegal characters in Java paths, e.g. &#33;, % etc.</li>
	<li><a name="KarafUsers%27Guideinonepage-WindowsSourceInstallation"></a> Build Karaf using Maven 2.0.8 or greater and Java 5.<br/>
The recommended method of building Karaf is the following:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
cd [karaf_install_dir]\\src
</pre>
</div></div>
<p> where <tt>[karaf_install_dir]</tt> is the directory in which Karaf was installed.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
mvn
</pre>
</div></div>
<p>Both steps take around 10 to 15 minutes.</p></li>
	<li>Unzip the distribution using your favorite zip tool. The windows distribution is available at
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
[karaf_install_dir]\assembly\target\apache-felix-karaf-x.y.zip
</pre>
</div></div></li>
	<li>Proceed to the <a href="#KarafUsers%27Guideinonepage-StartingKaraf">Starting Karaf</a> section of this document.</li>
	<li>Following start-up, go to the <a href="#KarafUsers%27Guideinonepage-TestingtheInstallation">Testing the Installation</a> section of this document.</li>
	<li>Optional: see <a href="/confluence/display/FELIX/7.1.+Enabling+Colorized+Console+Output+On+Windows" title="7.1. Enabling Colorized Console Output On Windows">7.1. Enabling Colorized Console Output On Windows</a></li>
</ol>


<h2><a name="KarafUsers%27Guideinonepage-InstallationProcedureForUnix"></a>Installation Procedure For Unix</h2>

<h3><a name="KarafUsers%27Guideinonepage-UnixBinaryInstallation"></a>Unix Binary Installation</h3>

<p>This procedure explains how to download and install the binary distribution on a Unix system.</p>
<ol>
	<li>From a browser, navigate to <a href="http://felix.apache.org/site/downloads.cgi" rel="nofollow">http://felix.apache.org/site/downloads.cgi</a>.</li>
	<li>Scroll down to the "Apache Felix Karaf" section and select the desired distribution.<br/>
For a binary Unix distribution, the filename will be similar to: apache-felix-karaf-x.y.tar.gz.</li>
	<li>Extract the files from the gzip file into a directory of your choice. For example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
gunzip apache-felix-karaf-x.y.tar.gz
tar xvf apache-felix-karaf-x.y.tar
</pre>
</div></div>
<p>Please remember the restrictions concerning illegal characters in Java paths, e.g. &#33;, % etc.</p></li>
	<li>Proceed to the <a href="#KarafUsers%27Guideinonepage-StartingKaraf">Starting Karaf</a> section of this document.</li>
	<li>Following start-up, go to the <a href="#KarafUsers%27Guideinonepage-TestingtheInstallation">Testing the Installation</a> section.</li>
</ol>


<h3><a name="KarafUsers%27Guideinonepage-UnixSourceInstallation"></a>Unix Source Installation</h3>

<p>This procedure explains how to download and install the source distribution on a Unix system. This procedure assumes the Unix machine has a browser. Please see the previous <a href="#KarafUsers%27Guideinonepage-UnixBinaryInstallation">Unix Binary Installation</a> section for ideas on how to install Karaf without a browser. <b>NOTE:</b> Karaf requires Java 5 to compile, build and run.</p>
<ol>
	<li>From a browser, navigate to <a href="http://felix.apache.org/site/downloads.cgi" rel="nofollow">http://felix.apache.org/site/downloads.cgi</a>.</li>
	<li>Scroll down to the "Apache Felix Karaf" section and select the desired distribution.<br/>
For a source distribution, the filename will be similar to: <tt>apache-felix-karaf-x.y-src.tar.gz</tt>.</li>
	<li>Extract the files from the ZIP file into a directory of your choice. For example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
gunzip apache-felix-karaf-x.y-src.tar.gz
tar xvf apache-felix-karaf-x.y-src.tar
</pre>
</div></div>
<p>Please remember the restrictions concerning illegal characters in Java paths, e.g. &#33;, % etc.</p></li>
	<li>Build Karaf using Maven 2.0.8 or greater and Java 5:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
The preferred method of building Karaf is the following:
cd [karaf_install_dir]/src
 where [karaf_install_dir] is the directory in which Karaf was installed.
mvn
</pre>
</div></div></li>
	<li>Uncompress the distribution that has just been created
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
cd [karaf_install_dir]/assembly/target
gunzip apache-felix-karaf-x.y.tar.gz
tar xvf apache-felix-karaf-x.y.tar
</pre>
</div></div></li>
	<li>Proceed to the <a href="#KarafUsers%27Guideinonepage-StartingKaraf">Starting Karaf</a> section of this document.</li>
	<li>Following start-up, go to the <a href="#KarafUsers%27Guideinonepage-TestingtheInstallation">Testing the Installation</a> section.</li>
</ol>



<h2><a name="KarafUsers%27Guideinonepage-StartingKaraf"></a>Starting Karaf</h2>


<h3><a name="KarafUsers%27Guideinonepage-OnWindows"></a>On Windows</h3>

<p>From a console window, change to the installation directory and run <tt>Karaf</tt>. For the binary distribution, go to</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
cd [karaf_install_dir]
</pre>
</div></div>
<p>and for the source distribution go to the target directory, for example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
cd [karaf_install_dir]\src\assembly\target\apache-felix-karaf-x.y-SNAPSHOT
</pre>
</div></div>
<p>where <tt>karaf_install_dir</tt> is the directory in which Karaf was installed, e.g., <tt>c:\Program Files\apache-felix-karaf-x.y</tt>.</p>

<p>Then type:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
bin\karaf.bat
</pre>
</div></div>
<p><em>Note:</em> Working directories get created relative to the current directory. For the working directories to be created in the proper place, Karaf must be launched from its home/installation directory.</p>

<h3><a name="KarafUsers%27Guideinonepage-OnUnix"></a>On Unix</h3>

<p>From a command shell, change to the installation directory and run <tt>Karaf</tt>. For the binary distribution, go to</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
cd [karaf_install_dir]
</pre>
</div></div>
<p>and for the source distribution go to the target directory, for example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
cd [karaf_install_dir]/src/assembly/target/apache-felix-karaf-x.y
</pre>
</div></div>
<p>where <tt>karaf_install_dir</tt> is the directory in which Karaf was installed, e.g., <tt>/usr/local/apache-felix-karaf-x.y</tt>.</p>

<p>Then type:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
bin/karaf.sh
</pre>
</div></div>

<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Warning</b><br /><p>Do NOT close the console or shell in which Karaf was started, as that will terminate Karaf (unless Karaf was started with nohup).</p></td></tr></table></div>

<h2><a name="KarafUsers%27Guideinonepage-TestingtheInstallation"></a>Testing the Installation</h2>

<p>If Karaf is up and running without problems, the Window's console window or the Unix command shell will display something similar to the following log line:</p>
<div class="panel" style="background-color: #000000;border-width: 1px;"><div class="panelContent" style="background-color: #000000;">
<p><font color="#00ffff"><pre>        __ __                  ____      
       / //_/____ __________ _/ __/      
      / ,&lt;  / __ `/ ___/ __ `/ /_        
     / /| |/ /_/ / /  / /_/ / __/        
    /_/ |_|\__,_/_/   \__,_/_/         

</pre></font><font color="#c0c0c0"><pre>  Apache Felix Karaf (1.0.0)

Hit '&lt;tab&gt;' for a list of available commands
and '[cmd] --help' for help on a specific command.

karaf@root&gt; 
</pre></font></p>
</div></div>

<h2><a name="KarafUsers%27Guideinonepage-StoppingKaraf"></a>Stopping Karaf</h2>

<p>For both Windows and Unix installations, you can perform a clean shutdown of Karaf Kernel by using the following command:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
osgi:shutdown
</pre>
</div></div>

<p>If Karaf was started in the background on Unix, the process can be killed, with the following:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
ps -ef | grep karaf
kill [PID]
 where [PID] is the process id of the Karaf process.
</pre>
</div></div>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/2.+Overview"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/2.+Overview">2. Overview</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide">Karaf Users' Guide</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/4.+Understanding+Karaf">4. Understanding Karaf</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/4.+Understanding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/3.+Installation"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/3.+Installation">3. Installation</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide">Karaf Users' Guide</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/5.+Using+Karaf">5. Using Karaf</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/5.+Using+Karaf"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-4.UnderstandingKaraf"></a>4. Understanding Karaf</h1>
<ul><li><a href="/confluence/display/FELIX/4.1.+Commands" title="4.1. Commands">4.1. Commands</a></li><li><a href="/confluence/display/FELIX/4.2.+Remote+Console" title="4.2. Remote Console">4.2. Remote Console</a></li><li><a href="/confluence/display/FELIX/4.3.+Logging+system" title="4.3. Logging system">4.3. Logging system</a></li><li><a href="/confluence/display/FELIX/4.4.+Deployer" title="4.4. Deployer">4.4. Deployer</a></li><li><a href="/confluence/display/FELIX/4.5.+Security+framework" title="4.5. Security framework">4.5. Security framework</a></li><li><a href="/confluence/display/FELIX/4.6.+Provisioning" title="4.6. Provisioning">4.6. Provisioning</a></li><li><a href="/confluence/display/FELIX/4.7.+Administration" title="4.7. Administration">4.7. Administration</a></li><li><a href="/confluence/display/FELIX/4.8.+Configuration" title="4.8. Configuration">4.8. Configuration</a></li></ul>


<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/3.+Installation"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/3.+Installation">3. Installation</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide">Karaf Users' Guide</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/5.+Using+Karaf">5. Using Karaf</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/5.+Using+Karaf"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td width='33%' class='ScrollbarPrevName'>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf">4. Understanding Karaf</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/4.2.+Remote+Console">4.2. Remote Console</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/4.2.+Remote+Console"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-4.1.ConsoleandCommands"></a>4.1. Console and Commands</h1>

<h2><a name="KarafUsers%27Guideinonepage-Overview"></a>Overview</h2>

<p>Karaf provides a powerful console and a set of commands that can be used to perform various tasks.  Commands can be located in the root shell or in a sub-shell.  A sub-shell is a group of related commands, like commands related to the OSGi framework or the log system.</p>

<p>The following shells are available out-of-the-box, but the console can be <a href="/confluence/display/FELIX/6.1.+Extending+the+console" title="6.1. Extending the console">easily extended</a>:</p>
<ul>
	<li><a href="#KarafUsers%27Guideinonepage-Adminshell">admin</a></li>
	<li><a href="#KarafUsers%27Guideinonepage-Configshell">config</a></li>
	<li><a href="#KarafUsers%27Guideinonepage-Featuresshell">features</a></li>
	<li><a href="#KarafUsers%27Guideinonepage-Logshell">log</a></li>
	<li><a href="#KarafUsers%27Guideinonepage-OBRshell">obr</a></li>
	<li><a href="#KarafUsers%27Guideinonepage-OSGishell">osgi</a></li>
	<li><a href="#KarafUsers%27Guideinonepage-Packageshell">package</a></li>
	<li><a href="#KarafUsers%27Guideinonepage-Shellshell">shell</a></li>
	<li><a href="#KarafUsers%27Guideinonepage-SSHshell">ssh</a></li>
	<li><a href="#KarafUsers%27Guideinonepage-Wrappershell">wrapper</a></li>
</ul>


<h2><a name="KarafUsers%27Guideinonepage-Adminshell"></a>Admin shell</h2>

<p>This shell is described extensively in section <a href="/confluence/display/FELIX/4.7.+Administration" title="4.7. Administration">4.7. Administration</a>.</p>

<h2><a name="KarafUsers%27Guideinonepage-Configshell"></a>Config shell</h2>

<p>This shell is described extensively in section <a href="/confluence/display/FELIX/4.8.+Configuration" title="4.8. Configuration">4.8. Configuration</a>.</p>

<h2><a name="KarafUsers%27Guideinonepage-Featuresshell"></a>Features shell</h2>

<p>The features shell contains a few commands to provision entire applications easily.<br/>
More information is available on the chapter <a href="/confluence/display/FELIX/4.6.+Provisioning" title="4.6. Provisioning">4.6. Provisioning</a>.</p>

<h2><a name="KarafUsers%27Guideinonepage-Logshell"></a>Log shell</h2>

<p>The log shell contains a few commands to display the log entries, retrieve or change the log levels:</p>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Command         </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> display           </td>
<td class='confluenceTd'> Display log entries. </td>
</tr>
<tr>
<td class='confluenceTd'> display-exception </td>
<td class='confluenceTd'> Display the last exception from the log. </td>
</tr>
<tr>
<td class='confluenceTd'> get               </td>
<td class='confluenceTd'> Show log level. </td>
</tr>
<tr>
<td class='confluenceTd'> set               </td>
<td class='confluenceTd'> Set log level. </td>
</tr>
</tbody></table>

<p>See the documentation on the <a href="/confluence/display/FELIX/4.3.+Logging+system#4.3.Loggingsystem-Commands">logging system</a> for more informations.</p>

<h2><a name="KarafUsers%27Guideinonepage-OBRshell"></a>OBR shell</h2>

<p>OBR (<a href="http://www2.osgi.org/Repository" rel="nofollow">OSGi Bundle Repository</a>) is a proposed specification that defines an xml format for repositories of OSGi bundles and an associated service to access it.  Karaf proposes a number of commands that can be used to deal with such repositories.</p>

<p>Note that this feature is not installed by default.  To install it, you must run the following command:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
smx@root:/&gt; features:install obr
</pre>
</div></div>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Command  </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> addUrl     </td>
<td class='confluenceTd'> Add a list of repository URLs to the repository service </td>
</tr>
<tr>
<td class='confluenceTd'> deploy     </td>
<td class='confluenceTd'> Deploy </td>
</tr>
<tr>
<td class='confluenceTd'> info       </td>
<td class='confluenceTd'> Display the meta-data for the specified bundles. </td>
</tr>
<tr>
<td class='confluenceTd'> list       </td>
<td class='confluenceTd'> List </td>
</tr>
<tr>
<td class='confluenceTd'> listUrl    </td>
<td class='confluenceTd'> Display the repository URLs currently associated with the repository service. </td>
</tr>
<tr>
<td class='confluenceTd'> removeUrl  </td>
<td class='confluenceTd'> Remove a list of repository URLs from the repository service </td>
</tr>
<tr>
<td class='confluenceTd'> source     </td>
<td class='confluenceTd'> Source </td>
</tr>
<tr>
<td class='confluenceTd'> start      </td>
<td class='confluenceTd'> Start </td>
</tr>
</tbody></table>

<h2><a name="KarafUsers%27Guideinonepage-OSGishell"></a>OSGi shell</h2>

<p>The OSGi sub-shell provides commands for managing the OSGi framework: listing OSGi bundles, services, managing bundle lifecycles.<br/>
Look at the online help (launch <tt>osgi help</tt> command) for more informations.</p>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Command           </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> bundle-level        </td>
<td class='confluenceTd'> Get or set the start level of a given bundle </td>
</tr>
<tr>
<td class='confluenceTd'> headers             </td>
<td class='confluenceTd'> Display headers </td>
</tr>
<tr>
<td class='confluenceTd'> install             </td>
<td class='confluenceTd'> Install bundle </td>
</tr>
<tr>
<td class='confluenceTd'> list                </td>
<td class='confluenceTd'> List bundles </td>
</tr>
<tr>
<td class='confluenceTd'> ls                  </td>
<td class='confluenceTd'> List services </td>
</tr>
<tr>
<td class='confluenceTd'> refresh             </td>
<td class='confluenceTd'> Refresh bundle </td>
</tr>
<tr>
<td class='confluenceTd'> update              </td>
<td class='confluenceTd'> Update bundle </td>
</tr>
<tr>
<td class='confluenceTd'> resolve             </td>
<td class='confluenceTd'> Resolve bundle </td>
</tr>
<tr>
<td class='confluenceTd'> shutdown            </td>
<td class='confluenceTd'> Shutdown </td>
</tr>
<tr>
<td class='confluenceTd'> start               </td>
<td class='confluenceTd'> Start bundle </td>
</tr>
<tr>
<td class='confluenceTd'> start-level         </td>
<td class='confluenceTd'> Get or set the start level </td>
</tr>
<tr>
<td class='confluenceTd'> stop                </td>
<td class='confluenceTd'> Stop bundle </td>
</tr>
<tr>
<td class='confluenceTd'> uninstall           </td>
<td class='confluenceTd'> Uninstall bundle </td>
</tr>
</tbody></table>

<h2><a name="KarafUsers%27Guideinonepage-Packageshell"></a>Package shell</h2>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Command      </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> imports        </td>
<td class='confluenceTd'> Display imported packages </td>
</tr>
<tr>
<td class='confluenceTd'> exports        </td>
<td class='confluenceTd'> Display exported packages </td>
</tr>
</tbody></table>

<h2><a name="KarafUsers%27Guideinonepage-Shellshell"></a>Shell shell</h2>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Command  </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> cat        </td>
<td class='confluenceTd'> Displays the content of a file or url </td>
</tr>
<tr>
<td class='confluenceTd'> echo       </td>
<td class='confluenceTd'> Echoes or prints arguments to STDOUT </td>
</tr>
<tr>
<td class='confluenceTd'> exec       </td>
<td class='confluenceTd'> Executes system processes </td>
</tr>
<tr>
<td class='confluenceTd'> grep       </td>
<td class='confluenceTd'> Prints lines matching the given pattern </td>
</tr>
<tr>
<td class='confluenceTd'> info       </td>
<td class='confluenceTd'> Prints system informations </td>
</tr>
<tr>
<td class='confluenceTd'> java       </td>
<td class='confluenceTd'> Execute a Java standard application </td>
</tr>
<tr>
<td class='confluenceTd'> printf     </td>
<td class='confluenceTd'> Format and print arguments </td>
</tr>
<tr>
<td class='confluenceTd'> sleep      </td>
<td class='confluenceTd'> Sleeps for a bit then wakes up </td>
</tr>
<tr>
<td class='confluenceTd'> sort       </td>
<td class='confluenceTd'> Write sorted concatenation of all files to standard output. </td>
</tr>
<tr>
<td class='confluenceTd'> tac        </td>
<td class='confluenceTd'> Captures the STDIN and returns it as a string. Optionally writes the content to a file </td>
</tr>
</tbody></table>


<p>Examples:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
cat mvn:org.apache.servicemix/servicemix/3.2.1/pom
</pre>
</div></div>
<p>or</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
log:display | grep error
</pre>
</div></div>

<h2><a name="KarafUsers%27Guideinonepage-SSHshell"></a>SSH shell</h2>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Command  </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> ssh        </td>
<td class='confluenceTd'> Connects to a remote SSH server </td>
</tr>
<tr>
<td class='confluenceTd'> sshd       </td>
<td class='confluenceTd'> Creates a SSH server </td>
</tr>
</tbody></table>

<h2><a name="KarafUsers%27Guideinonepage-Wrappershell"></a>Wrapper shell</h2>

<p>Note that this feature is not installed by default.  To install it, you must run the following command:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
smx@root:/&gt; features:install wrapper
</pre>
</div></div>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Command  </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> install    </td>
<td class='confluenceTd'> Install the container as a system service in the OS. </td>
</tr>
</tbody></table>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td width='33%' class='ScrollbarPrevName'>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf">4. Understanding Karaf</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/4.2.+Remote+Console">4.2. Remote Console</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/4.2.+Remote+Console"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/4.1.+Commands"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/4.1.+Commands">4.1. Commands</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf">4. Understanding Karaf</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/4.3.+Logging+system">4.3. Logging system</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/4.3.+Logging+system"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-4.2.RemoteConsole"></a>4.2. Remote Console</h1>

<p>The remote console feature allows to connect to a running Karaf instance from a remote computer and perform all the operations that are usually accessible from the local console.</p>

<h2><a name="KarafUsers%27Guideinonepage-Launchoptions"></a>Launch options</h2>

<p>The Karaf shell scripts supports a number of options to control the remote console:</p>
<ul>
	<li><b><tt>console</tt></b>: launch Karaf in the default mode (both local and remote console activated).  This is the default mode</li>
	<li><b><tt>server</tt></b>: launch Karaf in with a remote console but no local console</li>
	<li><b><tt>client</tt></b>: launch Karaf in with a local console only</li>
</ul>


<p>These options affect two system properties that can be set if you don't use the standard shell scripts:</p>
<ul>
	<li><tt>karaf.startLocalConsole</tt></li>
	<li><tt>karaf.startRemoteShell</tt></li>
</ul>


<h2><a name="KarafUsers%27Guideinonepage-Usingtheclientjar"></a>Using the client jar</h2>

<p>It is also possible to use a more lightweight way to connect to a Karaf instance using the following command line:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
java -jar lib/karaf-client.jar
</pre>
</div></div>

<p>There are a few parameters that can be set on the command line to change the URL used to connect to the Kernel, the user or the password.<br/>
All these parameters are detailed in the help screen:</p>
<div class="panel" style="background-color: #000000;border-width: 1px;"><div class="panelContent" style="background-color: #000000;">
<p><font color="#c0c0c0"><pre>&gt; java -jar lib/karaf-client.jar --help
Apache Felix Karaf client
  -a [address]  specify the URL to connect to
  -h [host]     specify the host to connect to
  -u [user]     specify the user name
  -p [password] specify the password
  --help        shows this help message
  [commands]    commands to run
If no commands are specified, the client will be put in an interactive mode
</pre></font></p>
</div></div>

<p>For example, to shut down the Kernel from the command line, you can run the following command:</p>
<div class="panel" style="background-color: #000000;border-width: 1px;"><div class="panelContent" style="background-color: #000000;">
<p><font color="#c0c0c0"><pre>&gt; java -jar lib/karaf-client.jar 
smx@root:/&gt; osgi:shutdown
smx@root:/&gt;
&gt;
</pre></font></p>
</div></div>

<p>The client jar also supports passing command line arguments to the remote Karaf.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&gt; java -jar lib/karaf-client.jar osgi:shutdown
&gt;
</pre>
</div></div>
<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>
<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>

<h2><a name="KarafUsers%27Guideinonepage-UsinganSSHclient"></a>Using an SSH client</h2>

<p>You can use any standard SSH client to connect to a Karaf instance.  The default port is 8101.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&gt; ssh -p 8101 -l karaf localhost
karaf@localhost's password: karaf
karaf@root:/&gt;
</pre>
</div></div>

<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Error messages when using some ssh clients</b><br /></td></tr></table></div>
<p>Some SSH clients will prompt some harmless warnings when connecting to ServiceMix Kernel.<br/>
In particular, openssh 5.1p1 will display the following output:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
channel_by_id: 1: bad id: channel free
channel_input_success_failure: 1: unknown
channel_by_id: 1: bad id: channel free
channel_input_success_failure: 1: unknown
</pre>
</div></div></td></tr></table></div>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>

<h2><a name="KarafUsers%27Guideinonepage-UsinganotherKernelinstance"></a>Using another Kernel instance</h2>

<p>First, open a terminal and launch Karaf in server mode (you could use a Karaf instance in console mode too):</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
bin/karaf server
</pre>
</div></div>

<p>On another terminal, start another Karaf instance in client mode:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
bin/karaf client
</pre>
</div></div>

<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>User another Kernel instance to start the client</b><br /><p>At this point in time, you can not use the same Karaf installation to start both the server and the client, so you need to create a new instance using the 'admin create xxx' command and use that one to start the client.  If you are on a different host or already use another copy of Karaf, this requirement does not hold.</p></td></tr></table></div>

<p>Once the console appears, you can run the <tt>remote rsh</tt> command to connect to the other Kernel:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
remote rsh tcp:<span class="code-comment">//localhost:8101/ -u karaf -p karaf </span>
</pre>
</div></div>

<p>You can also do that in a single command line from the prompt by appending the previous ServiceMix command to the shell command:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
bin/karaf client remote rsh tcp:<span class="code-comment">//localhost:8101/ -u karaf -p karaf </span>
</pre>
</div></div>

<p>To verify that your are connected to the remote Kernel, run the following command:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
info
</pre>
</div></div>
<p>and check the system informations.</p>

<h3><a name="KarafUsers%27Guideinonepage-Configuration"></a>Configuration</h3>

<p>The TCP port is configured at the following location:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
[KARAF]/etc/org.apache.felix.karaf.shell.cfg
</pre>
</div></div>

<p>The defaut configuration is as below:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
startLocalConsole=${karaf.startLocalConsole}
startRemoteShell=${karaf.startRemoteShell}
sshPort=8101
sshRealm=karaf
hostKey=${karaf.base}/etc/host.key
</pre>
</div></div>

<p>The port used can easily be changed by changing the default port <tt>8101</tt> in the <tt>sshPort</tt> property.</p>

<p>The security realm used by the console when authenticating remote users is named <tt>karaf</tt>, so you can override this realm as explained in the <a href="/confluence/display/FELIX/4.5.+Security+framework" title="4.5. Security framework">security section</a>.  </p>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/4.1.+Commands"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/4.1.+Commands">4.1. Commands</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf">4. Understanding Karaf</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/4.3.+Logging+system">4.3. Logging system</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/4.3.+Logging+system"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>

<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/4.2.+Remote+Console"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/4.2.+Remote+Console">4.2. Remote Console</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf">4. Understanding Karaf</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/4.4.+Deployer">4.4. Deployer</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/4.4.+Deployer"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-4.3.Loggingsystem"></a>4.3. Logging system</h1>

<p>Karaf provides a powerful logging system based on <a href="http://wiki.ops4j.org/confluence/display/ops4j/Pax+Logging" rel="nofollow">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><a name="KarafUsers%27Guideinonepage-Configuration"></a>Configuration</h2>

<p>The configuration of the logging system uses a <a href="http://logging.apache.org/log4j/1.2/manual.html" rel="nofollow">standard Log4j configuration file</a> at the following location:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
[karaf]/etc/org.ops4j.pax.logging.cfg
</pre>
</div></div>

<p>You can edit this file at runtime and any change will be reloaded and be effective immediately.</p>

<h2><a name="KarafUsers%27Guideinonepage-Commands"></a>Commands</h2>

<p>The log subshell comes with 3 commands:</p>
<ul>
	<li><tt>log:display</tt>: display the last log entries</li>
	<li><tt>log:display-exception</tt>: display the last exception from the log</li>
	<li><tt>log:get</tt>: show the log levels</li>
	<li><tt>log:set</tt>: set the log levels</li>
</ul>


<p>For example, if you want to debug something, you might want to run the following commands:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&gt; log:set DEBUG
... <span class="code-keyword">do</span> something ...
&gt; log:display
</pre>
</div></div>

<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.<br/>
<a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/4.2.+Remote+Console"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/4.2.+Remote+Console">4.2. Remote Console</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf">4. Understanding Karaf</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/4.4.+Deployer">4.4. Deployer</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/4.4.+Deployer"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/4.3.+Logging+system"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/4.3.+Logging+system">4.3. Logging system</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf">4. Understanding Karaf</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/4.5.+Security+framework">4.5. Security framework</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/4.5.+Security+framework"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-4.4.Deployer"></a>4.4. Deployer</h1>

<p>The following picture describes the architecture of the deployer.</p>

<p><img src="/confluence/download/attachments/85599/smx4-deployer.png" align="absmiddle" border="0" /></p>

<h2><a name="KarafUsers%27Guideinonepage-Springdeployer"></a>Spring deployer</h2>

<p>Karaf includes a deployer that is able to deploy plain spring / spring-dm configuration files.<br/>
The deployer will transform on the fly any spring configuration file dropped into the <tt>deploy</tt> folder into a valid OSGi bundle.</p>

<p>The generated OSGi manifest will contain the following headers:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
Manifest-Version: 2
Bundle-SymbolicName: [name of the file]
Bundle-Version: [version of the file]
Spring-Context: *;publish-context:=<span class="code-keyword">false</span>;create-asynchronously:=<span class="code-keyword">true</span>
Import-Package: [required packages]
DynamicImport-Package: *
</pre>
</div></div>

<p>The <tt>name</tt> and <tt>version</tt> of the file are extracted using a heuristic that will match common patterns.  For example <tt>my-config-1.0.1.xml</tt> will lead to <tt>name = my-config</tt> and <tt>version = 1.0.1</tt>.<br/>
The default imported packages are extracted from the spring file definition and includes all classes referenced directly.</p>

<p>If you need to customize the generated manifest, you can do so by including an xml element in your spring configuration:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;spring:beans ...&gt;</span>
  <span class="code-tag">&lt;manifest&gt;</span>
    Require-Bundle= my-bundle
  <span class="code-tag">&lt;/manifest&gt;</span>
</pre>
</div></div>

<h2><a name="KarafUsers%27Guideinonepage-Featuresdeployer"></a>Features deployer</h2>

<p>To be able to hot deploy features from the deploy folder, you can just drop a feature descriptor on that folder.  A bundle will be created and its installation (automatic) will trigger the installation of all features contained in the descriptor.  Removing the file from the deploy folder will uninstall the features.<br/>
If you want to install a single feature, you can do so by writing a feature descriptor like the following:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;features&gt;</span>
  <span class="code-tag">&lt;repository&gt;</span>mvn:org.apache.servicemix.nmr/apache-servicemix-nmr/1.0.0/xml/features<span class="code-tag">&lt;/repository&gt;</span>
  <span class="code-tag">&lt;feature name=<span class="code-quote">"nmr-only"</span>&gt;</span>
    <span class="code-tag">&lt;feature&gt;</span>nmr<span class="code-tag">&lt;/feature&gt;</span>
  <span class="code-tag">&lt;/feature&gt;</span>
<span class="code-tag">&lt;/features&gt;</span>
</pre>
</div></div>

<p>For more informations about features, see the <a href="/confluence/display/FELIX/4.6.+Provisioning" title="4.6. Provisioning">provisioning section</a>.</p>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/4.3.+Logging+system"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/4.3.+Logging+system">4.3. Logging system</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf">4. Understanding Karaf</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/4.5.+Security+framework">4.5. Security framework</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/4.5.+Security+framework"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/4.4.+Deployer"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/4.4.+Deployer">4.4. Deployer</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf">4. Understanding Karaf</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/4.6.+Provisioning">4.6. Provisioning</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/4.6.+Provisioning"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-4.5.Securityframework"></a>4.5. Security framework</h1>

<p>Karaf supports <a href="http://java.sun.com/j2se/1.4.2/docs/guide/security/jaas/JAASRefGuide.html" rel="nofollow">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><a name="KarafUsers%27Guideinonepage-Overview"></a>Overview</h2>

<p>This feature allow the deployment at runtime of JAAS based configuration for use in various parts of the application. This includes the remote console login, which uses the <tt>karaf</tt> realm, but which is configured with a dummy login module by default.  These realms can also be used by the NMR, JBI components or the JMX server to authenticate users logging in or sending messages into the bus.</p>

<p>In addition to JAAS realms, you can also deploy keystores and truststores to secure the remote shell console, setting up HTTPS connectors or using certificates for WS-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><a name="KarafUsers%27Guideinonepage-Schema"></a>Schema</h2>

<p>To 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>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>JAAS XSD Schema</b></div><div class="codeContent panelContent">
<pre class="code-xml">
&lt;xs:schema elementFormDefault='qualified'
           targetNamespace='http://felix.apache.org/karaf/xmlns/jaas/v1.0.0'
           <span class="code-keyword">xmlns:xs</span>='http://www.w3.org/2001/XMLSchema'
           <span class="code-keyword">xmlns:bp</span>=<span class="code-quote">"http://www.osgi.org/xmlns/blueprint/v1.0.0"</span>
           <span class="code-keyword">xmlns:tns</span>='http://felix.apache.org/karaf/xmlns/jaas/v1.0.0'&gt;

    <span class="code-tag">&lt;xs:import namespace=<span class="code-quote">"http://www.osgi.org/xmlns/blueprint/v1.0.0"</span>/&gt;</span>

    <span class="code-tag">&lt;xs:element name=<span class="code-quote">"config"</span>&gt;</span>
        <span class="code-tag">&lt;xs:complexType&gt;</span>
            <span class="code-tag">&lt;xs:sequence&gt;</span>
                <span class="code-tag">&lt;xs:element name=<span class="code-quote">"module"</span> minOccurs=<span class="code-quote">"0"</span> maxOccurs=<span class="code-quote">"unbounded"</span>&gt;</span>
                    <span class="code-tag">&lt;xs:complexType mixed=<span class="code-quote">"true"</span>&gt;</span>
                        <span class="code-tag">&lt;xs:attribute name=<span class="code-quote">"className"</span> use=<span class="code-quote">"required"</span> type=<span class="code-quote">"xs:string"</span> /&gt;</span>
                        <span class="code-tag">&lt;xs:attribute name=<span class="code-quote">"flags"</span> default=<span class="code-quote">"required"</span>&gt;</span>
                            <span class="code-tag">&lt;xs:simpleType&gt;</span>
                                <span class="code-tag">&lt;xs:restriction base=<span class="code-quote">"xs:NMTOKEN"</span>&gt;</span>
                                    <span class="code-tag">&lt;xs:enumeration value=<span class="code-quote">"required"</span>/&gt;</span>
                                    <span class="code-tag">&lt;xs:enumeration value=<span class="code-quote">"requisite"</span>/&gt;</span>
                                    <span class="code-tag">&lt;xs:enumeration value=<span class="code-quote">"sufficient"</span>/&gt;</span>
                                    <span class="code-tag">&lt;xs:enumeration value=<span class="code-quote">"optional"</span>/&gt;</span>
                                <span class="code-tag">&lt;/xs:restriction&gt;</span>
                            <span class="code-tag">&lt;/xs:simpleType&gt;</span>
                        <span class="code-tag">&lt;/xs:attribute&gt;</span>
                    <span class="code-tag">&lt;/xs:complexType&gt;</span>
                <span class="code-tag">&lt;/xs:element&gt;</span>
            <span class="code-tag">&lt;/xs:sequence&gt;</span>
            <span class="code-tag">&lt;xs:attribute name=<span class="code-quote">"name"</span> use=<span class="code-quote">"required"</span> type=<span class="code-quote">"xs:string"</span> /&gt;</span>
            <span class="code-tag">&lt;xs:attribute name=<span class="code-quote">"rank"</span> use=<span class="code-quote">"optional"</span> default=<span class="code-quote">"0"</span> type=<span class="code-quote">"xs:int"</span> /&gt;</span>
        <span class="code-tag">&lt;/xs:complexType&gt;</span>
    <span class="code-tag">&lt;/xs:element&gt;</span>

    <span class="code-tag">&lt;xs:element name=<span class="code-quote">"keystore"</span>&gt;</span>
        <span class="code-tag">&lt;xs:complexType&gt;</span>
            <span class="code-tag">&lt;xs:attribute name=<span class="code-quote">"name"</span> use=<span class="code-quote">"required"</span> type=<span class="code-quote">"xs:string"</span> /&gt;</span>
            <span class="code-tag">&lt;xs:attribute name=<span class="code-quote">"rank"</span> use=<span class="code-quote">"optional"</span> default=<span class="code-quote">"0"</span> type=<span class="code-quote">"xs:int"</span> /&gt;</span>
            <span class="code-tag">&lt;xs:attribute name=<span class="code-quote">"path"</span> use=<span class="code-quote">"required"</span> type=<span class="code-quote">"xs:string"</span> /&gt;</span>
            <span class="code-tag">&lt;xs:attribute name=<span class="code-quote">"keystorePassword"</span> use=<span class="code-quote">"optional"</span> type=<span class="code-quote">"xs:string"</span> /&gt;</span>
            <span class="code-tag">&lt;xs:attribute name=<span class="code-quote">"keyPasswords"</span> use=<span class="code-quote">"optional"</span> type=<span class="code-quote">"xs:string"</span> /&gt;</span>
        <span class="code-tag">&lt;/xs:complexType&gt;</span>
    <span class="code-tag">&lt;/xs:element&gt;</span>
    
<span class="code-tag">&lt;/xs:schema&gt;</span>
</pre>
</div></div>

<p>You can find the schema at the following <a href="https://svn.apache.org/repos/asf/felix/releases/karaf-1.0.0/jaas/config/src/main/resources/org/apache/felix/karaf/jaas/config/karaf-jaas.xsd" rel="nofollow">location</a>.</p>

<p>Here are two example using this schema:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>JAAS realm example</b></div><div class="codeContent panelContent">
<pre class="code-xml">
&lt;blueprint xmlns=<span class="code-quote">"http://www.osgi.org/xmlns/blueprint/v1.0.0"</span>
           <span class="code-keyword">xmlns:jaas</span>=<span class="code-quote">"http://felix.apache.org/karaf/xmlns/jaas/v1.0.0"</span>
           <span class="code-keyword">xmlns:ext</span>=<span class="code-quote">"http://geronimo.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0"</span>&gt;

    <span class="code-tag"><span class="code-comment">&lt;!-- Bean to allow the $[karaf.base] property to be correctly resolved --&gt;</span></span>
    <span class="code-tag">&lt;ext:property-placeholder placeholder-prefix=<span class="code-quote">"$["</span> placeholder-suffix=<span class="code-quote">"]"</span>/&gt;</span>

    <span class="code-tag">&lt;jaas:config name=<span class="code-quote">"karaf"</span>&gt;</span>
        <span class="code-tag">&lt;jaas:module className=<span class="code-quote">"org.apache.felix.karaf.jaas.modules.properties.PropertiesLoginModule"</span> flags=<span class="code-quote">"required"</span>&gt;</span>
            users = $[karaf.base]/etc/users.properties
        <span class="code-tag">&lt;/jaas:module&gt;</span>
    <span class="code-tag">&lt;/jaas:config&gt;</span>

<span class="code-tag">&lt;/blueprint&gt;</span>
</pre>
</div></div>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Keystore example</b></div><div class="codeContent panelContent">
<pre class="code-xml">
&lt;jaas:keystore <span class="code-keyword">xmlns:jaas</span>=<span class="code-quote">"http://felix.apache.org/karaf/xmlns/jaas/v1.0.0"</span>
               id=<span class="code-quote">"keystore"</span>
               name=<span class="code-quote">"ks"</span>
               rank=<span class="code-quote">"1"</span>
               path=<span class="code-quote">"classpath:privatestore.jks"</span>
               keystorePassword=<span class="code-quote">"keyStorePassword"</span>
               keyPasswords=<span class="code-quote">"myalias=myAliasPassword"</span>&gt;
<span class="code-tag">&lt;/jaas:keystore&gt;</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 <tt>name</tt> attribute is specified.   Additional attributes on the <tt>config</tt> elements are a <tt>rank</tt>, which is an integer.  When the LoginContext looks for a realm for authenticating a given user, the realms registered in the OSGi registry are matched against the required name.  If more than one realm is found, the one with the highest rank will be used, thus allowing the override of some realms with new values.  The last attribute is <tt>publish</tt> which can be set to false to not publish the realm in the OSGi registry, hereby disabling the use of this realm.</p>

<p>Each realm can contain one or more module definition.  Each module identify a LoginModule and the <tt>className</tt> attribute must be set to the class name of the login module to use.   Note that this login module must be available from the bundle classloader, so either it has to be defined in the bundle itself, or the needed package needs to be correctly imported. The <tt>flags</tt> attribute can take one of four values that are explained on the <a href="http://svn.apache.org/repos/asf/felix/releases/karaf-1.0.0/jaas/boot/src/main/java/org/apache/felix/karaf/jaas/boot/ProxyLoginModule.java" rel="nofollow">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/felix/releases/karaf-1.0.0/jaas/config/src/main/java/org/apache/felix/karaf/jaas/config/JaasRealm.java" rel="nofollow">JaasRealm</a> object in the OSGi registry, which will then be used when using the JAAS login module.</p>

<h2><a name="KarafUsers%27Guideinonepage-Architecture"></a>Architecture</h2>

<p>Due to constraints in the JAAS specification, one class has to be available for all bundles.  This class is called <a href="http://svn.apache.org/repos/asf/felix/releases/karaf-1.0.0/jaas/boot/src/main/java/org/apache/felix/karaf/jaas/boot/ProxyLoginModule.java" rel="nofollow">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 allow the use of a simple xml (leveraging spring xml extensibility) to configure and register a JAAS configuration for a given realm.  This configuration will be made available into the OSGi registry as a <a href="http://svn.apache.org/repos/asf/felix/releases/karaf-1.0.0/jaas/config/src/main/java/org/apache/felix/karaf/jaas/config/JaasRealm.java" rel="nofollow">JaasRealm</a> and the OSGi specific Configuration will look for such services.  Then the proxy login module will be able to use the information provided by the realm to actually load the class from the bundle containing the real login module.</p>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/4.4.+Deployer"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/4.4.+Deployer">4.4. Deployer</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf">4. Understanding Karaf</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/4.6.+Provisioning">4.6. Provisioning</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/4.6.+Provisioning"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/4.5.+Security+framework"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/4.5.+Security+framework">4.5. Security framework</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf">4. Understanding Karaf</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/4.7.+Administration">4.7. Administration</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/4.7.+Administration"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-4.6.Provisioning"></a>4.6. Provisioning</h1>

<p>Karaf provides a simple, yet flexible, way to provision applications or "features".  Such a mechanism is mainly provided by a set of commands available in the <tt>features</tt> shell.  The provisioning system uses xml "repositories" that define a set of features.</p>

<h2><a name="KarafUsers%27Guideinonepage-Repositories"></a>Repositories</h2>

<p>The xml repositories use the following Relax NG Compact syntax:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Repository schema</b></div><div class="codeContent panelContent">
<pre class="code-java">
element features {
  element repository { text }*
  element feature {
    attribute name { text },
    attribute version { text },
    element feature { 
      attribute version { text },
      text 
    }*,
    element config {
      attribute name { text },
      text
    }*,
    element bundle { text }*
  }*
}
</pre>
</div></div>

<p>Here is an example of such a repository:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;features&gt;</span>
    <span class="code-tag">&lt;feature name=<span class="code-quote">"spring"</span> version=<span class="code-quote">"2.5.6.SEC01"</span>&gt;</span>
        <span class="code-tag">&lt;bundle&gt;</span>mvn:org.apache.servicemix.bundles/org.apache.servicemix.bundles.aopalliance/1.0_1<span class="code-tag">&lt;/bundle&gt;</span>
        <span class="code-tag">&lt;bundle&gt;</span>mvn:org.springframework/spring-core/2.5.6.SEC01<span class="code-tag">&lt;/bundle&gt;</span>
        <span class="code-tag">&lt;bundle&gt;</span>mvn:org.springframework/spring-beans/2.5.6.SEC01<span class="code-tag">&lt;/bundle&gt;</span>
        <span class="code-tag">&lt;bundle&gt;</span>mvn:org.springframework/spring-aop/2.5.6.SEC01<span class="code-tag">&lt;/bundle&gt;</span>        
        <span class="code-tag">&lt;bundle&gt;</span>mvn:org.springframework/spring-context/2.5.6.SEC01<span class="code-tag">&lt;/bundle&gt;</span>
        <span class="code-tag">&lt;bundle&gt;</span>mvn:org.springframework/spring-context-support/2.5.6.SEC01<span class="code-tag">&lt;/bundle&gt;</span>
    <span class="code-tag">&lt;/feature&gt;</span>
<span class="code-tag">&lt;/features&gt;</span>
</pre>
</div></div>

<p>A repository includes a list of <tt>feature</tt> elements, each one representing an application that can be installed.  The feature is identified by its <tt>name</tt> which must be unique amongst all the repositories used and consists of a set of bundles that need to be installed along with some optional dependencies on other features and some optional configurations for the Configuration Admin OSGi service.</p>

<h3><a name="KarafUsers%27Guideinonepage-Bundles"></a>Bundles</h3>

<p>The main information provided by a feature is the set of OSGi bundles that defines the application.  Such bundles are URLs pointing to the actual bundle jars.  For example, one would write the following definition:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;bundle&gt;</span>http://repo1.maven.org/maven2/org/apache/servicemix/nmr/org.apache.servicemix.nmr.api/1.0.0-m2/org.apache.servicemix.nmr.api-1.0.0-m2.jar<span class="code-tag">&lt;/bundle&gt;</span>
</pre>
</div></div>
<p>Doing this will make sure the above bundle is installed while installing the feature.</p>

<p>However, Karaf provides several URL handlers, in addition to the usual ones (file, http, etc...). One of these is the maven URL handler, which allow reusing maven repositories to point to the bundles. </p>

<h4><a name="KarafUsers%27Guideinonepage-MavenURLHandler"></a>Maven URL Handler</h4>

<p>The equivalent of the above bundle would be:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;bundle&gt;mvn:org.apache.servicemix.nmr/org.apache.servicemix.nmr.api/1.0.0-m2&lt;/bundle&gt;
</pre>
</div></div>
<p>In addition to being less verbose, the maven url handlers can also resolve snapshots and can use a local copy of the jar if one is available in your maven local repository.</p>

<p>The <tt>org.ops4j.pax.url.mvn</tt> bundle resolves <tt>mvn</tt> URLs. This flexible tool can be configured through the configuration service. For example, to find the current repositories type:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
karaf@root:/&gt; config:list
...
----------------------------------------------------------------
Pid:            org.ops4j.pax.url.mvn
BundleLocation: mvn:org.ops4j.pax.url/pax-url-mvn/0.3.3
Properties:
   service.pid = org.ops4j.pax.url.mvn
   org.ops4j.pax.url.mvn.defaultRepositories = file:/opt/development/karaf/assembly/target/apache-felix-karaf-1.2.0-SNAPSHOT/system@snapshots
   org.ops4j.pax.url.mvn.repositories = http:<span class="code-comment">//repo1.maven.org/maven2, 
</span>                                         http:<span class="code-comment">//people.apache.org/repo/m2-snapshot-repository@snapshots@noreleases, 
</span>                                         http:<span class="code-comment">//repository.ops4j.org/maven2, 
</span>                                         http:<span class="code-comment">//svn.apache.org/repos/asf/servicemix/m2-repo 
</span>   below = list of repositories and even before the local repository
</pre>
</div></div>

<p>The repositories checked are controlled by these configuration properties. </p>

<p>For example, <tt>org.ops4j.pax.url.mvn.repositories</tt> is a comma separate list of repository URLs specifying those remote repositories to be checked. So, to replace the defaults with a new repository at <tt><a href="http://www.example.org/repo" rel="nofollow">http://www.example.org/repo</a></tt> on the local machine:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
karaf@root:/&gt; config:edit org.ops4j.pax.url.mvn
karaf@root:/&gt; config:proplist                  
   service.pid = org.ops4j.pax.url.mvn
   org.ops4j.pax.url.mvn.defaultRepositories = file:/opt/development/karaf/assembly/target/apache-felix-karaf-1.2.0-SNAPSHOT/system@snapshots
   org.ops4j.pax.url.mvn.repositories = http:<span class="code-comment">//repo1.maven.org/maven2,
</span>                                        http:<span class="code-comment">//people.apache.org/repo/m2-snapshot-repository@snapshots@noreleases,
</span>                                        http:<span class="code-comment">//repository.ops4j.org/maven2,
</span>                                        http:<span class="code-comment">//svn.apache.org/repos/asf/servicemix/m2-repo
</span>   below = list of repositories and even before the local repository
karaf@root:/&gt; config:propset org.ops4j.pax.url.mvn.repositories http:<span class="code-comment">//www.example.org/repo
</span>karaf@root:/&gt; config:update
</pre>
</div></div>

<p>By default, snapshots are disable. To enable an URL for snapshots append @snapshots. For example</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
http:<span class="code-comment">//www.example.org/repo@snapshots</span>
</pre>
</div></div>

<p>Repositories on the local are supported through <tt><a href="file:/" rel="nofollow">file:/</a></tt> URLs</p>

<h3><a name="KarafUsers%27Guideinonepage-Dependantfeatures"></a>Dependant features</h3>

<p>Dependant features are usefull when a given feature depends on another feature to be installed.  Such a dependency can be expressed easily in the feature definition:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;feature name=<span class="code-quote">"jbi"</span>&gt;</span>
  <span class="code-tag">&lt;feature&gt;</span>nmr<span class="code-tag">&lt;/feature&gt;</span>
  ...
<span class="code-tag">&lt;/feature&gt;</span>
</pre>
</div></div>

<p>The effect of such a dependency is to automatically install the required <tt>nmr</tt> feature when the <tt>jbi</tt> feature will be installed.</p>

<h3><a name="KarafUsers%27Guideinonepage-Configurations"></a>Configurations</h3>

<p>The configuration section allows to deploy configuration for the OSGi Configuration Admin service along a set of bundles.<br/>
Here is an example of such a configuration:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;config name=<span class="code-quote">"com.foo.bar"</span>&gt;</span>
  myProperty = myValue
<span class="code-tag">&lt;/config&gt;</span>
</pre>
</div></div>

<p>The <tt>name</tt> attribute of the <tt>configuration</tt> element will be used as the ManagedService PID for the configuration set in the Configuration Admin service.  When using a ManagedServiceFactory, the <tt>name</tt> attribute is <em>servicePid</em>-<em>aliasId</em>, where <em>servicePid</em> is the PID of the ManagedServiceFactory and <em>aliasId</em> is a label used to uniquely identify a particular service (an alias to the factory generated service PID).</p>

<p>Deploying such a configuration has the same effect than dropping a file named <tt>com.foo.bar.cfg</tt> into the <tt>etc</tt> folder.  </p>

<p>The content of the <tt>configuration</tt> element is set of properties parsed using the <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Properties.html#load(java.io.InputStream)" rel="nofollow">standard java property mechanism</a>.</p>

<p>Such configuration as usually used with Spring-DM or Blueprint support for the Configuration Admin service, as in the following example, but using plain OSGi APIs will of course work the same way:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;bean ...&gt;</span>
    <span class="code-tag">&lt;property name=<span class="code-quote">"propertyName"</span> value=<span class="code-quote">"${myProperty}"</span> /&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span>

<span class="code-tag">&lt;osgix:cm-properties id=<span class="code-quote">"cmProps"</span> persistent-id=<span class="code-quote">"com.foo.bar"</span>&gt;</span>
    <span class="code-tag">&lt;prop key=<span class="code-quote">"myProperty"</span>&gt;</span>myValue<span class="code-tag">&lt;/prop&gt;</span>
<span class="code-tag">&lt;/osgix:cm-properties&gt;</span>
<span class="code-tag">&lt;ctx:property-placeholder properties-ref=<span class="code-quote">"cmProps"</span> /&gt;</span>
</pre>
</div></div>

<p>For more informations 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" rel="nofollow">Spring-DM documentation</a>.</p>


<h2><a name="KarafUsers%27Guideinonepage-Commands"></a>Commands</h2>

<h3><a name="KarafUsers%27Guideinonepage-Repositorymanagement"></a>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 ServiceMix Kernel, the most common ones being http, file and mvn.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
features:addUrl      Add a list of repository URLs to the features service
features:removeUrl   Remove a list of repository URLs from the features service
features:listUrl     Display the repository URLs currently associated with the features service.
features:refreshUrl  Reload the repositories to obtain a fresh list of features
</pre>
</div></div>

<p>Karaf maintains a persistent list of these repositories so that if you add one URL and restart Karaf, the features will still be available.</p>

<p>The <tt>refreshUrl</tt> command is mostly used when developing features descriptors: when changing the descriptor, it can be handy to reload it in the Kernel without having to restart it or to remove then add again this URL.</p>

<h3><a name="KarafUsers%27Guideinonepage-Featuresmanagement"></a>Features management</h3>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
features:install
features:uninstall
features:list
</pre>
</div></div>

<h3><a name="KarafUsers%27Guideinonepage-Examples"></a>Examples</h3>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
features/addUrl mvn:org.apache.servicemix.nmr/apache-servicemix-nmr/1.0.0-m2/xml/features
features/install nmr
</pre>
</div></div>

<h2><a name="KarafUsers%27Guideinonepage-Serviceconfiguration"></a>Service configuration</h2>

<p>A simple configuration file located in <tt>[karaf]/etc/org.apache.servicemix.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 ServiceMix Kernel distribution which includes pre-installed features.  Such a process is detailed in the <a href="/confluence/display/FELIX/6.2.+Building+custom+distributions" title="6.2. Building custom distributions">6.2. Building custom distributions</a> section.</p>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/4.5.+Security+framework"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/4.5.+Security+framework">4.5. Security framework</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf">4. Understanding Karaf</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/4.7.+Administration">4.7. Administration</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/4.7.+Administration"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/4.6.+Provisioning"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/4.6.+Provisioning">4.6. Provisioning</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf">4. Understanding Karaf</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/4.8.+Configuration">4.8. Configuration</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/4.8.+Configuration"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-4.7.Administration"></a>4.7. Administration</h1>

<p>Karaf provides some commands to administer multiple instances.  An instance of Karaf is a copy that you can launch separately and deploy applications onto.  An instance does not contain a full copy of Karaf, but only a copy of the configuration files and <tt>data</tt> folder which contains all runtime informations, logs and temporary files.</p>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Commands     </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'>  change-port   </td>
<td class='confluenceTd'> Changes the port of an existing container instance. </td>
</tr>
<tr>
<td class='confluenceTd'>  connect       </td>
<td class='confluenceTd'> Connects to an existing container instance. </td>
</tr>
<tr>
<td class='confluenceTd'>  create        </td>
<td class='confluenceTd'> Creates a new container instance. </td>
</tr>
<tr>
<td class='confluenceTd'>  destroy       </td>
<td class='confluenceTd'> Destroys an existing container instance. </td>
</tr>
<tr>
<td class='confluenceTd'>  list          </td>
<td class='confluenceTd'> List all existing container instances. </td>
</tr>
<tr>
<td class='confluenceTd'>  start         </td>
<td class='confluenceTd'> Starts an existing container instance. </td>
</tr>
<tr>
<td class='confluenceTd'>  stop          </td>
<td class='confluenceTd'> Stops an existing container instance. </td>
</tr>
</tbody></table>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/4.6.+Provisioning"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/4.6.+Provisioning">4.6. Provisioning</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/4.+Understanding+Karaf">4. Understanding Karaf</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/4.8.+Configuration">4.8. Configuration</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/4.8.+Configuration"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<div class="error"><span class="error">Unable to render {include}</span> Couldn't find a page to include called: <a href="/confluence/pages/createpage.action?spaceKey=FELIX&amp;title=4.8+Configuration&amp;linkCreation=true&amp;fromPageId=4587566" class="createlink">4.8 Configuration</a></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/4.+Understanding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/4.+Understanding+Karaf">4. Understanding Karaf</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide">Karaf Users' Guide</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/6.+Advanced+uses">6. Advanced uses</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/6.+Advanced+uses"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-5.UsingKaraf"></a>5. Using Karaf</h1>

<ul><li><a href="/confluence/display/FELIX/5.1.+Troubleshooting%2C+Debugging+and+Profiling" title="5.1. Troubleshooting, Debugging and Profiling">5.1. Troubleshooting, Debugging and Profiling</a></li><li><a href="/confluence/display/FELIX/5.2.+Developping+applications" title="5.2. Developping applications">5.2. Developping applications</a></li><li><a href="/confluence/display/FELIX/5.3.+Creating+bundles+for+third+party+dependencies" title="5.3. Creating bundles for third party dependencies">5.3. Creating bundles for third party dependencies</a></li></ul>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/4.+Understanding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/4.+Understanding+Karaf">4. Understanding Karaf</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide">Karaf Users' Guide</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/6.+Advanced+uses">6. Advanced uses</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/6.+Advanced+uses"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td width='33%' class='ScrollbarPrevName'>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/5.+Using+Karaf"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/5.+Using+Karaf">5. Using Karaf</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/5.2.+Developping+applications">5.2. Developping applications</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/5.2.+Developping+applications"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-5.1.Troubleshooting%2CDebuggingandProfiling"></a>5.1. Troubleshooting, Debugging and Profiling</h1>

<h2><a name="KarafUsers%27Guideinonepage-Troubleshooting"></a>Troubleshooting</h2>

<h3><a name="KarafUsers%27Guideinonepage-Logging"></a>Logging</h3>

<p>Logging is easy to control through the console, with commands grouped under <em>log</em> shell. To learn about the available logging commands type:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
karaf@root&gt; log&lt;tab&gt;

log:display              log:display-exception    log:get                  log:set
karaf@root&gt;
</pre>
</div></div>

<p>Typical usage is:</p>

<ol>
	<li>Use <tt>log:set</tt> to dynamically change the global log level</li>
	<li>Execute the problematic operation</li>
	<li>Use <tt>log:display</tt> (or <tt>log:display-exception</tt> to display the log</li>
</ol>




<h3><a name="KarafUsers%27Guideinonepage-WorstCaseScenario"></a>Worst Case Scenario</h3>

<p>If you end up with a Karaf in a really bad state (i.e. you can not boot it anymore) or you just want to revert to a clean state quickly, you can safely remove the <tt>data</tt> directory just in the installation directory.  This folder contains transient data and will be recreated if you remove it and relaunch Karaf.<br/>
You may also want to remove the files in the <tt>deploy</tt> folder to avoid them being automatically installed when Karaf is started the first time.</p>

<h2><a name="KarafUsers%27Guideinonepage-Debugging"></a>Debugging</h2>

<p>Usually, the easiest way to debug Karaf or any application deployed onto it is to use remote debugging.<br/>
Remote debugging can be easily activated by setting the <tt>KARAF_DEBUG</tt> environment variable to <tt>TRUE</tt>.</p>

<p>This can be done using the following command on Unix systems:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>export KARAF_DEBUG=true
</pre>
</div></div>

<p>On Windows, use the following command</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>set KARAF_DEBUG=true
</pre>
</div></div>

<p>Then, you can launch Karaf using the usual way:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>bin/karaf
</pre>
</div></div>
<p>or</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>bin\karaf.bat
</pre>
</div></div>

<p>Last, inside your IDE, connect to the remote application (the default port to connect to is 5005).</p>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>

<h2><a name="KarafUsers%27Guideinonepage-Profiling"></a>Profiling</h2>

<h3><a name="KarafUsers%27Guideinonepage-YourKit"></a>YourKit</h3>

<p>You need a few steps to be able to profile Karaf using YourKit.<br/>
The first one is to edit the <tt>etc/config.properties</tt> configuration file and add the following property:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>org.osgi.framework.bootdelegation=com.yourkit.*
</pre>
</div></div>

<p>Then, set the <tt>JAVA_OPTS</tt> environment variable:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>export JAVA_OPTS='-Xmx512M -agentlib:yjpagent'
</pre>
</div></div>

<p>or, on Windows</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>set JAVA_OPTS='-Xmx512M -agentlib:yjpagent'
</pre>
</div></div>

<p>Run Karaf from the console, and you should now be able to connect using YourKit standalone or from your favorite IDE.</p>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td width='33%' class='ScrollbarPrevName'>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/5.+Using+Karaf"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/5.+Using+Karaf">5. Using Karaf</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/5.2.+Developping+applications">5.2. Developping applications</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/5.2.+Developping+applications"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/5.1.+Troubleshooting%2C+Debugging+and+Profiling"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/5.1.+Troubleshooting%2C+Debugging+and+Profiling">5.1. Troubleshooting, Debugging and Profiling</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/5.+Using+Karaf"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/5.+Using+Karaf">5. Using Karaf</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/5.3.+Creating+bundles+for+third+party+dependencies">5.3. Creating bundles for third party dependencies</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/5.3.+Creating+bundles+for+third+party+dependencies"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-5.2.Developpingapplications"></a>5.2. Developping applications</h1>

<p>TODO</p>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/5.1.+Troubleshooting%2C+Debugging+and+Profiling"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/5.1.+Troubleshooting%2C+Debugging+and+Profiling">5.1. Troubleshooting, Debugging and Profiling</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/5.+Using+Karaf"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/5.+Using+Karaf">5. Using Karaf</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/5.3.+Creating+bundles+for+third+party+dependencies">5.3. Creating bundles for third party dependencies</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/5.3.+Creating+bundles+for+third+party+dependencies"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/5.2.+Developping+applications"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/5.2.+Developping+applications">5.2. Developping applications</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/5.+Using+Karaf"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/5.+Using+Karaf">5. Using Karaf</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;</td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-5.3.Creatingbundlesforthirdpartydependencies"></a>5.3. Creating bundles for third party dependencies</h1>

<p>TODO</p>

<p>Some infos available at <a href="http://gnodet.blogspot.com/2008/09/id-like-to-talk-bit-about-third-party.html" rel="nofollow">http://gnodet.blogspot.com/2008/09/id-like-to-talk-bit-about-third-party.html</a>, <a href="http://blog.springsource.com/2008/02/18/creating-osgi-bundles/" rel="nofollow">http://blog.springsource.com/2008/02/18/creating-osgi-bundles/</a> and <a href="http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html" rel="nofollow">http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html</a>.</p>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/5.2.+Developping+applications"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/5.2.+Developping+applications">5.2. Developping applications</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/5.+Using+Karaf"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/5.+Using+Karaf">5. Using Karaf</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;</td></tr></table></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/5.+Using+Karaf"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/5.+Using+Karaf">5. Using Karaf</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide">Karaf Users' Guide</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/7.+Optional+Features">7. Optional Features</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/7.+Optional+Features"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-6.Advanceduses"></a>6. Advanced uses</h1>

<ul><li><a href="/confluence/display/FELIX/6.1.+Extending+the+console" title="6.1. Extending the console">6.1. Extending the console</a></li><li><a href="/confluence/display/FELIX/6.2.+Building+custom+distributions" title="6.2. Building custom distributions">6.2. Building custom distributions</a></li><li><a href="/confluence/display/FELIX/6.3.+Programmatically+connect+to+the+console" title="6.3. Programmatically connect to the console">6.3. Programmatically connect to the console</a></li><li><a href="/confluence/display/FELIX/6.4.+Embedding+Karaf" title="6.4. Embedding Karaf">6.4. Embedding Karaf</a></li><li><a href="/confluence/display/FELIX/6.5.+Deploying+security+providers" title="6.5. Deploying security providers">6.5. Deploying security providers</a></li><li><a href="/confluence/display/FELIX/6.6.+Installing+additional+features" title="6.6. Installing additional features">6.6. Installing additional features</a></li><li><a href="/confluence/display/FELIX/6.7.+Configuring+Failover+Deployments" title="6.7. Configuring Failover Deployments">6.7. Configuring Failover Deployments</a></li></ul>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/5.+Using+Karaf"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/5.+Using+Karaf">5. Using Karaf</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide">Karaf Users' Guide</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/7.+Optional+Features">7. Optional Features</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/7.+Optional+Features"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td width='33%' class='ScrollbarPrevName'>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/6.+Advanced+uses"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/6.+Advanced+uses">6. Advanced uses</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/6.2.+Building+custom+distributions">6.2. Building custom distributions</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/6.2.+Building+custom+distributions"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Outdated documentation</b><br /></td></tr></table></div>

<h1><a name="KarafUsers%27Guideinonepage-6.1.Extendingtheconsole"></a>6.1. Extending the console</h1>

<p>This chapter will guide you through the steps needed to extend the console and create a new shell.  We will leverage Maven, Spring, Spring-DM and OSGi, so you will need some knowledge of those products.</p>

<p>As an example, we will create a command that will leverage the OSGi ConfigAdmin to display the existing configurations.</p>

<h2><a name="KarafUsers%27Guideinonepage-Createtheprojectusingmaven"></a>Create the project using maven</h2>

<p>We first need to create the project using maven.  Let's leverage maven archetypes for that.</p>

<h3><a name="KarafUsers%27Guideinonepage-Commandline"></a>Command line</h3>

<p>Using the command line, we can create our project:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
mvn archetype:create \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DgroupId=org.apache.servicemix.gshell.samples \
  -DartifactId=gshell-commmands \
  -Dversion=1.0-SNAPSHOT
</pre>
</div></div>

<p>This generate the main <tt>pom.xml</tt> and some additional packages.</p>

<h3><a name="KarafUsers%27Guideinonepage-Interactiveshell"></a>Interactive shell</h3>

<p>You can also use the interactive mode for creating the skeleton project:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
mvn archetype:generate
</pre>
</div></div>
<p>Use the following values when prompted:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
Choose a number:  (1/2/3/4/5/6/7/8/9/10/11/12/13/14/15/16/17/18/19/20/21/22/23/24/25/26/27/28/29/30/31/32/33/34/35/36) 15: : 15
Define value <span class="code-keyword">for</span> groupId: : org.apache.servicemix.gshell.samples
Define value <span class="code-keyword">for</span> artifactId: : gshell-commmands
Define value <span class="code-keyword">for</span> version:  1.0-SNAPSHOT: : 
Define value <span class="code-keyword">for</span> <span class="code-keyword">package</span>: : org.apache.servicemix.gshell.sample
</pre>
</div></div>

<h3><a name="KarafUsers%27Guideinonepage-Manualcreation"></a>Manual creation</h3>

<p>Alternatively, you can simply create the directory <tt>org.apache.servicemix.kernel.gshell.config</tt> and create the <tt>pom.xml</tt> file inside it:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>pom.xml</b></div><div class="codeContent panelContent">
<pre class="code-xml">
&lt;project xmlns=<span class="code-quote">"http://maven.apache.org/POM/4.0.0"</span> <span class="code-keyword">xmlns:xsi</span>=<span class="code-quote">"http://www.w3.org/2001/XMLSchema-instance"</span>
  xsi:schemaLocation=<span class="code-quote">"http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"</span>&gt;
  <span class="code-tag">&lt;modelVersion&gt;</span>4.0.0<span class="code-tag">&lt;/modelVersion&gt;</span>
  <span class="code-tag">&lt;groupId&gt;</span>org.apache.servicemix.gshell.samples<span class="code-tag">&lt;/groupId&gt;</span>
  <span class="code-tag">&lt;artifactId&gt;</span>gshell-commands<span class="code-tag">&lt;artifactId&gt;</span>
  <span class="code-tag">&lt;packaging&gt;</span>jar<span class="code-tag">&lt;/packaging&gt;</span>
  <span class="code-tag">&lt;version&gt;</span>1.0-SNAPSHOT<span class="code-tag">&lt;/version&gt;</span>
  <span class="code-tag">&lt;name&gt;</span>Hello GShell Example<span class="code-tag">&lt;/name&gt;</span>
  <span class="code-tag">&lt;url&gt;</span>http://maven.apache.org<span class="code-tag">&lt;/url&gt;</span>
  <span class="code-tag">&lt;dependencies&gt;</span>
    <span class="code-tag">&lt;dependency&gt;</span>
      <span class="code-tag">&lt;groupId&gt;</span>junit<span class="code-tag">&lt;/groupId&gt;</span>
      <span class="code-tag">&lt;artifactId&gt;</span>junit<span class="code-tag">&lt;/artifactId&gt;</span>
      <span class="code-tag">&lt;version&gt;</span>3.8.1<span class="code-tag">&lt;/version&gt;</span>
      <span class="code-tag">&lt;scope&gt;</span>test<span class="code-tag">&lt;/scope&gt;</span>
    <span class="code-tag">&lt;/dependency&gt;</span>
  <span class="code-tag">&lt;/dependencies&gt;</span>
<span class="code-tag">&lt;/project&gt;</span>
</pre>
</div></div>

<h2><a name="KarafUsers%27Guideinonepage-Dependencies"></a>Dependencies</h2>

<p>We need to tell maven which libraries our project depends on.  In the <tt>dependencies</tt> section of the pom, add the following ones:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
  <span class="code-tag">&lt;dependency&gt;</span>
    <span class="code-tag">&lt;groupId&gt;</span>org.apache.felix<span class="code-tag">&lt;/groupId&gt;</span>
    <span class="code-tag">&lt;artifactId&gt;</span>org.osgi.core<span class="code-tag">&lt;/artifactId&gt;</span>
    <span class="code-tag">&lt;version&gt;</span>1.2.0<span class="code-tag">&lt;/version&gt;</span>
    <span class="code-tag">&lt;scope&gt;</span>provided<span class="code-tag">&lt;/scope&gt;</span>
  <span class="code-tag">&lt;/dependency&gt;</span>
  <span class="code-tag">&lt;dependency&gt;</span>
    <span class="code-tag">&lt;groupId&gt;</span>org.apache.servicemix.kernel.gshell<span class="code-tag">&lt;/groupId&gt;</span>
    <span class="code-tag">&lt;artifactId&gt;</span>org.apache.servicemix.kernel.gshell.core<span class="code-tag">&lt;/artifactId&gt;</span>
    <span class="code-tag">&lt;version&gt;</span>1.1.0-SNAPSHOT<span class="code-tag">&lt;/version&gt;</span>
  <span class="code-tag">&lt;/dependency&gt;</span>
  <span class="code-tag">&lt;dependency&gt;</span>
    <span class="code-tag">&lt;groupId&gt;</span>org.springframework.osgi<span class="code-tag">&lt;/groupId&gt;</span>
    <span class="code-tag">&lt;artifactId&gt;</span>spring-osgi-core<span class="code-tag">&lt;/artifactId&gt;</span>
    <span class="code-tag">&lt;version&gt;</span>1.2.0-m2<span class="code-tag">&lt;/version&gt;</span>
  <span class="code-tag">&lt;/dependency&gt;</span>
</pre>
</div></div>

<p>These are needed respectively for OSGi, ServiceMix Kernel commands support and Spring-DM.</p>

<p>Additionally, we need the ConfigAdmin service, which is in the OSGi Compendium jar:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
  <span class="code-tag">&lt;dependency&gt;</span>
    <span class="code-tag">&lt;groupId&gt;</span>org.apache.felix<span class="code-tag">&lt;/groupId&gt;</span>
    <span class="code-tag">&lt;artifactId&gt;</span>org.osgi.compendium<span class="code-tag">&lt;/artifactId&gt;</span>
    <span class="code-tag">&lt;version&gt;</span>1.0.0<span class="code-tag">&lt;/version&gt;</span>
    <span class="code-tag">&lt;scope&gt;</span>provided<span class="code-tag">&lt;/scope&gt;</span>
  <span class="code-tag">&lt;/dependency&gt;</span>
</pre>
</div></div>

<h2><a name="KarafUsers%27Guideinonepage-AddtheSpringMilestoneRepository"></a>Add the Spring Milestone Repository </h2>

<p>Due to the use of the spring-osgi-core milestone version we need to add the repository for that here.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
    <span class="code-tag">&lt;repositories&gt;</span>
        <span class="code-tag">&lt;repository&gt;</span>
            <span class="code-tag">&lt;id&gt;</span>spring-milestone<span class="code-tag">&lt;/id&gt;</span>
            <span class="code-tag">&lt;name&gt;</span>Spring Portfolio Milestone Repository<span class="code-tag">&lt;/name&gt;</span>
            <span class="code-tag">&lt;url&gt;</span>http://s3.amazonaws.com/maven.springframework.org/milestone<span class="code-tag">&lt;/url&gt;</span>
            <span class="code-tag">&lt;releases&gt;</span>
                <span class="code-tag">&lt;enabled&gt;</span>true<span class="code-tag">&lt;/enabled&gt;</span>
            <span class="code-tag">&lt;/releases&gt;</span>
            <span class="code-tag">&lt;snapshots&gt;</span>
                <span class="code-tag">&lt;enabled&gt;</span>false<span class="code-tag">&lt;/enabled&gt;</span>
            <span class="code-tag">&lt;/snapshots&gt;</span>
        <span class="code-tag">&lt;/repository&gt;</span>
    <span class="code-tag">&lt;/repositories&gt;</span>
</pre>
</div></div>

<h2><a name="KarafUsers%27Guideinonepage-LoadingtheprojectinyourIDE"></a>Loading the project in your IDE</h2>

<p>We can use maven to generate the needed files for your IDE:</p>

<p>Inside the project, run the following command</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
mvn eclipse:eclipse
</pre>
</div></div>
<p>or</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
mvn idea:idea
</pre>
</div></div>

<p>The project files for your IDE should now be created.  Just open the IDE and load the project.</p>

<h2><a name="KarafUsers%27Guideinonepage-Creatingabasiccommandclass"></a>Creating a basic command class</h2>

<p>We can now create the command class <tt>HelloGShellCommand.java</tt></p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>HelloGShellCommand.java</b></div><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">package</span> org.apache.servicemix.gshell.sample;

<span class="code-keyword">import</span> org.apache.servicemix.kernel.gshell.core.OsgiCommandSupport;

<span class="code-keyword">public</span> class HelloGShellCommand <span class="code-keyword">extends</span> OsgiCommandSupport {

    /* (non-Javadoc)
     * @see org.apache.servicemix.kernel.gshell.core.OsgiCommandSupport#doExecute()
     */
    @Override
    <span class="code-keyword">protected</span> <span class="code-object">Object</span> doExecute() <span class="code-keyword">throws</span> Exception {
        io.out.println(<span class="code-quote">"Executing Hello command"</span>);
        <span class="code-keyword">return</span> <span class="code-keyword">null</span>;
    }
}
</pre>
</div></div>

<h2><a name="KarafUsers%27Guideinonepage-Creatingtheassociatedspringconfigurationfiles"></a>Creating the associated spring configuration files</h2>

<p>The spring configuration files will be used to create the command and register it in the OSGi registry, which is the way to make the command available to the ServiceMix Kernel console.  This spring file must be located in the <tt>META-INF/spring/</tt> directory inside the bundle.</p>

<p>If you don't have the <tt>src/main/resources</tt> directory yet, create it.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
mkdir src/main/resources
</pre>
</div></div>

<p>Then, re-generate the IDE project files and reload it so that this folder is now recognized as a source folder.</p>

<p>Inside this directory, create the <tt>META-INF/spring/</tt> directory and put the following file inside (the name of this file has no impact at all):</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>gshell-config.xml</b></div><div class="codeContent panelContent">
<pre class="code-xml">
&lt;beans xmlns=<span class="code-quote">"http://www.springframework.org/schema/beans"</span>
       <span class="code-keyword">xmlns:xsi</span>=<span class="code-quote">"http://www.w3.org/2001/XMLSchema-instance"</span>
       <span class="code-keyword">xmlns:osgi</span>=<span class="code-quote">"http://www.springframework.org/schema/osgi"</span>
       <span class="code-keyword">xmlns:osgix</span>=<span class="code-quote">"http://www.springframework.org/schema/osgi-compendium"</span>
       <span class="code-keyword">xmlns:util</span>=<span class="code-quote">"http://www.springframework.org/schema/util"</span>
       <span class="code-keyword">xmlns:gshell</span>=<span class="code-quote">"http://servicemix.apache.org/schema/servicemix-gshell"</span>
       xsi:schemaLocation="
  http://www.springframework.org/schema/beans
  http://www.springframework.org/schema/beans/spring-beans.xsd
  http://www.springframework.org/schema/osgi
  http://www.springframework.org/schema/osgi/spring-osgi.xsd
  http://www.springframework.org/schema/osgi-compendium
  http://www.springframework.org/schema/osgi-compendium/spring-osgi-compendium.xsd
  http://www.springframework.org/schema/util
  http://www.springframework.org/schema/util/spring-util.xsd
  http://servicemix.apache.org/schema/servicemix-gshell
  http://servicemix.apache.org/schema/servicemix-gshell/servicemix-gshell.xsd"&gt;

    <span class="code-tag">&lt;import resource=<span class="code-quote">"classpath:org/apache/servicemix/kernel/gshell/core/commands.xml"</span> /&gt;</span>

    <span class="code-tag">&lt;gshell:command-bundle&gt;</span>
    
        <span class="code-tag"><span class="code-comment">&lt;!-- Commands --&gt;</span></span>
        <span class="code-tag">&lt;gshell:command name=<span class="code-quote">"sample/hello"</span>&gt;</span>
            <span class="code-tag">&lt;gshell:action class=<span class="code-quote">"org.apache.servicemix.gshell.sample.HelloGShellCommand"</span> /&gt;</span>
        <span class="code-tag">&lt;/gshell:command&gt;</span>

        <span class="code-tag"><span class="code-comment">&lt;!-- add more commands here --&gt;</span></span>

        <span class="code-tag"><span class="code-comment">&lt;!-- Links --&gt;</span></span>
        <span class="code-tag">&lt;gshell:link name=<span class="code-quote">"sample/hi"</span> target=<span class="code-quote">"sample/hello"</span> /&gt;</span>

        <span class="code-tag"><span class="code-comment">&lt;!-- add more links here --&gt;</span></span>
        
        <span class="code-tag"><span class="code-comment">&lt;!-- Aliases --&gt;</span></span>
        <span class="code-tag">&lt;gshell:alias name=<span class="code-quote">"sayhi"</span> alias=<span class="code-quote">"sample/hello"</span> /&gt;</span>

        <span class="code-tag"><span class="code-comment">&lt;!-- add more aliases here --&gt;</span></span>
        
    <span class="code-tag">&lt;/gshell:command-bundle&gt;</span>

<span class="code-tag">&lt;/beans&gt;</span>
</pre>
</div></div>

<h2><a name="KarafUsers%27Guideinonepage-Compilingthejar"></a>Compiling the jar</h2>

<p>Let's try to build the jar.  Remove the test classes and sample classes if you used the artifact, then from the command line, run:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
mvn install
</pre>
</div></div>

<p>The end of the maven output should look like:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
[SMX4KNL:INFO] ------------------------------------------------------------------------
[SMX4KNL:INFO] BUILD SUCCESSFUL
[SMX4KNL:INFO] ------------------------------------------------------------------------
</pre>
</div></div>

<h2><a name="KarafUsers%27Guideinonepage-TurningthejarintoanOSGibundle"></a>Turning the jar into an OSGi bundle</h2>

<p>OSGi bundles are jars but they require some manifest headers to be correctly recognized.  We will leverage Felix's manven plugin to easily generate those.  </p>

<p>Lets turn it into a bundle: modify the line in the <tt>pom.xml</tt> to adjust the packaging:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
  <span class="code-tag">&lt;packaging&gt;</span>bundle<span class="code-tag">&lt;/packaging&gt;</span>
</pre>
</div></div>

<p>Add the following section at the bottom of the <tt>pom.xml</tt></p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
  <span class="code-tag">&lt;build&gt;</span>
    <span class="code-tag">&lt;plugins&gt;</span>
      <span class="code-tag">&lt;plugin&gt;</span>
        <span class="code-tag">&lt;groupId&gt;</span>org.apache.felix<span class="code-tag">&lt;/groupId&gt;</span>
        <span class="code-tag">&lt;artifactId&gt;</span>maven-bundle-plugin<span class="code-tag">&lt;/artifactId&gt;</span>
        <span class="code-tag">&lt;version&gt;</span>1.4.0<span class="code-tag">&lt;/version&gt;</span>
        <span class="code-tag">&lt;extensions&gt;</span>true<span class="code-tag">&lt;/extensions&gt;</span>
        <span class="code-tag">&lt;configuration&gt;</span>
          <span class="code-tag">&lt;instructions&gt;</span>
            <span class="code-tag">&lt;Import-Package&gt;</span>org.apache.geronimo.gshell.command,org.apache.servicemix.kernel.gshell.core,*<span class="code-tag">&lt;/Import-Package&gt;</span>
            <span class="code-tag">&lt;Spring-Context&gt;</span>*;publish-context:=false;create-asynchronously:=false<span class="code-tag">&lt;/Spring-Context&gt;</span>
          <span class="code-tag">&lt;/instructions&gt;</span>
        <span class="code-tag">&lt;/configuration&gt;</span>
        <span class="code-tag">&lt;dependencies&gt;</span>
          <span class="code-tag">&lt;dependency&gt;</span>
            <span class="code-tag">&lt;groupId&gt;</span>
          <span class="code-tag">&lt;/dependency&gt;</span>
        <span class="code-tag">&lt;/dependencies&gt;</span>
      <span class="code-tag">&lt;/plugin&gt;</span>
    <span class="code-tag">&lt;/plugins&gt;</span>
  <span class="code-tag">&lt;/build&gt;</span>
</pre>
</div></div>

<p>Let's compiled it again using the <tt>mvn install</tt> command.</p>

<h2><a name="KarafUsers%27Guideinonepage-TestinServiceMixKernel"></a>Test in ServiceMix Kernel</h2>

<p>Launch a ServiceMix Kernel instance and run the following command to install are newly created bundle:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
osgi/install -s mvn:org.apache.servicemix.gshell.samples/gshell-commands/1.0-SNAPSHOT
</pre>
</div></div>

<p>If you run the <tt>help</tt> command, you should now see our new shell <tt>sample</tt>.</p>

<p>Let's try running the command:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
servicemix&gt; sample/hello
Executing Hello command
</pre>
</div></div>

<p>and for the link:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
servicemix&gt; sample/hi
Executing Hello command
</pre>
</div></div>

<p>and for the alias:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
servicemix&gt; sayhi
Executing Hello command
</pre>
</div></div>


<p>Yeah <img class="emoticon" src="/confluence/images/icons/emoticons/smile.gif" height="20" width="20" align="absmiddle" alt="" border="0"/></p>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td width='33%' class='ScrollbarPrevName'>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/6.+Advanced+uses"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/6.+Advanced+uses">6. Advanced uses</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/6.2.+Building+custom+distributions">6.2. Building custom distributions</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/6.2.+Building+custom+distributions"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/6.1.+Extending+the+console"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/6.1.+Extending+the+console">6.1. Extending the console</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/6.+Advanced+uses"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/6.+Advanced+uses">6. Advanced uses</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/6.3.+Programmatically+connect+to+the+console">6.3. Programmatically connect to the console</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/6.3.+Programmatically+connect+to+the+console"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-6.2.Buildingcustomdistributions"></a>6.2. Building custom distributions</h1>

<p>TODO</p>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/6.1.+Extending+the+console"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/6.1.+Extending+the+console">6.1. Extending the console</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/6.+Advanced+uses"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/6.+Advanced+uses">6. Advanced uses</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/6.3.+Programmatically+connect+to+the+console">6.3. Programmatically connect to the console</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/6.3.+Programmatically+connect+to+the+console"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/6.2.+Building+custom+distributions"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/6.2.+Building+custom+distributions">6.2. Building custom distributions</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/6.+Advanced+uses"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/6.+Advanced+uses">6. Advanced uses</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/6.4.+Embedding+Karaf">6.4. Embedding Karaf</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/6.4.+Embedding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Outdated documentation</b><br /></td></tr></table></div>

<h1><a name="KarafUsers%27Guideinonepage-6.3.Programmaticallyconnecttotheconsole"></a>6.3. Programmatically connect to the console</h1>

<p>A connection to the kernel can also be done programmatically.<br/>
The following code is a simplified version of the code from the client library.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">import</span> org.apache.geronimo.gshell.remote.crypto.CryptoContext;
<span class="code-keyword">import</span> org.apache.geronimo.gshell.remote.client.RshClient;
<span class="code-keyword">import</span> org.apache.geronimo.gshell.remote.client.RemoteExecuteException;
<span class="code-keyword">import</span> org.apache.geronimo.gshell.remote.client.handler.EchoHandler;
<span class="code-keyword">import</span> org.apache.geronimo.gshell.remote.client.handler.ClientMessageHandler;
<span class="code-keyword">import</span> org.apache.geronimo.gshell.whisper.transport.TransportException;
<span class="code-keyword">import</span> org.apache.geronimo.gshell.whisper.transport.TransportFactory;
<span class="code-keyword">import</span> org.apache.geronimo.gshell.whisper.transport.TransportFactoryLocator;
<span class="code-keyword">import</span> org.apache.geronimo.gshell.whisper.transport.tcp.SpringTcpTransportFactory;
<span class="code-keyword">import</span> org.apache.geronimo.gshell.whisper.stream.StreamFeeder;
<span class="code-keyword">import</span> org.apache.geronimo.gshell.layout.NotFoundException;
<span class="code-keyword">import</span> org.apache.geronimo.gshell.ExitNotification;

<span class="code-keyword">public</span> class Main {

    <span class="code-keyword">public</span> <span class="code-keyword">static</span> void main(<span class="code-object">String</span>[] args) <span class="code-keyword">throws</span> Exception {
        RshClient client = <span class="code-keyword">null</span>;
        <span class="code-keyword">try</span> {
            CryptoContext context = <span class="code-keyword">new</span> CryptoContext(<span class="code-quote">"RSA"</span>, <span class="code-keyword">null</span>);
            List&lt;ClientMessageHandler&gt; handlers = <span class="code-keyword">new</span> LinkedList&lt;ClientMessageHandler&gt;();
            handlers.add(<span class="code-keyword">new</span> EchoHandler());
            client = <span class="code-keyword">new</span> RshClient(context, <span class="code-keyword">new</span> Locator(), handlers);

            client.initialize();
            client.connect(address, <span class="code-keyword">new</span> URI(<span class="code-quote">"tcp:<span class="code-comment">//0.0.0.0:0"</span>));
</span>            client.login(user, password);
            StreamFeeder outputFeeder = <span class="code-keyword">new</span> StreamFeeder(client.getInputStream(), <span class="code-object">System</span>.out);
            outputFeeder.createThread().start();
            client.openShell();
            <span class="code-object">System</span>.out.println(<span class="code-quote">"Connected"</span>);

            client.execute(args[0]);
        } <span class="code-keyword">catch</span> (ExitNotification e) {
            <span class="code-object">System</span>.exit(0);
        } <span class="code-keyword">catch</span> (Throwable t) {
            t.printStackTrace();
            <span class="code-object">System</span>.exit(1);
        } <span class="code-keyword">finally</span> {
            <span class="code-keyword">try</span> {
                client.closeShell();
                client.close();
            } <span class="code-keyword">catch</span> (Throwable t) { }
        }
        <span class="code-object">System</span>.exit(0);
    }

    <span class="code-keyword">private</span> <span class="code-keyword">static</span> class Locator <span class="code-keyword">implements</span> TransportFactoryLocator {
        SpringTcpTransportFactory factory = <span class="code-keyword">new</span> SpringTcpTransportFactory();

        <span class="code-keyword">public</span> TransportFactory locate(URI arg0) <span class="code-keyword">throws</span> TransportException {
            <span class="code-keyword">return</span> factory;
        }

    }
}
</pre>
</div></div>

<p>You can find a more complete example at the <a href="http://svn.apache.org/repos/asf/servicemix/smx4/kernel/trunk/client/src/main/java/org/apache/servicemix/kernel/client/Main.java" rel="nofollow">following location</a>.</p>



<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/6.2.+Building+custom+distributions"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/6.2.+Building+custom+distributions">6.2. Building custom distributions</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/6.+Advanced+uses"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/6.+Advanced+uses">6. Advanced uses</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/6.4.+Embedding+Karaf">6.4. Embedding Karaf</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/6.4.+Embedding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/6.3.+Programmatically+connect+to+the+console"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/6.3.+Programmatically+connect+to+the+console">6.3. Programmatically connect to the console</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/6.+Advanced+uses"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/6.+Advanced+uses">6. Advanced uses</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/6.5.+Deploying+security+providers">6.5. Deploying security providers</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/6.5.+Deploying+security+providers"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-6.4.EmbeddingKaraf"></a>6.4. Embedding Karaf</h1>

<p>TODO: an example of embedding Karaf inside a web application is provided in the distribution</p>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/6.3.+Programmatically+connect+to+the+console"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/6.3.+Programmatically+connect+to+the+console">6.3. Programmatically connect to the console</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/6.+Advanced+uses"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/6.+Advanced+uses">6. Advanced uses</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/6.5.+Deploying+security+providers">6.5. Deploying security providers</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/6.5.+Deploying+security+providers"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/6.4.+Embedding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/6.4.+Embedding+Karaf">6.4. Embedding Karaf</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/6.+Advanced+uses"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/6.+Advanced+uses">6. Advanced uses</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/6.6.+Installing+additional+features">6.6. Installing additional features</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/6.6.+Installing+additional+features"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-6.5.Deployingsecurityproviders"></a>6.5. Deploying security providers</h1>

<p>Some applications require specific security providers to be available, such as <a href="http://www.bouncycastle.org" rel="nofollow">BouncyCastle</a>.  The JVM impose some restrictions about the use of such jars: they have to be signed and be available on the boot classpath.  One way to deploy those providers is to put them in the JRE folder at <tt>$JAVA_HOME/jre/lib/ext</tt> and modify the security policy configuration (<tt>$JAVA_HOME/jre/lib/security/java.security</tt>) in order to register such providers.</p>

<p>While this approach works fine, it has a global effect and require you to configure all your servers accordingly.</p>

<p>Karaf offers a simple way to configure additional security providers:</p>
<ul>
	<li>put your provider jar in <tt>[KARAF]/lib</tt></li>
	<li>modify the <tt>[KARAF]/etc/config.properties</tt> configuration file to add the following property</li>
</ul>


<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
org.apache.felix.karaf.security.providers = xxx,yyy
</pre>
</div></div>

<p>The value of this property is a comma separated list of the provider class names to register.<br/>
For example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
org.apache.felix.karaf.security.providers = org.bouncycastle.jce.provider.BouncyCastleProvider
</pre>
</div></div>

<p>In addition, you may want to provide access to the classes from those providers from the system bundle so that all bundles can access those.  It can be done by modifying the <tt>org.osgi.framework.bootdelegation</tt> property in the same configuration file:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
org.osgi.framework.bootdelegation = ...,org.bouncycastle*
</pre>
</div></div>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/6.4.+Embedding+Karaf"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/6.4.+Embedding+Karaf">6.4. Embedding Karaf</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/6.+Advanced+uses"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/6.+Advanced+uses">6. Advanced uses</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/FELIX/6.6.+Installing+additional+features">6.6. Installing additional features</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/FELIX/6.6.+Installing+additional+features"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>
<div class="error"><span class="error">Unable to render {include}</span> Couldn't find a page to include called: <a href="/confluence/pages/createpage.action?spaceKey=FELIX&amp;title=6.6+Installing+additional+features&amp;linkCreation=true&amp;fromPageId=4587566" class="createlink">6.6 Installing additional features</a></div>
<div class="error"><span class="error">Unable to render {include}</span> Couldn't find a page to include called: <a href="/confluence/pages/createpage.action?spaceKey=FELIX&amp;title=6.7+Configuring+Failover+Deployments&amp;linkCreation=true&amp;fromPageId=4587566" class="createlink">6.7 Configuring Failover Deployments</a></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/6.+Advanced+uses"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/6.+Advanced+uses">6. Advanced uses</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide">Karaf Users' Guide</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;</td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-7.OptionalFeatures"></a>7. Optional Features</h1>

<ul><li><a href="/confluence/display/FELIX/7.1.+Enabling+Colorized+Console+Output+On+Windows" title="7.1. Enabling Colorized Console Output On Windows">7.1. Enabling Colorized Console Output On Windows</a></li></ul>

<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/FELIX/6.+Advanced+uses"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/FELIX/6.+Advanced+uses">6. Advanced uses</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/Karaf+Users%27+Guide">Karaf Users' Guide</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;</td></tr></table></div>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td width='33%' class='ScrollbarPrevName'>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/7.+Optional+Features"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/7.+Optional+Features">7. Optional Features</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;</td></tr></table></div>
<p><a name="KarafUsers%27Guideinonepage-top"></a></p>

<h1><a name="KarafUsers%27Guideinonepage-7.1.EnablingColorizedConsoleOutputOnWindows"></a>7.1. Enabling Colorized Console Output On Windows</h1>

<p>The default Karaf installation does not produce colorized console output on Windows like it does on Unix based systems.  To enable it, you must install LGPL licensed library <a href="https://jna.dev.java.net/" rel="nofollow">JNA</a>.  This can be done using a few simple commands in the Karaf console:</p>

<p>You first need to install the JNA library:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
osgi:install wrap:mvn:http:<span class="code-comment">//download.java.net/maven/2!net.java.dev.jna/jna/3.1.0</span>
</pre>
</div></div>

<p>Next you need either restart karaf or you run the following Karaf commands to refresh the Karaf Console:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
osgi:list | grep <span class="code-quote">"Apache Felix Karaf :: Shell Console"</span>
</pre>
</div></div>

<p>Take note of the ID of the bundle, in my case it was 14 and then run:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
osgi:refresh 14
</pre>
</div></div>


<p><a href="#KarafUsers%27Guideinonepage-top">top</a></p>
<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td width='33%' class='ScrollbarPrevName'>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/FELIX/7.+Optional+Features"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/FELIX/7.+Optional+Features">7. Optional Features</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;</td></tr></table></div>
     </div>
     <div id="commentsSection" class="wiki-content pageSection">
       <div style="float: right;">
            <a href="http://cwiki.apache.org/confluence/users/viewnotifications.action" class="grey">Change Notification Preferences</a>
       </div>

       <a href="http://cwiki.apache.org/confluence/display/FELIX/Karaf+Users%27+Guide+in+one+page">View Online</a>
       |
       <a href="http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=4587566&revisedVersion=6&originalVersion=5">View Change</a>
              |
       <a href="http://cwiki.apache.org/confluence/display/FELIX/Karaf+Users%27+Guide+in+one+page?showComments=true&amp;showCommentArea=true#addcomment">Add Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message