You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@karaf.apache.org by jb...@apache.org on 2021/06/02 10:00:46 UTC
svn commit: r48085 - in /release/karaf/documentation: 4_x.html 4_x.pdf
Author: jbonofre
Date: Wed Jun 2 10:00:46 2021
New Revision: 48085
Log:
Update documentation
Modified:
release/karaf/documentation/4_x.html
release/karaf/documentation/4_x.pdf
Modified: release/karaf/documentation/4_x.html
==============================================================================
--- release/karaf/documentation/4_x.html (original)
+++ release/karaf/documentation/4_x.html Wed Jun 2 10:00:46 2021
@@ -734,6 +734,162 @@ table.CodeRay td.code>pre{padding:0}
<li><a href="#_access">4.19.2. Access</a></li>
</ul>
</li>
+<li><a href="#_scheduler">4.20. Scheduler</a>
+<ul class="sectlevel3">
+<li><a href="#_installation_4">4.20.1. Installation</a></li>
+<li><a href="#_configuration_7">4.20.2. Configuration</a></li>
+<li><a href="#_schedule_a_new_job_using_the_whitebox_service_paradigm_recommended">4.20.3. Schedule a new Job using the Whitebox-Service paradigm (recommended)</a></li>
+<li><a href="#_schedule_a_new_job_using_the_gogo_shell">4.20.4. Schedule a new Job using the Gogo Shell</a></li>
+<li><a href="#_schedule_a_command">4.20.5. Schedule a command</a></li>
+<li><a href="#_schedule_a_new_job_using_the_scheduler_service">4.20.6. Schedule a new Job using the Scheduler Service</a></li>
+<li><a href="#_update_scheduling_of_an_existing_job">4.20.7. Update scheduling of an existing job</a></li>
+<li><a href="#_using_shared_jobs_store">4.20.8. Using shared jobs store</a></li>
+</ul>
+</li>
+<li><a href="#_tuning">4.21. Tuning</a>
+<ul class="sectlevel3">
+<li><a href="#_garbage_collection">4.21.1. Garbage Collection</a></li>
+<li><a href="#_threads">4.21.2. Threads</a></li>
+<li><a href="#_system_packages">4.21.3. System packages</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="#_developer_guide">5. Developer Guide</a>
+<ul class="sectlevel2">
+<li><a href="#_developer_commands">5.1. Developer commands</a>
+<ul class="sectlevel3">
+<li><a href="#_dump">5.1.1. Dump</a></li>
+<li><a href="#_diagnostic">5.1.2. Diagnostic</a></li>
+<li><a href="#_dynamic_import">5.1.3. Dynamic import</a></li>
+<li><a href="#_osgi_framework">5.1.4. OSGi framework</a></li>
+<li><a href="#_stack_traces_printout">5.1.5. Stack traces printout</a></li>
+<li><a href="#_bundle_tree">5.1.6. Bundle tree</a></li>
+<li><a href="#_watch">5.1.7. Watch</a></li>
+</ul>
+</li>
+<li><a href="#_scripting_2">5.2. Scripting</a>
+<ul class="sectlevel3">
+<li><a href="#_assignation">5.2.1. Assignation</a></li>
+<li><a href="#_expressions">5.2.2. Expressions</a></li>
+<li><a href="#_list_maps_pipes_and_closures">5.2.3. List, maps, pipes and closures</a></li>
+<li><a href="#_startup">5.2.4. Startup</a></li>
+<li><a href="#_constants_and_variables">5.2.5. Constants and variables</a></li>
+<li><a href="#_built_in_variables_and_commands">5.2.6. Built-in variables and commands</a></li>
+<li><a href="#_leveraging_existing_java_capabilities_via_reflection">5.2.7. Leveraging existing Java capabilities (via reflection)</a></li>
+<li><a href="#_examples">5.2.8. Examples</a></li>
+</ul>
+</li>
+<li><a href="#_programmatically_connect">5.3. Programmatically connect</a>
+<ul class="sectlevel3">
+<li><a href="#_to_the_console">5.3.1. To the console</a></li>
+<li><a href="#_to_the_management_layer">5.3.2. To the management layer</a></li>
+</ul>
+</li>
+<li><a href="#_branding">5.4. Branding</a>
+<ul class="sectlevel3">
+<li><a href="#_console_2">5.4.1. Console</a></li>
+<li><a href="#_adding_a_branding_properties_file_to_etc">5.4.2. Adding a branding.properties file to etc</a></li>
+</ul>
+</li>
+<li><a href="#_adding_a_branding_ssh_properties_file_to_etc">5.5. Adding a branding-ssh.properties file to etc</a>
+<ul class="sectlevel3">
+<li><a href="#_branding_bundle">5.5.1. Branding bundle</a></li>
+<li><a href="#_webconsole_3">5.5.2. WebConsole</a></li>
+</ul>
+</li>
+<li><a href="#_extending">5.6. Extending</a>
+<ul class="sectlevel3">
+<li><a href="#_shell_commands">5.6.1. Shell commands</a></li>
+<li><a href="#_webconsole_4">5.6.2. WebConsole</a></li>
+</ul>
+</li>
+<li><a href="#_using_the_karaf_maven_plugin">5.7. Using the karaf-maven-plugin</a>
+<ul class="sectlevel3">
+<li><a href="#_packaging">5.7.1. Packaging</a></li>
+<li><a href="#_commands_goals">5.7.2. Commands goals</a></li>
+<li><a href="#_features_and_kar_goals">5.7.3. Features and kar goals</a></li>
+<li><a href="#_instances_and_distributions_goals">5.7.4. Instances and distributions goals</a></li>
+<li><a href="#_run_client_deploy_goals">5.7.5. Run, client, deploy goals</a></li>
+<li><a href="#_dockerfile_docker">5.7.6. Dockerfile, Docker</a></li>
+</ul>
+</li>
+<li><a href="#_custom_distributions">5.8. Custom distributions</a>
+<ul class="sectlevel3">
+<li><a href="#_maven_assembly">5.8.1. Maven assembly</a></li>
+<li><a href="#_deprecated_old_style_maven_assembly">5.8.2. (deprecated old style) Maven assembly</a></li>
+</ul>
+</li>
+<li><a href="#_creating_bundles">5.9. Creating Bundles</a>
+<ul class="sectlevel3">
+<li><a href="#_add_extended_information_to_bundles">5.9.1. Add extended information to bundles</a></li>
+<li><a href="#_wiki_syntax">5.9.2. Wiki Syntax</a></li>
+</ul>
+</li>
+<li><a href="#_creating_bundles_for_non_osgi_third_party_dependencies">5.10. Creating bundles for non OSGi third party dependencies</a>
+<ul class="sectlevel3">
+<li><a href="#_dynamically_wrapping_jars">5.10.1. Dynamically wrapping jars</a></li>
+<li><a href="#_statically_bundling_jars">5.10.2. Statically bundling jars</a></li>
+</ul>
+</li>
+<li><a href="#_blueprint">5.11. Blueprint</a></li>
+<li><a href="#_scr">5.12. SCR</a></li>
+<li><a href="#_archetypes">5.13. Archetypes</a>
+<ul class="sectlevel3">
+<li><a href="#_create_a_command_karaf_command_archetype">5.13.1. Create a command (karaf-command-archetype)</a></li>
+<li><a href="#_create_an_osgi_bundle_karaf_bundle_archetype">5.13.2. Create an OSGi bundle (karaf-bundle-archetype)</a></li>
+<li><a href="#_create_an_osgi_blueprint_bundle_karaf_blueprint_archetype">5.13.3. Create an OSGi blueprint bundle (karaf-blueprint-archetype)</a></li>
+<li><a href="#_create_a_features_xml_karaf_feature_archetype">5.13.4. Create a features XML (karaf-feature-archetype)</a></li>
+<li><a href="#_create_a_kar_file_karaf_kar_archetype">5.13.5. Create a KAR file (karaf-kar-archetype)</a></li>
+</ul>
+</li>
+<li><a href="#_security_framework">5.14. Security framework</a>
+<ul class="sectlevel3">
+<li><a href="#_overview_2">5.14.1. Overview</a></li>
+<li><a href="#_schema_and_deployer">5.14.2. Schema and Deployer</a></li>
+<li><a href="#_architecture">5.14.3. Architecture</a></li>
+<li><a href="#_available_realm_and_login_modules">5.14.4. Available realm and login modules</a></li>
+<li><a href="#_encryption_service">5.14.5. Encryption service</a></li>
+<li><a href="#_role_discovery_policies">5.14.6. Role discovery policies</a></li>
+<li><a href="#_default_role_policies">5.14.7. Default role policies</a></li>
+</ul>
+</li>
+<li><a href="#_troubleshooting_debugging_profiling_and_monitoring">5.15. Troubleshooting, Debugging, Profiling, and Monitoring</a>
+<ul class="sectlevel3">
+<li><a href="#_troubleshooting">5.15.1. Troubleshooting</a></li>
+<li><a href="#_debugging">5.15.2. Debugging</a></li>
+<li><a href="#_profiling">5.15.3. Profiling</a></li>
+<li><a href="#_monitoring">5.15.4. Monitoring</a></li>
+</ul>
+</li>
+<li><a href="#_configuration_9">5.16. Configuration</a></li>
+<li><a href="#_deployer_3">5.17. Deployer</a></li>
+<li><a href="#_dump_extender">5.18. Dump extender</a></li>
+<li><a href="#_jdbc_jpa">5.19. JDBC & JPA</a></li>
+<li><a href="#_jms_2">5.20. JMS</a></li>
+<li><a href="#_custom_log_appender">5.21. Custom log appender</a></li>
+<li><a href="#_custom_jmx_mbean">5.22. Custom JMX MBean</a></li>
+<li><a href="#_working_with_profiles">5.23. Working with profiles</a></li>
+<li><a href="#_security_jaas">5.24. Security & JAAS</a></li>
+<li><a href="#_servlet">5.25. Servlet</a></li>
+<li><a href="#_war">5.26. WAR</a></li>
+<li><a href="#_http_resources">5.27. HTTP Resources</a></li>
+<li><a href="#_rest_service">5.28. REST service</a></li>
+<li><a href="#_soap_service">5.29. SOAP service</a></li>
+<li><a href="#_websocket">5.30. Websocket</a></li>
+<li><a href="#_scheduler_2">5.31. Scheduler</a></li>
+<li><a href="#_quick_example_with_apache_camel">5.32. Quick example with Apache Camel</a></li>
+<li><a href="#_custom_url_handler">5.33. Custom URL handler</a></li>
+<li><a href="#_integration_tests">5.34. Integration Tests</a></li>
+<li><a href="#_distributions_docker">5.35. Distributions & Docker</a></li>
+<li><a href="#_github_contributions">5.36. Github Contributions</a>
+<ul class="sectlevel3">
+<li><a href="#_introduction">5.36.1. Introduction</a></li>
+<li><a href="#_suggested_workflow">5.36.2. Suggested Workflow</a></li>
+<li><a href="#_license_reminder">5.36.3. License Reminder</a></li>
+<li><a href="#_how_to_generate_a_one_file_patch_via_throw_away_branch">5.36.4. How to Generate a One-File-Patch Via Throw-Away Branch</a></li>
+</ul>
+</li>
</ul>
</li>
</ul>
@@ -14139,21 +14295,25 @@ with the <code>/system/console</code> co
_g_\:admingroup = group,admin,manager,viewer,systembundles,ssh</pre>
</div>
</div>
-<div class="exampleblock">
-<div class="content">
-
-</div>
-</div>
</td>
</tr>
</table>
</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">
<div class="paragraph">
<p>By default, only users with the <code>admin</code> role are allowed to logon to the Apache Karaf WebConsole.
Right now, the WebConsole doesn’t use RBAC system as we have for console commands, or MBeans.</p>
</div>
-<div class="exampleblock">
-<div class="content">
+</td>
+</tr>
+</table>
+</div>
<div class="paragraph">
<p>You can change the security configuration of the webconsole in the
<code>etc/org.apache.karaf.webconsole.cfg</code> configuration file:</p>
@@ -14167,18 +14327,18 @@ realm=karaf
role=admin</pre>
</div>
</div>
-<div class="paragraph">
-<p>=== Scheduler</p>
</div>
+</div>
+<div class="sect2">
+<h3 id="_scheduler">4.20. Scheduler</h3>
<div class="paragraph">
<p>Apache Karaf provides an optional Scheduler which provides a Service Listener which listens for Runnable Services and schedules their execution, based on the service properties.</p>
</div>
<div class="paragraph">
<p>This Scheduler implementation uses the Quartz Scheduler library to understand cron-like expressions.</p>
</div>
-<div class="paragraph">
-<p>==== Installation</p>
-</div>
+<div class="sect3">
+<h4 id="_installation_4">4.20.1. Installation</h4>
<div class="paragraph">
<p>To enable the Apache Karaf Scheduler, you just have to install the <code>scheduler</code> feature:</p>
</div>
@@ -14199,9 +14359,9 @@ scheduler:unschedule
scheduler:reschedule</pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Configuration</p>
</div>
+<div class="sect3">
+<h4 id="_configuration_7">4.20.2. Configuration</h4>
<div class="paragraph">
<p>All jobs allow configuration using service properties:</p>
</div>
@@ -14254,9 +14414,11 @@ This property needs to be of type Boolea
</tr>
</tbody>
</table>
+</div>
+<div class="sect3">
+<h4 id="_schedule_a_new_job_using_the_whitebox_service_paradigm_recommended">4.20.3. Schedule a new Job using the Whitebox-Service paradigm (recommended)</h4>
<div class="paragraph">
-<p>==== Schedule a new Job using the Whitebox-Service paradigm (recommended)
-This example uses Declarative Services to register a Service of Type "org.apache.karaf.scheduler.Job" so that it is recognized by the Scheduler Service.</p>
+<p>This example uses Declarative Services to register a Service of Type "org.apache.karaf.scheduler.Job" so that it is recognized by the Scheduler Service.</p>
</div>
<div class="paragraph">
<p>Alternatively, jobs can be registered as type "Runnable" in a more API neutral way. In this case you won’t get the "JobContext" information though.</p>
@@ -14343,9 +14505,9 @@ public class PingThread implements Runna
}</code></pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Schedule a new Job using the Gogo Shell</p>
</div>
+<div class="sect3">
+<h4 id="_schedule_a_new_job_using_the_gogo_shell">4.20.4. Schedule a new Job using the Gogo Shell</h4>
<div class="listingblock">
<div class="content">
<pre>karaf@root()> scheduler:schedule-script --help
@@ -14379,9 +14541,9 @@ OPTIONS
Name of this job</pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Schedule a command</p>
</div>
+<div class="sect3">
+<h4 id="_schedule_a_command">4.20.5. Schedule a command</h4>
<div class="listingblock">
<div class="content">
<pre>karaf@root()> scheduler:schedule-command --help
@@ -14414,9 +14576,9 @@ OPTIONS
The cron expression</pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Schedule a new Job using the Scheduler Service</p>
</div>
+<div class="sect3">
+<h4 id="_schedule_a_new_job_using_the_scheduler_service">4.20.6. Schedule a new Job using the Scheduler Service</h4>
<div class="paragraph">
<p>Recommendation: Before using this low level api for registering jobs, consider using the whitebox approach instead.</p>
</div>
@@ -14442,9 +14604,9 @@ public class Demo {
}</pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Update scheduling of an existing job</p>
</div>
+<div class="sect3">
+<h4 id="_update_scheduling_of_an_existing_job">4.20.7. Update scheduling of an existing job</h4>
<div class="paragraph">
<p>You can change the scheduling of an existing job using <code>scheduler:reschedule</code> command.</p>
</div>
@@ -14452,9 +14614,9 @@ public class Demo {
<p>This command works as the schedule command (using the same <code>at</code>, <code>period</code>, <code>cron</code>, …​ options) but taking the job name
as argument (as given by the <code>scheduler:list</code> command).</p>
</div>
-<div class="paragraph">
-<p>==== Using shared jobs store</p>
</div>
+<div class="sect3">
+<h4 id="_using_shared_jobs_store">4.20.8. Using shared jobs store</h4>
<div class="paragraph">
<p>By the default, the Apache Karaf scheduler uses a memory storage for jobs. It’s local to a single Karaf instance.</p>
</div>
@@ -14515,12 +14677,12 @@ org.quartz.jobStore.driverDelegateClass=
<div class="paragraph">
<p>Then several Karaf instances scheduler will share the same JDBC job store and can work in a "clustered" way.</p>
</div>
-<div class="paragraph">
-<p>=== Tuning</p>
</div>
-<div class="paragraph">
-<p>==== Garbage Collection</p>
</div>
+<div class="sect2">
+<h3 id="_tuning">4.21. Tuning</h3>
+<div class="sect3">
+<h4 id="_garbage_collection">4.21.1. Garbage Collection</h4>
<div class="paragraph">
<p>Like any Java applications, Apache Karaf uses a JVM. An important feature of the JVM is the Garbage Collector.</p>
</div>
@@ -14582,9 +14744,8 @@ memory leaks, and see the possible optim
<div class="paragraph">
<p>You can find introduction about GC here: [<a href="http://www.oracle.com/webfolder/technetwork/tutorials/obe/java/gc01/index.html" class="bare">http://www.oracle.com/webfolder/technetwork/tutorials/obe/java/gc01/index.html</a>].</p>
</div>
-<div class="paragraph">
-<p>===== Java 6</p>
-</div>
+<div class="sect4">
+<h5 id="_java_6">Java 6</h5>
<div class="paragraph">
<p>If you have enough resources available on the machine, a good configuration may be:</p>
</div>
@@ -14616,9 +14777,9 @@ memory leaks, and see the possible optim
<div class="paragraph">
<p>See <a href="http://www.oracle.com/technetwork/java/javase/gc-tuning-6-140523.html" class="bare">http://www.oracle.com/technetwork/java/javase/gc-tuning-6-140523.html</a> for details about Java 6 tuning.</p>
</div>
-<div class="paragraph">
-<p>===== Java 7</p>
</div>
+<div class="sect4">
+<h5 id="_java_7">Java 7</h5>
<div class="paragraph">
<p>Java 7 introduces a new GC algorithm: the GC1.</p>
</div>
@@ -14641,15 +14802,15 @@ memory leaks, and see the possible optim
<div class="paragraph">
<p>You can find a good article about Java 7 tuning here: <a href="http://java-is-the-new-c.blogspot.de/2013/07/tuning-and-benchmarking-java-7s-garbage.html" class="bare">http://java-is-the-new-c.blogspot.de/2013/07/tuning-and-benchmarking-java-7s-garbage.html</a></p>
</div>
-<div class="paragraph">
-<p>==== Threads</p>
</div>
-<div class="paragraph">
-<p>In a system under high load, the number of threads can be very large.</p>
</div>
+<div class="sect3">
+<h4 id="_threads">4.21.2. Threads</h4>
<div class="paragraph">
-<p>===== WebContainer</p>
+<p>In a system under high load, the number of threads can be very large.</p>
</div>
+<div class="sect4">
+<h5 id="_webcontainer">WebContainer</h5>
<div class="paragraph">
<p>If you use the Apache Karaf WebContainer, the Jetty connectors create threads to handle the incoming HTTP requests.</p>
</div>
@@ -14698,9 +14859,9 @@ this value, the status is "low on resour
</li>
</ul>
</div>
-<div class="paragraph">
-<p>===== Apache Camel</p>
</div>
+<div class="sect4">
+<h5 id="_apache_camel">Apache Camel</h5>
<div class="paragraph">
<p>For instance, if you use Apache Camel inside Apache Karaf, Camel components can create a lot of threads.</p>
</div>
@@ -14720,9 +14881,9 @@ this value, the status is "low on resour
<div class="paragraph">
<p>See the <a href="http://camel.apache.org" class="bare">http://camel.apache.org</a> for details.</p>
</div>
-<div class="paragraph">
-<p>===== Apache CXF</p>
</div>
+<div class="sect4">
+<h5 id="_apache_cxf">Apache CXF</h5>
<div class="paragraph">
<p>Apache CXF uses workqueues to handle server request/response.</p>
</div>
@@ -14749,9 +14910,10 @@ to all workqueues (a workqueue can be as
<div class="paragraph">
<p>See the <a href="http://cxf.apache.org" class="bare">http://cxf.apache.org</a> for details.</p>
</div>
-<div class="paragraph">
-<p>==== System packages</p>
</div>
+</div>
+<div class="sect3">
+<h4 id="_system_packages">4.21.3. System packages</h4>
<div class="paragraph">
<p>The <code>etc/jre.properties</code> defines the packages directly provided by the JVM.</p>
</div>
@@ -14768,12 +14930,15 @@ to all workqueues (a workqueue can be as
<p>In that case, you have to comment the packages in <code>etc/jre.properties</code> to avoid to be provided by the JVM and use the
ones from the bundles.</p>
</div>
-<div class="paragraph">
-<p>== Developer Guide</p>
</div>
-<div class="paragraph">
-<p>=== Developer commands</p>
</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_developer_guide">5. Developer Guide</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="_developer_commands">5.1. Developer commands</h3>
<div class="paragraph">
<p>As you can see in the users guide, Apache Karaf is an enterprise ready OSGi container.</p>
</div>
@@ -14781,9 +14946,8 @@ ones from the bundles.</p>
<p>It’s also a container designed to simplify life for developers and administrators to get details about the
running container.</p>
</div>
-<div class="paragraph">
-<p>==== Dump</p>
-</div>
+<div class="sect3">
+<h4 id="_dump">5.1.1. Dump</h4>
<div class="paragraph">
<p>If you encounter issues like performance degradations, weird behaviour, it could be helpful to have a kind of snapshot
about the current activity of the container.</p>
@@ -14855,9 +15019,9 @@ Diagnostic dump created.</pre>
Diagnostic dump created.</pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Diagnostic</p>
</div>
+<div class="sect3">
+<h4 id="_diagnostic">5.1.2. Diagnostic</h4>
<div class="paragraph">
<p>It’s not always easy for developers to understand why a bundle is not active.</p>
</div>
@@ -14903,9 +15067,9 @@ Unsatisfied Requirements:
[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.resource)(version>=6.1.0)(!(version>=7.0.0)))</pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Dynamic import</p>
</div>
+<div class="sect3">
+<h4 id="_dynamic_import">5.1.3. Dynamic import</h4>
<div class="paragraph">
<p>The <code>bundle:dynamic-import</code> command allows you to enable or disable the dynamic import of a given bundle:</p>
</div>
@@ -14923,9 +15087,9 @@ bundles to be considered for a wiring im
<div class="paragraph">
<p>The <code>bundle:dynamic-import</code> command allows or doesn’t allow this behaviour.</p>
</div>
-<div class="paragraph">
-<p>==== OSGi framework</p>
</div>
+<div class="sect3">
+<h4 id="_osgi_framework">5.1.4. OSGi framework</h4>
<div class="paragraph">
<p>The <code>system:framework</code> command allows to display the current OSGi framework in use, and enable/disable debugging inside the OSGi framework.</p>
</div>
@@ -14939,9 +15103,9 @@ karaf@root()> system:framework -nodeb
Disabling debug for OSGi framework (felix)</pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Stack traces printout</p>
</div>
+<div class="sect3">
+<h4 id="_stack_traces_printout">5.1.5. Stack traces printout</h4>
<div class="paragraph">
<p>The <code>shell:stack-traces-print</code> command prints the full stack trace when the execution of a command
throws an exception.</p>
@@ -14994,9 +15158,9 @@ karaf@root()> bundle:start
Error executing command: Access to system bundle 0 denied. You can override with -f</pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Bundle tree</p>
</div>
+<div class="sect3">
+<h4 id="_bundle_tree">5.1.6. Bundle tree</h4>
<div class="paragraph">
<p>The <code>bundle:tree-show</code> command shows the bundle dependency tree based on the wiring information of a given single bundle
ID.</p>
@@ -15030,9 +15194,9 @@ org.ops4j.pax.url.wrap [40]
+- org.ops4j.base.lang [41]</pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Watch</p>
</div>
+<div class="sect3">
+<h4 id="_watch">5.1.7. Watch</h4>
<div class="paragraph">
<p>The <code>bundle:watch</code> command enables watching the local Maven repository for updates on bundles.
If the bundle file changes in the Maven repository, Apache Karaf will automatically update the bundle.</p>
@@ -15042,13 +15206,20 @@ If the bundle file changes in the Maven
given URL will be automatically updated. It avoids needing to manually update the bundles or even copy the bundle to the
system folder.</p>
</div>
-</div>
-</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">
<div class="paragraph">
<p>Only Maven based URLs and Maven SNAPSHOTs will actually be updated automatically.</p>
</div>
-<div class="exampleblock">
-<div class="content">
+</td>
+</tr>
+</table>
+</div>
<div class="paragraph">
<p>The following command:</p>
</div>
@@ -15060,15 +15231,15 @@ system folder.</p>
<div class="paragraph">
<p>will monitor all bundles that have a location matching mvn:* and <em>-SNAPSHOT</em> in their URL.</p>
</div>
-<div class="paragraph">
-<p>=== Scripting</p>
</div>
-<div class="paragraph">
-<p>In the console section of the users guide, we introduced the scripting support.</p>
</div>
+<div class="sect2">
+<h3 id="_scripting_2">5.2. Scripting</h3>
<div class="paragraph">
-<p>==== Assignation</p>
+<p>In the console section of the users guide, we introduced the scripting support.</p>
</div>
+<div class="sect3">
+<h4 id="_assignation">5.2.1. Assignation</h4>
<div class="paragraph">
<p>You already know the first usage of scripting: execution of command.</p>
</div>
@@ -15110,9 +15281,9 @@ mvn:org.apache.karaf.jaas/org.apache.kar
We access to the <code>bundle</code> variable (an array containing all bundles), and we want to display the bundle location for
the bundle at the index 1 in the bundle array.</p>
</div>
-<div class="paragraph">
-<p>==== Expressions</p>
</div>
+<div class="sect3">
+<h4 id="_expressions">5.2.2. Expressions</h4>
<div class="paragraph">
<p>The shell has a built-in expression parser. Expressions must be enclosed with the <code>%(...)</code> syntax.</p>
</div>
@@ -15135,9 +15306,8 @@ karaf@root()> %(SQRT(a^2 + b^2))
1.7320508</pre>
</div>
</div>
-<div class="paragraph">
-<p>===== Mathematical Operators</p>
-</div>
+<div class="sect4">
+<h5 id="_mathematical_operators">Mathematical Operators</h5>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 50%;">
@@ -15176,9 +15346,9 @@ karaf@root()> %(SQRT(a^2 + b^2))
</tr>
</tbody>
</table>
-<div class="paragraph">
-<p>===== Boolean Operators</p>
</div>
+<div class="sect4">
+<h5 id="_boolean_operators">Boolean Operators</h5>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 50%;">
@@ -15233,9 +15403,9 @@ karaf@root()> %(SQRT(a^2 + b^2))
</tr>
</tbody>
</table>
-<div class="paragraph">
-<p>===== Supported Functions</p>
</div>
+<div class="sect4">
+<h5 id="_supported_functions">Supported Functions</h5>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 50%;">
@@ -15329,9 +15499,9 @@ karaf@root()> %(SQRT(a^2 + b^2))
<div class="paragraph">
<p>Functions names are case insensitive.</p>
</div>
-<div class="paragraph">
-<p>===== Supported Constants</p>
</div>
+<div class="sect4">
+<h5 id="_supported_constants">Supported Constants</h5>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 50%;">
@@ -15358,9 +15528,10 @@ karaf@root()> %(SQRT(a^2 + b^2))
</tr>
</tbody>
</table>
-<div class="paragraph">
-<p>==== List, maps, pipes and closures</p>
</div>
+</div>
+<div class="sect3">
+<h4 id="_list_maps_pipes_and_closures">5.2.3. List, maps, pipes and closures</h4>
<div class="paragraph">
<p>Using [], you can define an array variable:</p>
</div>
@@ -15410,16 +15581,16 @@ karaf@root()> echo2 hello world
xxx hello world yyy</pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Startup</p>
</div>
+<div class="sect3">
+<h4 id="_startup">5.2.4. Startup</h4>
<div class="paragraph">
<p>The <code>etc/shell.init.script</code> file is executed at startup in each shell session, allowing the definition of additional
variables or aliases or even complex functions. It’s like the bashrc or profile on Unix.</p>
</div>
-<div class="paragraph">
-<p>==== Constants and variables</p>
</div>
+<div class="sect3">
+<h4 id="_constants_and_variables">5.2.5. Constants and variables</h4>
<div class="paragraph">
<p>Apache Karaf console provides a set of implicit constants and variables that you can use in your script.</p>
</div>
@@ -15450,9 +15621,9 @@ ii
karaf@root></pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Built-in variables and commands</p>
</div>
+<div class="sect3">
+<h4 id="_built_in_variables_and_commands">5.2.6. Built-in variables and commands</h4>
<div class="paragraph">
<p>Apache Karaf console provides built-in variables that are very useful for scripting:</p>
</div>
@@ -15491,9 +15662,9 @@ karaf@root></pre>
<div class="paragraph">
<p>See the <a href="commands">full list of <code>shell</code> commands</a> for details.</p>
</div>
-<div class="paragraph">
-<p>==== Leveraging existing Java capabilities (via reflection)</p>
</div>
+<div class="sect3">
+<h4 id="_leveraging_existing_java_capabilities_via_reflection">5.2.7. Leveraging existing Java capabilities (via reflection)</h4>
<div class="paragraph">
<p>Apache Karaf console supports loading and execution of Java classes.</p>
</div>
@@ -15548,9 +15719,9 @@ karaf@root> $map
0 0</pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Examples</p>
</div>
+<div class="sect3">
+<h4 id="_examples">5.2.8. Examples</h4>
<div class="paragraph">
<p>The following examples show some scripts defined in <code>etc/shell.init.script</code>.</p>
</div>
@@ -15614,16 +15785,16 @@ wait-for-command = {
}</pre>
</div>
</div>
-<div class="paragraph">
-<p>=== Programmatically connect</p>
</div>
+</div>
+<div class="sect2">
+<h3 id="_programmatically_connect">5.3. Programmatically connect</h3>
<div class="paragraph">
<p>As described in the users guide, Apache Karaf supports remote access to both the console (by embedding a SSHd server) and
the management layer.</p>
</div>
-<div class="paragraph">
-<p>==== To the console</p>
-</div>
+<div class="sect3">
+<h4 id="_to_the_console">5.3.1. To the console</h4>
<div class="paragraph">
<p>You can write a Apache Karaf remote console client in Java (or other language).</p>
</div>
@@ -15680,9 +15851,9 @@ public class Main {
}</pre>
</div>
</div>
-<div class="paragraph">
-<p>==== To the management layer</p>
</div>
+<div class="sect3">
+<h4 id="_to_the_management_layer">5.3.2. To the management layer</h4>
<div class="paragraph">
<p>The Apache Karaf management layer uses JMX. Apache Karaf embeds a JMX MBeanServer that you can use remotely.</p>
</div>
@@ -15710,12 +15881,12 @@ public class Main {
}</pre>
</div>
</div>
-<div class="paragraph">
-<p>=== Branding</p>
</div>
-<div class="paragraph">
-<p>==== Console</p>
</div>
+<div class="sect2">
+<h3 id="_branding">5.4. Branding</h3>
+<div class="sect3">
+<h4 id="_console_2">5.4.1. Console</h4>
<div class="paragraph">
<p>You can "brand" the Apache Karaf console.</p>
</div>
@@ -15745,9 +15916,9 @@ public class Main {
</li>
</ol>
</div>
-<div class="paragraph">
-<p>==== Adding a branding.properties file to etc</p>
</div>
+<div class="sect3">
+<h4 id="_adding_a_branding_properties_file_to_etc">5.4.2. Adding a branding.properties file to etc</h4>
<div class="paragraph">
<p>Create a <code>etc/branding.properties</code> file similar to:</p>
</div>
@@ -15772,23 +15943,23 @@ prompt = \u001B[1m${USER}@${APPLICATION}
<div class="paragraph">
<p>Start Karaf and you will see your branded Karaf console.</p>
</div>
-<div class="paragraph">
-<p>=== Adding a branding-ssh.properties file to etc</p>
</div>
+</div>
+<div class="sect2">
+<h3 id="_adding_a_branding_ssh_properties_file_to_etc">5.5. Adding a branding-ssh.properties file to etc</h3>
<div class="paragraph">
<p>In a similar way, a <code>etc/branding-ssh.properties</code> file can be added. It should contain the same
<code>welcome</code> and <code>prompt</code> entries but those will be used for external clients connecting through ssh.
The values default to the ones in <code>etc/branding.properties</code> if this file is not defined.</p>
</div>
-<div class="paragraph">
-<p>==== Branding bundle</p>
-</div>
+<div class="sect3">
+<h4 id="_branding_bundle">5.5.1. Branding bundle</h4>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-branding-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-branding-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>==== WebConsole</p>
</div>
+<div class="sect3">
+<h4 id="_webconsole_3">5.5.2. WebConsole</h4>
<div class="paragraph">
<p>It’s also possible to brand the Apache Karaf WebConsole.</p>
</div>
@@ -15871,30 +16042,31 @@ webconsole.stylesheet = /res/karaf/ui/we
<p>With the <code>webconsole</code> feature installed, you can install this bundle (using <code>bundle:install</code> or by editing the
<code>etc/startup.properties</code>), you will see the WebConsole with your branding.</p>
</div>
-<div class="paragraph">
-<p>=== Extending</p>
</div>
-<div class="paragraph">
-<p>Apache Karaf is a very flexible container that you can extend very easily.</p>
</div>
+<div class="sect2">
+<h3 id="_extending">5.6. Extending</h3>
<div class="paragraph">
-<p>==== Shell commands</p>
+<p>Apache Karaf is a very flexible container that you can extend very easily.</p>
</div>
+<div class="sect3">
+<h4 id="_shell_commands">5.6.1. Shell commands</h4>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-command-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-command-example/README.md</a> to add your own shell commands.</p>
</div>
-<div class="paragraph">
-<p>==== WebConsole</p>
</div>
+<div class="sect3">
+<h4 id="_webconsole_4">5.6.2. WebConsole</h4>
<div class="paragraph">
<p>You can also extend the Apache Karaf WebConsole by providing and installing a webconsole plugin.</p>
</div>
<div class="paragraph">
<p>A plugin is an OSGi bundle that registers a Servlet as an OSGi service with webconsole properties.</p>
</div>
-<div class="paragraph">
-<p>=== Using the karaf-maven-plugin</p>
</div>
+</div>
+<div class="sect2">
+<h3 id="_using_the_karaf_maven_plugin">5.7. Using the karaf-maven-plugin</h3>
<div class="paragraph">
<p>The Karaf Maven plugin allows you:</p>
</div>
@@ -15914,9 +16086,8 @@ webconsole.stylesheet = /res/karaf/ui/we
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-maven-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-maven-example/README.md</a> for details.</p>
</div>
-<div class="paragraph">
-<p>==== Packaging</p>
-</div>
+<div class="sect3">
+<h4 id="_packaging">5.7.1. Packaging</h4>
<div class="paragraph">
<p>The most generally useful features of the karaf-maven-plugin are exposed as packagings. To use the packagings the pom or an ancestor must configure the karaf-maven-plugin with extensions:</p>
</div>
@@ -15976,15 +16147,14 @@ webconsole.stylesheet = /res/karaf/ui/we
</tr>
</tbody>
</table>
-<div class="paragraph">
-<p>==== Commands goals</p>
</div>
+<div class="sect3">
+<h4 id="_commands_goals">5.7.2. Commands goals</h4>
<div class="paragraph">
<p>The <code>karaf-maven-plugin</code> is able to generate documentation for Karaf commands</p>
</div>
-<div class="paragraph">
-<p>===== <code>karaf:commands-generate-help</code></p>
-</div>
+<div class="sect4">
+<h5 id="_code_karaf_commands_generate_help_code"><code>karaf:commands-generate-help</code></h5>
<div class="paragraph">
<p>The <code>karaf:commands-generate-help</code> goal generates documentation containing Karaf commands help.</p>
</div>
@@ -15992,9 +16162,8 @@ webconsole.stylesheet = /res/karaf/ui/we
<p>It looks for Karaf commands in the current project class loader and generates the help as displayed with the <code>--help</code>
option in the Karaf shell console.</p>
</div>
-<div class="paragraph">
-<p>====== Example</p>
-</div>
+<div class="sect5">
+<h6 id="_example">Example</h6>
<div class="paragraph">
<p>The example below generates help for the commands in the current project:</p>
</div>
@@ -16026,9 +16195,9 @@ option in the Karaf shell console.</p>
</project></pre>
</div>
</div>
-<div class="paragraph">
-<p>====== Parameters</p>
</div>
+<div class="sect5">
+<h6 id="_parameters">Parameters</h6>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 33.3333%;">
@@ -16060,22 +16229,30 @@ option in the Karaf shell console.</p>
</tr>
</tbody>
</table>
-<div class="paragraph">
-<p>==== Features and kar goals</p>
</div>
</div>
</div>
+<div class="sect3">
+<h4 id="_features_and_kar_goals">5.7.3. Features and kar goals</h4>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">
<div class="paragraph">
<p>You should use the features or kar packaging instead of these individual goals.</p>
</div>
-<div class="exampleblock">
-<div class="content">
-<div class="paragraph">
-<p>The <code>karaf-maven-plugin</code> provides several goals to help you create and verify features XML descriptors as well as leverage your features to create a custom Karaf distribution.</p>
+</td>
+</tr>
+</table>
</div>
<div class="paragraph">
-<p>===== <code>karaf:features-generate-descriptor</code></p>
+<p>The <code>karaf-maven-plugin</code> provides several goals to help you create and verify features XML descriptors as well as leverage your features to create a custom Karaf distribution.</p>
</div>
+<div class="sect4">
+<h5 id="_code_karaf_features_generate_descriptor_code"><code>karaf:features-generate-descriptor</code></h5>
<div class="paragraph">
<p>The <code>karaf:features-generate-descriptor</code> goal generates a features XML file based on the Maven dependencies.
By default, it will follow Maven transitive dependencies, stopping when it encounters bundles already present in features that are Maven dependencies.</p>
@@ -16086,9 +16263,8 @@ By default, it will follow Maven transit
<div class="paragraph">
<p>You can track dependency changes and warn or fail on change.</p>
</div>
-<div class="paragraph">
-<p>====== Configuration</p>
-</div>
+<div class="sect5">
+<h6 id="_configuration_8">Configuration</h6>
<div class="paragraph">
<p>Specify the packaging as a top level element</p>
</div>
@@ -16164,9 +16340,9 @@ This can be overridden by specifying the
</tr>
</tbody>
</table>
-<div class="paragraph">
-<p>====== Example</p>
</div>
+<div class="sect5">
+<h6 id="_example_2">Example</h6>
<div class="listingblock">
<div class="content">
<pre><project>
@@ -16204,9 +16380,10 @@ This can be overridden by specifying the
</project></pre>
</div>
</div>
-<div class="paragraph">
-<p>===== <code>karaf:verify</code></p>
</div>
+</div>
+<div class="sect4">
+<h5 id="_code_karaf_verify_code"><code>karaf:verify</code></h5>
<div class="paragraph">
<p>Except in unusual circumstances, use the <code><packaging>feature</packaging></code> to run this goal.</p>
</div>
@@ -16219,9 +16396,8 @@ for the bundles defined in the features
It means that it’s not required to explicitly define the Karaf features descriptor in the repository section of
your features descriptor.</p>
</div>
-<div class="paragraph">
-<p>====== Example</p>
-</div>
+<div class="sect5">
+<h6 id="_example_3">Example</h6>
<div class="paragraph">
<p>The example below validates the features defined in the <code>target/features.xml</code> by checking all the imports and exports.
It reads the definition for the packages that are exported by the system bundle from the <code>src/main/resources/config.properties</code> file.</p>
@@ -16262,9 +16438,9 @@ It reads the definition for the packages
</project></pre>
</div>
</div>
-<div class="paragraph">
-<p>====== Parameters</p>
</div>
+<div class="sect5">
+<h6 id="_parameters_2">Parameters</h6>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 33.3333%;">
@@ -16301,9 +16477,10 @@ It reads the definition for the packages
</tr>
</tbody>
</table>
-<div class="paragraph">
-<p>===== <code>karaf:features-add-to-repository</code></p>
</div>
+</div>
+<div class="sect4">
+<h5 id="_code_karaf_features_add_to_repository_code"><code>karaf:features-add-to-repository</code></h5>
<div class="paragraph">
<p>Consider using the karaf-assembly packaging which makes it easy to assemble a custom distribution in one step instead
of this individual goal.</p>
@@ -16315,9 +16492,8 @@ You can use this goal to create a <code>
<div class="paragraph">
<p>By default, the Karaf core features descriptors (standard and enterprise) are automatically included in the descriptors set.</p>
</div>
-<div class="paragraph">
-<p>====== Example</p>
-</div>
+<div class="sect5">
+<h6 id="_example_4">Example</h6>
<div class="paragraph">
<p>The example below copies the bundles for the <code>spring</code> and <code>war</code> features defined in the Karaf features XML descriptor
into the <code>target/features-repo</code> directory.</p>
@@ -16359,9 +16535,9 @@ into the <code>target/features-repo</cod
</project></pre>
</div>
</div>
-<div class="paragraph">
-<p>====== Parameters</p>
</div>
+<div class="sect5">
+<h6 id="_parameters_3">Parameters</h6>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 33.3333%;">
@@ -16398,16 +16574,24 @@ into the <code>target/features-repo</cod
</tr>
</tbody>
</table>
-<div class="paragraph">
-<p>===== <code>karaf:create-kar</code></p>
-</div>
</div>
</div>
+<div class="sect4">
+<h5 id="_code_karaf_create_kar_code"><code>karaf:create-kar</code></h5>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">
<div class="paragraph">
<p>Except in unusual circumstances, use the <code><packaging>kar</packaging></code> to run this goal.</p>
</div>
-<div class="exampleblock">
-<div class="content">
+</td>
+</tr>
+</table>
+</div>
<div class="paragraph">
<p>The <code>karaf:kar</code> goal assembles a KAR archive from a features XML descriptor file, normally generated in the same project
with the <code>karaf:features-generate-descriptor</code> goal.</p>
@@ -16432,9 +16616,8 @@ Therefore resources you want installed i
This choice is so other resources such as legal files from the maven-remote-resources-plugin can be included under
META-INF in the kar, without getting installed into Karaf.</p>
</div>
-<div class="paragraph">
-<p>====== Example</p>
-</div>
+<div class="sect5">
+<h6 id="_example_5">Example</h6>
<div class="listingblock">
<div class="content">
<pre><project>
@@ -16454,31 +16637,39 @@ META-INF in the kar, without getting ins
</project></pre>
</div>
</div>
-<div class="paragraph">
-<p>===== <code>karaf:install-kar</code></p>
</div>
-<div class="paragraph">
-<p>==== Instances and distributions goals</p>
</div>
-<div class="paragraph">
-<p>The <code>karaf-maven-plugin</code> helps you to build custom Karaf distributions or archives existing Karaf instances:</p>
-</div>
-<div class="paragraph">
-<p>===== <code>karaf:assembly</code></p>
+<div class="sect4">
+<h5 id="_code_karaf_install_kar_code"><code>karaf:install-kar</code></h5>
+
</div>
</div>
+<div class="sect3">
+<h4 id="_instances_and_distributions_goals">5.7.4. Instances and distributions goals</h4>
+<div class="paragraph">
+<p>The <code>karaf-maven-plugin</code> helps you to build custom Karaf distributions or archives existing Karaf instances:</p>
</div>
+<div class="sect4">
+<h5 id="_code_karaf_assembly_code"><code>karaf:assembly</code></h5>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">
<div class="paragraph">
<p>This goal is run as part of the karaf-assembly packaging.</p>
</div>
-<div class="exampleblock">
-<div class="content">
-<div class="paragraph">
-<p>The <code>karaf:assembly</code> goal creates a Karaf instance (assembly) filesystem using the Maven dependencies and a provided configuration.</p>
+</td>
+</tr>
+</table>
</div>
<div class="paragraph">
-<p>====== Example</p>
+<p>The <code>karaf:assembly</code> goal creates a Karaf instance (assembly) filesystem using the Maven dependencies and a provided configuration.</p>
</div>
+<div class="sect5">
+<h6 id="_example_6">Example</h6>
<div class="listingblock">
<div class="content">
<pre> ...
@@ -16578,9 +16769,9 @@ META-INF in the kar, without getting ins
</build></pre>
</div>
</div>
-<div class="paragraph">
-<p>====== Parameters</p>
</div>
+<div class="sect5">
+<h6 id="_parameters_4">Parameters</h6>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 33.3333%;">
@@ -16742,25 +16933,32 @@ META-INF in the kar, without getting ins
</tr>
</tbody>
</table>
-<div class="paragraph">
-<p>===== <code>karaf:archive</code></p>
-</div>
</div>
</div>
+<div class="sect4">
+<h5 id="_code_karaf_archive_code"><code>karaf:archive</code></h5>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">
<div class="paragraph">
<p>This goal is run as part of the karaf-assembly packaging.</p>
</div>
-<div class="exampleblock">
-<div class="content">
+</td>
+</tr>
+</table>
+</div>
<div class="paragraph">
<p>The <code>karaf:archive</code> goal packages a Karaf instance archive from a given assembled instance.</p>
</div>
<div class="paragraph">
<p>Both tar.gz and zip formats are generated in the destination folder.</p>
</div>
-<div class="paragraph">
-<p>====== Example</p>
-</div>
+<div class="sect5">
+<h6 id="_example_7">Example</h6>
<div class="paragraph">
<p>The example below create archives for the given Karaf instance:</p>
</div>
@@ -16793,9 +16991,9 @@ META-INF in the kar, without getting ins
</project></pre>
</div>
</div>
-<div class="paragraph">
-<p>====== Parameters</p>
</div>
+<div class="sect5">
+<h6 id="_parameters_5">Parameters</h6>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 33.3333%;">
@@ -16862,24 +17060,24 @@ META-INF in the kar, without getting ins
</tr>
</tbody>
</table>
-<div class="paragraph">
-<p>==== Run, client, deploy goals</p>
</div>
-<div class="paragraph">
-<p>These goals allows you to run Karaf via Maven or interact with a running instance.</p>
</div>
+</div>
+<div class="sect3">
+<h4 id="_run_client_deploy_goals">5.7.5. Run, client, deploy goals</h4>
<div class="paragraph">
-<p>===== <code>karaf:run</code></p>
+<p>These goals allows you to run Karaf via Maven or interact with a running instance.</p>
</div>
+<div class="sect4">
+<h5 id="_code_karaf_run_code"><code>karaf:run</code></h5>
<div class="paragraph">
<p><code>karaf:run</code> goal runs a Karaf instance from Maven.</p>
</div>
<div class="paragraph">
<p>It can use the current project if it’s a bundle to directly deploy the project artifact in the running Karaf instance.</p>
</div>
-<div class="paragraph">
-<p>====== Example</p>
-</div>
+<div class="sect5">
+<h6 id="_example_8">Example</h6>
<div class="listingblock">
<div class="content">
<pre> <build>
@@ -16905,9 +17103,9 @@ META-INF in the kar, without getting ins
</build></pre>
</div>
</div>
-<div class="paragraph">
-<p>====== Parameters</p>
</div>
+<div class="sect5">
+<h6 id="_parameters_6">Parameters</h6>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 33.3333%;">
@@ -16959,15 +17157,15 @@ META-INF in the kar, without getting ins
</tr>
</tbody>
</table>
-<div class="paragraph">
-<p>===== <code>karaf:client</code></p>
</div>
-<div class="paragraph">
-<p>The <code>karaf:client</code> interacts with a running Karaf instance directly from Maven via SSH.</p>
</div>
+<div class="sect4">
+<h5 id="_code_karaf_client_code"><code>karaf:client</code></h5>
<div class="paragraph">
-<p>====== Example</p>
+<p>The <code>karaf:client</code> interacts with a running Karaf instance directly from Maven via SSH.</p>
</div>
+<div class="sect5">
+<h6 id="_example_9">Example</h6>
<div class="listingblock">
<div class="content">
<pre><execution>
@@ -16986,9 +17184,9 @@ META-INF in the kar, without getting ins
</execution></pre>
</div>
</div>
-<div class="paragraph">
-<p>====== Parameters</p>
</div>
+<div class="sect5">
+<h6 id="_parameters_7">Parameters</h6>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 33.3333%;">
@@ -17055,15 +17253,16 @@ META-INF in the kar, without getting ins
</tr>
</tbody>
</table>
-<div class="paragraph">
-<p>===== <code>karaf:deploy</code></p>
</div>
+</div>
+<div class="sect4">
+<h5 id="_code_karaf_deploy_code"><code>karaf:deploy</code></h5>
<div class="paragraph">
<p>The <code>karaf:deploy</code> goal allows you to deploy bundles on a running Karaf instance (via SSH or JMX).</p>
</div>
-<div class="paragraph">
-<p>===== Example</p>
</div>
+<div class="sect4">
+<h5 id="_example_10">Example</h5>
<div class="listingblock">
<div class="content">
<pre><execution>
@@ -17077,9 +17276,9 @@ META-INF in the kar, without getting ins
</execution></pre>
</div>
</div>
-<div class="paragraph">
-<p>===== Parameters</p>
</div>
+<div class="sect4">
+<h5 id="_parameters_8">Parameters</h5>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 33.3333%;">
@@ -17151,21 +17350,20 @@ META-INF in the kar, without getting ins
</tr>
</tbody>
</table>
-<div class="paragraph">
-<p>==== Dockerfile, Docker</p>
</div>
-<div class="paragraph">
-<p>The Karaf Maven plugin is also able to generate Dockerfile and eventually interact with a local Docker daemon.</p>
</div>
+<div class="sect3">
+<h4 id="_dockerfile_docker">5.7.6. Dockerfile, Docker</h4>
<div class="paragraph">
-<p>===== Dockerfile</p>
+<p>The Karaf Maven plugin is also able to generate Dockerfile and eventually interact with a local Docker daemon.</p>
</div>
+<div class="sect4">
+<h5 id="_dockerfile">Dockerfile</h5>
<div class="paragraph">
<p>The <code>karaf:dockerfile</code> goal creates a ready to use Dockerfile for a given Karaf distribution/assembly.</p>
</div>
-<div class="paragraph">
-<p>====== Example</p>
-</div>
+<div class="sect5">
+<h6 id="_example_11">Example</h6>
<div class="listingblock">
<div class="content">
<pre><execution>
@@ -17176,9 +17374,9 @@ META-INF in the kar, without getting ins
</execution></pre>
</div>
</div>
-<div class="paragraph">
-<p>====== Parameters</p>
</div>
+<div class="sect5">
+<h6 id="_parameters_9">Parameters</h6>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 33.3333%;">
@@ -17205,22 +17403,29 @@ META-INF in the kar, without getting ins
</tr>
</tbody>
</table>
-<div class="paragraph">
-<p>===== Docker</p>
</div>
+</div>
+<div class="sect4">
+<h5 id="_docker_2">Docker</h5>
<div class="paragraph">
<p>The <code>karaf:docker</code> goal interacts directly with a local Docker daemon (via the command line) to directly create a Docker image with your Karaf assembly.</p>
</div>
-</div>
-</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">
<div class="paragraph">
<p>This goal requires a local Docker daemon and runs only on Unix. The <code>docker</code> command has to be in the <code>PATH</code>.</p>
</div>
-<div class="exampleblock">
-<div class="content">
-<div class="paragraph">
-<p>====== Example</p>
+</td>
+</tr>
+</table>
</div>
+<div class="sect5">
+<h6 id="_example_12">Example</h6>
<div class="listingblock">
<div class="content">
<pre><execution>
@@ -17231,9 +17436,9 @@ META-INF in the kar, without getting ins
</execution></pre>
</div>
</div>
-<div class="paragraph">
-<p>====== Parameters</p>
</div>
+<div class="sect5">
+<h6 id="_parameters_10">Parameters</h6>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 33.3333%;">
@@ -17260,9 +17465,12 @@ META-INF in the kar, without getting ins
</tr>
</tbody>
</table>
-<div class="paragraph">
-<p>=== Custom distributions</p>
</div>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_custom_distributions">5.8. Custom distributions</h3>
<div class="paragraph">
<p>As Karaf is an OSGi container, it’s heavily used as as application and middleware kernel.</p>
</div>
@@ -17297,9 +17505,8 @@ META-INF in the kar, without getting ins
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/tree/master/examples/karaf-maven-example/karaf-maven-example-assembly" class="bare">https://github.com/apache/karaf/tree/master/examples/karaf-maven-example/karaf-maven-example-assembly</a> for a custom distribution example.</p>
</div>
-<div class="paragraph">
-<p>==== Maven assembly</p>
-</div>
+<div class="sect3">
+<h4 id="_maven_assembly">5.8.1. Maven assembly</h4>
<div class="paragraph">
<p>The recommended way to create a Karaf server assembly is to use the karaf-assembly packaging with the karaf-maven-plugin.
This assembles a server from the maven dependencies in the project pom. After explanation of the configuration options
@@ -17313,9 +17520,8 @@ limitations we have to simulate rather t
<p>This packaging creates tar.gz and zip archives containing the assembled server.
They are identical except that zip archives don’t unpack with appropriate unix file permissions for the scripts.</p>
</div>
-<div class="paragraph">
-<p>===== Maven dependencies</p>
-</div>
+<div class="sect4">
+<h5 id="_maven_dependencies">Maven dependencies</h5>
<div class="paragraph">
<p>Maven dependencies in a karaf-assembly project can be feature repositories (classifier "features") or kar archives.
Feature repositories are installed in the internal "system" Maven structured repository.
@@ -17337,9 +17543,9 @@ in the karaf-maven-plugin configuration.
</li>
</ul>
</div>
-<div class="paragraph">
-<p>===== Plugin configuration</p>
</div>
+<div class="sect4">
+<h5 id="_plugin_configuration">Plugin configuration</h5>
<div class="paragraph">
<p>Control how features are installed using these elements referring to features from installed feature repositories:</p>
</div>
@@ -17377,9 +17583,9 @@ For instance:</p>
</libraries></pre>
</div>
</div>
-<div class="paragraph">
-<p>===== Minimal Distribution Example</p>
</div>
+<div class="sect4">
+<h5 id="_minimal_distribution_example">Minimal Distribution Example</h5>
<div class="paragraph">
<p>This is the minimal assembly pom changed to use the packaging and annotated</p>
</div>
@@ -17455,9 +17661,9 @@ For instance:</p>
</project></pre>
</div>
</div>
-<div class="paragraph">
-<p>===== Custom Distribution Example</p>
</div>
+<div class="sect4">
+<h5 id="_custom_distribution_example">Custom Distribution Example</h5>
<div class="paragraph">
<p>It’s possible to specify feature versions using the name/version format.</p>
</div>
@@ -17543,9 +17749,10 @@ For instance:</p>
</project></pre>
</div>
</div>
-<div class="paragraph">
-<p>==== (deprecated old style) Maven assembly</p>
</div>
+</div>
+<div class="sect3">
+<h4 id="_deprecated_old_style_maven_assembly">5.8.2. (deprecated old style) Maven assembly</h4>
<div class="paragraph">
<p>Basically a Karaf custom distribution involves:</p>
</div>
@@ -18009,9 +18216,10 @@ assembly descriptor, configured in POM a
<div class="paragraph">
<p>You will find your Karaf custom distribution tar.gz in the target directory.</p>
</div>
-<div class="paragraph">
-<p>=== Creating Bundles</p>
</div>
+</div>
+<div class="sect2">
+<h3 id="_creating_bundles">5.9. Creating Bundles</h3>
<div class="paragraph">
<p>The examples provides different kind of bundles and services definition:</p>
</div>
@@ -18028,9 +18236,8 @@ assembly descriptor, configured in POM a
</li>
</ul>
</div>
-<div class="paragraph">
-<p>==== Add extended information to bundles</p>
-</div>
+<div class="sect3">
+<h4 id="_add_extended_information_to_bundles">5.9.1. Add extended information to bundles</h4>
<div class="paragraph">
<p>Karaf supports a OSGI-INF/bundle.info file in a bundle.
This file is an extended description of the bundle.
@@ -18060,9 +18267,9 @@ h1. SEE ALSO
<pre>root@karaf> bundles:info</pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Wiki Syntax</p>
</div>
+<div class="sect3">
+<h4 id="_wiki_syntax">5.9.2. Wiki Syntax</h4>
<div class="paragraph">
<p>Karaf supports some simple wiki syntax in bundle info files:</p>
</div>
@@ -18074,12 +18281,12 @@ h1. SEE ALSO
**text** : bold text</pre>
</div>
</div>
-<div class="paragraph">
-<p>=== Creating bundles for non OSGi third party dependencies</p>
</div>
-<div class="paragraph">
-<p>==== Dynamically wrapping jars</p>
</div>
+<div class="sect2">
+<h3 id="_creating_bundles_for_non_osgi_third_party_dependencies">5.10. Creating bundles for non OSGi third party dependencies</h3>
+<div class="sect3">
+<h4 id="_dynamically_wrapping_jars">5.10.1. Dynamically wrapping jars</h4>
<div class="paragraph">
<p>Karaf supports the wrap: protocol execution.</p>
</div>
@@ -18143,9 +18350,9 @@ h1. SEE ALSO
</features></pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Statically bundling jars</p>
</div>
+<div class="sect3">
+<h4 id="_statically_bundling_jars">5.10.2. Statically bundling jars</h4>
<div class="paragraph">
<p>You can also create a wrap bundle for a third party dependency.
This bundle is simply a Maven POM that shades an existing jar and package into a jar bundle.</p>
@@ -18240,34 +18447,33 @@ This bundle is simply a Maven POM that s
<pre>root@karaf> bundles:install -s mvn:osgi.commons-lang/osgi.commons-lang/2.4</pre>
</div>
</div>
-<div class="paragraph">
-<p>=== Blueprint</p>
</div>
+</div>
+<div class="sect2">
+<h3 id="_blueprint">5.11. Blueprint</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-blueprint-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-blueprint-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>=== SCR</p>
</div>
+<div class="sect2">
+<h3 id="_scr">5.12. SCR</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/tree/master/examples/karaf-scr-example" class="bare">https://github.com/apache/karaf/tree/master/examples/karaf-scr-example</a></p>
</div>
-<div class="paragraph">
-<p>=== Archetypes</p>
</div>
+<div class="sect2">
+<h3 id="_archetypes">5.13. Archetypes</h3>
<div class="paragraph">
<p>Karaf provides archetypes to easily create commands, manage features or repository and create a kar archive.
This section describes each of them and explain How to use it.</p>
</div>
-<div class="paragraph">
-<p>==== Create a command (karaf-command-archetype)</p>
-</div>
+<div class="sect3">
+<h4 id="_create_a_command_karaf_command_archetype">5.13.1. Create a command (karaf-command-archetype)</h4>
<div class="paragraph">
<p>This archetype creates a Maven skeleton project that you will use to develop new Karaf commands.</p>
</div>
-<div class="paragraph">
-<p>===== Command line</p>
-</div>
+<div class="sect4">
+<h5 id="_command_line">Command line</h5>
<div class="paragraph">
<p>Using the command line, we can create our project:</p>
</div>
@@ -18283,9 +18489,9 @@ This section describes each of them and
-Dpackage=com.mycompany.package</pre>
</div>
</div>
-<div class="paragraph">
-<p>===== Additional parameters</p>
</div>
+<div class="sect4">
+<h5 id="_additional_parameters">Additional parameters</h5>
<div class="paragraph">
<p>During the maven creation process, additional questions will be asked on the console :</p>
</div>
@@ -18304,9 +18510,9 @@ This description will be displayed in th
</li>
</ul>
</div>
-<div class="paragraph">
-<p>===== Result of Maven command execution</p>
</div>
+<div class="sect4">
+<h5 id="_result_of_maven_command_execution">Result of Maven command execution</h5>
<div class="listingblock">
<div class="content">
<pre>[INFO] Scanning for projects...
@@ -18367,16 +18573,16 @@ scope: my
<div class="paragraph">
<p>Next, you can import your project in Eclipse/IntelliJ and developp the Karaf command.</p>
</div>
-<div class="paragraph">
-<p>==== Create an OSGi bundle (karaf-bundle-archetype)</p>
</div>
+</div>
+<div class="sect3">
+<h4 id="_create_an_osgi_bundle_karaf_bundle_archetype">5.13.2. Create an OSGi bundle (karaf-bundle-archetype)</h4>
<div class="paragraph">
<p>This archetype creates a Maven skeleton to create an OSGi bundle, including a bundle Activator (a special callback
class for bundle start/stop).</p>
</div>
-<div class="paragraph">
-<p>===== Command line</p>
-</div>
+<div class="sect4">
+<h5 id="_command_line_2">Command line</h5>
<div class="paragraph">
<p>Using the command line, we can create our project:</p>
</div>
@@ -18392,9 +18598,9 @@ class for bundle start/stop).</p>
-Dpackage=com.mycompany.package</pre>
</div>
</div>
-<div class="paragraph">
-<p>===== Result of Maven command execution</p>
</div>
+<div class="sect4">
+<h5 id="_result_of_maven_command_execution_2">Result of Maven command execution</h5>
<div class="listingblock">
<div class="content">
<pre>[INFO] Scanning for projects...
@@ -18442,16 +18648,16 @@ package: com.mycompany.package
[INFO] ------------------------------------------------------------------------</pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Create an OSGi blueprint bundle (karaf-blueprint-archetype)</p>
</div>
+</div>
+<div class="sect3">
+<h4 id="_create_an_osgi_blueprint_bundle_karaf_blueprint_archetype">5.13.3. Create an OSGi blueprint bundle (karaf-blueprint-archetype)</h4>
<div class="paragraph">
<p>This archetype creates a Maven skeleton project to create an OSGi blueprint bundle, including a sample bean exposed as
an OSGi service in the blueprint XML descriptor.</p>
</div>
-<div class="paragraph">
-<p>===== Command line</p>
-</div>
+<div class="sect4">
+<h5 id="_command_line_3">Command line</h5>
<div class="paragraph">
<p>Using the command line, we can create our project:</p>
</div>
@@ -18467,9 +18673,9 @@ an OSGi service in the blueprint XML des
-Dpackage=com.mycompany.blueprint</pre>
</div>
</div>
-<div class="paragraph">
-<p>===== Result of Maven command execution</p>
</div>
+<div class="sect4">
+<h5 id="_result_of_maven_command_execution_3">Result of Maven command execution</h5>
<div class="listingblock">
<div class="content">
<pre>[INFO] Scanning for projects...
@@ -18517,16 +18723,16 @@ package: com.mycompany.package
[INFO] ------------------------------------------------------------------------</pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Create a features XML (karaf-feature-archetype)</p>
</div>
+</div>
+<div class="sect3">
+<h4 id="_create_a_features_xml_karaf_feature_archetype">5.13.4. Create a features XML (karaf-feature-archetype)</h4>
<div class="paragraph">
<p>This archetype creates a Maven skeleton project which create a features XML file, using the dependencies that you define
in the POM.</p>
</div>
-<div class="paragraph">
-<p>===== Command line</p>
-</div>
+<div class="sect4">
+<h5 id="_command_line_4">Command line</h5>
<div class="paragraph">
<p>Using the command line, we can create our project:</p>
</div>
@@ -18542,9 +18748,9 @@ in the POM.</p>
-Dpackage=my.company.package</pre>
</div>
</div>
-<div class="paragraph">
-<p>===== Result of maven command execution</p>
</div>
+<div class="sect4">
+<h5 id="_result_of_maven_command_execution_4">Result of maven command execution</h5>
<div class="listingblock">
<div class="content">
<pre>[INFO] Scanning for projects...
@@ -18592,15 +18798,15 @@ package: com.mycompany.package
[INFO] ------------------------------------------------------------------------</pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Create a KAR file (karaf-kar-archetype)</p>
</div>
-<div class="paragraph">
-<p>This archetype creates a Maven skeleton project including a features XML sample, used to generate a KAR file.</p>
</div>
+<div class="sect3">
+<h4 id="_create_a_kar_file_karaf_kar_archetype">5.13.5. Create a KAR file (karaf-kar-archetype)</h4>
<div class="paragraph">
-<p>===== Command line</p>
+<p>This archetype creates a Maven skeleton project including a features XML sample, used to generate a KAR file.</p>
</div>
+<div class="sect4">
+<h5 id="_command_line_5">Command line</h5>
<div class="paragraph">
<p>Using the command line, we can create our project:</p>
</div>
@@ -18616,9 +18822,9 @@ package: com.mycompany.package
-Dpackage=com.mycompany.package</pre>
</div>
</div>
-<div class="paragraph">
-<p>===== Result of maven command execution</p>
</div>
+<div class="sect4">
+<h5 id="_result_of_maven_command_execution_5">Result of maven command execution</h5>
<div class="listingblock">
<div class="content">
<pre>[INFO] Scanning for projects...
@@ -18666,9 +18872,11 @@ package: com.mycompany.package
[INFO] ------------------------------------------------------------------------</pre>
</div>
</div>
-<div class="paragraph">
-<p>=== Security framework</p>
</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_security_framework">5.14. Security framework</h3>
<div class="paragraph">
<p>Karaf supports <a href="http://download.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html">JAAS</a> with
some enhancements to allow JAAS to work nicely in an OSGi environment.</p>
@@ -18676,9 +18884,8 @@ some enhancements to allow JAAS to work
<div class="paragraph">
<p>This framework also features an OSGi keystore manager with the ability to deploy new keystores or truststores at runtime.</p>
</div>
-<div class="paragraph">
-<p>==== Overview</p>
-</div>
+<div class="sect3">
+<h4 id="_overview_2">5.14.1. Overview</h4>
<div class="paragraph">
<p>This feature allows runtime deployment of JAAS based configuration for use in various parts of the application. This
includes the remote console login, which uses the <code>karaf</code> realm, but which is configured with a dummy login module
@@ -18692,9 +18899,9 @@ up HTTPS connectors or using certificate
<div class="paragraph">
<p>A very simple XML schema for spring has been defined, allowing the deployment of a new realm or a new keystore very easily.</p>
</div>
-<div class="paragraph">
-<p>==== Schema and Deployer</p>
</div>
+<div class="sect3">
+<h4 id="_schema_and_deployer">5.14.2. Schema and Deployer</h4>
<div class="paragraph">
<p>To override or deploy a new realm, you can use the following XSD which is supported by a Blueprint namespace handler and
can thus be defined in a Blueprint xml configuration file.
@@ -18761,9 +18968,8 @@ The content of the <code>module</code> e
<div class="paragraph">
<p>Deploying such a code will lead to a JaasRealm object in the OSGi registry, which will then be used when using the JAAS login module.</p>
</div>
-<div class="paragraph">
-<p>===== Configuration override and use of the <code>rank</code> attribute</p>
-</div>
+<div class="sect4">
+<h5 id="_configuration_override_and_use_of_the_code_rank_code_attribute">Configuration override and use of the <code>rank</code> attribute</h5>
<div class="paragraph">
<p>The <code>rank</code> attribute on the <code>config</code> element is tied to the ranking of the underlying OSGi service. When the JAAS
framework performs an authentication, it will use the realm name to find a matching JAAS configuration. If multiple
@@ -18792,9 +18998,10 @@ JMX layer), you need to deploy a JAAS co
</blueprint></pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Architecture</p>
</div>
+</div>
+<div class="sect3">
+<h4 id="_architecture">5.14.3. Architecture</h4>
<div class="paragraph">
<p>Due to constraints in the JAAS specification, one class has to be available for all bundles.
This class is called ProxyLoginModule and is a LoginModule that acts as a proxy for an OSGi defined LoginModule.
@@ -18818,18 +19025,17 @@ allows you to manipulate users and roles
The backend engine is constructed by a backend engine factory, registered as an OSGi service.
Some login modules (for security reasons for instance) don’t provide backend engine.</p>
</div>
-<div class="paragraph">
-<p>==== Available realm and login modules</p>
</div>
+<div class="sect3">
+<h4 id="_available_realm_and_login_modules">5.14.4. Available realm and login modules</h4>
<div class="paragraph">
<p>Karaf comes with a default realm named "karaf" using login modules.</p>
</div>
<div class="paragraph">
<p>Karaf also provides a set of login modules and backend engines to handle authentication needs for your environment.</p>
</div>
-<div class="paragraph">
-<p>===== PropertiesLoginModule</p>
-</div>
+<div class="sect4">
+<h5 id="_propertiesloginmodule">PropertiesLoginModule</h5>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 50%;">
@@ -18947,9 +19153,9 @@ shows how to register the PropertiesLogi
</blueprint></pre>
</div>
</div>
-<div class="paragraph">
-<p>===== OsgiConfigLoginModule</p>
</div>
+<div class="sect4">
+<h5 id="_osgiconfigloginmodule">OsgiConfigLoginModule</h5>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 50%;">
@@ -19020,16 +19226,23 @@ user.user=password,role</pre>
</blueprint></pre>
</div>
</div>
-</div>
-</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">
<div class="paragraph">
<p>The OsgiConfigLoginModule doesn’t provide a backend engine.</p>
</div>
-<div class="exampleblock">
-<div class="content">
-<div class="paragraph">
-<p>===== JDBCLoginModule</p>
+</td>
+</tr>
+</table>
+</div>
</div>
+<div class="sect4">
+<h5 id="_jdbcloginmodule">JDBCLoginModule</h5>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 50%;">
@@ -19131,13 +19344,20 @@ services via JNDI.</p>
</li>
</ul>
</div>
-</div>
-</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">
<div class="paragraph">
<p>The groups are not fully supported by the JDBCBackingEngine.</p>
</div>
-<div class="exampleblock">
-<div class="content">
+</td>
+</tr>
+</table>
+</div>
<div class="paragraph">
<p>The following blueprint shows how to define the JDBCLoginModule with the corresponding backend engine:</p>
</div>
@@ -19166,9 +19386,9 @@ services via JNDI.</p>
</blueprint></pre>
</div>
</div>
-<div class="paragraph">
-<p>===== LDAPLoginModule</p>
</div>
+<div class="sect4">
+<h5 id="_ldaploginmodule">LDAPLoginModule</h5>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 50%;">
@@ -19381,17 +19601,24 @@ default <code>karaf</code> realm):</p>
</jaas:config></pre>
</div>
</div>
-</div>
-</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">
<div class="paragraph">
<p>The LDAPLoginModule doesn’t provide backend engine. It means that the administration of the users and roles should be
performed directly on the LDAP backend.</p>
</div>
-<div class="exampleblock">
-<div class="content">
-<div class="paragraph">
-<p>===== KerberosLoginModule</p>
+</td>
+</tr>
+</table>
</div>
+</div>
+<div class="sect4">
+<h5 id="_kerberosloginmodule">KerberosLoginModule</h5>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 50%;">
@@ -19455,9 +19682,9 @@ Here is a simple example of a krb5 confi
example.com = EXAMPLE.COM</pre>
</div>
</div>
-<div class="paragraph">
-<p>===== GSSAPILdapLoginModule</p>
</div>
+<div class="sect4">
+<h5 id="_gssapildaploginmodule">GSSAPILdapLoginModule</h5>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 50%;">
@@ -19512,9 +19739,9 @@ Typical use is using this and a Kerberos
<div class="paragraph">
<p>Note the <em>gssapiRealm</em> property of the LDAP login module that match the name of the Kerberos Configuration.</p>
</div>
-<div class="paragraph">
-<p>===== SyncopeLoginModule</p>
</div>
+<div class="sect4">
+<h5 id="_syncopeloginmodule">SyncopeLoginModule</h5>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 50%;">
@@ -19619,9 +19846,10 @@ users and roles directly from Karaf. To
</blueprint></pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Encryption service</p>
</div>
+</div>
+<div class="sect3">
+<h4 id="_encryption_service">5.14.5. Encryption service</h4>
<div class="paragraph">
<p>The EncryptionService is a service registered in the OSGi registry providing means to encrypt and check encrypted passwords.
This service acts as a factory for Encryption objects actually performing the encryption.</p>
@@ -19629,9 +19857,8 @@ This service acts as a factory for Encry
<div class="paragraph">
<p>This service is used in all Karaf login modules to support encrypted passwords.</p>
</div>
-<div class="paragraph">
-<p>===== Configuring properties</p>
-</div>
+<div class="sect4">
+<h5 id="_configuring_properties">Configuring properties</h5>
<div class="paragraph">
<p>Each login module supports the following additional set of properties:</p>
</div>
@@ -19697,16 +19924,16 @@ This service acts as a factory for Encry
</jaas:config></pre>
</div>
</div>
-<div class="paragraph">
-<p>===== Prefix and suffix</p>
</div>
+<div class="sect4">
+<h5 id="_prefix_and_suffix">Prefix and suffix</h5>
<div class="paragraph">
<p>The login modules have the ability to support both encrypted and plain passwords at the same time.
In some cases, some login modules may be able to encrypt the passwords on the fly and save them back in an encrypted form.</p>
</div>
-<div class="paragraph">
-<p>===== Jasypt</p>
</div>
+<div class="sect4">
+<h5 id="_jasypt">Jasypt</h5>
<div class="paragraph">
<p>Karaf default installation comes with a simple encryption service which usually fullfill simple needs. However, in some
cases, you may want to install the Jasypt (<a href="http://www.jasypt.org/" class="bare">http://www.jasypt.org/</a>) library which provides stronger encryption algorithms
@@ -19782,9 +20009,9 @@ and more control over them.</p>
</jaas:config></pre>
</div>
</div>
-<div class="paragraph">
-<p>===== Using encrypted property placeholders</p>
</div>
+<div class="sect4">
+<h5 id="_using_encrypted_property_placeholders">Using encrypted property placeholders</h5>
<div class="paragraph">
<p>When using blueprint framework for OSGi for configuring devices that requires passwords like JDBC datasources,
it is undesirable to use plain text passwords in configuration files. To avoid this problem it is good to store database
@@ -19856,9 +20083,10 @@ Jasypt documentation (<a href="http://ww
<pre>karaf@root()> feature:install jasypt-encryption</pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Role discovery policies</p>
</div>
+</div>
+<div class="sect3">
+<h4 id="_role_discovery_policies">5.14.6. Role discovery policies</h4>
<div class="paragraph">
<p>The JAAS specification does not provide means to distinguish between User and Role Principals without referring to the
specification classes. In order to provide means to the application developer to decouple the application from Karaf
@@ -19944,9 +20172,9 @@ for (Principal p : subject.getPrincipals
}</pre>
</div>
</div>
-<div class="paragraph">
-<p>==== Default role policies</p>
</div>
+<div class="sect3">
+<h4 id="_default_role_policies">5.14.7. Default role policies</h4>
<div class="paragraph">
<p>The previous section describes how to leverage role policies. However, Karaf provides a default role policy, based on the following class names:</p>
</div>
@@ -19977,16 +20205,14 @@ for (Principal p : subject.getPrincipals
}</pre>
</div>
</div>
-<div class="paragraph">
-<p>=== Troubleshooting, Debugging, Profiling, and Monitoring
-:imagesdir: ../images</p>
-</div>
-<div class="paragraph">
-<p>==== Troubleshooting</p>
</div>
-<div class="paragraph">
-<p>===== Logging</p>
</div>
+<div class="sect2">
+<h3 id="_troubleshooting_debugging_profiling_and_monitoring">5.15. Troubleshooting, Debugging, Profiling, and Monitoring</h3>
+<div class="sect3">
+<h4 id="_troubleshooting">5.15.1. Troubleshooting</h4>
+<div class="sect4">
+<h5 id="_logging">Logging</h5>
<div class="paragraph">
<p>Logging is easy to control through the console, with commands grouped under <em>log</em> shell. To learn about the available
logging commands type:</p>
@@ -20015,9 +20241,9 @@ karaf@root></pre>
</li>
</ol>
</div>
-<div class="paragraph">
-<p>===== Worst Case Scenario</p>
</div>
+<div class="sect4">
+<h5 id="_worst_case_scenario">Worst Case Scenario</h5>
<div class="paragraph">
<p>If you end up with 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 <code>data</code> directory just in the installation directory. This folder
@@ -20025,9 +20251,10 @@ contains transient data and will be recr
You may also want to remove the files in the <code>deploy</code> folder to avoid them being automatically installed when Karaf
is started the first time.</p>
</div>
-<div class="paragraph">
-<p>==== Debugging</p>
</div>
+</div>
+<div class="sect3">
+<h4 id="_debugging">5.15.2. Debugging</h4>
<div class="paragraph">
<p>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 using the <code>debug</code> parameter on the command line.</p>
@@ -20105,9 +20332,8 @@ how early in the startup they are.</p>
<pre>bin\karaf.bat debugs</pre>
</div>
</div>
-<div class="paragraph">
-<p>===== Debugging Environment Variables</p>
-</div>
+<div class="sect4">
+<h5 id="_debugging_environment_variables">Debugging Environment Variables</h5>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 33.3333%;">
@@ -20144,12 +20370,12 @@ how early in the startup they are.</p>
</tr>
</tbody>
</table>
-<div class="paragraph">
-<p>==== Profiling</p>
</div>
-<div class="paragraph">
-<p>===== jVisualVM</p>
</div>
+<div class="sect3">
+<h4 id="_profiling">5.15.3. Profiling</h4>
+<div class="sect4">
+<h5 id="_jvisualvm">jVisualVM</h5>
<div class="paragraph">
<p>You have to edit the <code>etc/config.properties</code> configuration file to add the jVisualVM package:</p>
</div>
@@ -20161,9 +20387,9 @@ how early in the startup they are.</p>
<div class="paragraph">
<p>Run Karaf from the console, and you should now be able to connect using jVisualVM.</p>
</div>
-<div class="paragraph">
-<p>===== YourKit</p>
</div>
+<div class="sect4">
+<h5 id="_yourkit">YourKit</h5>
<div class="paragraph">
<p>You need a few steps to be able to profile Karaf using YourKit.</p>
</div>
@@ -20194,9 +20420,10 @@ how early in the startup they are.</p>
<div class="paragraph">
<p>Run Karaf from the console, and you should now be able to connect using YourKit standalone or from your favorite IDE.</p>
</div>
-<div class="paragraph">
-<p>==== Monitoring</p>
</div>
+</div>
+<div class="sect3">
+<h4 id="_monitoring">5.15.4. Monitoring</h4>
<div class="paragraph">
<p>Karaf uses JMX for monitoring and management of all Karaf components.</p>
</div>
@@ -20276,144 +20503,144 @@ allowing you to create, rename, destroy,
<div class="paragraph">
<p><span class="image"><img src="src/main/asciidoc/images/jconsole_features.jpg" alt="jconsole features"></span></p>
</div>
-<div class="paragraph">
-<p>=== Configuration</p>
</div>
+</div>
+<div class="sect2">
+<h3 id="_configuration_9">5.16. Configuration</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-config-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-config-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>=== Deployer</p>
</div>
+<div class="sect2">
+<h3 id="_deployer_3">5.17. Deployer</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-deployer-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-deployer-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>=== Dump extender</p>
</div>
+<div class="sect2">
+<h3 id="_dump_extender">5.18. Dump extender</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-dump-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-dump-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>=== JDBC & JPA</p>
</div>
+<div class="sect2">
+<h3 id="_jdbc_jpa">5.19. JDBC & JPA</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-jdbc-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-jdbc-example/README.md</a></p>
</div>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-jpa-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-jpa-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>=== JMS</p>
</div>
+<div class="sect2">
+<h3 id="_jms_2">5.20. JMS</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-jms-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-jms-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>=== Custom log appender</p>
</div>
+<div class="sect2">
+<h3 id="_custom_log_appender">5.21. Custom log appender</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-log-appender-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-log-appender-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>=== Custom JMX MBean</p>
</div>
+<div class="sect2">
+<h3 id="_custom_jmx_mbean">5.22. Custom JMX MBean</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-mbean-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-mbean-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>=== Working with profiles</p>
</div>
+<div class="sect2">
+<h3 id="_working_with_profiles">5.23. Working with profiles</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-profile-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-profile-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>=== Security & JAAS</p>
</div>
+<div class="sect2">
+<h3 id="_security_jaas">5.24. Security & JAAS</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-jaas-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-jaas-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>=== Servlet</p>
</div>
+<div class="sect2">
+<h3 id="_servlet">5.25. Servlet</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-servlet-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-servlet-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>=== WAR</p>
</div>
+<div class="sect2">
+<h3 id="_war">5.26. WAR</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-war-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-war-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>=== HTTP Resources</p>
</div>
+<div class="sect2">
+<h3 id="_http_resources">5.27. HTTP Resources</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-http-resource-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-http-resource-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>=== REST service</p>
</div>
+<div class="sect2">
+<h3 id="_rest_service">5.28. REST service</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-rest-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-rest-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>=== SOAP service</p>
</div>
+<div class="sect2">
+<h3 id="_soap_service">5.29. SOAP service</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-soap-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-soap-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>=== Websocket</p>
</div>
+<div class="sect2">
+<h3 id="_websocket">5.30. Websocket</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-websocket-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-websocket-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>=== Scheduler</p>
</div>
+<div class="sect2">
+<h3 id="_scheduler_2">5.31. Scheduler</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-scheduler-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-scheduler-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>=== Quick example with Apache Camel</p>
</div>
+<div class="sect2">
+<h3 id="_quick_example_with_apache_camel">5.32. Quick example with Apache Camel</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-camel-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-camel-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>=== Custom URL handler</p>
</div>
+<div class="sect2">
+<h3 id="_custom_url_handler">5.33. Custom URL handler</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-url-namespace-handler-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-url-namespace-handler-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>=== Integration Tests</p>
</div>
+<div class="sect2">
+<h3 id="_integration_tests">5.34. Integration Tests</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-itest-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-itest-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>=== Distributions & Docker</p>
</div>
+<div class="sect2">
+<h3 id="_distributions_docker">5.35. Distributions & Docker</h3>
<div class="paragraph">
<p>See <a href="https://github.com/apache/karaf/blob/master/examples/karaf-docker-example/README.md" class="bare">https://github.com/apache/karaf/blob/master/examples/karaf-docker-example/README.md</a></p>
</div>
-<div class="paragraph">
-<p>=== Github Contributions</p>
</div>
+<div class="sect2">
+<h3 id="_github_contributions">5.36. Github Contributions</h3>
<div class="paragraph">
<p>Some people prefer to make contributions to karaf source via github. If you are one of them, this is for you!</p>
</div>
-<div class="paragraph">
-<p>==== Introduction</p>
-</div>
+<div class="sect3">
+<h4 id="_introduction">5.36.1. Introduction</h4>
<div class="paragraph">
<p>Apache Karaf is available as a periodically replicated mirror on: <a href="https://github.com/apache/karaf" class="bare">https://github.com/apache/karaf</a></p>
</div>
-<div class="paragraph">
-<p>==== Suggested Workflow</p>
</div>
+<div class="sect3">
+<h4 id="_suggested_workflow">5.36.2. Suggested Workflow</h4>
<div class="olist arabic">
<ol class="arabic">
<li>
@@ -20439,9 +20666,9 @@ allowing you to create, rename, destroy,
</li>
</ol>
</div>
-<div class="paragraph">
-<p>==== License Reminder</p>
</div>
+<div class="sect3">
+<h4 id="_license_reminder">5.36.3. License Reminder</h4>
<div class="paragraph">
<p>In order for your contributions to be accepted:</p>
</div>
@@ -20455,9 +20682,9 @@ allowing you to create, rename, destroy,
</li>
</ul>
</div>
-<div class="paragraph">
-<p>==== How to Generate a One-File-Patch Via Throw-Away Branch</p>
</div>
+<div class="sect3">
+<h4 id="_how_to_generate_a_one_file_patch_via_throw_away_branch">5.36.4. How to Generate a One-File-Patch Via Throw-Away Branch</h4>
<div class="paragraph">
<p>Here is one way to generate squash of your commits:</p>
</div>
@@ -20504,8 +20731,6 @@ git format-patch archon/trunk</pre>
</div>
</div>
</div>
-</div>
-</div>
</div>
</div>
</div>
Modified: release/karaf/documentation/4_x.pdf
==============================================================================
Binary files release/karaf/documentation/4_x.pdf (original) and release/karaf/documentation/4_x.pdf Wed Jun 2 10:00:46 2021 differ