You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@karaf.apache.org by gn...@apache.org on 2011/02/09 10:38:51 UTC
svn commit: r1068812 [1/2] - in
/karaf/sandbox/website/src/main/webapp/index/documentation: ./
karaf-users-guide/ karaf-users-guide/2.-quick-start/
karaf-users-guide/4.-understanding-karaf/ karaf-users-guide/5.-using-karaf/
karaf-users-guide/6.-advance...
Author: gnodet
Date: Wed Feb 9 09:38:50 2011
New Revision: 1068812
URL: http://svn.apache.org/viewvc?rev=1068812&view=rev
Log:
Add back the manual to have a better comparison over the existing web site
Added:
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide-in-one-page.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/1.-overview.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/2.-quick-start/
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/2.-quick-start.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/2.-quick-start/2.1.-quick-start-source.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/3.-installation.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.1.-console-and-commands.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.2.-remote-console.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.3.-logging-system.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.4.-deployer.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.5.-security-framework.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.6.-provisioning.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.7.-administration.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.8.-configuration.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf/
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf/5.1.-troubleshooting-debugging-and-profiling.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf/5.2.-developping-applications.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf/5.3.-creating-bundles-for-third-party-dependencies.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf/5.4.-writing-integration-tests.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/6.-advanced-uses/
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/6.-advanced-uses.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/6.-advanced-uses/6.1.-extending-the-console.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/6.-advanced-uses/6.2.-building-custom-distributions.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/6.-advanced-uses/6.3.-programmatically-connect-to-the-console.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/6.-advanced-uses/6.4.-embedding-karaf.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/6.-advanced-uses/6.5.-deploying-security-providers.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/6.-advanced-uses/6.6.-installing-additional-features.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/6.-advanced-uses/6.7.-configuring-failover-deployments.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/7.-optional-features/
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/7.-optional-features.page
karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/7.-optional-features/7.1.-enabling-colorized-console-output-on-windows.page
Added: karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide-in-one-page.page
URL: http://svn.apache.org/viewvc/karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide-in-one-page.page?rev=1068812&view=auto
==============================================================================
--- karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide-in-one-page.page (added)
+++ karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide-in-one-page.page Wed Feb 9 09:38:50 2011
@@ -0,0 +1,58 @@
+---
+title: Karaf Users' Guide in one page
+page_version: 20
+page_creator: fdiotalevi
+page_modifier: gnodet
+--- pipeline:conf
+{div:class=title}
+!/images/karaf-logos.png!
+\\
+\\
+\\
+\\
+Apache Karaf
+Users' Guide
+\\
+\\
+\\
+\\
+{div}
+
+{div:class=copyright-section}
+Copyright 2010 The Apache Software Foundation
+{div}
+
+
+{div:class=toc-title}
+Table of contents
+{div}
+
+{toc:maxLevel=1}
+
+{include:1. Overview}
+{include:2. Quick Start}
+{include:2.1. Quick Start (Source)}
+{include:3. Installation}
+{include:4. Understanding Karaf}
+{include:4.1. Console and Commands}
+{include:4.2. Remote Console}
+{include:4.3. Logging system}
+{include:4.4. Deployer}
+{include:4.5. Security framework}
+{include:4.6. Provisioning}
+{include:4.7. Administration}
+{include:4.8. Configuration}
+{include:5. Using Karaf}
+{include:5.1. Troubleshooting, Debugging and Profiling}
+{include:5.2. Developping applications}
+{include:5.3. Creating bundles for third party dependencies}
+{include:6. Advanced uses}
+{include:6.1. Extending the console}
+{include:6.2. Building custom distributions}
+{include:6.3. Programmatically connect to the console}
+{include:6.4. Embedding Karaf}
+{include:6.5. Deploying security providers}
+{include:6.6. Installing additional features}
+{include:6.7. Configuring Failover Deployments}
+{include:7. Optional Features}
+{include:7.1. Enabling Colorized Console Output On Windows}
\ No newline at end of file
Added: karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide.page
URL: http://svn.apache.org/viewvc/karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide.page?rev=1068812&view=auto
==============================================================================
--- karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide.page (added)
+++ karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide.page Wed Feb 9 09:38:50 2011
@@ -0,0 +1,14 @@
+---
+title: Karaf Users' Guide
+page_version: 22
+page_creator: gnodet
+page_modifier: gnodet
+--- pipeline:conf
+h1. Apache Karaf Users' Guide
+
+Welcome to the Karaf Users' Guide. This guide is a work in progress from the Apache Karaf community.
+*Your contributions to this documentation effort are welcome*.
+
+This version is based on the latest release (2.x).
+
+{children:all=true}
Added: karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/1.-overview.page
URL: http://svn.apache.org/viewvc/karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/1.-overview.page?rev=1068812&view=auto
==============================================================================
--- karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/1.-overview.page (added)
+++ karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/1.-overview.page Wed Feb 9 09:38:50 2011
@@ -0,0 +1,15 @@
+---
+title: 1. Overview
+page_version: 16
+page_creator: gnodet
+page_modifier: gnodet
+--- pipeline:conf
+{scrollbar}
+{anchor:top}
+
+h1. 1. Overview
+
+{include:Karaf Overview}
+
+[#top]
+{scrollbar}
Added: karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/2.-quick-start.page
URL: http://svn.apache.org/viewvc/karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/2.-quick-start.page?rev=1068812&view=auto
==============================================================================
--- karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/2.-quick-start.page (added)
+++ karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/2.-quick-start.page Wed Feb 9 09:38:50 2011
@@ -0,0 +1,179 @@
+---
+title: 2. Quick Start
+page_version: 47
+page_creator: gnodet
+page_modifier: nanthrax
+--- pipeline:conf
+{scrollbar}
+{anchor:top}
+
+h1. 2. Quick start
+
+If you are in a hurry to have Apache 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.
+
+All you need is 5 to 10 minutes and to follow these basic steps.
+* [#Background]
+* [#Getting the software]
+* [#Start the server]
+* [#Deploy a sample application]
+
+h2. Background
+
+Apache Karaf is a small and lightweight OSGi based runtime. This provides a small lightweight container onto which various bundles can be deployed.
+{tip}
+Apache Karaf started life as the [Apache ServiceMix|http://servicemix.apache.org] kernel and then moved as a [Apache Felix|http://felix.apache.org] subproject.
+Don't be surprised by any transitional references which remain.
+{tip}
+[#top]
+
+h2. Getting the software
+
+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 Karaf up and running in the fastest way only the binary download will be covered at this time.
+
+h3. Prerequisites
+
+Although this installation path is the fastest one, still you will need to install some software before installing Karaf.
+
+Karaf requires a Java 5 environment to run. Refer to [http://java.sun.com] for details on how to download and install J2SE 1.5 or greater.
+
+h3. Download binaries
+
+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).
+
+[http://karaf.apache.org/download.html]
+
+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:\karaf - from now on this directory will be referenced as <KARAF_HOME>. Please remember the restrictions concerning illegal characters in Java paths, e.g. \!, % etc.
+
+The installation of Karaf is as simple as uncompressing the .zip or .tar files. The next step is to start the server.
+
+[#top]
+
+h2. Start the server
+
+With Karaf already installed, open a command line console and change directory to <KARAF_HOME>. To start the server, run the following command in Windows:
+{code}
+bin\karaf.bat
+{code}
+respectively on Unix:
+{code}
+bin/karaf
+{code}
+You should see the following informations on the command line console:
+{include:Karaf welcome screen}
+You can now run your first command. Simply type the {{<tab>}} key in the console.
+{code:borderStyle=solid}
+karaf@root>
+
+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 dev:dynamic-import
+dev:framework dev:print-stack-traces dev:show-tree features:addUrl
+features:info 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:clear shell:each shell:echo shell:exec
+shell:grep shell:history shell:if shell:info
+shell:java shell:logout shell:new shell:printf
+shell:sleep shell:sort shell:tac ssh:ssh
+ssh:sshd cat clear each
+echo exec grep history
+if info java logout
+new printf sleep sort
+tac bundle-level headers install
+list ls refresh resolve
+restart shutdown start start-level
+stop uninstall update
+karaf@root>
+{code}
+
+You can then grab more specific help for a given command using the {{--help}} option for this command:
+
+{code:borderStyle=solid}
+karaf@root> admin:create --help
+DESCRIPTION
+ admin:create
+
+ Create a new instance.
+
+SYNTAX
+ admin:create [options] name
+
+ARGUMENTS
+ name
+ The name of the new container instance
+
+OPTIONS
+ --help
+ Display this help message
+ -f, --feature
+ Initial features. This option can be specified multiple times to enable multiple initial
+ features
+ -p, --port
+ Port number for remote shell connection
+ -l, --location
+ Location of the new container instance in the file system
+ -furl, --featureURL
+ Additional feature descriptor URLs. This option can be specified multiple times to add
+ multiple URLs
+
+karaf@root>
+{code}
+
+Note that the console supports tab completion, so you just need to enter {{ad <tab> cr <tab>}} instead of {{admin:create}}.
+[#top]
+
+h2. Deploy a sample application
+
+While you will learn in the remainder of this guide how to use and leverage Apache Karaf, we will just use the pre-built packaging for now.
+
+In the console, run the following commands:
+{code}
+features:addurl mvn:org.apache.camel/camel-example-osgi/2.5.0/xml/features
+features:install camel-example-osgi
+{code}
+
+The example installed is using [Camel|http://camel.apache.org] to start a timer every 2 seconds and output a message on the console. The previous commands download the [Camel|http://camel.apache.org] features descriptor and install the example feature.
+
+{code}
+>>>> SpringDSL set body: Fri Jan 07 11:59:51 CET 2011
+>>>> SpringDSL set body: Fri Jan 07 11:59:53 CET 2011
+>>>> SpringDSL set body: Fri Jan 07 11:59:55 CET 2011
+{code}
+
+h3. Stopping and uninstalling the sample application
+
+To stop this demo, run the following command:
+
+{code}
+features:uninstall camel-example-osgi
+{code}
+
+h3. Common Problems
+
+# 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:
+{code}
+rm -rf data/cache/*
+{code}
+
+h2. Stopping Karaf
+
+To stop Karaf from the console, enter {{^D}} in the console:
+{code}
+^D
+{code}
+Alternatively, you can also run the following command:
+{code}
+osgi:shutdown
+{code}
+
+h2. Summary
+
+This document showed you how simple it is to have Apache 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|http://camel.apache.org] application in less than five minutes.
+
+[#top]
+{scrollbar}
\ No newline at end of file
Added: karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/2.-quick-start/2.1.-quick-start-source.page
URL: http://svn.apache.org/viewvc/karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/2.-quick-start/2.1.-quick-start-source.page?rev=1068812&view=auto
==============================================================================
--- karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/2.-quick-start/2.1.-quick-start-source.page (added)
+++ karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/2.-quick-start/2.1.-quick-start-source.page Wed Feb 9 09:38:50 2011
@@ -0,0 +1,184 @@
+---
+title: 2.1. Quick Start (Source)
+page_version: 17
+page_creator: robert burrell donkin
+page_modifier: gnodet
+--- pipeline:conf
+{scrollbar}
+{anchor:top}
+
+h1. 2.1. Quick Start (Source)
+
+If you are in a hurry to have Apache 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.
+
+All you need is 15 minutes and to follow these basic steps.
+* [#Background]
+* [#Getting the software]
+* [#Start the server]
+* [#Deploy a sample application]
+
+h2. Background
+
+Apache Karaf is a small and lightweight OSGi based runtime. This provides a small lightweight container onto which various bundles can be deployed.
+{tip}
+Apache Felix Karaf started life as the [Apache ServiceMix | http://servicemix.apache.org] kernel and then moved as a [Apache Felix|http://felix.apache.org] subproject.
+Don't be surprised by any transitional references which remain.
+{tip}
+[#top]
+
+h2. Getting the software
+
+This document describes how to build the server from the latest Karaf source.
+
+h3. Prerequisites
+
+Although this installation path is the fastest one, still you will need to install some software before installing Karaf.
+
+Karaf requires a Java 5 environment to run. Refer to [http://java.sun.com] for details on how to download and install J2SE 1.5 or greater.
+
+[Subversion | http://subversion.tigris.org] is required to checkout the source.
+
+[Maven 2| http://maven.apache.org] is required to build Karaf.
+
+h3. Checkout Source
+
+The Karaf source is found at http://svn.apache.org/repos/asf/karaf/trunk/. To check out with a command line client:
+
+{code:borderStyle=solid}
+$ svn co http://svn.apache.org/repos/asf/karaf/trunk/
+{code}
+
+h3. Build
+
+Change directory to the top level of the source checkout. Build Karaf using Maven as follows:
+
+{code:borderStyle=solid}
+$ mvn -Pfastinstall
+{code}
+
+Distributions will be created in assembly/target. Select the file compression format compatible with your system (apache-karaf-2.0.0.zip for windows, apache-karaf-2.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 <KARAF_HOME>. Please remember the restrictions concerning illegal characters in Java paths, e.g. \!, % etc.
+
+The installation of Karaf is as simple as uncompressing the .zip or .tar files. The next step is to start the server.
+
+{tip}
+To generate Eclipse projects for all modules, in KARAF_HOME type:
+
+mvn -Psetup.eclipse
+
+Then add each module location, prefixing each name with _org.apache.karaf_ (for example _org.apache.karaf.shell.core_)
+{tip}
+
+[#top]
+
+h2. Start the server
+
+With Karaf already installed, open a command line console and change directory to <KARAF_HOME>. To start the server, run the following command in Windows:
+{code}
+bin\karaf.bat
+{code}
+respectively on Unix:
+{code}
+bin/karaf
+{code}
+You should see the following informations on the command line console:
+{include:Karaf welcome screen}
+You can now run your first command. Simply type the {{<tab>}} key in the console.
+{code:borderStyle=solid}
+karaf@root>
+
+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 dev:dynamic-import
+dev:framework dev:print-stack-traces dev:show-tree features:addUrl
+features:info 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:clear shell:each shell:echo shell:exec
+shell:grep shell:history shell:if shell:info
+shell:java shell:logout shell:new shell:printf
+shell:sleep shell:sort shell:tac ssh:ssh
+ssh:sshd cat clear each
+echo exec grep history
+if info java logout
+new printf sleep sort
+tac bundle-level headers install
+list ls refresh resolve
+restart shutdown start start-level
+stop uninstall update
+karaf@root>
+{code}
+[#top]
+
+h2. Deploy a sample application
+
+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.
+
+In the console, run the following commands:
+{code}
+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
+{code}
+This commands will download, install and start the specified jars.
+
+The example installed is using [Camel|http://activemq.apache.org/camel] to start a timer every 2 seconds and output a message on the console.
+{code}
+>>>> MyTransform set body: Wed Jan 02 23:34:19 CET 2010
+>>>> MyTransform set body: Wed Jan 02 23:34:21 CET 2010
+{code}
+
+h3. Stopping and uninstalling the sample application
+
+To stop this demo, run the following command:
+{code}
+osgi:list | grep example
+{code}
+In the output, locate the line containing {{camel-example-osgi}} and note the id of the bundle in the first column. Then launch the following command:
+{code}
+osgi:stop [id]
+{code}
+If you wish, you can start again the sample by using the following command:
+{code}
+osgi:start [id]
+{code}
+To uninstall the demo, run the following command:
+{code}
+osgi:uninstall [id]
+{code}
+
+h3. Common Problems
+
+# 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:
+{code}
+rm -rf data/cache/*
+{code}
+
+h2. Stopping Karaf
+
+To stop Karaf from the console, enter {{^D}} in the console:
+{code}
+^D
+{code}
+Alternatively, you can also run the following command:
+{code}
+osgi:shutdown
+{code}
+
+h2. Summary
+
+This document showed you how simple it is to have Apache 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|http://camel.apache.org] application in less than five minutes.
+
+[#top]
+{scrollbar}
\ No newline at end of file
Added: karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/3.-installation.page
URL: http://svn.apache.org/viewvc/karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/3.-installation.page?rev=1068812&view=auto
==============================================================================
--- karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/3.-installation.page (added)
+++ karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/3.-installation.page Wed Feb 9 09:38:50 2011
@@ -0,0 +1,210 @@
+---
+title: 3. Installation
+page_version: 24
+page_creator: gnodet
+page_modifier: nanthrax
+--- pipeline:conf
+{scrollbar}
+{anchor:top}
+
+h1. 3. Installation
+
+This document describes how to install and configure Apache Karaf for both Unix and Windows' platforms.
+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.
+
+This article contains the following sections:
+{toc:minLevel=2}
+
+h2. Pre-Installation Requirements
+
+*Hardware:*
+* 5 MB of free disk space for the Apache Karaf x.y binary distribution.
+* 3 MB of free disk space for the Apache 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.
+
+*Operating Systems:*
+* Windows: Windows XP SP2, Windows 2000.
+* Unix: Ubuntu Linux, Powerdog Linux, MacOS, AIX, HP-UX, Solaris, any Unix platform that supports Java.
+
+*Environment:*
+* Java Developer Kit (JDK) 1.5.x or greater ([http://java.sun.com/]).
+* The JAVA_HOME environment variable must be set to the directory where the JDK is installed, e.g., {{c:\Program Files\jdk.1.5.0_06}}. 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.
+* Apache Maven 2.0.9 ([http://maven.apache.org/download.html]).
+
+h2. Installation Procedure for Windows
+
+This section of the Getting Started guide explains how to install binary and source distributions of Karaf on a Windows system.
+{tip:title=Handy Hint}
+In case you have to install Karaf into a very deep path or a path containing illegal characters for Java paths, e.g. \!, % etc., you may add a bat file to _start \-> startup_ that executes
+{noformat}
+subst S: "C:\your very % problematic path!\KARAF"
+{noformat}
+so your Karaf root directory is S: --- which works for sure and is short to type.
+{tip}
+
+h3. Windows Binary Installation
+
+This procedure explains how to download and install the binary distribution on a Windows system.
+# From a browser, navigate to [http://karaf.apache.org/download.html].
+# Scroll down to the "Apache Karaf" section and select the desired distribution.
+For a binary distribution, the filename will be similar to: {{apache-karaf-x.y.zip}}.
+# 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. \!, % etc.
+# Proceed to the [#Starting Karaf] section of this document.
+# Following start-up, go to the [#Testing the Installation] section of this document.
+# Optional: see [7.1. Enabling Colorized Console Output On Windows]
+
+h3. Windows Source Installation
+
+This procedure explains how to download and install the source distribution on a Windows system. *NOTE:* Karaf requires Java 5 is compile, build and run.
+# From a browser, navigate to [http://karaf.apache.org/download.html].
+# Scroll down to the "Apache Karaf" section and select the desired distribution.
+For a source distribution, the filename will be similar to: {{apache-karaf-x.y-src.zip}}.
+# Extract Karaf from the ZIP file into a directory of your choice. Please remember the restrictions concerning illegal characters in Java paths, e.g. \!, % etc.
+# {anchor:Windows Source Installation} Build Karaf using Maven 2.0.9 or greater and Java 5.
+The recommended method of building Karaf is the following:
+{code}
+cd [karaf_install_dir]\\src
+{code}
+ where {{\[karaf_install_dir\]}} is the directory in which Karaf was installed.
+{code}
+mvn
+{code}
+Both steps take around 10 to 15 minutes.
+# Unzip the distribution using your favorite zip tool. The windows distribution is available at
+{code}
+\[karaf_install_dir\]\assembly\target\apache-karaf-x.y.zip
+{code}
+# Proceed to the [#Starting Karaf] section of this document.
+# Following start-up, go to the [#Testing the Installation] section of this document.
+# Optional: see [7.1. Enabling Colorized Console Output On Windows]
+
+h2. Installation Procedure For Unix
+
+h3. Unix Binary Installation
+
+This procedure explains how to download and install the binary distribution on a Unix system.
+# From a browser, navigate to [http://karaf.apache.org/download.html].
+# Scroll down to the "Apache Karaf" section and select the desired distribution.
+For a binary Unix distribution, the filename will be similar to: apache-karaf-x.y.tar.gz.
+# Extract the files from the gzip file into a directory of your choice. For example:
+{code}
+gunzip apache-karaf-x.y.tar.gz
+tar xvf apache-karaf-x.y.tar
+{code}
+Please remember the restrictions concerning illegal characters in Java paths, e.g. \!, % etc.
+# Proceed to the [#Starting Karaf] section of this document.
+# Following start-up, go to the [#Testing the Installation] section.
+
+h3. Unix Source Installation
+
+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 [#Unix Binary Installation] section for ideas on how to install Karaf without a browser. *NOTE:* Karaf requires Java 5 to compile, build and run.
+# From a browser, navigate to [http://karaf.apache.org/download.html].
+# Scroll down to the "Apache Karaf" section and select the desired distribution.
+For a source distribution, the filename will be similar to: {{apache-karaf-x.y-src.tar.gz}}.
+# Extract the files from the ZIP file into a directory of your choice. For example:
+{code}
+gunzip apache-karaf-x.y-src.tar.gz
+tar xvf apache-karaf-x.y-src.tar
+{code}
+Please remember the restrictions concerning illegal characters in Java paths, e.g. \!, % etc.
+# Build Karaf using Maven 2.0.8 or greater and Java 5:
+{code}
+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
+{code}
+# Uncompress the distribution that has just been created
+{code}
+cd [karaf_install_dir]/assembly/target
+gunzip apache-karaf-x.y.tar.gz
+tar xvf apache-karaf-x.y.tar
+{code}
+# Proceed to the [#Starting Karaf] section of this document.
+# Following start-up, go to the [#Testing the Installation] section.
+
+
+h2. Starting Karaf
+
+
+h3. On Windows
+
+From a console window, change to the installation directory and run {{Karaf}}. For the binary distribution, go to
+{code}
+cd [karaf_install_dir]
+{code}
+and for the source distribution go to the target directory, for example:
+{code}
+cd [karaf_install_dir]\src\assembly\target\apache-karaf-x.y-SNAPSHOT
+{code}
+where {{karaf_install_dir}} is the directory in which Karaf was installed, e.g., {{c:\Program Files\apache-karaf-x.y}}.
+
+Then type:
+{code}
+bin\karaf.bat
+{code}
+_Note:_ 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.
+
+It will start a Karaf console, allowing you to administrate your Karaf instance.
+
+You can launch Karaf in server mode (without terminal output):
+{code}
+bin\start.bat
+{code}
+
+h3. On Unix
+
+From a command shell, change to the installation directory and run {{Karaf}}. For the binary distribution, go to
+{code}
+cd [karaf_install_dir]
+{code}
+and for the source distribution go to the target directory, for example:
+{code}
+cd [karaf_install_dir]/src/assembly/target/apache-karaf-x.y
+{code}
+where {{karaf_install_dir}} is the directory in which Karaf was installed, e.g., {{/usr/local/apache-karaf-x.y}}.
+
+Then type:
+{code}
+bin/karaf
+{code}
+
+{warning:title=Warning}
+Do NOT close the console or shell in which Karaf was started, as that will terminate Karaf (unless Karaf was started with nohup).
+{warning}
+
+h2. Testing the Installation and connecting to a running Karaf
+
+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:
+{include:Karaf welcome screen}
+
+You can use the client mode to connect to a running Karaf:
+On Windows:
+{code}
+bin\client.bat
+{code}
+
+On Unix:
+{code}
+bin/client
+{code}
+
+h2. Stopping Karaf
+
+For both Windows and Unix installations, you can perform a clean shutdown of Karaf by using the following command:
+{code}
+osgi:shutdown
+{code}
+
+You can use the stop script too:
+On Windows:
+{code}
+bin\stop.bat
+{code}
+
+On Unix:
+{code}
+bin/stop
+{code}
+
+[#top]
+{scrollbar}
\ No newline at end of file
Added: karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf.page
URL: http://svn.apache.org/viewvc/karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf.page?rev=1068812&view=auto
==============================================================================
--- karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf.page (added)
+++ karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf.page Wed Feb 9 09:38:50 2011
@@ -0,0 +1,15 @@
+---
+title: 4. Understanding Karaf
+page_version: 8
+page_creator: gnodet
+page_modifier: gnodet
+--- pipeline:conf
+{scrollbar}
+{anchor:top}
+
+h1. 4. Understanding Karaf
+{children}
+
+
+[#top]
+{scrollbar}
Added: karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.1.-console-and-commands.page
URL: http://svn.apache.org/viewvc/karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.1.-console-and-commands.page?rev=1068812&view=auto
==============================================================================
--- karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.1.-console-and-commands.page (added)
+++ karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.1.-console-and-commands.page Wed Feb 9 09:38:50 2011
@@ -0,0 +1,139 @@
+---
+title: 4.1. Console and Commands
+page_version: 22
+page_creator: gnodet
+page_modifier: gnodet
+--- pipeline:conf
+{scrollbar}
+{anchor:top}
+
+h1. 4.1. Console and Commands
+
+h2. Overview
+
+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.
+
+The following shells are available out-of-the-box, but the console can be [easily extended|6.1. Extending the console]:
+ * [admin|#Admin shell]
+ * [config|#Config shell]
+ * [features|#Features shell]
+ * [log|#Log shell]
+ * [obr|#OBR shell]
+ * [osgi|#OSGi shell]
+ * [package|#Package shell]
+ * [shell|#Shell shell]
+ * [ssh|#SSH shell]
+ * [wrapper|#Wrapper shell]
+
+h2. Admin shell
+
+This shell is described extensively in section [4.7. Administration].
+
+h2. Config shell
+
+This shell is described extensively in section [4.8. Configuration].
+
+h2. Features shell
+
+The features shell contains a few commands to provision entire applications easily.
+More information is available on the chapter [4.6. Provisioning].
+
+h2. Log shell
+
+The log shell contains a few commands to display the log entries, retrieve or change the log levels:
+
+|| Command || Description ||
+| display | Display log entries. |
+| display-exception | Display the last exception from the log. |
+| get | Show log level. |
+| set | Set log level. |
+
+See the documentation on the [logging system|4.3. Logging system#Commands] for more informations.
+
+h2. OBR shell
+
+OBR ([OSGi Bundle Repository|http://www2.osgi.org/Repository]) 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.
+
+Note that this feature is not installed by default. To install it, you must run the following command:
+{code}
+karaf@root:/> features:install obr
+{code}
+
+|| Command || Description ||
+| addUrl | Add a list of repository URLs to the repository service |
+| deploy | Deploy |
+| info | Display the meta-data for the specified bundles. |
+| list | List |
+| listUrl | Display the repository URLs currently associated with the repository service. |
+| removeUrl | Remove a list of repository URLs from the repository service |
+| source | Source |
+| start | Start |
+
+h2. OSGi shell
+
+The OSGi sub-shell provides commands for managing the OSGi framework: listing OSGi bundles, services, managing bundle lifecycles.
+Look at the online help (launch {{osgi help}} command) for more informations.
+
+|| Command || Description ||
+| bundle-level | Get or set the start level of a given bundle |
+| headers | Display headers |
+| install | Install bundle |
+| list | List bundles |
+| ls | List services |
+| refresh | Refresh bundle |
+| update | Update bundle |
+| resolve | Resolve bundle |
+| shutdown | Shutdown |
+| start | Start bundle |
+| start-level | Get or set the start level |
+| stop | Stop bundle |
+| uninstall | Uninstall bundle |
+
+h2. Package shell
+
+|| Command || Description ||
+| imports | Display imported packages |
+| exports | Display exported packages |
+
+h2. Shell shell
+
+|| Command || Description ||
+| cat | Displays the content of a file or url |
+| echo | Echoes or prints arguments to STDOUT |
+| exec | Executes system processes |
+| grep | Prints lines matching the given pattern |
+| info | Prints system informations |
+| java | Execute a Java standard application |
+| printf | Format and print arguments |
+| sleep | Sleeps for a bit then wakes up |
+| sort | Write sorted concatenation of all files to standard output. |
+| tac | Captures the STDIN and returns it as a string. Optionally writes the content to a file |
+
+
+Examples:
+{code}
+cat mvn:org.apache.servicemix/servicemix/3.2.1/pom
+{code}
+or
+{code}
+log:display | grep error
+{code}
+
+h2. SSH shell
+
+|| Command || Description ||
+| ssh | Connects to a remote SSH server |
+| sshd | Creates a SSH server |
+
+h2. Wrapper shell
+
+Note that this feature is not installed by default. To install it, you must run the following command:
+{code}
+karaf@root:/> features:install wrapper
+{code}
+
+|| Command || Description ||
+| install | Install the container as a system service in the OS. |
+
+[#top]
+{scrollbar}
Added: karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.2.-remote-console.page
URL: http://svn.apache.org/viewvc/karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.2.-remote-console.page?rev=1068812&view=auto
==============================================================================
--- karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.2.-remote-console.page (added)
+++ karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.2.-remote-console.page Wed Feb 9 09:38:50 2011
@@ -0,0 +1,127 @@
+---
+title: 4.2. Remote Console
+page_version: 23
+page_creator: gnodet
+page_modifier: gnodet
+--- pipeline:conf
+{scrollbar}
+{anchor:top}
+
+h1. 4.2. Remote Console
+
+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.
+
+h2. Launch options
+
+The Karaf shell scripts supports a number of options to control the remote console:
+* *{{console}}*: launch Karaf in the default mode (both local and remote console activated). This is the default mode
+* *{{server}}*: launch Karaf in with a remote console but no local console
+* *{{client}}*: launch Karaf in with a local console only
+
+These options affect two system properties that can be set if you don't use the standard shell scripts:
+* {{karaf.startLocalConsole}}
+* {{karaf.startRemoteShell}}
+
+h2. Using the client jar
+
+It is also possible to use a more lightweight way to connect to a Karaf instance using the following command line:
+{code}
+java -jar lib/karaf-client.jar
+{code}
+
+There are a few parameters that can be set on the command line to change the URL used to connect to Karaf, the user or the password.
+All these parameters are detailed in the help screen:
+
+{code:borderStyle=solid}
+> java -jar lib/karaf-client.jar --help
+Apache Karaf client
+ -a [port] specify the port 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
+ -v raise verbosity
+ -r [attempts] retry connection establishment (up to attempts times)
+ -d [delay] intra-retry delay (defaults to 2 seconds)
+ [commands] commands to run
+If no commands are specified, the client will be put in an interactive mode
+{code}
+
+For example, to shut down Karaf from the command line, you can run the following command:
+
+{code:borderStyle=solid}
+> java -jar lib/karaf-client.jar
+smx@root:/> osgi:shutdown
+smx@root:/>
+>
+{code}
+
+The client jar also supports passing command line arguments to the remote Karaf.
+{code}
+> java -jar lib/karaf-client.jar osgi:shutdown
+>
+{code}
+
+[#top]
+
+h2. Using an SSH client
+
+You can use any standard SSH client to connect to a Karaf instance. The default port is 8101.
+
+{code}
+> ssh -p 8101 -l karaf localhost
+karaf@localhost's password: karaf
+karaf@root:/>
+{code}
+
+[#top]
+
+h2. Using another Karaf instance
+
+First, open a terminal and launch Karaf in server mode (you could use a Karaf instance in console mode too):
+{code}
+bin/karaf server
+{code}
+
+On another terminal, start another Karaf instance in client mode:
+{code}
+bin/karaf client
+{code}
+
+{tip:title=User another Karaf instance to start the client}
+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.
+{tip}
+
+Once the console appears, you can run the {{remote rsh}} command to connect to the other Kernel:
+{code}
+ssh:ssh -l karaf -P karaf -p 8101 localhost
+{code}
+
+To verify that your are connected to the remote instance, run the following command:
+{code}
+info
+{code}
+and check the system informations.
+
+h3. Configuration
+
+The TCP port is configured at the following location:
+{code}
+[KARAF]/etc/org.apache.karaf.shell.cfg
+{code}
+
+The defaut configuration is as below:
+{code}
+sshPort=8102
+sshHost=0.0.0.0
+sshRealm=karaf
+hostKey=${karaf.base}/etc/host.key
+{code}
+
+The port used can easily be changed by changing the default port {{8101}} in the {{sshPort}} property.
+
+The security realm used by the console when authenticating remote users is named {{karaf}}, so you can override this realm as explained in the [security section|4.5. Security framework].
+
+[#top]
+{scrollbar}
+
Added: karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.3.-logging-system.page
URL: http://svn.apache.org/viewvc/karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.3.-logging-system.page?rev=1068812&view=auto
==============================================================================
--- karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.3.-logging-system.page (added)
+++ karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.3.-logging-system.page Wed Feb 9 09:38:50 2011
@@ -0,0 +1,49 @@
+---
+title: 4.3. Logging system
+page_version: 8
+page_creator: gnodet
+page_modifier: gnodet
+--- pipeline:conf
+{scrollbar}
+{anchor:top}
+
+h1. 4.3. Logging system
+
+Karaf provides a powerful logging system based on [OPS4j Pax Logging|http://wiki.ops4j.org/confluence/display/ops4j/Pax+Logging].
+
+In addition to being a standard OSGi Log service, it supports the following APIs:
+* Apache Commons Logging
+* SLF4J
+* Apache Log4j
+* Java Util Logging
+
+Karaf also comes with a set of console commands that can be used to display, view and change the log levels.
+
+h2. Configuration
+
+The configuration of the logging system uses a [standard Log4j configuration file|http://logging.apache.org/log4j/1.2/manual.html] at the following location:
+{code}
+[karaf]/etc/org.ops4j.pax.logging.cfg
+{code}
+
+You can edit this file at runtime and any change will be reloaded and be effective immediately.
+
+h2. Commands
+
+The log subshell comes with 3 commands:
+* {{log:display}}: display the last log entries
+* {{log:display-exception}}: display the last exception from the log
+* {{log:get}}: show the log levels
+* {{log:set}}: set the log levels
+
+For example, if you want to debug something, you might want to run the following commands:
+{code}
+> log:set DEBUG
+... do something ...
+> log:display
+{code}
+
+Note that the log levels set using the {{log:set}} commands are not persistent and will be lost upon restart.
+To configure those in a persistent way, you should edit the configuration file mentioned above.
+[#top]
+{scrollbar}
Added: karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.4.-deployer.page
URL: http://svn.apache.org/viewvc/karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.4.-deployer.page?rev=1068812&view=auto
==============================================================================
--- karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.4.-deployer.page (added)
+++ karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.4.-deployer.page Wed Feb 9 09:38:50 2011
@@ -0,0 +1,61 @@
+---
+title: 4.4. Deployer
+page_version: 11
+page_creator: gnodet
+page_modifier: gnodet
+--- pipeline:conf
+{scrollbar}
+{anchor:top}
+
+h1. 4.4. Deployer
+
+The following picture describes the architecture of the deployer.
+
+!/images/smx4-deployer.png!
+
+h2. Spring deployer
+
+Karaf includes a deployer that is able to deploy plain blueprint or spring-dm configuration files.
+The deployer will transform on the fly any spring configuration file dropped into the {{deploy}} folder into a valid OSGi bundle.
+
+The generated OSGi manifest will contain the following headers:
+
+{code}
+Manifest-Version: 2
+Bundle-SymbolicName: [name of the file]
+Bundle-Version: [version of the file]
+Spring-Context: *;publish-context:=false;create-asynchronously:=true
+Import-Package: [required packages]
+DynamicImport-Package: *
+{code}
+
+The {{name}} and {{version}} of the file are extracted using a heuristic that will match common patterns. For example {{my-config-1.0.1.xml}} will lead to {{name = my-config}} and {{version = 1.0.1}}.
+The default imported packages are extracted from the spring file definition and includes all classes referenced directly.
+
+If you need to customize the generated manifest, you can do so by including an xml element in your spring configuration:
+
+{code:lang=xml}
+<spring:beans ...>
+ <manifest>
+ Require-Bundle= my-bundle
+ </manifest>
+{code}
+
+h2. Features deployer
+
+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.
+If you want to install a single feature, you can do so by writing a feature descriptor like the following:
+
+{code:lang=xml}
+<features>
+ <repository>mvn:org.apache.servicemix.nmr/apache-servicemix-nmr/1.0.0/xml/features</repository>
+ <feature name="nmr-only">
+ <feature>nmr</feature>
+ </feature>
+</features>
+{code}
+
+For more informations about features, see the [provisioning section|4.6. Provisioning].
+
+[#top]
+{scrollbar}
\ No newline at end of file
Added: karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.5.-security-framework.page
URL: http://svn.apache.org/viewvc/karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.5.-security-framework.page?rev=1068812&view=auto
==============================================================================
--- karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.5.-security-framework.page (added)
+++ karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.5.-security-framework.page Wed Feb 9 09:38:50 2011
@@ -0,0 +1,116 @@
+---
+title: 4.5. Security framework
+page_version: 12
+page_creator: gnodet
+page_modifier: iocanel
+--- pipeline:conf
+{scrollbar}
+{anchor:top}
+
+h1. 4.5. Security framework
+
+Karaf supports [JAAS|http://java.sun.com/j2se/1.4.2/docs/guide/security/jaas/JAASRefGuide.html] 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.
+
+h2. Overview
+
+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 {{karaf}} realm, but which is configured with a dummy login module by default. These realms can also be used by the NMR, JBI components or the JMX server to authenticate users logging in or sending messages into the bus.
+
+In addition to JAAS realms, you can also deploy keystores and truststores to secure the remote shell console, setting up HTTPS connectors or using certificates for WS-Security.
+
+A very simple XML schema for spring has been defined, allowing the deployment of a new realm or a new keystore very easily.
+
+h2. Schema
+
+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.
+
+{code:lang=xml|title=JAAS XSD Schema}
+<xs:schema elementFormDefault='qualified'
+ targetNamespace='http://karaf.apache.org/xmlns/jaas/v1.0.0'
+ xmlns:xs='http://www.w3.org/2001/XMLSchema'
+ xmlns:bp="http://www.osgi.org/xmlns/blueprint/v1.0.0"
+ xmlns:tns='http://karaf.apache.org/xmlns/jaas/v1.0.0'>
+
+ <xs:import namespace="http://www.osgi.org/xmlns/blueprint/v1.0.0"/>
+
+ <xs:element name="config">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="module" minOccurs="0" maxOccurs="unbounded">
+ <xs:complexType mixed="true">
+ <xs:attribute name="className" use="required" type="xs:string" />
+ <xs:attribute name="flags" default="required">
+ <xs:simpleType>
+ <xs:restriction base="xs:NMTOKEN">
+ <xs:enumeration value="required"/>
+ <xs:enumeration value="requisite"/>
+ <xs:enumeration value="sufficient"/>
+ <xs:enumeration value="optional"/>
+ </xs:restriction>
+ </xs:simpleType>
+ </xs:attribute>
+ </xs:complexType>
+ </xs:element>
+ </xs:sequence>
+ <xs:attribute name="name" use="required" type="xs:string" />
+ <xs:attribute name="rank" use="optional" default="0" type="xs:int" />
+ </xs:complexType>
+ </xs:element>
+
+ <xs:element name="keystore">
+ <xs:complexType>
+ <xs:attribute name="name" use="required" type="xs:string" />
+ <xs:attribute name="rank" use="optional" default="0" type="xs:int" />
+ <xs:attribute name="path" use="required" type="xs:string" />
+ <xs:attribute name="keystorePassword" use="optional" type="xs:string" />
+ <xs:attribute name="keyPasswords" use="optional" type="xs:string" />
+ </xs:complexType>
+ </xs:element>
+
+</xs:schema>
+{code}
+
+You can find the schema at the following [location|https://svn.apache.org/repos/asf/karaf/tags/karaf-2.0.0/jaas/config/src/main/resources/org/apache/karaf/jaas/config/karaf-jaas.xsd].
+
+Here are two example using this schema:
+{code:lang=xml|title=JAAS realm example}
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
+ xmlns:jaas="http://karaf.apache.org/xmlns/jaas/v1.0.0"
+ xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0">
+
+ <!-- Bean to allow the $[karaf.base] property to be correctly resolved -->
+ <ext:property-placeholder placeholder-prefix="$[" placeholder-suffix="]"/>
+
+ <jaas:config name="karaf">
+ <jaas:module className="org.apache.karaf.jaas.modules.properties.PropertiesLoginModule" flags="required">
+ users = $[karaf.base]/etc/users.properties
+ </jaas:module>
+ </jaas:config>
+
+</blueprint>
+{code}
+{code:lang=xml|title=Keystore example}
+<jaas:keystore xmlns:jaas="http://karaf.apache.org/xmlns/jaas/v1.0.0"
+ id="keystore"
+ name="ks"
+ rank="1"
+ path="classpath:privatestore.jks"
+ keystorePassword="keyStorePassword"
+ keyPasswords="myalias=myAliasPassword">
+</jaas:keystore>
+{code}
+
+The {{id}} attribute is the blueprint id of the bean, but it will be used by default as the name of the realm if no {{name}} attribute is specified. Additional attributes on the {{config}} elements are a {{rank}}, which is an integer. When the LoginContext looks for a realm for authenticating a given user, the realms registered in the OSGi registry are matched against the required name. If more than one realm is found, the one with the highest rank will be used, thus allowing the override of some realms with new values. The last attribute is {{publish}} which can be set to false to not publish the realm in the OSGi registry, hereby disabling the use of this realm.
+
+Each realm can contain one or more module definition. Each module identify a LoginModule and the {{className}} attribute must be set to the class name of the login module to use. Note that this login module must be available from the bundle classloader, so either it has to be defined in the bundle itself, or the needed package needs to be correctly imported. The {{flags}} attribute can take one of four values that are explained on the [JAAS documentation|http://svn.apache.org/repos/asf/karaf/tags/karaf-2.0.0/jaas/boot/src/main/java/org/apache/karaf/jaas/boot/ProxyLoginModule.java].
+The content of the {{module}} element is parsed as a properties file and will be used to further configure the login module.
+
+Deploying such a code will lead to a [JaasRealm|http://svn.apache.org/repos/asf/karaf/tags/karaf-2.0.0/jaas/config/src/main/java/org/apache/karaf/jaas/config/JaasRealm.java] object in the OSGi registry, which will then be used when using the JAAS login module.
+
+h2. Architecture
+
+Due to constraints in the JAAS specification, one class has to be available for all bundles. This class is called [ProxyLoginModule|http://svn.apache.org/repos/asf/karaf/tags/karaf-2.0.0/jaas/boot/src/main/java/org/apache/karaf/jaas/boot/ProxyLoginModule.java] and is a LoginModule that acts as a proxy for an OSGi defines LoginModule. If you plan to integrate this feature into another OSGi runtime, this class must be made available from the system classloader and the related package be part of the boot delegation classpath (or be deployed as a fragment attached to the system bundle).
+
+The xml schema defined above 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 [JaasRealm|http://svn.apache.org/repos/asf/karaf/tags/karaf-2.0.0/jaas/config/src/main/java/org/apache/karaf/jaas/config/JaasRealm.java] 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.
+
+[#top]
+{scrollbar}
\ No newline at end of file
Added: karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.6.-provisioning.page
URL: http://svn.apache.org/viewvc/karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.6.-provisioning.page?rev=1068812&view=auto
==============================================================================
--- karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.6.-provisioning.page (added)
+++ karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.6.-provisioning.page Wed Feb 9 09:38:50 2011
@@ -0,0 +1,299 @@
+---
+title: 4.6. Provisioning
+page_version: 24
+page_creator: gnodet
+page_modifier: christian schneider
+--- pipeline:conf
+{scrollbar}
+{anchor:top}
+
+h1. 4.6. Provisioning
+
+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 {{features}} shell. The provisioning system uses xml "repositories" that define a set of features.
+
+h2. Commands
+
+h3. Repository management
+
+The following commands can be used to manage the list of descriptors known by Karaf. They use URLs pointing to features descriptors. These URLs can use any protocol known to the Apache Karaf, the most common ones being http, file and mvn.
+
+{code}
+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
+{code}
+
+Karaf maintains a persistent list of these repositories so that if you add one URL and restart Karaf, the features will still be available.
+
+The {{refreshUrl}} 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.
+
+h4. Some Featue Repositories you might want to add
+
+|| Project || Feature Repository URL ||
+| Camel | mvn:org.apache.camel.karaf/apache-camel/2.6.0/xml/features |
+| ActiveMQ | mvn:org.apache.activemq/activemq-karaf/5.4.2/xml/features |
+
+If you know some more URLs feel free to add them here
+
+h3. Features management
+
+{code}
+features:install
+features:uninstall
+features:list
+{code}
+
+h3. Examples
+
+1. Install features using mvn handler
+{code}
+features:addUrl mvn:org.apache.servicemix.nmr/apache-servicemix-nmr/1.0.0-m2/xml/features
+features:install nmr
+{code}
+
+2. Use file handler to deploy features file
+{code}
+features:addUrl file:base/features/features.xml
+{code}
+
+Remark : The path is relative to the Apache Karaf installation directory
+
+3. Deploy bundles from file system without using maven
+
+As we can use file:// as protocol handler to deploy bundles, you can use the following syntax to deploy bundles when they are
+located in a directory which is not available using maven
+
+{code:xml}
+<features>
+ <feature name="spring-web" version="2.5.6.SEC01">
+ <bundle>file:base/bundles/spring-web-2.5.6.SEC01.jar</bundle>
+ </feature>
+</features>
+{code}
+
+Remark : The path is relative to the Apache Karaf installation directory
+
+h2. Service configuration
+
+A simple configuration file located in {{\[FELIX:karaf\]/etc/org.apache.karaf.features.cfg}} can be modified to customize the behavior when starting the Kernel for the first time.
+This configuration file contains two properties:
+* {{featuresBoot}}: a comma separated list of features to install at startup
+* {{featuresRepositories}}: a comma separated list of feature repositories to load at startup
+
+This configuration file is of interest if you plan to distribute Apache Karaf distribution which includes pre-installed features. Such a process is detailed in the [6.2. Building custom distributions] section.
+
+h2. Repositories
+
+The xml features repositories use the following Relax NG Compact syntax:
+
+{code:title=Repository schema}
+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 }*
+ }*
+}
+{code}
+
+Here is an example of such a repository:
+{code:lang=xml}
+<features>
+ <feature name="spring" version="2.5.6.SEC01">
+ <bundle>mvn:org.apache.servicemix.bundles/org.apache.servicemix.bundles.aopalliance/1.0_1</bundle>
+ <bundle>mvn:org.springframework/spring-core/2.5.6.SEC01</bundle>
+ <bundle>mvn:org.springframework/spring-beans/2.5.6.SEC01</bundle>
+ <bundle>mvn:org.springframework/spring-aop/2.5.6.SEC01</bundle>
+ <bundle>mvn:org.springframework/spring-context/2.5.6.SEC01</bundle>
+ <bundle>mvn:org.springframework/spring-context-support/2.5.6.SEC01</bundle>
+ </feature>
+</features>
+{code}
+
+A repository includes a list of {{feature}} elements, each one representing an application that can be installed. The feature is identified by its {{name}} 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.
+
+References to features define in other repositories are allow and can be achieved by adding a list of repository.
+
+{code:xml}
+<features>
+ <repository>mvn:org.apache.servicemix.nmr/apache-servicemix-nmr/1.2.0/xml/features</repository>
+ <repository>mvn:org.apache.camel.karaf/apache-camel/2.2.0/xml/features</repository>
+ <repository>mvn:org.apache.felix.karaf/apache-felix-karaf/1.4.0/xml/features</repository>
+ ...
+{code}
+
+{warning}
+Be carefull when you define them as there is a risk of 'cycling' dependencies.
+{warning}
+
+Remark : By default, all the features defined in a repository are not installed at the launch of Apache Karaf (see section hereafter 'h2. Service configuration' for more info).
+
+h3. Bundles
+
+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:
+{code:lang=xml}
+<bundle>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</bundle>
+{code}
+Doing this will make sure the above bundle is installed while installing the feature.
+
+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.
+
+h4. Maven URL Handler
+
+The equivalent of the above bundle would be:
+{code}
+<bundle>mvn:org.apache.servicemix.nmr/org.apache.servicemix.nmr.api/1.0.0-m2</bundle>
+{code}
+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.
+
+The {{org.ops4j.pax.url.mvn}} bundle resolves {{mvn}} URLs. This flexible tool can be configured through the configuration service. For example, to find the current repositories type:
+
+{code}
+karaf@root:/> 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://repo1.maven.org/maven2,
+ http://people.apache.org/repo/m2-snapshot-repository@snapshots@noreleases,
+ http://repository.ops4j.org/maven2,
+ http://svn.apache.org/repos/asf/servicemix/m2-repo
+ below = list of repositories and even before the local repository
+{code}
+
+The repositories checked are controlled by these configuration properties.
+
+For example, {{org.ops4j.pax.url.mvn.repositories}} 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 {{http://www.example.org/repo}} on the local machine:
+
+{code}
+karaf@root:/> config:edit org.ops4j.pax.url.mvn
+karaf@root:/> 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://repo1.maven.org/maven2,
+ http://people.apache.org/repo/m2-snapshot-repository@snapshots@noreleases,
+ http://repository.ops4j.org/maven2,
+ http://svn.apache.org/repos/asf/servicemix/m2-repo
+ below = list of repositories and even before the local repository
+karaf@root:/> config:propset org.ops4j.pax.url.mvn.repositories http://www.example.org/repo
+karaf@root:/> config:update
+{code}
+
+By default, snapshots are disable. To enable an URL for snapshots append @snapshots. For example
+
+{code}
+http://www.example.org/repo@snapshots
+{code}
+
+Repositories on the local are supported through {{file:/}} URLs
+
+h4. Bundle start-level
+
+*Available since Karaf 2.0*
+
+By default, the bundles deployed through the feature mechanism will have a start-level equals to the value defined in the configuration file {{config.properties}}
+with the variable {{karaf.startlevel.bundle=60}}. This value can be changed using the xml attribute start-level.
+
+{code:xml}
+ <feature name='my-project' version='1.0.0'>
+ <feature version='2.4.0'>camel-spring</feature>
+ <bundle start-level='80'>mvn:com.mycompany.myproject/myproject-dao</bundle>
+ <bundle start-level='85'>mvn:com.mycompany.myproject/myproject-service</bundle>
+ <bundle start-level='85'>mvn:com.mycompany.myproject/myproject-camel-routing</bundle>
+ </feature>
+{code}
+
+The advantage to define the start-level of a bundle is that you can deploy all your bundles including those of the project with the 'infrastructure' bundles required (e.g : camel, activemq)
+at the same time and you will have the guaranty when you use Spring Dynamic Module (to register service through OSGI service layer), Blueprint that by example
+Spring context will not be created without all the required services installed.
+
+h4. Bundle 'stop/start'
+
+*Available since Karaf 2.0*
+
+The OSGI specification allows to install a bundle without starting it. To use this functionality, simply add the following attribute in your <bundle> definition
+
+{code:xml}
+ <feature name='my-project' version='1.0.0'>
+ <feature version='2.4.0'>camel-spring</feature>
+ <bundle start-level='80' start='false'>mvn:com.mycompany.myproject/myproject-dao</bundle>
+ <bundle start-level='85' start='false'>mvn:com.mycompany.myproject/myproject-service</bundle>
+ <bundle start-level='85' start='false'>mvn:com.mycompany.myproject/myproject-camel-routing</bundle>
+ </feature>
+{code}
+
+h3. Dependent features
+
+Dependent features are useful when a given feature depends on another feature to be installed. Such a dependency can be expressed easily in the feature definition:
+{code:lang=xml}
+<feature name="jbi">
+ <feature>nmr</feature>
+ ...
+</feature>
+{code}
+
+The effect of such a dependency is to automatically install the required {{nmr}} feature when the {{jbi}} feature will be installed.
+
+h3. Configurations
+
+The configuration section allows to deploy configuration for the OSGi Configuration Admin service along a set of bundles.
+Here is an example of such a configuration:
+
+{code:lang=xml}
+<config name="com.foo.bar">
+ myProperty = myValue
+</config>
+{code}
+
+The {{name}} attribute of the {{configuration}} element will be used as the ManagedService PID for the configuration set in the Configuration Admin service. When using a ManagedServiceFactory, the {{name}} attribute is _servicePid_-_aliasId_, where _servicePid_ is the PID of the ManagedServiceFactory and _aliasId_ is a label used to uniquely identify a particular service (an alias to the factory generated service PID).
+
+Deploying such a configuration has the same effect than dropping a file named {{com.foo.bar.cfg}} into the {{etc}} folder.
+
+The content of the {{configuration}} element is set of properties parsed using the [standard java property mechanism|http://java.sun.com/j2se/1.5.0/docs/api/java/util/Properties.html#load(java.io.InputStream)].
+
+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:
+
+{code:lang=xml}
+<bean ...>
+ <property name="propertyName" value="${myProperty}" />
+</bean>
+
+<osgix:cm-properties id="cmProps" persistent-id="com.foo.bar">
+ <prop key="myProperty">myValue</prop>
+</osgix:cm-properties>
+<ctx:property-placeholder properties-ref="cmProps" />
+{code}
+
+There may also be cases where you want to make the properties from multiple configuration files available to your bundle context. This is something you may want to do if you have a multi-bundle application where there are application properties used by multiple bundles, and each bundle has its own specific properties. In that case, {{<ctx:property-placeholder>}} won't work as it was designed to make only one configuration file available to a bundle context.
+To make more than one configuration file available to your bundle-context you would do something like this:
+
+{code:lang=xml}
+<beans:bean id="myBundleConfigurer"
+ class="org.springframework.beans.factory.config.PropertyPlaceholderConfig">
+ <beans:property name="ignoreUnresolvablePlaceholders" value="true"/>
+ <beans:property name="propertiesArray">
+ <osgix:cm-properties id="myAppProps" persistent-id="myApp.props"/>
+ <osgix:cm-properties id="myBundleProps" persistent-id="my.bundle.props"/>
+ </beans:property>
+</beans:bean>
+{code}
+
+In this example, we are using SpringDM with osgi as the primary namespace. Instead of using ctx:context-placeholder we are using the "PropertyPlaceholderConfig" class. Then we are passing in a beans array and inside of that array is where we set our osgix:cm-properties elements. This element "returns" a properties bean.
+
+For more informations about using the Configuration Admin service in Spring-DM, see the [Spring-DM documentation|http://static.springframework.org/osgi/docs/1.2.0-m2/reference/html/compendium.html#compendium:cm:props].
+
+[#top]
+{scrollbar}
\ No newline at end of file
Added: karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.7.-administration.page
URL: http://svn.apache.org/viewvc/karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.7.-administration.page?rev=1068812&view=auto
==============================================================================
--- karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.7.-administration.page (added)
+++ karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.7.-administration.page Wed Feb 9 09:38:50 2011
@@ -0,0 +1,26 @@
+---
+title: 4.7. Administration
+page_version: 6
+page_creator: gnodet
+page_modifier: gnodet
+--- pipeline:conf
+{scrollbar}
+{anchor:top}
+
+h1. 4.7. Administration
+
+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 {{data}} folder which contains all runtime informations, logs and temporary files.
+
+|| Commands || Description ||
+| change-port | Changes the port of an existing container instance. |
+| connect | Connects to an existing container instance. |
+| create | Creates a new container instance. |
+| destroy | Destroys an existing container instance. |
+| list | List all existing container instances. |
+| start | Starts an existing container instance. |
+| stop | Stops an existing container instance. |
+
+Those commands are also available from outside the OSGi environment using the {{admin}}/{{admin.bat}} script in the {{bin}} folder.
+
+[#top]
+{scrollbar}
\ No newline at end of file
Added: karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.8.-configuration.page
URL: http://svn.apache.org/viewvc/karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.8.-configuration.page?rev=1068812&view=auto
==============================================================================
--- karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.8.-configuration.page (added)
+++ karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/4.-understanding-karaf/4.8.-configuration.page Wed Feb 9 09:38:50 2011
@@ -0,0 +1,54 @@
+---
+title: 4.8. Configuration
+page_version: 4
+page_creator: robert burrell donkin
+page_modifier: gnodet
+--- pipeline:conf
+{scrollbar}
+{anchor:top}
+
+h1. 4.8. Configuration
+
+The files in the {{etc}} directory are used to set the startup configuration.
+
+For dynamic configuration, Karaf provides a suite of command to administer the configuration service grouped under {{config}}. To learn about all currently supported configuration commands type:
+
+|| Command || Description ||
+| cancel | Change the changes to the configuration being edited. |
+| edit | Create or edit a configuration. |
+| list | List existing configurations. |
+| propdel | Delete a property from the edited configuration. |
+| proplist | List properties from the edited configuration. |
+| propset | Set a property on the edited configuration. |
+| update | Save and propagate changes from the configuration being edited. |
+
+
+h2. Editing
+
+h3. Select Configuration To Edit
+
+For example to edit configuration {{foo.bar}}:
+
+{code}
+karaf@root:/> config:edit foo.bar
+{code}
+
+h3. Modify Properties
+
+Use:
+
+ * {{config:proplist}} to list existing properties
+ * {{config:propdel}} to delete existing properties
+ * {{config:propset}} to set a new value for a property
+
+Any number of properties can be modified within a single editing session.
+
+h3. Commit Or Rollback Changes
+
+Use
+
+ * {{config:update}} to commit all changes made in the current session
+ * {{config:cancel}} to roll back any changes made in the current session
+
+[#top]
+{scrollbar}
\ No newline at end of file
Added: karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf.page
URL: http://svn.apache.org/viewvc/karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf.page?rev=1068812&view=auto
==============================================================================
--- karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf.page (added)
+++ karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf.page Wed Feb 9 09:38:50 2011
@@ -0,0 +1,15 @@
+---
+title: 5. Using Karaf
+page_version: 4
+page_creator: gnodet
+page_modifier: gnodet
+--- pipeline:conf
+{scrollbar}
+{anchor:top}
+
+h1. 5. Using Karaf
+
+{children:all}
+
+[#top]
+{scrollbar}
\ No newline at end of file
Added: karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf/5.1.-troubleshooting-debugging-and-profiling.page
URL: http://svn.apache.org/viewvc/karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf/5.1.-troubleshooting-debugging-and-profiling.page?rev=1068812&view=auto
==============================================================================
--- karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf/5.1.-troubleshooting-debugging-and-profiling.page (added)
+++ karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf/5.1.-troubleshooting-debugging-and-profiling.page Wed Feb 9 09:38:50 2011
@@ -0,0 +1,102 @@
+---
+title: 5.1. Troubleshooting, Debugging and Profiling
+page_version: 16
+page_creator: gnodet
+page_modifier: gnodet
+--- pipeline:conf
+{scrollbar}
+{anchor:top}
+
+h1. 5.1. Troubleshooting, Debugging and Profiling
+
+h2. Troubleshooting
+
+h3. Logging
+
+Logging is easy to control through the console, with commands grouped under _log_ shell. To learn about the available logging commands type:
+
+{code}
+karaf@root> log<tab>
+
+log:display log:display-exception log:get log:set
+karaf@root>
+{code}
+
+Typical usage is:
+
+ # Use {{log:set}} to dynamically change the global log level
+ # Execute the problematic operation
+ # Use {{log:display}} (or {{log:display-exception}} to display the log
+
+
+
+h3. Worst Case Scenario
+
+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 {{data}} directory just in the installation directory. This folder contains transient data and will be recreated if you remove it and relaunch Karaf.
+You may also want to remove the files in the {{deploy}} folder to avoid them being automatically installed when Karaf is started the first time.
+
+h2. Debugging
+
+Usually, the easiest way to debug Karaf or any application deployed onto it is to use remote debugging.
+Remote debugging can be easily activated by setting the {{KARAF_DEBUG}} environment variable to {{TRUE}}.
+
+This can be done using the following command on Unix systems:
+{noformat}
+export KARAF_DEBUG=true
+{noformat}
+
+On Windows, use the following command
+{noformat}
+set KARAF_DEBUG=true
+{noformat}
+
+Then, you can launch Karaf using the usual way:
+{noformat}
+bin/karaf
+{noformat}
+or
+{noformat}
+bin\karaf.bat
+{noformat}
+
+Last, inside your IDE, connect to the remote application (the default port to connect to is 5005).
+
+This option works fine when we have to debug a project deployed top of Apache Karaf. Nervertheless, you will be blocked if you would like to debug the server Karaf. In this case, you can change the following parameter suspend=y in the karaf.bat script file. That will cause the JVM to pause just before running main() until you attach a debugger then it will resume the execution. This way you can set
+your breakpoints anywhere in the code and you should hit them no matter how early in the startup they are
+
+{code}
+export DEFAULT_JAVA_DEBUG_OPTS='-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005'
+{code}
+and on Windows,
+{code}
+set DEFAULT_JAVA_DEBUG_OPTS='-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005'
+{code}
+
+
+[#top]
+
+h2. Profiling
+
+h3. YourKit
+
+You need a few steps to be able to profile Karaf using YourKit.
+The first one is to edit the {{etc/config.properties}} configuration file and add the following property:
+{noformat}
+org.osgi.framework.bootdelegation=com.yourkit.*
+{noformat}
+
+Then, set the {{JAVA_OPTS}} environment variable:
+{noformat}
+export JAVA_OPTS='-Xmx512M -agentlib:yjpagent'
+{noformat}
+
+or, on Windows
+
+{noformat}
+set JAVA_OPTS='-Xmx512M -agentlib:yjpagent'
+{noformat}
+
+Run Karaf from the console, and you should now be able to connect using YourKit standalone or from your favorite IDE.
+
+[#top]
+{scrollbar}
Added: karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf/5.2.-developping-applications.page
URL: http://svn.apache.org/viewvc/karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf/5.2.-developping-applications.page?rev=1068812&view=auto
==============================================================================
--- karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf/5.2.-developping-applications.page (added)
+++ karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf/5.2.-developping-applications.page Wed Feb 9 09:38:50 2011
@@ -0,0 +1,15 @@
+---
+title: 5.2. Developping applications
+page_version: 6
+page_creator: gnodet
+page_modifier: gnodet
+--- pipeline:conf
+{scrollbar}
+{anchor:top}
+
+h1. 5.2. Developping applications
+
+TODO
+
+[#top]
+{scrollbar}
Added: karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf/5.3.-creating-bundles-for-third-party-dependencies.page
URL: http://svn.apache.org/viewvc/karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf/5.3.-creating-bundles-for-third-party-dependencies.page?rev=1068812&view=auto
==============================================================================
--- karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf/5.3.-creating-bundles-for-third-party-dependencies.page (added)
+++ karaf/sandbox/website/src/main/webapp/index/documentation/karaf-users-guide/5.-using-karaf/5.3.-creating-bundles-for-third-party-dependencies.page Wed Feb 9 09:38:50 2011
@@ -0,0 +1,17 @@
+---
+title: 5.3. Creating bundles for third party dependencies
+page_version: 4
+page_creator: gnodet
+page_modifier: tmoloney
+--- pipeline:conf
+{scrollbar}
+{anchor:top}
+
+h1. 5.3. Creating bundles for third party dependencies
+
+TODO
+
+Some infos available at [http://gnodet.blogspot.com/2008/09/id-like-to-talk-bit-about-third-party.html], [http://blog.springsource.com/2008/02/18/creating-osgi-bundles/] and [http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html].
+
+[#top]
+{scrollbar}
\ No newline at end of file