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 2010/10/18 10:10:20 UTC
svn commit: r1023680 [2/2] - in /karaf/trunk: ./ documentation/
documentation/src/ documentation/src/main/ documentation/src/main/webapp/
documentation/src/main/webapp/WEB-INF/
documentation/src/main/webapp/WEB-INF/scalate/
documentation/src/main/webap...
Added: karaf/trunk/documentation/src/main/webapp/users-guide/colorized-console.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/documentation/src/main/webapp/users-guide/colorized-console.conf?rev=1023680&view=auto
==============================================================================
--- karaf/trunk/documentation/src/main/webapp/users-guide/colorized-console.conf (added)
+++ karaf/trunk/documentation/src/main/webapp/users-guide/colorized-console.conf Mon Oct 18 08:10:19 2010
@@ -0,0 +1,25 @@
+h1. Enabling Colorized Console on Windows
+
+
+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 [JNA|https://jna.dev.java.net/]. This can be done using a few simple commands in the Karaf console:
+
+You first need to install the JNA library:
+{code}
+osgi:install wrap:mvn:http://download.java.net/maven/2!net.java.dev.jna/jna/3.1.0
+{code}
+
+Next you need either restart karaf or you run the following Karaf commands to refresh the Karaf Console:
+
+{code}
+osgi:list | grep "Apache Karaf :: Shell Console"
+{code}
+
+Take note of the ID of the bundle, in my case it was 14 and then run:
+
+{code}
+osgi:refresh 14
+{code}
+
+{warning}
+TODO: refactor that using a nicer script to find the correct bundle
+{warning}
\ No newline at end of file
Added: karaf/trunk/documentation/src/main/webapp/users-guide/configuration.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/documentation/src/main/webapp/users-guide/configuration.conf?rev=1023680&view=auto
==============================================================================
--- karaf/trunk/documentation/src/main/webapp/users-guide/configuration.conf (added)
+++ karaf/trunk/documentation/src/main/webapp/users-guide/configuration.conf Mon Oct 18 08:10:19 2010
@@ -0,0 +1,46 @@
+
+
+h1. 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
+
+
Added: karaf/trunk/documentation/src/main/webapp/users-guide/deployer.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/documentation/src/main/webapp/users-guide/deployer.conf?rev=1023680&view=auto
==============================================================================
--- karaf/trunk/documentation/src/main/webapp/users-guide/deployer.conf (added)
+++ karaf/trunk/documentation/src/main/webapp/users-guide/deployer.conf Mon Oct 18 08:10:19 2010
@@ -0,0 +1,70 @@
+
+
+h1. Deployer
+
+The following picture describes the architecture of the deployer.
+
+!images/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|provisioning].
+
+h2. War deployer
+
+To be able to hot deploy web application (war) from the deploy folder, you have to install the war feature:
+
+{code}
+karaf@root> features:install war
+{code}
+
+You should now be able to see the war deployer:
+
+{code}
+karaf@root> osgi:list |grep "WAR Deployer"
+[ 42] [Active ] [Created ] [ 60] Apache Karaf :: WAR Deployer (2.0.1.SNAPSHOT)
+{code}
+
+You can deploy a web application packaged in war or exploded in a directory.
+
+Your web application should at least contain a WEB-INF/web.xml file.
\ No newline at end of file
Added: karaf/trunk/documentation/src/main/webapp/users-guide/directory-structure.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/documentation/src/main/webapp/users-guide/directory-structure.conf?rev=1023680&view=auto
==============================================================================
--- karaf/trunk/documentation/src/main/webapp/users-guide/directory-structure.conf (added)
+++ karaf/trunk/documentation/src/main/webapp/users-guide/directory-structure.conf Mon Oct 18 08:10:19 2010
@@ -0,0 +1,21 @@
+h1. Directory structure
+
+The directory layout of a Karaf installation is as follows:
+* {{/bin}}: startup scripts
+* {{/etc}}: configuration files
+* {{/data}}: working directory
+** {{/cache}}: OSGi framework bundle cache
+** {{/generated-bundles}}: temporary folder used by the deployer
+** {{/log}}: log files
+* {{/deploy}}: hot deploy directory
+* {{/instances}}: directory containing [child instances|child-instances]
+* {{/lib}}: contains the bootstrap libraries
+** {{/lib/ext}}: directory for JRE extensions
+** {{/lib/endorsed}}: directory for endorsed libraries
+* {{/system}}: OSGi bundles repository, laid out as a Maven 2 repository
+
+{tip}
+The {{data}} folder contains all the working and temporary files for Karaf. If you want to restart from a clean state, you can wipe out this directory, which has the same effect as [using the clean option|start-stop#Starting Karaf from clean].
+{tip}
+
+
Added: karaf/trunk/documentation/src/main/webapp/users-guide/failover.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/documentation/src/main/webapp/users-guide/failover.conf?rev=1023680&view=auto
==============================================================================
--- karaf/trunk/documentation/src/main/webapp/users-guide/failover.conf (added)
+++ karaf/trunk/documentation/src/main/webapp/users-guide/failover.conf Mon Oct 18 08:10:19 2010
@@ -0,0 +1,115 @@
+h1. Failover Deployments
+
+Karaf provides failover capability using either a simple lock file system or a JDBC locking mechanism. In both cases, a container-level lock system allows bundles to be preloaded into the slave Karaf instance in order to provide faster failover performance.
+
+h2. Simple lock file
+
+The simple lock file mechanism is intended for failover configurations where instances reside on the same host machine.
+
+To use this feature, edit the {{$KARAF_HOME/etc/system.properties}} file as follows on each system in the master/slave setup:
+
+{noformat}
+karaf.lock=true
+karaf.lock.class=org.apache.felix.karaf.main.SimpleFileLock
+karaf.lock.dir=<PathToLockFileDirectory>
+karaf.lock.delay=10
+{noformat}
+
+*Note*: Ensure that the {{karaf.lock.dir}} property points to the same directory for both the master and slave instance, so that the slave can only acquire the lock when the master releases it.
+
+
+h2. JDBC locking
+
+The JDBC locking mechanism is intended for failover configurations where instances exist on separate machines. In this deployment, the master instance holds a lock on a Karaf locking table hosted on a database. If the master loses the lock, a waiting slave process gains access to the locking table and fully starts its container.
+
+To use this feature, do the following on each system in the master/slave setup:
+
+* Update the classpath to include the JDBC driver
+* Update the {{$KARAF_HOME/bin/karaf}} script to have unique JMX remote port set if instances reside on the same host
+* Update the {{$KARAF_HOME/etc/system.properties}} file as follows:
+
+{noformat}
+karaf.lock=true
+karaf.lock.class=org.apache.felix.karaf.main.DefaultJDBCLock
+karaf.lock.level=50
+karaf.lock.delay=10
+karaf.lock.jdbc.url=jdbc:derby://dbserver:1527/sample
+karaf.lock.jdbc.driver=org.apache.derby.jdbc.ClientDriver
+karaf.lock.jdbc.user=user
+karaf.lock.jdbc.password=password
+karaf.lock.jdbc.table=KARAF_LOCK
+karaf.lock.jdbc.clustername=karaf
+karaf.lock.jdbc.timeout=30
+{noformat}
+
+*Note*:
+
+* Will fail if JDBC driver is not on classpath.
+* The database name "sample" will be created if it does not exist on the database.
+* The first Karaf instance to acquire the locking table is the master instance.
+* If the connection to the database is lost, the master instance tries to gracefully shutdown, allowing a slave instance to become master when the database service is restored. The former master will require manual restart.
+
+h3. JDBC locking on Oracle
+
+If you are using Oracle as your database in a JDBC locking scenario, the {{karaf.lock.class}} property in the {{$KARAF_HOME/etc/system.properties}} file must point to {{org.apache.felix.karaf.main.OracleJDBCLock}}.
+
+Otherwise, configure the system.properties file as normal for your setup, for example:
+
+{noformat}
+karaf.lock=true
+karaf.lock.class=org.apache.felix.karaf.main.OracleJDBCLock
+karaf.lock.jdbc.url=jdbc:oracle:thin:@hostname:1521:XE
+karaf.lock.jdbc.driver=oracle.jdbc.OracleDriver
+karaf.lock.jdbc.user=user
+karaf.lock.jdbc.password=password
+karaf.lock.jdbc.table=KARAF_LOCK
+karaf.lock.jdbc.clustername=karaf
+karaf.lock.jdbc.timeout=30
+{noformat}
+
+As with the default JDBC locking setup, the Oracle JDBC driver JAR file must be in your classpath. You can ensure this by copying the {{ojdbc14.jar}} into Karaf's {{lib}} folder before starting Karaf.
+
+*Note*: The {{karaf.lock.jdbc.url}} requires an active SID, which means you must manually create a database instance before using this particular lock.
+
+h3. Derby
+
+{warning}
+TODO
+{warning}
+
+h3. MySQL
+
+{warning}
+TODO
+{warning}
+
+
+{anchor:locklevel}
+
+h2. Container-level locking
+
+Container-level locking allows bundles to be preloaded into the slave kernel instance in order to provide faster failover performance. Container-level locking is supported in both the simple file and JDBC locking mechanisms.
+
+To implement container-level locking, add the following to the {{$KARAF_HOME/etc/system.properties}} file on each system in the master/slave setup:
+
+{noformat}
+karaf.lock=true
+karaf.lock.level=50
+karaf.lock.delay=10
+{noformat}
+
+The {{karaf.log.level}} property tells the Karaf instance how far up the boot process to bring the OSGi container. Bundles assigned the same start level or lower will then also be started in that Karaf instance.
+
+Bundle start levels are specified in {{$KARAF_HOME/etc/startup.properties}}, in the format {{jar.name=level}}. The core system bundles have levels below 50, where as user bundles have levels greater than 50.
+
+|| Level || Behavior ||
+| 1 | A 'cold' standby instance. Core bundles are not loaded into container. Slaves will wait until lock acquired to start server. |
+| <50 | A 'hot' standby instance. Core bundles are loaded into the container. Slaves will wait until lock acquired to start user level bundles. The console will be accessible for each slave instance at this level. |
+| >50 | This setting is not recommended as user bundles will be started. |
+
+*Note*: When using a 'hot' spare on the same host you need to set the JMX remote port to a unique value to avoid bind conflicts. You can edit the Karaf start script to include the following:
+
+{noformat}
+DEFAULT_JAVA_OPTS="-server $DEFAULT_JAVA_OPTS -Dcom.sun.management.jmxremote.port=1100 -Dcom.sun.management.jmxremote.authenticate=false"
+{noformat}
+
Added: karaf/trunk/documentation/src/main/webapp/users-guide/index.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/documentation/src/main/webapp/users-guide/index.conf?rev=1023680&view=auto
==============================================================================
--- karaf/trunk/documentation/src/main/webapp/users-guide/index.conf (added)
+++ karaf/trunk/documentation/src/main/webapp/users-guide/index.conf Mon Oct 18 08:10:19 2010
@@ -0,0 +1,17 @@
+h1. Karaf Users Guide
+
+* [Installing Karaf|installation]
+* [Directory Structure|directory-structure]
+* [Starting and stopping Karaf|start-stop]
+* [Using the console|using-console]
+* [Web console|web-console]
+* [Remote console|remote-console]
+* [Child instances|child-instances]
+* [Security|security]
+* [Failover Deployments|failover]
+* [Logging system|logging-system]
+
+* [Installing additional features|installing-features]
+* [Deployer|deployer]
+* [Provisioning|provisioning]
+* [Configuration|configuration]
Added: karaf/trunk/documentation/src/main/webapp/users-guide/installation.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/documentation/src/main/webapp/users-guide/installation.conf?rev=1023680&view=auto
==============================================================================
--- karaf/trunk/documentation/src/main/webapp/users-guide/installation.conf (added)
+++ karaf/trunk/documentation/src/main/webapp/users-guide/installation.conf Mon Oct 18 08:10:19 2010
@@ -0,0 +1,121 @@
+h1. Installation
+
+This chapter describes how to install 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 install it.
+
+This article contains the following sections:
+{toc:minLevel=2}
+
+h2. Pre-Installation Requirements
+
+*Hardware:*
+* 20 MB of free disk space for the Apache Karaf x.y binary distribution.
+
+*Operating Systems:*
+* Windows: Windows Vista, Windows XP SP2, Windows 2000.
+* Unix: Ubuntu Linux, Powerdog Linux, MacOS, AIX, HP-UX, Solaris, any Unix platform that supports Java.
+
+*Environment:*
+* Java SE 1.5.x or greater ([http://www.oracle.com/technetwork/java/javase/]).
+* The JAVA_HOME environment variable must be set to the directory where the Java runtime 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.
+
+h2. Building from Sources
+
+If you intend to build Karaf from the sources, the requirements are a bit different:
+
+*Hardware:*
+* 200 MB of free disk space for the Apache Karaf x.y source distributions or SVN checkout, the Maven build and the dependencies Maven downloads.
+
+*Environment:*
+* Java SE Developement Kit 1.5.x or greater ([http://www.oracle.com/technetwork/java/javase/]).
+* Apache Maven 2.2.1 ([http://maven.apache.org/download.html]).
+
+h3. Building on Windows
+
+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.2.1 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|start-stop#Starting Karaf] chapter.
+
+h3. Building on Unix
+
+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:
+The preferred 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}
+# 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|start-stop#Starting Karaf] chapter.
+
+h2. Installation Procedure for Windows
+
+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|start-stop#Starting Karaf] chapter.
+# Optional: see [enabling Colorized Console Output On Windows|colorized-console]
+
+{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}
+
+h2. Installation Procedure For Unix
+
+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|start-stop#Starting Karaf] chapter.
+
+h2. Post-Installation steps
+
+Thought it is not always required, it is strongly advised to set up the {{JAVA_HOME}} environment property to point to the JDK you want Karaf to use before starting it.
+This property is used to locate the {{java}} executable and should be configured to point to the home directory of the Java SE 5 or 6 installation.
+
Added: karaf/trunk/documentation/src/main/webapp/users-guide/installing-features.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/documentation/src/main/webapp/users-guide/installing-features.conf?rev=1023680&view=auto
==============================================================================
--- karaf/trunk/documentation/src/main/webapp/users-guide/installing-features.conf (added)
+++ karaf/trunk/documentation/src/main/webapp/users-guide/installing-features.conf Mon Oct 18 08:10:19 2010
@@ -0,0 +1,95 @@
+
+
+{warning:title=Outdated documentation}
+
+h1. Installing additional features
+
+This chapter will demonstrate how to add additional features from a remote maven repository to a default installation of Karaf.
+
+{info}Last updated September 3, 2010 using Karaf 2.0.0{info}
+
+h2. Adding additional feature repositories
+
+The following steps will add in the URLs for the Camel & ActiveMQ features locations.
+# Start Karaf
+{noformat}
+cd bin
+./karaf or karaf.bat
+{noformat}
+# Add the following feature install locations
+{noformat}
+karaf@root> features:addUrl mvn:org.apache.activemq/activemq-karaf/5.4.0/xml/features
+karaf@root> features:addUrl mvn:org.apache.camel.karaf/features/2.0.0/xml/features
+{noformat}
+# Verify the feature URLs were added -
+{noformat}
+karaf@root> features:listUrl
+mvn:org.apache.camel.karaf/features/2.0.0/xml/features valid
+mvn:org.apache.activemq/activemq-karaf/5.4.0/xml/features valid
+mvn:org.apache.karaf/apache-karaf/2.0.1-SNAPSHOT/xml/features valid
+{noformat}
+
+h2. Installing a new feature (war)
+
+The following steps will install the "war" feature (support for deploying WAR files with Servlet and JSPs into a Jetty server) into your Karaf instance.
+# List the available features -
+{noformat}
+karaf@root> features:list
+ State Name
+. . .
+[uninstalled] [2.0.0] obr karaf-2.0.0
+[uninstalled] [2.0.0] config karaf-2.0.0
+[uninstalled] [2.0.0] http karaf-2.0.0
+[uninstalled] [2.0.0] war karaf-2.0.0
+[uninstalled] [2.0.0] webconsole karaf-2.0.0
+[installed ] [2.0.0] ssh karaf-2.0.0
+. . .
+{noformat}
+# Install the war feature (and the sub-features it requires) -
+{noformat}
+karaf@root> features:install war
+{noformat}
+# Verify the features were installed
+{noformat}
+servicemix> features/list
+ State Name
+. . .
+[installed ] [2.0.0] http karaf-2.0.0
+[installed ] [2.0.0] war karaf-2.0.0
+. . .
+{noformat}
+# Verify the installed bundles were started
+{noformat}
+karaf@root> osgi:list
+START LEVEL 100
+ ID State Level Name
+. . .
+[ 32] [Active ] [ ] [ 60] geronimo-servlet_2.5_spec (1.1.2)
+[ 33] [Active ] [ ] [ 60] Apache ServiceMix :: Bundles :: jetty (6.1.22.2)
+[ 34] [Active ] [ ] [ 60] OPS4J Pax Web - API (0.7.2)
+[ 35] [Active ] [ ] [ 60] OPS4J Pax Web - Service SPI (0.7.2)
+[ 36] [Active ] [ ] [ 60] OPS4J Pax Web - Runtime (0.7.2)
+[ 37] [Active ] [ ] [ 60] OPS4J Pax Web - Jetty (0.7.2)
+[ 38] [Active ] [ ] [ 60] OPS4J Pax Web - Jsp Support (0.7.2)
+[ 39] [Active ] [ ] [ 60] OPS4J Pax Web - Extender - WAR (0.7.2)
+[ 40] [Active ] [ ] [ 60] OPS4J Pax Web - Extender - Whiteboard (0.7.2)
+[ 41] [Active ] [ ] [ 60] OPS4J Pax Url - war:, war-i: (1.1.3)
+[ 42] [Active ] [Created ] [ 60] Apache Karaf :: WAR Deployer (2.0.0)
+. . .
+{noformat}
+# The Jetty server should now be listening on http://localhost:8181/, but with no published applications available.
+{noformat}
+HTTP ERROR: 404
+NOT_FOUND
+RequestURI=/
+Powered by jetty://
+{noformat}
+
+h2. Deploying a WAR to the installed web feature
+
+The following steps will describe how to install a simple WAR file (with JSPs or Servlets) to the just installed web feature.
+# To deploy a WAR (JSP or Servlet) to Jetty, update its MANIFEST.MF to include the required OSGi headers as described here - \\
+[http://wiki.ops4j.org/confluence/display/ops4j/Pax+Web+Extender+-+War+-+OSGi-fy]
+# Copy the updated WAR (archive or extracted files) to the _deploy_ directory.
+
+
Added: karaf/trunk/documentation/src/main/webapp/users-guide/logging-system.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/documentation/src/main/webapp/users-guide/logging-system.conf?rev=1023680&view=auto
==============================================================================
--- karaf/trunk/documentation/src/main/webapp/users-guide/logging-system.conf (added)
+++ karaf/trunk/documentation/src/main/webapp/users-guide/logging-system.conf Mon Oct 18 08:10:19 2010
@@ -0,0 +1,155 @@
+
+h1. 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
+
+h3. Configuration files
+
+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_install_dir]/etc/org.ops4j.pax.logging.cfg
+{code}
+You can edit this file at runtime and any change will be reloaded and be effective immediately.
+
+The log commands has a separate configuration file:
+{code}
+[karaf_install_dir]/etc/org.apache.felix.karaf.log.cfg
+{code}
+
+h3. Configuring the appenders
+
+The default logging configuration defines three appenders:
+* the {{stdout}} console appender is disabled by default. If you plan to run Karaf in server mode only (i.e. with the locale console disabled), you can turn on this appender on by adding it to the list of configured appenders using the {{log4j.rootLogger}} property
+* the {{out}} appender is the one enabled by default. It logs events to a number of rotating log files of a fixed size. You can easily change the parameters to control the number of files using {{maxBackupIndex}} and their size size {{maxFileSize}}
+* the {{sift}} appender can be used instead to provide a per-bundle log file. The default configuration uses the bundle symbolic name as the file name to log to
+
+h3. Changing the log levels
+
+The default logging configuration sets the logging levels so that the log file will provide enough information to monitor the behavior of the runtime and provide clues about what caused a problem. However, the default configuration will not provide enough information to debug most problems.
+
+The most useful logger to change when trying to debug an issue with Karaf is the root logger. You will want to set its logging level to {{DEBUG}} in the {{org.ops4j.pax.logging.cfg}} file.
+{pygmentize:text}
+log4j.rootLogger=DEBUG, out, osgi:VmLogAppender
+...
+{pygmentize}
+
+When debugging a problem in Karaf you may want to change the level of logging information that is displayed on the console. The example below shows how to set the root logger to {{DEBUG}} but limiting the information displayed on the console to WARN.
+{pygmentize:text}
+log4j.rootLogger=DEBUG, out, stdout, osgi:VmLogAppender
+log4j.appender.stdout.threshold=WARN
+...
+{pygmentize}
+
+h2. Commands
+
+The log subshell comes with 3 commands:
+* [{{log:display}}|/commands/log-display]: display the last log entries
+* [{{log:display-exception}}|/commands/log-display-exception]: display the last exception from the log
+* [{{log:get}}|/commands/log-get]: show the log levels
+* [{{log:set}}|/commands/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 using the config commands or directly using a text editor of your choice.
+
+h2. Advanced configuration
+
+The logging backend uses Log4j, but offer a number of additional features.
+
+h3. Nested filters, appenders and error handlers
+
+h4. Filters
+
+Appender filters can be added using the following syntax:
+{pygmentize:text}
+log4j.appender.[appender-name].filter.[filter-name]=[filter-class]
+log4j.appender.[appender-name].filter.[filter-name].[option]=[value]
+{pygmentize}
+
+Below is a real example:
+{pygmentize:text}
+log4j.appender.out.filter.f1=org.apache.log4j.varia.LevelRangeFilter
+log4j.appender.out.filter.f1.LevelMax=FATAL
+log4j.appender.out.filter.f1.LevelMin=DEBUG
+{pygmentize}
+
+h4. Nested appenders
+
+Nested appenders can be added using the following syntax:
+{pygmentize:text}
+log4j.appender.[appender-name].appenders=[comma-separated-list-of-appender-names]
+{pygmentize}
+
+Below is a real example:
+{pygmentize:text}
+log4j.appender.async=org.apache.log4j.AsyncAppender
+log4j.appender.async.appenders=jms
+
+log4j.appender.jms=org.apache.log4j.net.JMSAppender
+...
+{pygmentize}
+
+h4. Error handlers
+
+Error handlers can be added using the following syntax:
+{pygmentize:text}
+log4j.appender.[appender-name].errorhandler=[error-handler-class]
+log4j.appender.[appender-name].errorhandler.root-ref=[true|false]
+log4j.appender.[appender-name].errorhandler.logger-ref=[logger-ref]
+log4j.appender.[appender-name].errorhandler.appender-ref=[appender-ref]
+{pygmentize}
+
+h3. OSGi specific MDC attributes
+
+Pax-Logging provides the following attributes by default:
+* {{bundle.id}}: the id of the bundle from which the class is loaded
+* {{bundle.name}}: the symbolic-name of the bundle
+* {{bundle.version}}: the version of the bundle
+
+An MDC sifting appender is available to split the log events based on MDC attributes. Below is a configuration example for this appender:
+{pygmentize:text}
+log4j.appender.sift=org.apache.log4j.sift.MDCSiftingAppender
+log4j.appender.sift.key=bundle.name
+log4j.appender.sift.default=karaf
+log4j.appender.sift.appender=org.apache.log4j.FileAppender
+log4j.appender.sift.appender.layout=org.apache.log4j.PatternLayout
+log4j.appender.sift.appender.layout.ConversionPattern=%d{ABSOLUTE} | %-5.5p | %-16.16t | %-32.32c{1} | %-32.32C %4L | %m%n
+log4j.appender.sift.appender.file=${karaf.data}/log/$\\{bundle.name\\}.log
+log4j.appender.sift.appender.append=true
+{pygmentize}
+
+h3. Enhanced OSGi stack trace renderer
+
+This renderer is configured by default in Karaf and will give additional informations when printing stack traces.
+For each line of the stack trace, it will display OSGi specific informations related to the class on that line: the bundle id, the bundle symbolic name and the bundle version. This information can greatly help diagnosing problems in some cases.
+The information is appended at the end of each line in the following format {{[id:name:version]}} as shown below
+{pygmentize:text}
+java.lang.IllegalArgumentException: Command not found: *:foo
+ at org.apache.felix.gogo.runtime.shell.Closure.execute(Closure.java:225)[21:org.apache.karaf.shell.console:2.1.0]
+ at org.apache.felix.gogo.runtime.shell.Closure.executeStatement(Closure.java:162)[21:org.apache.karaf.shell.console:2.1.0]
+ at org.apache.felix.gogo.runtime.shell.Pipe.run(Pipe.java:101)[21:org.apache.karaf.shell.console:2.1.0]
+ at org.apache.felix.gogo.runtime.shell.Closure.execute(Closure.java:79)[21:org.apache.karaf.shell.console:2.1.0]
+ at org.apache.felix.gogo.runtime.shell.CommandSessionImpl.execute(CommandSessionImpl.java:71)[21:org.apache.karaf.shell.console:2.1.0]
+ at org.apache.karaf.shell.console.jline.Console.run(Console.java:169)[21:org.apache.karaf.shell.console:2.1.0]
+ at java.lang.Thread.run(Thread.java:637)[:1.6.0_20]
+{pygmentize}
+
+h3. Using your own appenders
+
+If you plan to use your own appenders, you need to create an OSGi bundle and attach it as a fragment to the bundle with a symbolic name of {{org.ops4j.pax.logging.pax-logging-service}}. This way, the underlying logging system will be able to see and use your appenders.
Added: karaf/trunk/documentation/src/main/webapp/users-guide/provisioning.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/documentation/src/main/webapp/users-guide/provisioning.conf?rev=1023680&view=auto
==============================================================================
--- karaf/trunk/documentation/src/main/webapp/users-guide/provisioning.conf (added)
+++ karaf/trunk/documentation/src/main/webapp/users-guide/provisioning.conf Mon Oct 18 08:10:19 2010
@@ -0,0 +1,268 @@
+
+
+h1. 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. 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}
+
+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].
+
+
+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.
+
+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.
+
+
Added: karaf/trunk/documentation/src/main/webapp/users-guide/remote-console.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/documentation/src/main/webapp/users-guide/remote-console.conf?rev=1023680&view=auto
==============================================================================
--- karaf/trunk/documentation/src/main/webapp/users-guide/remote-console.conf (added)
+++ karaf/trunk/documentation/src/main/webapp/users-guide/remote-console.conf Mon Oct 18 08:10:19 2010
@@ -0,0 +1,115 @@
+h1. Using remote instances
+
+h2. Configuring remote instances
+
+It does not always make sense to manage an instance of Karaf using its local console. You can manage Karaf remotely using a remote console.
+
+When you start Karaf, it enables a remote console that can be accessed over SSH from any other Karaf conolse or plain SSH client. The remote console provides all the features of the local console and gives a remote user complete control over the container and services running inside of it.
+
+The SSH hostname and port number is configured in the {{\[karaf_install_dir\]/etc/org.apache.karaf.shell.cfg}} configuration file with the following defaults values:
+
+{code}
+sshPort=8101
+sshHost=0.0.0.0
+sshRealm=karaf
+hostKey=${karaf.base}/etc/host.key
+{code}
+
+You can change this configuration using the [config commands|configuration] or by editing the above file, but you need to restart the ssh console in order for it to use the new parameters.
+
+{code}
+# define helper functions
+bundle-by-sn = { bm = new java.util.HashMap ; each (bundles) { $bm put ($it symbolicName) $it } ; $bm get $1 }
+bundle-id-by-sn = { b = (bundle-by-sn $1) ; if { $b } { $b bundleId } { -1 } }
+# edit config
+config:edit org.apache.karaf.shell
+config:propset sshPort 8102
+config:update
+# force a restart
+osgi:restart --force (bundle-id-by-sn org.apache.karaf.shell.ssh)
+{code}
+
+h2. Connecting and disconnecting remotely
+
+h3. Using the {{ssh:ssh}} command
+
+You can connect to a remote Karaf's console using the [{{ssh:ssh}}|/commands/ssh-ssh] command.
+
+{code}
+karaf@root> ssh:ssh -l karaf -P karaf -p 8101 hostname
+{code}
+
+{warning}
+The default password is {{karaf}} but we recommend to change it. See the [security] section for more informations.
+{warning}
+
+To confirm that you have connected to the correct Karaf instance, type [{{shell:info}}|/commands/shell-info] at the {{karaf>}} prompt. Information about the currently connected instance is returned, as shown.
+
+{code}
+Karaf
+ Karaf home /local/apache-karaf-2.0.0
+ Karaf base /local/apache-karaf-2.0.0
+ OSGi Framework org.eclipse.osgi - 3.5.1.R35x_v20090827
+JVM
+ Java Virtual Machine Java HotSpot(TM) Server VM version 14.1-b02
+ ...
+{code}
+
+h3. Using the karaf client
+
+The Karaf client allows you to securely connect to a remote Karaf instance without having to launch a Karaf instance locally.
+
+For example, to quickly connect to a Karaf instance running in server mode on the same machine, run the following command from the {{[karaf-install-dir]}} directory:
+{code}
+bin/client
+{code}
+
+More usually, you would provide a hostname, port, username and password to connect to a remote instance. And, if you were using the client within a larger script, you could append console commands as follows:
+{code}
+bin/client -a 8101 -h hostname -u karaf -p karaf features:install wrapper
+{code}
+
+To display the available options for the client, type:
+{code}
+> bin/client --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}
+
+h3. Using a plain SSH client
+
+You can also connect using a plain SSH client from your *nix system or Windows SSH client like Putty.
+{code}
+~$ ssh -p 8101 karaf@localhost
+karaf@localhost's password:
+{code}
+
+h3. Disconnecting from a remote console
+
+To disconnect from a remote console, press {{Ctrl+D}}, {{shell:logout}} or simply {{logout}} at the Karaf prompt.
+
+h2. Stopping a remote instance
+
+h3. Using the remote console
+
+If you have connected to a remote console using the [{{ssh:ssh}}|/commands/ssh-ssh] command or the Karaf client, you can stop the remote instance using the [{{osgi:shutdown}}|/commands/osgi-shutdown] command.
+
+{info}
+Pressing {{Ctrl+D}} in a remote console simply closes the remote connection and returns you to the local shell.
+{info}
+
+h3. Using the karaf client
+
+To stop a remote instance using the Karaf client, run the following from the {{[karaf-install-dir]/lib}} directory:
+{code}
+bin/client -u karaf -p karaf -a 8101 hostname osgi:shutdown
+{code}
Added: karaf/trunk/documentation/src/main/webapp/users-guide/security.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/documentation/src/main/webapp/users-guide/security.conf?rev=1023680&view=auto
==============================================================================
--- karaf/trunk/documentation/src/main/webapp/users-guide/security.conf (added)
+++ karaf/trunk/documentation/src/main/webapp/users-guide/security.conf Mon Oct 18 08:10:19 2010
@@ -0,0 +1,66 @@
+h1. Security
+
+h2. Managing users and passwords
+
+The default security configuration uses a property file located at {{[karaf-install-dir]/etc/users.properties}} to store authorized users and their passwords.
+
+The default user name is {{karaf}} and the associated password is {{karaf}} too. We strongly encourage you to change the default password by editing the above file before moving Karaf into production.
+
+The users are currenly used in three different places in Karaf:
+* access to the SSH console
+* access to the JMX management layer
+* access to the Web console
+
+The {{users.properties}} file contains one or more lines, each line defining a user, its password and the associated roles.
+
+{code}
+user=password[,role][,role]...
+{code}
+
+h2. Enabling password encryption
+
+In order to not keep the passwords in plain text, the passwords can be stored encrypted in the configuration file.
+This can be easily enabled using the following commands:
+
+{code}
+# edit config
+config:edit org.apache.karaf.jaas
+config:propset encryption.enabled true
+config:update
+# force a restart
+dev:restart
+{code}
+
+The passwords will be encrypted automatically in the {{etc/users.properties}} configuration file the first time the user logs in.
+Encrypted passwords are prepended with {{\{CRYPT\}}} so that are easy to recognize.
+
+h2. Managing realms
+
+More informations about modifying the default realm or deploying new realms is provided in the [developers guide|/developers-guide/security-framework].
+
+h2. Deploying security providers
+
+Some applications require specific security providers to be available, such as [BouncyCastle|http://www.bouncycastle.org]. 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 {{$JAVA_HOME/jre/lib/ext}} and modify the security policy configuration ({{$JAVA_HOME/jre/lib/security/java.security}}) in order to register such providers.
+
+While this approach works fine, it has a global effect and require you to configure all your servers accordingly.
+
+Karaf offers a simple way to configure additional security providers:
+* put your provider jar in {{[karaf-install-dir]/lib/ext}}
+* modify the {{[karaf-install-dir]/etc/config.properties}} configuration file to add the following property
+
+{code}
+org.apache.karaf.security.providers = xxx,yyy
+{code}
+
+The value of this property is a comma separated list of the provider class names to register.
+For example:
+{code}
+org.apache.karaf.security.providers = org.bouncycastle.jce.provider.BouncyCastleProvider
+{code}
+
+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 {{org.osgi.framework.bootdelegation}} property in the same configuration file:
+{code}
+org.osgi.framework.bootdelegation = ...,org.bouncycastle*
+{code}
+
+
Added: karaf/trunk/documentation/src/main/webapp/users-guide/start-stop.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/documentation/src/main/webapp/users-guide/start-stop.conf?rev=1023680&view=auto
==============================================================================
--- karaf/trunk/documentation/src/main/webapp/users-guide/start-stop.conf (added)
+++ karaf/trunk/documentation/src/main/webapp/users-guide/start-stop.conf Mon Oct 18 08:10:19 2010
@@ -0,0 +1,87 @@
+h1. Starting and Stopping Karaf
+
+This chapter describes how to start and stop Apache Karaf and the various options that are available.
+
+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}
+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}
+
+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}
+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.sh
+{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. Starting Karaf without console
+
+Karaf can be started without the console if you don't intend to use it (one can always connect using the remote ssh access) using the following command:
+{code}
+bin\karaf.bat server
+{code}
+or, on Unix:
+{code}
+bin\karaf server
+{code}
+
+h2. Starting Karaf in the background
+
+Karaf can be easily started as a background process using the following command:
+{code}
+bin\start.bat
+{code}
+or, on Unix:
+{code}
+bin\start
+{code}
+
+h2. Starting Karaf from clean
+
+Karaf can be reset to a clean state by simply deleting the {{\[karaf_install_dir\]/data}} folder.
+For convenience, a parameter on the {{karaf}} and {{start}} scripts is available:
+{code}
+bin/start clean
+{code}
+
+h2. Stopping Karaf
+
+For both Windows and Unix installations, you can perform a clean shutdown of Karaf by using the following command when inside a Karaf console:
+{code}
+osgi:shutdown
+{code}
+or simply:
+{code}
+shutdown
+{code}
+
+If you're running from the main console, exiting the shell using {{logout}} or {{Ctrl+D}} will also terminate the Karaf instance.
+
+From a command shell, you can run the following command:
+{code}
+bin\stop.bat
+{code}
+or, on Unix:
+{code}
+bin/stop
+{code}
Added: karaf/trunk/documentation/src/main/webapp/users-guide/using-console.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/documentation/src/main/webapp/users-guide/using-console.conf?rev=1023680&view=auto
==============================================================================
--- karaf/trunk/documentation/src/main/webapp/users-guide/using-console.conf (added)
+++ karaf/trunk/documentation/src/main/webapp/users-guide/using-console.conf Mon Oct 18 08:10:19 2010
@@ -0,0 +1,75 @@
+h1. Using the console
+
+h2. Viewving available commands
+
+To see a list of the available commands in the console press the {{<tab>}} key at the prompt.
+
+{code}
+root@karaf> <tab>
+*:help addurl admin:change-port admin:connect
+admin:create admin:destroy admin:list admin:start
+admin:stop bundle-level cancel cat
+change-port clear config:cancel config:edit
+config:list config:propappend config:propdel config:proplist
+config:propset config:update connect create
+destroy dev:dynamic-import dev:framework dev:print-stack-traces
+dev:restart dev:show-tree display display-exception
+dynamic-import each echo edit
+exec exports features:addurl features:info
+features:install features:list features:listrepositories features:listurl
+features:listversions features:refreshurl features:removerepository features:removeurl
+features:uninstall framework get grep
+headers help history if
+imports info install java
+list listrepositories listurl listversions
+log:display log:display-exception log:get log:set
+logout ls new 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 print-stack-traces
+printf propappend propdel proplist
+propset refresh refreshurl removerepository
+removeurl resolve restart set
+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
+show-tree shutdown sleep sort
+ssh ssh:ssh ssh:sshd sshd
+start start-level stop tac
+uninstall update
+{code}
+
+The {{<tab>}} key toggles completion anywhere on the line, so if you want to see the commands in the {{osgi}} group, type the first letters and hit {{<tab>}}. Depending on the commands, completion may be available on options and arguments too.
+
+h2. Getting help on a command
+
+To view help on a particulare command, type the command followed by {{--help}} or use the {{help}} command followed by the name of the command:
+
+{code}
+karaf@root> features:list --help
+DESCRIPTION
+ features:list
+
+ Lists all existing features available from the defined repositories.
+
+SYNTAX
+ features:list [options]
+
+OPTIONS
+ --help
+ Display this help message
+ -i, --installed
+ Display a list of all installed features only
+{code}
+
+
+h2. More...
+
+The list of all available commands and their usage is also available in a [dedicated section|/commands/commands].
+
+You'll find a more in depth guide to the shell syntax in the [developers guide|/developers-guide/shell-syntax].
+
+The console can also be easily extended by creating new commands as explained in the [developers guide|/developers-guide/extending-console].
+
Added: karaf/trunk/documentation/src/main/webapp/users-guide/web-console.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/documentation/src/main/webapp/users-guide/web-console.conf?rev=1023680&view=auto
==============================================================================
--- karaf/trunk/documentation/src/main/webapp/users-guide/web-console.conf (added)
+++ karaf/trunk/documentation/src/main/webapp/users-guide/web-console.conf Mon Oct 18 08:10:19 2010
@@ -0,0 +1,35 @@
+h1. Web console
+
+The Karaf web console provides a graphical overview of the runtime.
+You can use it to:
+* install and uninstall features
+* start, stop, install bundles
+* create child instances
+* configure Karaf
+* view logging informations
+
+h2. Installing the web console
+
+The web console is not installed by default. To install it, run the following command from the Karaf prompt:
+
+{code}
+root@karaf> features:install webconsole
+{code}
+
+h2. Accessing the web console
+
+To access the console for an instance of Karaf running locally, enter the following address in your web browser:
+
+{code}
+http://localhost:8081/system/console
+{code}
+
+Log in with the username {{karaf}} and the password {{karaf}}. If you have changed the default user or password, use the one you have configured.
+
+h2. Changing the web console port number
+
+By default, the console runs on port 8181. You can change the port number by creating the properties file, {{etc/org.ops4j.pax.web.cfg}}, and adding the following property setting (changing the port number to whatever value you want):
+
+{code}
+org.osgi.service.http.port=8181
+{code}
Modified: karaf/trunk/pom.xml
URL: http://svn.apache.org/viewvc/karaf/trunk/pom.xml?rev=1023680&r1=1023679&r2=1023680&view=diff
==============================================================================
--- karaf/trunk/pom.xml (original)
+++ karaf/trunk/pom.xml Mon Oct 18 08:10:19 2010
@@ -44,6 +44,7 @@
<module>jaas</module>
<module>client</module>
<module>management</module>
+ <module>documentation</module>
<module>webconsole</module>
<module>manual</module>
<module>exception</module>