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 2013/03/22 23:07:47 UTC
svn commit: r1460030 [19/23] - in /karaf/site/production/manual/latest: ./
commands/ css/ css/scalate/ developers-guide/ images/ users-guide/
Added: karaf/site/production/manual/latest/manual.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/manual.html?rev=1460030&view=auto
==============================================================================
--- karaf/site/production/manual/latest/manual.html (added)
+++ karaf/site/production/manual/latest/manual.html Fri Mar 22 22:07:43 2013
@@ -0,0 +1,3742 @@
+
+<!DOCTYPE html>
+<html>
+<head>
+ <style type="text/css">
+/*
+
+Copyright (c) 2005 Hakon Wium Lie and Bert Bos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+*/
+html {
+ margin: 0; padding: 0;
+ font: 10pt/1.26 "Gill Sans", sans-serif;
+}
+
+h1, h2, h3, h4, h5, h6 {
+ font-family: "Gill Sans", sans-serif;
+ margin: 2em 0 0.5em 0;
+ page-break-after: avoid;
+}
+
+h1 {
+ font-size: 2.0em;
+ font-weight: 900;
+
+ margin: 0;
+ margin-left:-2cm;
+ margin-top:-1cm;
+ margin-bottom:1.5cm;
+ top: 0cm;
+ left: 0cm;
+ padding: 2cm;
+ padding-top: 0cm;
+ padding-bottom: 1cm;
+ background: #888;
+ border-bottom-right-radius: 2cm;
+ page-break-before: always;
+ page-break-inside: avoid;
+}
+
+@media screen, handheld {
+h1 {
+ margin-top:1cm;
+ background-image: url("chapter-rounded-bottom.png");
+ background-repeat: no-repeat;
+ background-position: bottom right;
+}
+div.page-reset > h1 {
+ margin-top:0cm;
+}
+}
+
+
+h2 {
+ font-size: 1.2em;
+ text-transform: uppercase;
+ font-weight: bold;
+}
+
+h3 {
+ font-size: 1em;
+ font-weight: bold;
+}
+
+q::before {
+ content: "\201C";
+}
+
+q::after {
+ content: "\201D";
+}
+
+p { margin: 0 }
+p + p { text-indent: 1.3em ; margin-top: 0.2em; }
+p.sidenote + p, p.caption, p.art { text-indent: 0 }
+
+p.author {
+ margin-top: 2em;
+ text-indent: 0;
+ text-align: right;
+}
+
+a { text-decoration: none; color: black }
+
+/* cross-references */
+
+a.pageref::after { content: " on page " target-counter(attr(href), page); }
+a.chapref::before { content: " Chapter " target-counter(attr(href), chapter) ", "; }
+a.figref { content: " Figure " target-counter(attr(href), figure); }
+a.tableref { content: " Table " target-counter(attr(href), figure); }
+a.listingref { content: " Listing " target-counter(attr(href), listing); }
+
+/* sidenotes */
+
+.sidenote {
+ float: left;
+ clear: left;
+ margin: 0 0 1em -41%;
+ width: 37%;
+ font-size: 0.9em;
+ font-style: normal;
+ text-indent: 0;
+ text-align: right;
+ page-break-inside: avoid;
+}
+
+/* sidebars */
+
+div.sidebar {
+ float: top-next;
+ margin: 1.2em 0 1.2em 0;
+ border: thin solid;
+ background: #CCC;
+ padding: 0.5em 1em;
+ page-break-inside: avoid;
+ column-count: 2;
+ column-gap: 1.5em;
+}
+
+div.sidebar h2 {
+ margin-top: 0;
+}
+
+/* frontpage */
+
+.title p{
+ font-size:22pt;
+ font-family: "Gill Sans", sans-serif;
+ text-align: center;
+}
+
+.copyright-section {
+ text-align: center;
+ font-size: 9pt;
+ page-break-after: always;
+ margin-top: 50pt;
+ margin-bottom: 20pt;
+}
+
+.toc-title {
+ font-size:18pt;
+ font-family: "Gill Sans", sans-serif;
+ text-align: left;
+ margin-left:20pt;
+ margin-bottom: 40pt;
+
+}
+
+/* figures, tables, and listings */
+
+div.confluenceTableSmall th.confluenceTh {
+ font-size: 11px;
+}
+
+div.confluenceTableSmall td.confluenceTd {
+ font-size: 7px;
+}
+
+div.figure {
+ margin: 1em 0;
+ counter-increment: figure;
+}
+
+div.figure .caption, div.table .caption {
+ font-size: 0.9em;
+ font-style: italic;
+}
+
+div.figure .caption::before {
+ content: "Figure " counter(figure) ". ";
+ font-weight: bold;
+ font-style: normal;
+}
+
+div.table .caption::before {
+ content: "Table " counter(table) ". ";
+ font-weight: bold;
+ font-style: normal;
+}
+
+div.table {
+ margin: 1em 0;
+ counter-increment: table;
+}
+
+div.table th {
+ text-align: left;
+}
+
+table th, table td {
+ text-align: left;
+ padding-right: 1em;
+ page-break-inside: avoid;
+}
+
+table th {
+ border-top: thin solid;
+ border-bottom: thin solid;
+ padding-top: 0.2em;
+ padding-bottom: 0.2em;
+}
+table td {
+ border-top: none;
+ border-bottom: thin dotted;
+ padding-top: 0.2em;
+ padding-bottom: 0.2em;
+}
+
+div.Scrollbar {
+ display: none;
+}
+
+
+/* Weird div.codeHeader a b::before would be a better selection
+ but prince does not properly match it.. Firefox does. */
+div.codeHeader::before {
+ content: "Listing " counter(listing) ". ";
+ font-weight: bold;
+ font-style: normal;
+}
+div.codeHeader a b {
+ font-style: italic;
+ font-weight: normal;
+}
+div.codeHeader {
+ font-size: 0.9em;
+ counter-increment: listing;
+}
+div.code {
+ border: 1px dashed #c0c0c0;
+ font-size: 12px;
+ font-family: Courier;
+ margin: 5px;
+ line-height: 13px;
+ padding: 3px;
+ background-color: #f8f8f8;
+
+}
+
+
+@page {
+ margin: 2cm;
+ size: 7in 9.25in;
+
+ @footnotes {
+ border-top: thin solid black;
+ padding-top: 0.3em;
+ margin-top: 0.6em;
+ }
+}
+
+
+/* define default page and names pages: cover, blank, frontmatter */
+div.page-reset {
+ counter-reset: page 1;
+}
+
+@page :left {
+ @top-left-corner {
+ font-weight: 900; font: 9pt "Gill Sans", serif;
+ content: counter(page);
+ text-align: left;
+ margin-left: 1cm;
+ visibility: hidden;
+ }
+ @top-left {
+ font-weight: 900;
+ font: 9pt "Gill Sans", serif; white-space: pre; text-transform: uppercase; letter-spacing: 0.1em;
+ content: string(header, first);
+ visibility: hidden;
+ }
+ @bottom-left-corner {
+ font-weight: 900; font: 9pt "Gill Sans", serif;
+ content: counter(page);
+ text-align: left;
+ margin-left: 1cm;
+ }
+ @bottom-left {
+ font-weight: 900;
+ font: 9pt "Gill Sans", serif; white-space: pre; text-transform: uppercase; letter-spacing: 0.1em;
+ content: string(header, first);
+ }
+}
+
+@page :right {
+ @top-right-corner {
+ font-weight: 900; font: 9pt "Gill Sans", serif;
+ content: counter(page);
+ text-align: left;
+ margin-left: 1cm;
+ visibility: hidden;
+ }
+ @top-right {
+ font-weight: 900;
+ font: 9pt "Gill Sans", serif; white-space: pre; text-transform: uppercase; letter-spacing: 0.1em;
+ content: string(header, first)
+ visibility: hidden;
+ }
+ @bottom-right-corner {
+ font-weight: 900; font: 9pt "Gill Sans", serif;
+ content: counter(page);
+ text-align: right;
+ margin-right: 1cm;
+ }
+ @bottom-right {
+ font-weight: 900; font: 9pt "Gill Sans", serif;
+ white-space: pre; text-transform: uppercase; letter-spacing: 0.1em;
+ content: string(header, first)
+ }
+}
+
+/*
+ In theory we should be able to use the :first selector so taht
+ we can put the page numbering on the bottom of the first page of the chapter
+ but have the rest of the pages number at the top. But this does not seem
+ to work. See http://www.princexml.com/doc/6.0/page-selectors/
+
+ So for now just always number at the bottom :(
+*/
+/*
+div.chapter { page: bottom-number; }
+@page bottom-number :first {
+ @top-left {
+ visibility: hidden;
+ }
+ @bottom-left {
+ visibility: visible;
+ }
+ @top-right {
+ visibility: hidden;
+ }
+ @bottom-right {
+ visibility: visible;
+ }
+}
+*/
+
+@page cover { margin: 0; }
+
+@page frontmatter :left {
+ @bottom-left-corner {
+ content: counter(page, lower-roman);
+ }
+ @bottom-left-corner {
+ content: counter(page, lower-roman);
+ }
+}
+
+@page frontmatter :right {
+ @bottom-right-corner {
+ content: counter(page, lower-roman);
+ }
+ @bottom-right-corner {
+ content: counter(page, lower-roman);
+ }
+}
+
+@page blank :left {
+ @top-left { visibility: hidden; }
+ @bottom-left { visibility: hidden; }
+ @top-left-corner { visibility: hidden; }
+ @bottom-left-corner { visibility: hidden; }
+}
+
+@page blank :right {
+ @top-right { visibility: hidden; }
+ @bottom-right { visibility: hidden; }
+ @top-right-corner { visibility: hidden; }
+ @bottom-right-corner { visibility: hidden; }
+}
+
+/* footnotes */
+.footnote {
+ display: none; /* default rule */
+
+ display: prince-footnote; /* prince-specific rules */
+ position: footnote;
+ footnote-style-position: inside;
+
+ counter-increment: footnote;
+ margin-left: 1.4em;
+ font-size: 90%;
+ line-height: 1.4;
+}
+
+.footnote::footnote-call {
+ vertical-align: super;
+ font-size: 80%;
+}
+
+.footnote::footnote-marker {
+ vertical-align: super;
+ color: green;
+ padding-right: 0.4em;
+}
+
+/* Confluence contents to hide */
+#labels-section {
+ display: none;
+}
+#comments-section {
+ display: none;
+}
+#footer {
+ display: none;
+}
+.hidden {
+ display: none;
+}
+
+/*
+ A book consists of different types of sections. We propose to use
+ DIV elements with these class names:
+
+ frontcover
+ halftitlepage: contains the title of the book
+ titlepage: contains the title of the book, name of author(s) and publisher
+ imprint: left page with copyright, publisher, library printing information
+ dedication: right page with short dedication
+ foreword: written by someone other than the author(s)
+ toc: table of contents
+ preface: preface, including acknowledgements
+ chapter: each chapter is given its own DIV element
+ references: contains list of references
+ appendix: each appendix is given its own
+ bibliography
+ glossary
+ index
+ colophon: describes how the book was produced
+ backcover
+
+ A book will use several of the types listed above, but few books
+ will use all of them.
+*/
+
+/* which section uses which named page */
+
+div.halftitlepage, div.titlepage, div.imprint, div.dedication { page: blank }
+div.foreword, div.toc, div.preface { page: frontmatter }
+
+
+/* page breaks */
+div.frontcover, div.halftitlepage, div.titlepage { page-break-before: right }
+div.imprint { page-break-before: always; }
+div.chapter { page-break-before: always; }
+div.dedication, div.foreword, div.toc, div.preface, div.reference,
+div.appendix, div.bibliography, div.glossary, div.index, div.colophon {
+ page-break-before: always
+}
+div.backcover { page-break-before: left }
+
+/* titlepage, halftitlepage */
+
+div.titlepage h1, div.halftitlepage h1 { margin-bottom: 2em; }
+div.titlepage h2, div.halftitlepage h2 { font-size: 1.2em; margin-bottom: 3em; }
+div.titlepage h3, div.halftitlepage h3 { font-size: 1em; margin-bottom: 3em; }
+div.titlepage p, div.halftitlepage p {
+ font-size: 1.4em;
+ font-weight: bold;
+ margin: 0; padding: 0;
+}
+
+
+/* TOC */
+
+ul.toc, ul.toc ul {
+ list-style-type: none;
+ margin: 0; padding: 0;
+ margin-left: 3cm;
+}
+ul.toc ul {
+ margin-left: 1em;
+ font-weight: normal;
+}
+ul.toc > li {
+ font-weight: bold;
+ margin-bottom: 0.5em;
+}
+ul.toc a::after {
+ content: leader('.') target-counter(attr(href), page);
+ font-style: normal;
+}
+ul.toc > li.frontmatter a::after {
+ content: leader('.') target-counter(attr(href), page, lower-roman);
+ font-style: normal;
+}
+ul.toc > li.endmatter a::after {
+ content: leader('.') target-counter(attr(href), page);
+ font-style: normal;
+}
+ul.toc > li.chapter::before {
+ content: "Chapter " counter(toc-chapter, decimal);
+ display: block;
+ margin: 1em 0 0.1em -2.5cm;
+ font-weight: normal;
+ counter-increment: toc-chapter;
+ page-break-after: avoid;
+}
+
+/* chapter numbers */
+
+div.chapter { counter-increment: chapter; }
+div.chapter h1::before {
+ text-transform: uppercase;
+ letter-spacing: 0.15em;
+ content: "Chapter " counter(chapter) " \A\B0 \B0 \B0 \B0\A";
+ white-space: pre;
+ font-size: 50%;
+}
+
+div.frontcover h1::before, div.titlepage h1::before, div.halftitlepage h1::before {
+ content: normal; /* that is, none */
+}
+
+h1 { string-set: header content();}
+div.chapter h1 { string-set: header "Chapter " counter(chapter) " - " content(); }
+
+/* index */
+
+ul.index {
+ list-style-type: none;
+ margin: 0; padding: 0;
+ column-count: 2;
+ column-gap: 1em;
+}
+
+ul.index a::after { content: ", " target-counter(attr(href), page); }
+
+
+span.element, span.attribute {
+ text-transform: uppercase;
+ font-weight: bold;
+ font-size: 80%;
+}
+span.property { font-weight: bold }
+code, span.css, span.value, span.declaration {
+ font: 90% "Lucida Console", "Lucida Sans Typewriter", monospace;
+}
+
+
+@media screen, handheld {
+ html {font: 14px "Gill Sans", sans-serif; }
+ h1 { margin-bottom: 0.5em }
+ div.frontcover, div.halftitlepage, div.titlepage, div.imprint,
+ div.dedication, div.foreword, div.toc, div.index { display: none }
+ body {
+ margin: 0cm;
+ margin-left: 2cm;
+ margin-right: 2cm;
+ }
+}
+
+/*
+ * Enhancements to the take advantage of some of the style markup that
+ * Confluence generates
+ */
+a sup img { visibility: hidden; position: absolute;}
+
+img {
+ prince-image-resolution:150dpi;
+}
+
+table {
+ font: "Lucida Console", "Lucida Sans Typewriter", monospace;
+}
+
+table td {
+ font-size: 10pt;
+}
+
+pre {
+ white-space: pre-wrap;
+}
+
+.codeContent {
+ font-size: 80%;
+}
+.code {
+}
+.code-keyword {
+ color: #000091;
+ background-color: inherit;
+}
+
+.code-object {
+ color: #910091;
+ background-color: inherit;
+}
+
+.code-quote {
+ color: #009100;
+ background-color: inherit;
+}
+
+.code-comment {
+ color: #808080;
+ background-color: inherit;
+}
+
+
+.code-xml .code-keyword {
+ color: inherit;
+ font-weight: bold;
+}
+
+.code-tag {
+ color: #000091;
+ background-color: inherit;
+}
+
+.noteMacro { border-color: #F0C000; background-color: #FFFFCE;}
+.warningMacro { border-color: #CC0000; background-color: #FFCCCC }
+.infoMacro { border-color: #3c78b5; background-color: #D8E4F1; }
+.tipMacro { border-color: #090; background-color: #dfd;}
+.noteMacro, .warningMacro, .infoMacro, .tipMacro, .informationMacroPadding {
+ border: thin solid;
+ float: top-next;
+ margin: 1em 0 1.2em 0;
+ padding: 0.5em;
+ column-count: 2;
+ column-gap: 1.5em;
+ width: 100%;
+}
+table.infoMacro td, table.warningMacro td, table.tipMacro td, table.noteMacro td, table.sectionMacro td {
+ border: none;
+}
+table.infoMacro p, table.warningMacro p, table.tipMacro p, table.noteMacro p, table.sectionMacro p {
+ font-size:x-small;
+ margin-top: 1em;
+}
+ </style>
+ <style type="text/css">
+.syntax .hll { background-color: #ffffcc }
+.syntax { background: #f0f0f0; }
+.syntax .c { color: #60a0b0; font-style: italic } /* Comment */
+.syntax .err { border: 1px solid #FF0000 } /* Error */
+.syntax .k { color: #007020; font-weight: bold } /* Keyword */
+.syntax .o { color: #666666 } /* Operator */
+.syntax .cm { color: #60a0b0; font-style: italic } /* Comment.Multiline */
+.syntax .cp { color: #007020 } /* Comment.Preproc */
+.syntax .c1 { color: #60a0b0; font-style: italic } /* Comment.Single */
+.syntax .cs { color: #60a0b0; background-color: #fff0f0 } /* Comment.Special */
+.syntax .gd { color: #A00000 } /* Generic.Deleted */
+.syntax .ge { font-style: italic } /* Generic.Emph */
+.syntax .gr { color: #FF0000 } /* Generic.Error */
+.syntax .gh { color: #000080; font-weight: bold } /* Generic.Heading */
+.syntax .gi { color: #00A000 } /* Generic.Inserted */
+.syntax .go { color: #808080 } /* Generic.Output */
+.syntax .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */
+.syntax .gs { font-weight: bold } /* Generic.Strong */
+.syntax .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
+.syntax .gt { color: #0040D0 } /* Generic.Traceback */
+.syntax .kc { color: #007020; font-weight: bold } /* Keyword.Constant */
+.syntax .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */
+.syntax .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */
+.syntax .kp { color: #007020 } /* Keyword.Pseudo */
+.syntax .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */
+.syntax .kt { color: #902000 } /* Keyword.Type */
+.syntax .m { color: #40a070 } /* Literal.Number */
+.syntax .s { color: #4070a0 } /* Literal.String */
+.syntax .na { color: #4070a0 } /* Name.Attribute */
+.syntax .nb { color: #007020 } /* Name.Builtin */
+.syntax .nc { color: #0e84b5; font-weight: bold } /* Name.Class */
+.syntax .no { color: #60add5 } /* Name.Constant */
+.syntax .nd { color: #555555; font-weight: bold } /* Name.Decorator */
+.syntax .ni { color: #d55537; font-weight: bold } /* Name.Entity */
+.syntax .ne { color: #007020 } /* Name.Exception */
+.syntax .nf { color: #06287e } /* Name.Function */
+.syntax .nl { color: #002070; font-weight: bold } /* Name.Label */
+.syntax .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */
+.syntax .nt { color: #062873; font-weight: bold } /* Name.Tag */
+.syntax .nv { color: #bb60d5 } /* Name.Variable */
+.syntax .ow { color: #007020; font-weight: bold } /* Operator.Word */
+.syntax .w { color: #bbbbbb } /* Text.Whitespace */
+.syntax .mf { color: #40a070 } /* Literal.Number.Float */
+.syntax .mh { color: #40a070 } /* Literal.Number.Hex */
+.syntax .mi { color: #40a070 } /* Literal.Number.Integer */
+.syntax .mo { color: #40a070 } /* Literal.Number.Oct */
+.syntax .sb { color: #4070a0 } /* Literal.String.Backtick */
+.syntax .sc { color: #4070a0 } /* Literal.String.Char */
+.syntax .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */
+.syntax .s2 { color: #4070a0 } /* Literal.String.Double */
+.syntax .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */
+.syntax .sh { color: #4070a0 } /* Literal.String.Heredoc */
+.syntax .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */
+.syntax .sx { color: #c65d09 } /* Literal.String.Other */
+.syntax .sr { color: #235388 } /* Literal.String.Regex */
+.syntax .s1 { color: #4070a0 } /* Literal.String.Single */
+.syntax .ss { color: #517918 } /* Literal.String.Symbol */
+.syntax .bp { color: #007020 } /* Name.Builtin.Pseudo */
+.syntax .vc { color: #bb60d5 } /* Name.Variable.Class */
+.syntax .vg { color: #bb60d5 } /* Name.Variable.Global */
+.syntax .vi { color: #bb60d5 } /* Name.Variable.Instance */
+.syntax .il { color: #40a070 } /* Literal.Number.Integer.Long */
+
+
+/* don't highlight errors */
+.syntax .err {
+ border: none;
+}
+
+.syntax {
+ font-size: .9em;
+ font-family:Monaco,"Courier New","DejaVu Sans Mono","Bitstream Vera Sans Mono",monospace;
+ background-color: #F8F8FF;
+
+ overflow:auto;
+ -moz-background-clip:border;
+ -moz-background-inline-policy:continuous;
+ -moz-background-origin:padding;
+ margin: 1em 0 1em 0;
+ border:1px solid #DDDDDD;
+
+ border-top-left-radius: 8px; -webkit-border-top-left-radius: 8px; -moz-border-radius-topleft: 8px;
+ border-top-right-radius: 8px; -webkit-border-top-right-radius: 8px; -moz-border-radius-topright: 8px;
+ border-style: solid; border-width: 1px; border-color: #dedede !important;
+ padding: 1em;
+}
+.syntax .linenodiv {
+ background-color:#ECECEC;
+ border-right:1px solid #DDDDDD;
+ color:#AAAAAA;
+ padding: .5em;
+ text-align:right;
+}
+.syntax .highlight {
+}
+.syntax pre {
+ margin:0;
+}
+
+pre.syntax {
+ padding: .5em;
+ background-color: #F8F8FF; overflow:auto;
+}
+
+.syntax code {
+ font-family:Monaco,"Courier New","DejaVu Sans Mono","Bitstream Vera Sans Mono",monospace;
+ font-size: 10pt;
+}
+
+div.compare { width: 700px; }
+div.compare div.compare-left { float:left; width:340px; padding:5px; margin-top: 15px; }
+div.compare div.compare-right { float:right; width:340px; padding:5px; margin-top: 15px; }
+div.compare div h3 {
+ margin-left: 15px;
+ padding: 5px 15px;
+ display: inline;
+ font-size: .8em;
+ color: #666;
+
+ border-top: 1px solid #ccc; -moz-border-top-colors: #ccc white white #e5e5e5;
+ border-left: 1px solid #ccc; -moz-border-left-colors: #ccc white white #e5e5e5;
+ border-right: 1px solid #ccc;-moz-border-right-colors: #ccc white white #e5e5e5;
+ border-top-left-radius: 8px; -webkit-border-top-left-radius: 8px; -moz-border-radius-topleft: 8px;
+ border-top-right-radius: 8px; -webkit-border-top-right-radius: 8px; -moz-border-radius-topright: 8px;
+}
+div.compare div div {
+ margin: 5px 0px 0px 0px;
+}
+.clear {
+ clear:both;
+}
+.wide div.compare div.compare-left { float:none; width:700px; }
+.wide div.compare div.compare-right { float:none; width:700px; }
+
+ </style>
+
+ <title>Apache Karaf 3.0.0-SNAPSHOT Guides</title>
+</head>
+<body>
+ <div id="titlepage">
+ <div id="title">Apache Karaf</div>
+ <div id="subtitle">Version 3.0.0-SNAPSHOT</div>
+ </div>
+ <div id="main">
+ <div class="title"><p><img border="0" src="images/karaf-logos.png"/><br/><br/><br/><br/><br/><br/><br/><br/><br/>Apache Karaf<br/>Users' Guide<br/><br/><br/><br/><br/><br/><br/><br/></p></div><div class="copyright-section"><p>Copyright 2011 The Apache Software Foundation</p><p>The PDF format of the Karaf Manual has been generated by Prince XML (http://www.princexml.com).</p></div><div class="toc-title"><p>Table of contents</p></div><ol style="list-style: none;"><li><a href="#Overview.html">Overview</a></li><li><a href="#QuickStart.html">Quick Start</a></li><li><a href="#UsersGuide.html">Users Guide</a></li><li><a href="#DevelopersGuide.html">Developers Guide</a></li></ol><h1 id="Overview">Overview</h1><h1 id="KarafOverview">Karaf Overview</h1><p>Apache Karaf is a small OSGi based runtime which provides a lightweight container onto which various components and applications can be deployed.</p><ul><li>Uses either Apache Felix or Eclipse Equinox as OSGi framework and extend
s these with many features that make it a fully featured server</li><li>Can be scaled from a very lightweight small container to a fully featured enterprise Server</li></ul><p><a href="users-guide/features.html">See all Karaf features in detail</a></p><p>Here is a short list of features supported by the Karaf:</p><ul><li><strong>Hot deployment</strong>: Karaf supports hot deployment of OSGi bundles by monitoring jar files inside the <tt>deploy</tt> directory. Each time a jar is copied in this folder, it will be installed inside the runtime. You can then update or delete it and changes will be handled automatically. In addition, Karaf also supports exploded bundles and custom deployers (Blueprint and Spring ones are included by default).</li><li><strong>Dynamic configuration</strong>: Services are usually configured through the ConfigurationAdmin OSGi service. Such configuration can be defined in Karaf using property files inside the <tt>etc</tt> directory. These configu
rations are monitored and changes on the properties files will be propagated to the services.</li><li><strong>Logging System</strong>: using a centralized logging back end supported by Log4J, Karaf supports a number of different APIs (JDK 1.4, JCL, SLF4J, Avalon, Tomcat, OSGi)</li><li><strong>Provisioning</strong>: Provisioning of libraries or applications can be done through a number of different ways, by which they will be downloaded locally, installed and started.</li><li><strong>Native OS integration</strong>: Karaf can be integrated into your own Operating System as a service so that the lifecycle will be bound to your Operating System.</li><li><strong>Extensible Shell console</strong>: Karaf features a nice text console where you can manage the services, install new applications or libraries and manage their state. This shell is easily extensible by deploying new commands dynamically along with new features or applications.</li><li><strong>Remote access</strong>: use
any SSH client to connect to Karaf and issue commands in the console</li><li><strong>Security framework</strong> based on JAAS</li><li><strong>Managing instances</strong>: Karaf provides simple commands for managing multiple instances. You can easily create, delete, start and stop instances of Karaf through the console.</li><li>Supports the latest OSGi 4.3 containers: Apache Felix Framework 4.0 and Eclipse Equinox 3.8</li></ul><p><img border="0" src="images/karaf.png"/></p><h1 id="QuickStart">Quick Start</h1><h1 id="QuickStart">Quick Start</h1><p>This instructions should help you get Apache Karaf up and running in 5 to 15 minutes.</p><h2 id="Prerequisites">Prerequisites</h2><p>Karaf requires a Java SE 6 environment to run. Refer to <a href="http://www.oracle.com/technetwork/java/javase/">http://www.oracle.com/technetwork/java/javase/</a> for details on how to download and install Java SE 1.6 or greater.</p><ul><li>Open a Web browser and access the following URL: <a href="htt
p://karaf.apache.org/index/community/download.html">http://karaf.apache.org/index/community/download.html</a></li><li>Download the binary distribution that matches your system (zip for windows, tar.gz for unixes) </li><li>Extract the archive a new folder on your hard drive; for example in c:\karaf - from now on this directory will be referenced as <KARAF_HOME>.</li></ul><h2 id="Starttheserver">Start the server</h2><p>Open a command line console and change the directory to <KARAF_HOME>. </p><p>To start the server, run the following command in Windows:</p><pre>
+bin\karaf.bat
+</pre><p>respectively on Unix:</p><pre>
+bin/karaf
+</pre><p>You should see the following information on the command line console:</p><pre>
+ __ __ ____
+ / //_/____ __________ _/ __/
+ / ,< / __ `/ ___/ __ `/ /_
+ / /| |/ /_/ / / / /_/ / __/
+ /_/ |_|\__,_/_/ \__,_/_/
+
+ Apache Karaf (3.0.0-SNAPSHOT)
+
+Hit '<tab>' for a list of available commands
+and '[cmd] --help' for help on a specific command.
+Hit '<ctrl-d>' or 'system:shutdown' to shutdown Karaf.
+
+karaf@root()>
+</pre><h2 id="SomeshellBasics">Some shell Basics</h2><p>You can now run your first command. Simply type the <tt><tab></tt> key in the console.</p><pre>
+karaf@root>
+
+instance:change-port instance:connect instance:create instance:destroy
+instance:list instance:start instance:stop config:cancel
+...
+</pre><p>You can then grab more specific help for a given command using the <tt>--help</tt> option for this command:</p><pre>
+karaf@root()> bundle:list --help
+DESCRIPTION
+ bundle:list
+
+ Lists all installed bundles.
+...
+</pre><p>Note that the console supports tab completion so if your start typing a command it will show possible completions and also auto complete if there is only one completion.</p><h2 id="Deployasampleapplication">Deploy a sample application</h2><p>While you will learn in the Karaf user's guide how to fully use and leverage Apache Karaf, let's install a sample <a href="http://camel.apache.org">Apache Camel</a> application for now:</p><p>In the console, run the following commands:</p><pre>
+feature:repo-add camel 2.10.0
+feature:install camel-spring
+install -s mvn:org.apache.camel/camel-example-osgi/2.10.1
+</pre><p>The example installed is using Camel to start a timer every 2 seconds and output a message on the console.<br/>The previous commands download the Camel features descriptor and install the example feature.</p><pre>
+>>>> SpringDSL set body: Fri Jan 07 11:59:51 CET 2011
+>>>> SpringDSL set body: Fri Jan 07 11:59:53 CET 2011
+>>>> SpringDSL set body: Fri Jan 07 11:59:55 CET 2011
+
+</pre><h3 id="Stoppinganduninstallingthesampleapplication">Stopping and uninstalling the sample application</h3><p>To stop this demo, run the following command:</p><pre>
+bundle:stop org.apache.camel.camel-example-osgi
+</pre><h2 id="StoppingKaraf">Stopping Karaf</h2><p>To stop Karaf from the console, enter <tt>^D</tt> in the console:</p><pre>
+^D
+</pre><p>Alternatively, you can also run the following command:</p><pre>
+system:shutdown
+</pre><h3 id="CleaningtheKarafstate">Cleaning the Karaf state</h3><p>Normally Karaf remembers the features and bundles you installed and started. The reset Karaf into a clean state just delete the data directory when karaf is not running.</p><h2 id="Summary">Summary</h2><p>This document showed how simple it is to have Apache Karaf up and running and install a simple Apache Camel application.</p><h1 id="UsersGuide">Users Guide</h1><h1 id="Installation">Installation</h1><p>This chapter describes how to install Apache Karaf for both Unix and Windows platforms, including<br/>prerequisite software and necessary download links.</p><h2 id="PreInstallationRequirements">Pre-Installation Requirements</h2><p><strong>Hardware:</strong></p><ul><li>20 MB of free disk space for the Apache Karaf binary distribution.</li></ul><p><strong>Operating Systems:</strong></p><ul><li>Windows: Windows Vista, Windows XP SP2, Windows 2000.</li><li>Unix: Ubuntu Linux, Powerdog Linux, MacOS, AIX, HP-UX, S
olaris, any Unix platform that supports Java.</li></ul><p><strong>Environment:</strong></p><ul><li>Java SE 1.6.x or greater (<a href="http://www.oracle.com/technetwork/java/javase/">http://www.oracle.com/technetwork/java/javase/</a>).</li><li>The JAVA_HOME environment variable must be set to the directory where the Java runtime is installed, e.g., <tt>c:\Program Files\jdk.1.6.0_24</tt>. To accomplish that, press Windows key and Break key together, switch to "Advanced" tab and click on "Environment Variables". Here, check for the variable and, if necessary, add it.</li></ul><h2 id="InstallationProcedureforWindows">Installation Procedure for Windows</h2><p>This procedure explains how to download and install the binary distribution on a Windows system.</p><ol><li>From a browser, navigate to <a href="http://karaf.apache.org/index/community/download.html">http://karaf.apache.org/index/community/download.html</a>.</li><li>Scroll down to the "Apache Karaf" section and select the de
sired distribution.<p>For a binary distribution, the filename will be similar to: <tt>apache-karaf-x.y.zip</tt>.</p></li><li>Extract the files from the ZIP file into a directory of your choice. Please remember the restrictions concerning illegal characters in Java paths, e.g. !, % etc.</li><li>Proceed to the <a href="start-stop#Starting Karaf.html">Starting Karaf</a> chapter.</li></ol><div class="tip" style="border: 1px solid #090;background-color: #dfd;margin: 20px;padding: 0px 6px 0px 6px;"><p><b>Handy Hint</b></p><p>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 <em>start \-> startup</em> that executes</p><pre>subst S: "C:\your very % problematic path!\KARAF"
+</pre><p>so your Karaf root directory is S: <del>-</del> which works for sure and is short to type.</p></div><h2 id="InstallationProcedureForUnix">Installation Procedure For Unix</h2><p>This procedure explains how to download and install the binary distribution on a Unix system.</p><ol><li>From a browser, navigate to <a href="http://karaf.apache.org/download.html">http://karaf.apache.org/download.html</a>.</li><li>Scroll down to the "Apache Karaf" section and select the desired distribution.<p>For a binary Unix distribution, the filename will be similar to: apache-karaf-x.y.tar.gz.</p></li><li>Extract the files from the gzip file into a directory of your choice. For example:<pre>
+gunzip apache-karaf-x.y.tar.gz
+tar xvf apache-karaf-x.y.tar
+</pre><p>Please remember the restrictions concerning illegal characters in Java paths, e.g. !, % etc.</p></li><li>Proceed to the <a href="start-stop#Starting Karaf.html">Starting Karaf</a> chapter.</li></ol><h2 id="PostInstallationsteps">Post-Installation steps</h2><p>Thought it is not always required, it is strongly advised to set up the <tt>JAVA_HOME</tt> environment property to point to the JDK you want Karaf to use before starting it.<br/>This property is used to locate the <tt>java</tt> executable and should be configured to point to the home directory of the Java SE 6 installation.</p><h2 id="BuildingfromSources">Building from Sources</h2><p>If you intend to build Karaf from the sources, the requirements are a bit different:</p><p><strong>Hardware:</strong></p><ul><li>200 MB of free disk space for the Apache Karaf source distributions or SVN checkout, the Maven build and the dependencies Maven downloads.</li></ul><p><strong>Environment:</strong></p><ul><li>Java SE Deve
lopment Kit 1.6.x or greater (<a href="http://www.oracle.com/technetwork/java/javase/">http://www.oracle.com/technetwork/java/javase/</a>).</li><li>Apache Maven 3.0.3 (<a href="http://maven.apache.org/download.html">http://maven.apache.org/download.html</a>).</li></ul><h3 id="BuildingonWindows">Building on Windows</h3><p>This procedure explains how to download and install the source distribution on a Windows system. <strong>NOTE:</strong> Karaf requires Java 6 to compile, build and run.</p><ol><li>From a browser, navigate to <a href="http://karaf.apache.org/index/community/download.html">http://karaf.apache.org/index/community/download.html</a>.</li><li>Scroll down to the "Apache Karaf" section and select the desired distribution.<p>For a source distribution, the filename will be similar to: <tt>apache-karaf-x.y-src.zip</tt>.</p></li><li>Extract Karaf from the ZIP file into a directory of your choice. Please remember the restrictions concerning illegal characters in Java pat
hs, e.g. !, % etc.</li><li><span id="WindowsSourceInstallation"></span> Build Karaf using Maven 3.0.3 or greater and Java 6.<p>The recommended method of building Karaf is the following:</p><pre>
+cd [karaf_install_dir]\src
+</pre><p> where <tt>karaf_install_dir</tt> is the directory in which Karaf was installed.</p><pre>
+mvn
+</pre><p>Both steps take around 10 to 15 minutes.</p></li><li>Unzip the distribution using your favorite zip tool. The windows distribution is available at<pre>
+[karaf_install_dir]\assemblies\apache-karaf\target\apache-karaf-x.y.zip
+</pre></li><li>Proceed to the <a href="start-stop#Starting Karaf.html">Starting Karaf</a> chapter.</li></ol><h3 id="BuildingonUnix">Building on Unix</h3><p>This procedure explains how to download and install the source distribution on a Unix system. This procedure assumes the Unix machine has a browser. Please see the previous <a href="#UnixBinaryInstallation.html">Unix Binary Installation</a> section for ideas on how to install Karaf without a browser. <strong>NOTE:</strong> Karaf requires Java 6 to compile, build and run.</p><ol><li>From a browser, navigate to <a href="http://karaf.apache.org/download.html">http://karaf.apache.org/download.html</a>.</li><li>Scroll down to the "Apache Karaf" section and select the desired distribution.<p>For a source distribution, the filename will be similar to: <tt>apache-karaf-x.y-src.tar.gz</tt>.</p></li><li>Extract the files from the tarball file into a directory of your choice. For example:<pre>
+gunzip apache-karaf-x.y-src.tar.gz
+tar xvf apache-karaf-x.y-src.tar
+</pre><p>Please remember the restrictions concerning illegal characters in Java paths, e.g. !, % etc.</p></li><li>Build Karaf using Maven:<p>The preferred method of building Karaf is the following:</p><pre>
+cd [karaf_install_dir]/src
+</pre><p> where <tt>karaf_install_dir</tt> is the directory in which Karaf was installed.</p><pre>
+mvn
+</pre></li><li>Uncompress the distribution that has just been created<pre>
+cd [karaf_install_dir]/assemblies/apache-karaf/target
+gunzip apache-karaf-x.y.tar.gz
+tar xvf apache-karaf-x.y.tar
+</pre></li><li>Proceed to the <a href="start-stop#Starting Karaf.html">Starting Karaf</a> chapter.</li></ol><h1 id="Directorystructure">Directory structure</h1><p>The directory layout of a Karaf installation is as follows:</p><ul><li><tt>/bin</tt>: startup scripts</li><li><tt>/etc</tt>: configuration files</li><li><tt>/data</tt>: working directory <ul><li><tt>/cache</tt>: OSGi framework bundle cache</li><li><tt>/generated-bundles</tt>: temporary folder used by the deployer</li><li><tt>/log</tt>: log files</li></ul></li><li><tt>/deploy</tt>: hot deploy directory</li><li><tt>/instances</tt>: directory containing <a href="users-guide/child-instances.html">child instances</a></li><li><tt>/lib</tt>: contains the bootstrap libraries<ul><li><tt>/lib/ext</tt>: directory for JRE extensions</li><li><tt>/lib/endorsed</tt>: directory for endorsed libraries</li></ul></li><li><tt>/system</tt>: OSGi bundles repository, laid out as a Maven 2 repository</li></ul><div class="tip" style="borde
r: 1px solid #090;background-color: #dfd;margin: 20px;padding: 0px 6px 0px 6px;"><p>The <tt>data</tt> 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 <a href="start-stop#Starting Karaf from clean.html">using the clean option</a>.</p></div> <h1 id="StartingandStoppingKaraf">Starting and Stopping Karaf</h1><p>This chapter describes how to start and stop Apache Karaf from the command line as well as from the Karaf console.</p><h2 id="StartingKaraf">Starting Karaf</h2><h3 id="OnWindows">On Windows</h3><p>From a console window, change to the installation directory and run <tt>Karaf</tt>. For the binary distribution, go to</p><pre>
+cd [karaf_install_dir]
+</pre><p>where <tt>karaf_install_dir</tt> is the directory in which Karaf was installed, e.g., <tt>c:\Program Files\apache-karaf-x.y</tt>.</p><p>Then type:</p><pre>
+bin\karaf.bat
+</pre><h3 id="OnUnix">On Unix</h3><p>From a command shell, change to the installation directory and run <tt>Karaf</tt>. For the binary distribution, go to</p><pre>
+cd [karaf_install_dir]
+</pre><p>where <tt>karaf_install_dir</tt> is the directory in which Karaf was installed, e.g., <tt>/usr/local/apache-karaf-x.y</tt>.</p><p>Then type:</p><pre>
+bin/karaf
+</pre><div class="warning" style="border: 1px solid #c00;background-color: #fcc;margin: 20px;padding: 0px 6px 0px 6px;"><p><b>Warning</b></p><p>Closing the console or shell window will cause karaf to terminate.</p></div><h2 id="StartingKarafwithoutconsole">Starting Karaf without console</h2><p>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:</p><pre>
+bin\karaf.bat server
+</pre><p>or, on Unix:</p><pre>
+bin\karaf server
+</pre><h2 id="StartingKarafinthebackground">Starting Karaf in the background</h2><p>Karaf can be easily started as a background process using the following command:</p><pre>
+bin\start.bat
+</pre><p>or, on Unix:</p><pre>
+bin\start
+</pre><h2 id="StartingKaraffromclean">Starting Karaf from clean</h2><p>Karaf can be reset to a clean state by simply deleting the <tt>data</tt> folder.<br/>For convenience, a parameter on the <tt>karaf</tt> and <tt>start</tt> scripts is available:</p><pre>
+bin/start clean
+</pre><h2 id="StoppingKaraf">Stopping Karaf</h2><p>For both Windows and Unix installations, you can perform a clean shutdown of Karaf by using the following command when inside a Karaf console:</p><pre>
+system:shutdown
+</pre><p>The shutdown command has several options you can use to change the behaviour. See <a href="commands/shutdown.html">commands/shutdown</a>.</p><p>It's also possible to delay the shutdown using the time argument. The time argument can have different formats. First, it can be an absolute time in the format hh:mm, in which hh is the hour (1 or 2 digits) and mm is the minute of the hour (in two digits). Second, it can be in the format +m, in which m is the number of minutes to wait. The work now is an alias for +0.</p><p>The following command will shutdown Karaf at 10:35am:</p><pre>
+system:shutdown 10:35
+</pre><p>The following command will shutdown Karaf in 10 minutes:</p><pre>
+system:shutdown +10
+</pre><p>If you're running from the main console, exiting the shell using <tt>logout</tt> or <tt>Ctrl+D</tt> will also terminate the Karaf instance.</p><p>From a command shell, you can run the following command:</p><pre>
+bin\stop.bat
+</pre><p>or, on Unix:</p><pre>
+bin/stop
+</pre><h1 id="ServiceWrapper">Service Wrapper</h1><h2 id="Introduction">Introduction</h2><p>The Karaf Wrapper (for service wrapper) makes it possible to install Karaf as a Windows Service. Likewise, the scripts shipped with Karaf also make it very easy to install Karaf as a daemon process on Unix systems.</p><p>The Wrapper correctly handles "user's log outs" under Windows, service dependencies, and the ability to run services which interact with the desktop.</p><h2 id="Supportedplatforms">Supported platforms</h2><p>The following platforms are supported by the Karaf Wrapper:</p><ul><li>AIX</li><li>FreeBSD</li><li>HP-UX, 32-bit and 64-bit versions</li><li>SGI Irix</li><li>Linux kernels 2.2.x, 2.4.x, 2.6.x. Known to work with Debian, Ubuntu, and Red Hat, but should work with any distribution. Currently supported on both 32-bit and 64-bit x86, Itanium, and PPC systems.</li><li>Macintosh OS X</li><li>Sun OS, Solaris 9 and 10. Currently supported on both 32-bit and 64-bit sparc, a
nd x86 systems.</li><li>Windows - Windows 2000, XP, 2003, Vista, 2008 and Windows 7. Currently supported on both 32-bit and 64-bit x86 and Itanium systems. Also known to run on Windows 98 and ME, however due the lack of support for services in the OS, the Wrapper can be run only in console mode.</li></ul><h2 id="Installation">Installation</h2><p>Karaf Wrapper is an optional feature. To install it, simply type:</p><pre>
+karaf@root> features:install wrapper
+</pre><p>Once installed, wrapper feature will provide <tt>wrapper:install</tt> new command in the Karaf shell:</p><pre>
+karaf@root> wrapper:install --help
+DESCRIPTION
+ wrapper:install
+
+ Install the container as a system service in the OS.
+
+SYNTAX
+ wrapper:install [options]
+
+OPTIONS
+ -s, --start-type
+ Mode in which the service is installed. AUTO_START or DEMAND_START (Default: AUTO_START)
+ (defaults to AUTO_START)
+ --help
+ Display this help message
+ -n, --name
+ The service name that will be used when installing the service. (Default: karaf)
+ (defaults to karaf)
+ -d, --display
+ The display name of the service.
+ -D, --description
+ The description of the service.
+ (defaults to )
+</pre><p>Using <tt>wrapper:install</tt>, you can install Karaf as a service.</p><p>For instance, to register Karaf as a service (depending of the running OS), in automatic start mode, simply type:</p><pre>
+karaf@root> wrapper:install -s AUTO_START -n KARAF -d Karaf -D "Karaf Service"
+</pre><p>For instance, on Linux, <tt>wrapper:install</tt> command will do:</p><pre>
+karaf@root> wrapper:install -s AUTO_START -n KARAF -d Karaf -D "Karaf Service"
+Creating file: /home/onofreje/apache-karaf-2.1.3/bin/KARAF-wrapper
+Creating file: /home/onofreje/apache-karaf-2.1.3/bin/KARAF-service
+Creating file: /home/onofreje/apache-karaf-2.1.3/etc/KARAF-wrapper.conf
+Creating file: /home/onofreje/apache-karaf-2.1.3/lib/libwrapper.so
+Creating file: /home/onofreje/apache-karaf-2.1.3/lib/karaf-wrapper.jar
+Creating file: /home/onofreje/apache-karaf-2.1.3/lib/karaf-wrapper-main.jar
+
+Setup complete. You may wish to tweak the JVM properties in the wrapper configuration file:
+ /home/onofreje/apache-karaf-2.1.3/etc/KARAF-wrapper.conf
+before installing and starting the service.
+
+The way the service is installed depends upon your flavor of Linux.
+
+On Redhat/Fedora/CentOS Systems:
+ To install the service:
+ $ ln -s /home/onofreje/apache-karaf-2.1.3/bin/KARAF-service /etc/init.d/
+ $ chkconfig KARAF-service --add
+
+ To start the service when the machine is rebooted:
+ $ chkconfig KARAF-service on
+
+ To disable starting the service when the machine is rebooted:
+ $ chkconfig KARAF-service off
+
+ To start the service:
+ $ service KARAF-service start
+
+ To stop the service:
+ $ service KARAF-service stop
+
+ To uninstall the service :
+ $ chkconfig KARAF-service --del
+ $ rm /etc/init.d/KARAF-service
+
+On Ubuntu/Debian Systems:
+ To install the service:
+ $ ln -s /home/onofreje/apache-karaf-2.1.3/bin/KARAF-service /etc/init.d/
+
+ To start the service when the machine is rebooted:
+ $ update-rc.d KARAF-service defaults
+
+ To disable starting the service when the machine is rebooted:
+ $ update-rc.d -f KARAF-service remove
+
+ To start the service:
+ $ /etc/init.d/KARAF-service start
+
+ To stop the service:
+ $ /etc/init.d/KARAF-service stop
+
+ To uninstall the service :
+ $ rm /etc/init.d/KARAF-service
+
+h2. Configuration Hints
+
+If you need to append parameters to the "java" invoke (like memory configurations) you add those in the KARAF-wrapper file using "wrapper.java.additional.n=PARAMETER" where "n" is the number of the additional config (typically you simply look for the last entry and use n+1) and PARAMTER is any JVM parameter you would like to append, such as "-XX:MaxPermSize=1024m".
+
+</pre><h1 id="Configuration">Configuration</h1><p>All files in the <tt>etc</tt> directory that end with ".cfg" are loaded as config admin service pids. Changes to these config files are refelected in the config admin service.</p><p>Karaf provides a suite of commands to work on any config admin service pid grouped under <tt>config</tt>. To learn about all currently supported configuration commands type:</p><div class="table-wrap"><table class="confluenceTable"><tr><th class="confluenceTh"> Command </th><th class="confluenceTh"> Description </th></tr><tr><td class="confluenceTd"> <a href="commands/config-cancel.html"><tt>cancel</tt></a> </td><td class="confluenceTd"> Discard changes </td></tr><tr><td class="confluenceTd"> <a href="commands/config-edit.html"><tt>edit</tt></a> </td><td class="confluenceTd"> Create or edit a configuration </td></tr><tr><td class="confluenceTd"> <a href="commands/config-list.html"><tt>list</tt></a>
</td><td class="confluenceTd"> List existing configurations </td></tr><tr><td class="confluenceTd"> <a href="commands/config-property-delete.html"><tt>property-delete</tt></a> </td><td class="confluenceTd"> Delete a property from the edited configuration </td></tr><tr><td class="confluenceTd"> <a href="commands/config-property-list.html"><tt>property-list</tt></a> </td><td class="confluenceTd"> List properties from the edited configuration </td></tr><tr><td class="confluenceTd"> <a href="commands/config-property-set.html"><tt>property-set</tt></a> </td><td class="confluenceTd"> Set a property on the edited configuration </td></tr><tr><td class="confluenceTd"> <a href="commands/config-update.html"><tt>update</tt></a> </td><td class="confluenceTd"> Save and propagate changes from the configuration being edited </td></tr></table></div><h2 id="Editing">Editing</h2><h3 id="a1.SelectconfigurationPIDtoedit">1. Select configuration PID to edit</h3><p>For example to edit
configuration <tt>foo.bar</tt>:</p><pre>
+karaf@root> config:edit foo.bar
+</pre><h3 id="a2.Workonproperties">2. Work on properties</h3><p>Use the property commands to work on the properties. Any number of properties can be modified within a single editing session. </p><h3 id="a3.Updateorcanceltheedit">3. Update or cancel the edit</h3><p> * <a href="commands/config-update.html"><tt>config:update</tt></a> save all changes<br/> * <a href="commands/config-cancel.html"><tt>config:cancel</tt></a> discard all changes</p><h3 id="Modifyasingleproperty">Modify a single property</h3><p>To change a single property and commit the change in one step use:</p><pre>
+config:property-set -p <pid> <prop name> <value>
+
+For example:
+config:property-set -p org.ops4j.pax.web org.osgi.service.http.port 8182
+</pre><h3 id="JMX">JMX</h3><p>Karaf also provides a Config MBean (org.apache.karaf:type=config) which allows work on configs using JMX.</p><h1 id="Usingtheconsole">Using the console</h1><h2 id="Viewingavailablecommands">Viewing available commands</h2><p>To see a list of the available commands in the console enter</p><pre>
+help
+</pre><p>This will show the list of all karaf commands together with a short description.</p><p>The list of all karaf commands and their usage is also available in the <a href="commands/commands.html">Commands section</a>.</p><h2 id="Tabcompletion">Tab completion</h2><p>The Karaf shell offers Tab completion at almost any place in the shell. So another way to see all commands is to <tt><tab></tt> key at the empty prompt.</p><pre>
+karaf@root> Display all 208 possibilities? (y or n)
+add-role add-url add-user addbundle addfilter addregion append-property bundle:capabilities
+bundle:headers bundle:info bundle:install bundle:list bundle:refresh bundle:requirements bundle:resolve bundle:restart
+...
+karaf@root>
+</pre><p>The <tt><tab></tt> key toggles autocompletion anywhere on the line, so if you want to see the commands in the <tt>osgi</tt> group, type the first letters and hit <tt><tab></tt>.<br/>Depending on the commands, autocompletion may be available for options and arguments too.</p><h2 id="Gettinghelpforacommand">Getting help for a command</h2><p>To view help on a particular command, type the command followed by <tt>--help</tt> or use the <tt>help</tt> command followed by the name of the command:</p><pre>
+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
+</pre><h2 id="More...">More...</h2><p>You'll find a more in-depth guide to the shell syntax in the <a href="developers-guide/shell-syntax.html">developers guide</a>.</p><p>The console can also be easily extended by creating new commands as explained in the <a href="developers-guide/extending-console.html">developers guide</a>.</p><h1 id="Webconsole">Web console</h1><p>The Karaf web console provides a graphical overview of the runtime.<br/>You can use it to:</p><ul><li>install and uninstall features</li><li>start, stop, install bundles</li><li>create child instances</li><li>configure Karaf</li><li>view logging informations</li></ul><h2 id="Installingthewebconsole">Installing the web console</h2><p>The web console is not installed by default. To install it, run the following command from the Karaf prompt:</p><pre>
+root@karaf> feature:install webconsole
+</pre><p>For changing the web console port number see the <a href="users-guide/http.html">HTTPService config</a>.</p><h2 id="Accessingthewebconsole">Accessing the web console</h2><p>To access the console for an instance of Karaf running locally, enter the following address in your web browser: </p><p><a href="http://localhost:8181/system/console">http://localhost:8181/system/console</a></p><p>Log in with the username <tt>karaf</tt> and the password <tt>karaf</tt>. If you have changed the default user or password, use the one you have configured.</p><h1 id="Usingremoteinstances">Using remote instances</h1><h2 id="Configuringsshaccess">Configuring ssh access</h2><p>It does not always make sense to manage an instance of Karaf using its local console. You can manage Karaf remotely using a the ssh console.</p><p>When you start Karaf, it enables a remote console that can be accessed over SSH from any other Karaf console or plain SSH client. The remote console provides all the fe
atures of the local console and gives a remote user complete control over the container and services running inside of it.</p><p>The SSH hostname and port number is configured in the <tt>etc/org.apache.karaf.shell.cfg</tt> configuration file with the following default values:</p><pre>
+sshPort=8101
+sshHost=0.0.0.0
+sshRealm=karaf
+hostKey=${karaf.base}/etc/host.key
+</pre><p>You can change this configuration using the <a href="users-guide/configuration.html">config commands</a> or by editing the above file, but you'll need to restart the ssh console in order for it to use the new parameters.</p><pre>
+config:property-set -p org.apache.karaf.shell sshPort 8102
+bundle:restart -f org.apache.karaf.shell.ssh
+</pre><h2 id="Connectingremotely">Connecting remotely</h2><h3 id="Usingthesshsshcommand">Using the <tt>ssh:ssh</tt> command</h3><p>You can connect to a remote Karaf's console using the <a href="commands/ssh-ssh.html"><tt>ssh:ssh</tt></a> command.</p><pre>
+karaf@root> ssh:ssh -l karaf -P karaf -p 8101 hostname
+</pre><div class="warning" style="border: 1px solid #c00;background-color: #fcc;margin: 20px;padding: 0px 6px 0px 6px;"><p>The default password is <tt>karaf</tt> but we recommend changing it. See the <a href="users-guide/security.html">security</a> section for more information.</p></div><p>To confirm that you have connected to the correct Karaf instance, type <a href="commands/shell-info.html"><tt>shell:info</tt></a> at the <tt>karaf></tt> prompt. Information about the currently connected instance is returned, as shown.</p><pre>
+Karaf
+ Karaf version 3.0.0-SNAPSHOT
+ Karaf home C:\java\apache-karaf-3.0.0-SNAPSHOT
+ Karaf base C:\java\apache-karaf-3.0.0-SNAPSHOT
+ OSGi Framework org.apache.felix.framework - 4.0.3
+ ...
+</pre><h3 id="UsingtheKarafclient">Using the Karaf client</h3><p>The Karaf client allows to securely connect to a running local or remote Karaf instance.</p><p>For example, to quickly connect to a Karaf instance running in server mode on the same machine, run the following command:</p><pre>
+bin/client
+</pre><p>To connect to remote instances provide a hostname, port, username and password. It is also possible to append console commands as follows:</p><pre>
+bin/client -a 8101 -h hostname -u karaf -p karaf features:install wrapper
+</pre><p>To display the available options for the client, type:</p><pre>
+> 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
+</pre><h3 id="UsingaplainSSHclient">Using a plain SSH client</h3><p>You can also connect using a plain SSH client from your *nix system or Windows SSH client like Putty.</p><pre>
+~$ ssh -p 8101 karaf@localhost
+karaf@localhost's password:
+</pre><h3 id="Disconnectingfromaremoteconsole">Disconnecting from a remote console</h3><p>To disconnect from a remote console, press <tt>Ctrl+D</tt>, <tt>shell:logout</tt> or simply <tt>logout</tt> at the Karaf prompt.</p><h2 id="Stoppingaremoteinstance">Stopping a remote instance</h2><h3 id="Usingtheremoteconsole">Using the remote console </h3><p>If you have connected to a remote console using the <a href="commands/ssh-ssh.html"><tt>ssh:ssh</tt></a> command or the Karaf client, you can stop the remote instance using the <a href="commands/osgi-shutdown.html"><tt>system:shutdown</tt></a> command.</p><div class="info" style="border: 1px solid #3c78b5;background-color: #D8E4F1;margin: 20px;padding: 0px 6px 0px 6px;"><p>Pressing <tt>Ctrl+D</tt> in a remote console simply closes the remote connection and returns you to the local shell.</p></div><h3 id="Usingthekarafclient">Using the karaf client</h3><p>To stop a remote instance using the Karaf client, run the following from the <
tt>lib</tt> directory:</p><pre>
+bin/client -u karaf -p karaf -a 8101 hostname system:shutdown
+</pre><h1 id="Deployer">Deployer</h1><p>The following picture describes the architecture of the deployer.</p><p><img border="0" src="images/deployer.png"/></p><h2 id="Blueprintdeployer">Blueprint deployer</h2><p>Karaf includes a deployer that is able to deploy plain blueprint configuration files.<br/>The deployer will transform on the fly any spring configuration file dropped into the <tt>deploy</tt> folder into a valid OSGi bundle.</p><p>The generated OSGi manifest will contain the following headers:</p><pre>
+Manifest-Version: 2
+Bundle-SymbolicName: [name of the file]
+Bundle-Version: [version of the file]
+Import-Package: [required packages]
+DynamicImport-Package: *
+</pre><p>The <tt>name</tt> and <tt>version</tt> of the file are extracted using a heuristic that will match common patterns. For example <tt>my-config-1.0.1.xml</tt> will lead to <tt>name = my-config</tt> and <tt>version = 1.0.1</tt>.<br/>The default imported packages are extracted from the spring file definition and includes all classes referenced directly.</p><p>If you need to customize the generated manifest, you can do so by including an xml element in your blueprint configuration:</p><pre>
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
+ <manifest xmlns="http://karaf.apache.org/xmlns/deployer/blueprint/v1.0.0">
+ Require-Bundle= my-bundle
+ </manifest>
+</pre><h2 id="Springdeployer">Spring deployer</h2><p>Similar to the blueprint deployer, you can deploy spring-dm configuration files.</p><p>The generated OSGi manifest will contain the following headers:</p><pre>
+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: *
+</pre><p>If you need to customize the generated manifest, you can do so by including an xml element in your spring configuration:</p><pre>
+<spring:beans ...>
+ <manifest xmlns="http://karaf.apache.org/xmlns/deployer/spring/v1.0.0">
+ Require-Bundle= my-bundle
+ </manifest>
+</pre><h2 id="Featuresdeployer">Features deployer</h2><p>To be able to hot deploy features from the deploy folder, you can just drop a feature descriptor on that folder. A bundle will be created and its installation (automatic) will trigger the installation of all features contained in the descriptor. Removing the file from the deploy folder will uninstall the features.<br/>If you want to install a single feature, you can do so by writing a feature descriptor like the following:</p><pre>
+<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>
+</pre><p>For more informations about features, see the <a href="users-guide/provisioning.html">provisioning section</a>.</p><h2 id="Wardeployer">War deployer</h2><p>To be able to hot deploy web application (war) from the deploy folder, you have to install the war feature:</p><pre>
+karaf@root> features:install war
+</pre><p>NB: you can use the -v or --verbose option to see exactly what is performed by the feature deployer.</p><pre>
+karaf@root> features:install -v war
+Installing feature war 2.99.99-SNAPSHOT
+Installing feature http 2.99.99-SNAPSHOT
+Installing feature jetty 7.2.2.v20101205
+Installing bundle mvn:org.apache.geronimo.specs/geronimo-servlet_2.5_spec/1.1.2
+Found installed bundle: org.apache.servicemix.bundles.asm [9]
+Installing bundle mvn:org.eclipse.jetty/jetty-util/7.2.2.v20101205
+Installing bundle mvn:org.eclipse.jetty/jetty-io/7.2.2.v20101205
+Installing bundle mvn:org.eclipse.jetty/jetty-http/7.2.2.v20101205
+Installing bundle mvn:org.eclipse.jetty/jetty-continuation/7.2.2.v20101205
+Installing bundle mvn:org.eclipse.jetty/jetty-server/7.2.2.v20101205
+Installing bundle mvn:org.eclipse.jetty/jetty-security/7.2.2.v20101205
+Installing bundle mvn:org.eclipse.jetty/jetty-servlet/7.2.2.v20101205
+Installing bundle mvn:org.eclipse.jetty/jetty-xml/7.2.2.v20101205
+Checking configuration file mvn:org.apache.karaf/apache-karaf/2.99.99-SNAPSHOT/xml/jettyconfig
+Installing bundle mvn:org.ops4j.pax.web/pax-web-api/1.0.0
+Installing bundle mvn:org.ops4j.pax.web/pax-web-spi/1.0.0
+Installing bundle mvn:org.ops4j.pax.web/pax-web-runtime/1.0.0
+Installing bundle mvn:org.ops4j.pax.web/pax-web-jetty/1.0.0
+Installing bundle mvn:org.apache.karaf.web/org.apache.karaf.web.core/3.0.0-SNAPSHOT
+Installing bundle mvn:org.apache.karaf.web/org.apache.karaf.web.command/3.0.0-SNAPSHOT
+Installing bundle mvn:org.ops4j.pax.web/pax-web-jsp/1.0.0
+Installing bundle mvn:org.ops4j.pax.web/pax-web-extender-war/1.0.0
+Installing bundle mvn:org.ops4j.pax.web/pax-web-extender-whiteboard/1.0.0
+Installing bundle mvn:org.ops4j.pax.web/pax-web-deployer/1.0.0
+Installing bundle mvn:org.ops4j.pax.url/pax-url-war/1.2.5
+</pre><p>As you can see, the war feature uses PAX Web as war deployer.</p><p>You should now be able to see the PAX Web war deployer:</p><pre>
+karaf@root> bundles:list |grep -i war
+[ 57] [Active ] [ ] [ 60] OPS4J Pax Web - Extender - WAR (1.0.0)
+[ 60] [Active ] [ ] [ 60] OPS4J Pax Url - war:, war-i: (1.2.5)
+</pre><p>You can deploy a web application packaged in war or exploded in a directory.</p><p>Your web application should at least contain a WEB-INF/web.xml file.</p><h2 id="Wrapdeployer">Wrap deployer</h2><p>The wrap deployer allows you to hot deploy non-OSGi jar files ("classical" jar files) from the deploy folder.</p><p>It's a standard deployer (you don't need to install additional Karaf features):</p><pre>
+karaf@root> la|grep -i wrap
+[ 1] [Active ] [ ] [ 5] OPS4J Pax Url - wrap: (1.2.5)
+[ 32] [Active ] [Created ] [ 30] Apache Karaf :: Deployer :: Wrap Non OSGi Jar (2.99.99.SNAPSHOT)
+</pre><p>Karaf wrap deployer looks for jar files in the deploy folder. The jar files is considered as non-OSGi if the MANIFEST<br/>doesn't contain the Bundle-SymbolicName and Bundle-Version attributes, or if there is no MANIFEST at all.</p><p>The non-OSGi jar file is transformed into an OSGi bundle.</p><p>The deployer tries to populate the Bundle-SymbolicName and Bundle-Version extracted from the jar file path.</p><p>For example, if you simply copy commons-lang-2.3.jar (which is not an OSGi bundle) into the deploy folder, you<br/>will see:</p><pre>
+karaf@root> la|grep -i commons-lang
+[ 41] [Active ] [ ] [ 60] commons-lang (2.3)
+</pre><p>If you take a look on the commons-lang headers, you can see that the bundle exports all packages with optional resolution<br/>and that Bundle-SymbolicName and Bundle-Version have been populated:</p><pre>
+karaf@root> bundles:headers 41
+
+commons-lang (41)
+-----------------
+Specification-Title = Commons Lang
+Tool = Bnd-0.0.357
+Specification-Version = 2.3
+Specification-Vendor = Apache Software Foundation
+Implementation-Version = 2.3
+Generated-By-Ops4j-Pax-From = wrap:file:/home/onofreje/workspace/karaf/assembly/target/apache-karaf-2.99.99-SNAPSHOT/deploy/commons-lang-2.3.jar$Bundle-SymbolicName=commons-lang&Bundle-Version=2.3
+Implementation-Vendor-Id = org.apache
+Created-By = 1.6.0_21 (Sun Microsystems Inc.)
+Implementation-Title = Commons Lang
+Manifest-Version = 1.0
+Bnd-LastModified = 1297248243231
+X-Compile-Target-JDK = 1.1
+Originally-Created-By = 1.3.1_09-85 ("Apple Computer, Inc.")
+Ant-Version = Apache Ant 1.6.5
+Package = org.apache.commons.lang
+X-Compile-Source-JDK = 1.3
+Extension-Name = commons-lang
+Implementation-Vendor = Apache Software Foundation
+
+Bundle-Name = commons-lang
+Bundle-SymbolicName = commons-lang
+Bundle-Version = 2.3
+Bundle-ManifestVersion = 2
+
+Import-Package =
+ org.apache.commons.lang;resolution:=optional,
+ org.apache.commons.lang.builder;resolution:=optional,
+ org.apache.commons.lang.enum;resolution:=optional,
+ org.apache.commons.lang.enums;resolution:=optional,
+ org.apache.commons.lang.exception;resolution:=optional,
+ org.apache.commons.lang.math;resolution:=optional,
+ org.apache.commons.lang.mutable;resolution:=optional,
+ org.apache.commons.lang.text;resolution:=optional,
+ org.apache.commons.lang.time;resolution:=optional
+Export-Package =
+ org.apache.commons.lang;uses:="org.apache.commons.lang.builder,org.apache.commons.lang.math,org.apache.commons.lang.exception",
+ org.apache.commons.lang.builder;uses:="org.apache.commons.lang.math,org.apache.commons.lang",
+ org.apache.commons.lang.enum;uses:=org.apache.commons.lang,
+ org.apache.commons.lang.enums;uses:=org.apache.commons.lang,
+ org.apache.commons.lang.exception;uses:=org.apache.commons.lang,
+ org.apache.commons.lang.math;uses:=org.apache.commons.lang,
+ org.apache.commons.lang.mutable;uses:="org.apache.commons.lang,org.apache.commons.lang.math",
+ org.apache.commons.lang.text;uses:=org.apache.commons.lang,
+ org.apache.commons.lang.time;uses:=org.apache.commons.lang
+
+</pre><p>You may set the manifest headers by specifying them as URL parameters, '$' is used separate the hierarch path and query parts of the URL, with standard URL syntax for query parameters of key=value pairs joined by '&'.</p><p>On the command line you must use single quotes around the URL to prevent the shell from attempting variable expansion, and if present, you must escape exclamation marks with a backslash.</p><pre>
+install -s 'wrap:mvn:jboss/jbossall-client/4.2.3.GA/$Bundle-SymbolicName=jbossall-client&Bundle-Version=4.2.3.GA&Export-Package=org.jboss.remoting;version="4.2.3.GA",\!*'
+</pre><p>When defined in a features.xml file, it's necessary to escape any ampersands and quotes, or use a CDATA tag.</p><pre>
+<bundle>wrap:mvn:jboss/jbossall-client/4.3.2.GA/$Bundle-SymbolicName=jbossall-client&undle-Version=4.3.2.GA&xport-Package=org.jboss.remoting;version=".3.2.GA"!*</bundle>
+</pre><h2 id="Kardeployer">Kar deployer</h2><p>The Kar deploy allows you to deploy KAR archive (Karaf ARchive). See the section of this user guide.</p><h1 id="Managingchildinstances">Managing child instances</h1><p>A child instance of Karaf is a copy that you can launch separately and deploy applications into. An instance does not contain the full copy of Karaf, but only a copy of the configuration files and data folder which contains all the runtime information, logs and temporary files.</p><h2 id="Usingtheinstanceconsolecommands">Using the instance console commands</h2><p>The <strong>instance</strong> console commands allow you to create and manage instances of Karaf on the same machine. Each new runtime is a child instance of the runtime that created it. You can easily manage the children using names instead of network addresses. For details on the <strong>admin</strong> commands, see the <a href="commands/admin.html"><tt>admin</tt> commands</a>.</p> <h2 id="Creatin
gchildinstances">Creating child instances</h2><p>You create a new runtime instance by typing <a href="commands/instance-create.html"><tt>instance:create</tt></a> in the Karaf console.</p><p>As shown in the following example, <tt>instance:create</tt> causes the runtime to create a new runtime installation in the active runtime's {{instances/<a href="name.html">name</a>} directory. The new instance is a new Karaf instance and is assigned an SSH port number based on an incremental count starting at 8101 and a RMI registry port number based on an incremental count starting at 1099.</p><pre>
+karaf@root> instance:create finn
+Creating new instance on SSH port 8106 and RMI port 1100 at: /home/user/instances/test
+Creating dir: /home/user/instances/test/bin
+Creating dir: /home/user/instances/test/etc
+Creating dir: /home/user/instances/test/system
+Creating dir: /home/user/instances/test/deploy
+Creating dir: /home/user/instances/test/data
+Creating file: /home/user/instances/test/etc/config.properties
+Creating file: /home/user/instances/test/etc/java.util.logging.properties
+Creating file: /home/user/instances/test/etc/org.apache.felix.fileinstall-deploy.cfg
+Creating file: /home/user/instances/test/etc/org.apache.karaf.log.cfg
+Creating file: /home/user/instances/test/etc/org.apache.karaf.features.cfg
+Creating file: /home/user/instances/test/etc/org.ops4j.pax.logging.cfg
+Creating file: /home/user/instances/test/etc/org.ops4j.pax.url.mvn.cfg
+Creating file: /home/user/instances/test/etc/startup.properties
+Creating file: /home/user/instances/test/etc/system.properties
+Creating file: /home/user/instances/test/etc/org.apache.karaf.shell.cfg
+Creating file: /home/user/instances/test/etc/org.apache.karaf.management.cfg
+Creating file: /home/user/instances/test/bin/karaf
+Creating file: /home/user/instances/test/bin/start
+Creating file: /home/user/instances/test/bin/stop
+karaf@root>
+</pre><h2 id="Changingachildsports">Changing a child's ports</h2><p>You can change the SSH port number assigned to a child instance using the <a href="commands/instance-change-port.html"><tt>instance:change-ssh-port</tt></a> command. The syntax for the command is:</p><pre>
+instance:change-ssh-port instance port
+</pre><p>Note that the child instance has to be stopped in order to run this command.</p><p>In the same way, you can change the RMI registry port number assigned to a child instance using the <a href="commands/instance-change-rmi-registry-port.html"><tt>instance:change-rmi-registry-port</tt></a> command. The syntax for the command is:</p><pre>
+instance:change-rmi-registry-port instance port
+</pre><p>Note that the child instance has to be stopped in order to run this command.</p><h2 id="Startingchildinstances">Starting child instances</h2><p>New instances are created in a stopped state. To start a child instance and make it ready to host applications, use the <a href="commands/instance-start.html"><tt>instance:start</tt></a> command. This command takes a single argument <tt><a href="instance-name.html">instance-name</a></tt> that identifies the child you want started.</p><h2 id="Listingallcontainerinstances">Listing all container instances</h2><p>To see a list of all Karaf instances running under a particular installation, use the <a href="commands/instance-list.html"><tt>instance:list</tt></a> command.</p><pre>
+karaf@root> instance:list
+ SSH Port RMI Port State Pid Name
+[ 8107] [ 1106] [Started ] [10628] harry
+[ 8101] [ 1099] [Started ] [20076] root
+[ 8106] [ 1105] [Stopped ] [15924] dick
+[ 8105] [ 1104] [Started ] [18224] tom
+karaf@root>
+</pre><h2 id="Connectingtoachildinstance">Connecting to a child instance</h2><p>You can connect to a started child instance's remote console using the <a href="commands/instance-connect.html"><tt>instance:connect</tt></a> command which takes three arguments:</p><pre>
+admin:connect [-u username] instance [command]
+</pre><p>NB: the password will be prompted.</p><p>NB: you can directly execute shell command on the target instance.</p><p>Once you are connected to the child instance, the Karaf prompt changes to display the name of the current instance, as shown:</p><pre>
+karaf@harry>
+</pre><h2 id="Stoppingachildinstance">Stopping a child instance</h2><p>To stop a child instance from within the instance itself, type <tt>system:shutdown</tt>.</p><p>To stop a child instance remotely, in other words, from a parent or sibling instance, use the <a href="commands/instance-stop.html"><tt>instance:stop</tt></a>:</p><pre>
+karaf@root> instance:stop instance
+</pre><h2 id="Destroyingachildinstance">Destroying a child instance</h2><p>You can permanently delete a stopped child instance using the <a href="commands/instance-destroy.html"><tt>instance:destroy</tt></a> command:</p><pre>
+karaf@root> instance:destroy instance
+</pre><p>Note that only stopped instances can be destroyed.</p><h2 id="Renamingachildinstance">Renaming a child instance</h2><p>You can easily change the name of an existing instance using the <a href="commands/instance-rename.html"><tt>instance:rename</tt></a> command:</p><pre>
+karaf@root> instance:rename instance newName
+</pre><p>Note that only stopped instances can be renamed.</p><h2 id="Cloningachildinstance">Cloning a child instance</h2><p>You can easily clone (copy) an existing instance using the <a href="commands/instance-clone.html"><tt>instance:clone</tt></a> command:</p><pre>
+karaf@root> instance:clone instance cloneName
+</pre><p>Note that only stopped instances can be cloned.</p><p>All instance files will be copied and the name and port numbers are changed in the cloned instance.</p><h2 id="Usingtheinstancescript">Using the instance script</h2><p>You can also manage the local instances of Karaf. The <tt>instance</tt> script in the <tt>bin</tt> directory provides the same commands as the <tt>instance</tt> console commands, apart from <a href="commands/instance-connect.html"><tt>instance:connect</tt></a>.</p> <pre>
+bin/instance
+</pre><p>You can also manage the local instances of Karaf. The <tt>admin</tt> script in the <tt>bin</tt> directory provides the same commands as the <tt>admin</tt> console commands, apart from <a href="commands/admin-connect.html"><tt>admin:connect</tt></a>.</p> <pre>
+bin/admin
+Available commands:
+ change-ssh-port - Changes the secure shell port of an existing container instance.
+ change-rmi-registry-port - Changes the RMI registry port (used by management layer) of an existing container instance.
+ create - Creates a new container instance.
+ destroy - Destroys an existing container instance.
+ list - List all existing container instances.
+ start - Starts an existing container instance.
+ stop - Stops an existing container instance.
+Type 'command --help' for more help on the specified command.
+</pre><p>For example, to list all the instances of Karaf on the local machine, type:</p><pre>
+bin/instance list
+</pre><h1 id="Security">Security</h1><h2 id="Managingusersandpasswords">Managing users and passwords</h2><p>The default security configuration uses a property file located at <tt>etc/users.properties</tt> to store authorized users and their passwords.</p><p>The default user name is <tt>karaf</tt> and the associated password is <tt>karaf</tt> too. We strongly encourage you to change the default password by editing the above file before moving Karaf into production.</p><p>The users are currently used in three different places in Karaf:</p><ul><li>access to the SSH console</li><li>access to the JMX management layer</li><li>access to the Web console<p>Those three ways all delegate to the same JAAS based security authentication.</p><p>The <tt>users.properties</tt> file contains one or more lines, each line defining a user, its password and the associated roles.</p><pre>
+user=password[,role][,role]...
+</pre></li></ul><h2 id="Managingroles">Managing roles</h2><p>JAAS roles can be used by various components. The three management layers (SSH, JMX and WebConsole) all use a global role based authorization system. The default role name is configured in the <tt>etc/system.properties</tt> using the <tt>karaf.admin.role</tt> system property and the default value is <tt>admin</tt>. All users authenticating for the management layer must have this role defined.</p><p>The syntax for this value is the following:</p><pre>
+[classname:]principal
+</pre><p>where classname is the class name of the principal object (defaults to org.apache.karaf.jaas.modules.RolePrincipal) and principal is the name of the principal of that class (defaults to admin).</p><p>Note that roles can be changed for a given layer using ConfigAdmin in the following configurations:</p><div class="table-wrap"><table class="confluenceTable"><tr><th class="confluenceTh"> Layer </th><th class="confluenceTh"> PID </th><th class="confluenceTh"> Value </th></tr><tr><td class="confluenceTd"> SSH </td><td class="confluenceTd"> org.apache.karaf.shell </td><td class="confluenceTd"> sshRole </td></tr><tr><td class="confluenceTd"> JMX </td><td class="confluenceTd"> org.apache.karaf.management </td><td class="confluenceTd"> jmxRole </td></tr><tr><td class="confluenceTd"> Web </td><td class="confluenceTd"> org.apache.karaf.webconsole </td><td class="confluenceTd"> role </td></tr></table></div><h2 id="Enablingpasswordencr
yption">Enabling password encryption</h2><p>In order to not keep the passwords in plain text, the passwords can be stored encrypted in the configuration file.<br/>This can be easily enabled using the following commands:</p><pre>
+config:propset -p org.apache.karaf.jaas encryption.enabled true
+system:shutdown -r -f
+</pre><p>The passwords will be encrypted automatically in the <tt>etc/users.properties</tt> configuration file the first time the user logs in.<br/>Encrypted passwords are prepended with <tt>{CRYPT}</tt> so that are easy to recognize.</p><h2 id="Managingrealms">Managing realms</h2><p>More information about modifying the default realm or deploying new realms is provided in the <a href="developers-guide/security-framework.html">developers guide</a>.</p><h2 id="Deployingsecurityproviders">Deploying security providers</h2><p>Some applications require specific security providers to be available, such as <a href="http://www.bouncycastle.org">BouncyCastle</a>. The JVM impose some restrictions about the use of such jars: they have to be signed and be available on the boot classpath. One way to deploy those providers is to put them in the JRE folder at <tt>$JAVA_HOME/jre/lib/ext</tt> and modify the security policy configuration (<tt>$JAVA_HOME/jre/lib/security/java.security</tt>) i
n order to register such providers.</p><p>While this approach works fine, it has a global effect and requires you to configure all your servers accordingly.</p><p>Karaf offers a simple way to configure additional security providers:</p><ul><li>put your provider jar in <tt>lib/ext</tt></li><li>modify the <tt>etc/config.properties</tt> configuration file to add the following property</li></ul><pre>
+org.apache.karaf.security.providers = xxx,yyy
+</pre><p>The value of this property is a comma separated list of the provider class names to register.<br/>For example:</p><pre>
+org.apache.karaf.security.providers = org.bouncycastle.jce.provider.BouncyCastleProvider
+</pre><p>In addition, you may want to provide access to the classes from those providers from the system bundle so that all bundles can access those. It can be done by modifying the <tt>org.osgi.framework.bootdelegation</tt> property in the same configuration file:</p><pre>
+org.osgi.framework.bootdelegation = ...,org.bouncycastle*
+</pre><h1 id="FailoverDeployments">Failover Deployments</h1><p>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.</p><h2 id="Simplelockfile">Simple lock file</h2><p>The simple lock file mechanism is intended for failover configurations where instances reside on the same host machine.</p><p>To use this feature, edit the <tt>$KARAF_HOME/etc/system.properties</tt> file as follows on each system in the master/slave setup:</p><pre>karaf.lock=true
+karaf.lock.class=org.apache.karaf.main.SimpleFileLock
+karaf.lock.dir=<PathToLockFileDirectory>
+karaf.lock.delay=10
+</pre><p><strong>Note</strong>: Ensure that the <tt>karaf.lock.dir</tt> property points to the same directory for both the master and slave instance, so that the slave can acquire the lock only when the master releases it.</p><h2 id="JDBClocking">JDBC locking</h2><p>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. </p><p>To use this feature, do the following on each system in the master/slave setup:</p><ul><li>Update the classpath to include the JDBC driver</li><li>Update the <tt>$KARAF_HOME/bin/karaf</tt> script to have a unique JMX remote port set if instances reside on the same host</li><li>Update the <tt>$KARAF_HOME/etc/system.properties</tt> file as follows:</li></ul><pre>karaf.lock=true
+karaf.lock.class=org.apache.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
+</pre><p><strong>Note</strong>:</p><ul><li>This process will fail if a JDBC driver is not on the classpath.</li><li>The "sample" database referred to above will be created if it does not exist.</li><li>The first Karaf instance to acquire the locking table is the master instance.</li><li>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 a manual restart.</li></ul><h3 id="JDBClockingonOracle">JDBC locking on Oracle</h3><p>If you are using Oracle as your database for JDBC locking, the <tt>karaf.lock.class</tt> property in the <tt>$KARAF_HOME/etc/system.properties</tt> file must point to <tt>org.apache.karaf.main.OracleJDBCLock</tt>.</p><p>Otherwise, configure the system.properties file as normal for your setup, for example:</p><pre>karaf.lock=true
+karaf.lock.class=org.apache.karaf.main.lock.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
+</pre><p>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 <tt>ojdbc14.jar</tt> into Karaf's <tt>lib</tt> folder before starting Karaf.</p><p><strong>Note</strong>: The <tt>karaf.lock.jdbc.url</tt> requires an active SID, which means you must manually create a database instance before using this particular lock.</p><h3 id="Derby">Derby</h3><p>The same rules apply when using derby. Make sure you have the driver jar file in the Karaf <tt>lib</tt> folder before starting Karaf.</p><p>Then make you update the properties in <tt>$KARAF_HOME/etc/system.properties</tt> to look something like this example:</p><pre>karaf.lock=true
+karaf.lock.class=org.apache.karaf.main.lock.DerbyJDBCLock
+karaf.lock.jdbc.url=jdbc:derby://127.0.0.1:1527/dbname
+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
+</pre><h3 id="MySQL">MySQL</h3><p>Make sure you have the MySQL driver jar file in the Karaf <tt>lib</tt> folder before starting Karaf.</p><p><strong>NOTE</strong>: for 2.2.x, 2.3.x, 3.0.x you need to rename the MySQL Driver jar to prefix with 'karaf-' in order for karaf to pick it up, otherwise you will see karaf just hang on startup and the log will show you that it could not find the driver.</p><p>Then make you update the properties in <tt>$KARAF_HOME/etc/system.properties</tt> to look something like this example:</p><pre>karaf.lock=true
+karaf.lock.class=org.apache.karaf.main.lock.MySQLJDBCLock
+karaf.lock.jdbc.url=jdbc:mysql://127.0.0.1:3306/dbname
+karaf.lock.jdbc.driver=com.mysql.jdbc.Driver
+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
+</pre><h3 id="PostgreSQL">PostgreSQL</h3><p>Make sure you have the PostgreSQL driver jar file in the Karaf <tt>lib</tt> folder before starting Karaf.</p><p><strong>NOTE</strong>: for 2.2.x, 2.3.x, 3.0.x you need to rename the PostgreSQL Driver jar to prefix with 'karaf-' in order for karaf to pick it up, otherwise you will see karaf just hang on startup and the log will show you that it could not find the driver.</p><p>Then make you update the properties in <tt>$KARAF_HOME/etc/system.properties</tt> to look something like this example:</p><pre>karaf.lock=true
+karaf.lock.class=org.apache.karaf.main.lock.PostgreSQLJDBCLock
+karaf.lock.jdbc.url=jdbc:postgresql://127.0.0.1:1527/dbname
+karaf.lock.jdbc.driver=org.postgresql.Driver
+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=0
+</pre><p><span id="locklevel"></span></p><h2 id="Containerlevellocking">Container-level locking</h2><p>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.</p><p>To implement container-level locking, add the following to the <tt>$KARAF_HOME/etc/system.properties</tt> file on each system in the master/slave setup:</p><pre>karaf.lock=true
+karaf.lock.level=50
+karaf.lock.delay=10
+</pre><p>The <tt>karaf.lock.level</tt> property tells the Karaf instance how far up the boot process to bring the OSGi container. All bundles with an ID equals or lower to this start level will be started in that Karaf instance.</p><p>Bundle start levels are specified in <tt>$KARAF_HOME/etc/startup.properties</tt>, in the format <tt>jar.name=level</tt>. The core system bundles have levels below 50, while user bundles have levels greater than 50.</p><div class="table-wrap"><table class="confluenceTable"><tr><th class="confluenceTh"> Level </th><th class="confluenceTh"> Behavior </th></tr><tr><td class="confluenceTd"> 1 </td><td class="confluenceTd"> A 'cold' standby instance. Core bundles are not loaded into container. Slaves will wait until lock acquired to start server. </td></tr><tr><td class="confluenceTd"> <50 </td><td class="confluenceTd"> A 'hot' standby instance. Core bundles are loaded into the container. Slaves will wait until lock acquired to start user level bu
ndles. The console will be accessible for each slave instance at this level. </td></tr><tr><td class="confluenceTd"> >50 </td><td class="confluenceTd"> This setting is not recommended as user bundles will end up being started. </td></tr></table></div><p><strong>Note</strong>: 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:</p><pre>DEFAULT_JAVA_OPTS="-server $DEFAULT_JAVA_OPTS -Dcom.sun.management.jmxremote.port=1100 -Dcom.sun.management.jmxremote.authenticate=false"
+</pre><h1 id="Loggingsystem">Logging system</h1><p>Karaf provides a powerful logging system based on <a href="http://team.ops4j.org/wiki/display/paxlogging/Pax+Logging">OPS4j Pax Logging</a>. </p><p>In addition to being a standard OSGi Log service, it supports the following APIs:</p><ul><li>Apache Commons Logging</li><li>SLF4J</li><li>Apache Log4j</li><li>Java Util Logging</li></ul><p>Karaf also comes with a set of console commands that can be used to display, view and change the log levels.</p><h2 id="Configuration">Configuration</h2><h3 id="Configurationfile">Configuration file</h3><p>The configuration of the logging system uses a <a href="http://logging.apache.org/log4j/1.2/manual.html">standard Log4j configuration file</a> at the following location:</p><pre>
+[karaf_install_dir]/etc/org.ops4j.pax.logging.cfg
[... 2441 lines stripped ...]