| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="UTF-8"> |
| <!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]--> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="generator" content="Asciidoctor 1.5.3"> |
| <title>Configuration</title> |
| <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"> |
| <style> |
| /* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */ |
| /* Remove comment around @import statement below when using as a custom stylesheet */ |
| /*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";*/ |
| article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section,summary{display:block} |
| audio,canvas,video{display:inline-block} |
| audio:not([controls]){display:none;height:0} |
| [hidden],template{display:none} |
| script{display:none!important} |
| html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%} |
| body{margin:0} |
| a{background:transparent} |
| a:focus{outline:thin dotted} |
| a:active,a:hover{outline:0} |
| h1{font-size:2em;margin:.67em 0} |
| abbr[title]{border-bottom:1px dotted} |
| b,strong{font-weight:bold} |
| dfn{font-style:italic} |
| hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0} |
| mark{background:#ff0;color:#000} |
| code,kbd,pre,samp{font-family:monospace;font-size:1em} |
| pre{white-space:pre-wrap} |
| q{quotes:"\201C" "\201D" "\2018" "\2019"} |
| small{font-size:80%} |
| sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline} |
| sup{top:-.5em} |
| sub{bottom:-.25em} |
| img{border:0} |
| svg:not(:root){overflow:hidden} |
| figure{margin:0} |
| fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em} |
| legend{border:0;padding:0} |
| button,input,select,textarea{font-family:inherit;font-size:100%;margin:0} |
| button,input{line-height:normal} |
| button,select{text-transform:none} |
| button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer} |
| button[disabled],html input[disabled]{cursor:default} |
| input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0} |
| input[type="search"]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box} |
| input[type="search"]::-webkit-search-cancel-button,input[type="search"]::-webkit-search-decoration{-webkit-appearance:none} |
| button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0} |
| textarea{overflow:auto;vertical-align:top} |
| table{border-collapse:collapse;border-spacing:0} |
| *,*:before,*:after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box} |
| html,body{font-size:100%} |
| body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto} |
| a:hover{cursor:pointer} |
| img,object,embed{max-width:100%;height:auto} |
| object,embed{height:100%} |
| img{-ms-interpolation-mode:bicubic} |
| .left{float:left!important} |
| .right{float:right!important} |
| .text-left{text-align:left!important} |
| .text-right{text-align:right!important} |
| .text-center{text-align:center!important} |
| .text-justify{text-align:justify!important} |
| .hide{display:none} |
| body{-webkit-font-smoothing:antialiased} |
| img,object,svg{display:inline-block;vertical-align:middle} |
| textarea{height:auto;min-height:50px} |
| select{width:100%} |
| .center{margin-left:auto;margin-right:auto} |
| .spread{width:100%} |
| p.lead,.paragraph.lead>p,#preamble>.sectionbody>.paragraph:first-of-type p{font-size:1.21875em;line-height:1.6} |
| .subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em} |
| div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr} |
| a{color:#2156a5;text-decoration:underline;line-height:inherit} |
| a:hover,a:focus{color:#1d4b8f} |
| a img{border:none} |
| p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility} |
| p aside{font-size:.875em;line-height:1.35;font-style:italic} |
| h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em} |
| h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0} |
| h1{font-size:2.125em} |
| h2{font-size:1.6875em} |
| h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em} |
| h4,h5{font-size:1.125em} |
| h6{font-size:1em} |
| hr{border:solid #ddddd8;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0} |
| em,i{font-style:italic;line-height:inherit} |
| strong,b{font-weight:bold;line-height:inherit} |
| small{font-size:60%;line-height:inherit} |
| code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)} |
| ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit} |
| ul,ol,ul.no-bullet,ol.no-bullet{margin-left:1.5em} |
| ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em} |
| ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit} |
| ul.square{list-style-type:square} |
| ul.circle{list-style-type:circle} |
| ul.disc{list-style-type:disc} |
| ul.no-bullet{list-style:none} |
| ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0} |
| dl dt{margin-bottom:.3125em;font-weight:bold} |
| dl dd{margin-bottom:1.25em} |
| abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help} |
| abbr{text-transform:none} |
| blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd} |
| blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)} |
| blockquote cite:before{content:"\2014 \0020"} |
| blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)} |
| blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)} |
| @media only screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2} |
| h1{font-size:2.75em} |
| h2{font-size:2.3125em} |
| h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em} |
| h4{font-size:1.4375em}} |
| table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede} |
| table thead,table tfoot{background:#f7f8f7;font-weight:bold} |
| table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left} |
| table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)} |
| table tr.even,table tr.alt,table tr:nth-of-type(even){background:#f8f8f7} |
| table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6} |
| body{tab-size:4} |
| h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em} |
| h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400} |
| .clearfix:before,.clearfix:after,.float-group:before,.float-group:after{content:" ";display:table} |
| .clearfix:after,.float-group:after{clear:both} |
| *:not(pre)>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background-color:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed} |
| pre,pre>code{line-height:1.45;color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;text-rendering:optimizeSpeed} |
| .keyseq{color:rgba(51,51,51,.8)} |
| kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background-color:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap} |
| .keyseq kbd:first-child{margin-left:0} |
| .keyseq kbd:last-child{margin-right:0} |
| .menuseq,.menu{color:rgba(0,0,0,.8)} |
| b.button:before,b.button:after{position:relative;top:-1px;font-weight:400} |
| b.button:before{content:"[";padding:0 3px 0 2px} |
| b.button:after{content:"]";padding:0 2px 0 3px} |
| p a>code:hover{color:rgba(0,0,0,.9)} |
| #header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em} |
| #header:before,#header:after,#content:before,#content:after,#footnotes:before,#footnotes:after,#footer:before,#footer:after{content:" ";display:table} |
| #header:after,#content:after,#footnotes:after,#footer:after{clear:both} |
| #content{margin-top:1.25em} |
| #content:before{content:none} |
| #header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0} |
| #header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #ddddd8} |
| #header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #ddddd8;padding-bottom:8px} |
| #header .details{border-bottom:1px solid #ddddd8;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap} |
| #header .details span:first-child{margin-left:-.125em} |
| #header .details span.email a{color:rgba(0,0,0,.85)} |
| #header .details br{display:none} |
| #header .details br+span:before{content:"\00a0\2013\00a0"} |
| #header .details br+span.author:before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)} |
| #header .details br+span#revremark:before{content:"\00a0|\00a0"} |
| #header #revnumber{text-transform:capitalize} |
| #header #revnumber:after{content:"\00a0"} |
| #content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #ddddd8;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem} |
| #toc{border-bottom:1px solid #efefed;padding-bottom:.5em} |
| #toc>ul{margin-left:.125em} |
| #toc ul.sectlevel0>li>a{font-style:italic} |
| #toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0} |
| #toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none} |
| #toc li{line-height:1.3334;margin-top:.3334em} |
| #toc a{text-decoration:none} |
| #toc a:active{text-decoration:underline} |
| #toctitle{color:#7a2518;font-size:1.2em} |
| @media only screen and (min-width:768px){#toctitle{font-size:1.375em} |
| body.toc2{padding-left:15em;padding-right:0} |
| #toc.toc2{margin-top:0!important;background-color:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #efefed;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto} |
| #toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em} |
| #toc.toc2>ul{font-size:.9em;margin-bottom:0} |
| #toc.toc2 ul ul{margin-left:0;padding-left:1em} |
| #toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em} |
| body.toc2.toc-right{padding-left:0;padding-right:15em} |
| body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #efefed;left:auto;right:0}} |
| @media only screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0} |
| #toc.toc2{width:20em} |
| #toc.toc2 #toctitle{font-size:1.375em} |
| #toc.toc2>ul{font-size:.95em} |
| #toc.toc2 ul ul{padding-left:1.25em} |
| body.toc2.toc-right{padding-left:0;padding-right:20em}} |
| #content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px} |
| #content #toc>:first-child{margin-top:0} |
| #content #toc>:last-child{margin-bottom:0} |
| #footer{max-width:100%;background-color:rgba(0,0,0,.8);padding:1.25em} |
| #footer-text{color:rgba(255,255,255,.8);line-height:1.44} |
| .sect1{padding-bottom:.625em} |
| @media only screen and (min-width:768px){.sect1{padding-bottom:1.25em}} |
| .sect1+.sect1{border-top:1px solid #efefed} |
| #content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400} |
| #content h1>a.anchor:before,h2>a.anchor:before,h3>a.anchor:before,#toctitle>a.anchor:before,.sidebarblock>.content>.title>a.anchor:before,h4>a.anchor:before,h5>a.anchor:before,h6>a.anchor:before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em} |
| #content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible} |
| #content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none} |
| #content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221} |
| .audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em} |
| .admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic} |
| table.tableblock>caption.title{white-space:nowrap;overflow:visible;max-width:0} |
| .paragraph.lead>p,#preamble>.sectionbody>.paragraph:first-of-type p{color:rgba(0,0,0,.85)} |
| table.tableblock #preamble>.sectionbody>.paragraph:first-of-type p{font-size:inherit} |
| .admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%} |
| .admonitionblock>table td.icon{text-align:center;width:80px} |
| .admonitionblock>table td.icon img{max-width:none} |
| .admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase} |
| .admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #ddddd8;color:rgba(0,0,0,.6)} |
| .admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0} |
| .exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px} |
| .exampleblock>.content>:first-child{margin-top:0} |
| .exampleblock>.content>:last-child{margin-bottom:0} |
| .sidebarblock{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px} |
| .sidebarblock>:first-child{margin-top:0} |
| .sidebarblock>:last-child{margin-bottom:0} |
| .sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center} |
| .exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0} |
| .literalblock pre,.listingblock pre:not(.highlight),.listingblock pre[class="highlight"],.listingblock pre[class^="highlight "],.listingblock pre.CodeRay,.listingblock pre.prettyprint{background:#f7f7f8} |
| .sidebarblock .literalblock pre,.sidebarblock .listingblock pre:not(.highlight),.sidebarblock .listingblock pre[class="highlight"],.sidebarblock .listingblock pre[class^="highlight "],.sidebarblock .listingblock pre.CodeRay,.sidebarblock .listingblock pre.prettyprint{background:#f2f1f1} |
| .literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;padding:1em;font-size:.8125em} |
| .literalblock pre.nowrap,.literalblock pre[class].nowrap,.listingblock pre.nowrap,.listingblock pre[class].nowrap{overflow-x:auto;white-space:pre;word-wrap:normal} |
| @media only screen and (min-width:768px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:.90625em}} |
| @media only screen and (min-width:1280px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:1em}} |
| .literalblock.output pre{color:#f7f7f8;background-color:rgba(0,0,0,.9)} |
| .listingblock pre.highlightjs{padding:0} |
| .listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px} |
| .listingblock pre.prettyprint{border-width:0} |
| .listingblock>.content{position:relative} |
| .listingblock code[data-lang]:before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:#999} |
| .listingblock:hover code[data-lang]:before{display:block} |
| .listingblock.terminal pre .command:before{content:attr(data-prompt);padding-right:.5em;color:#999} |
| .listingblock.terminal pre .command:not([data-prompt]):before{content:"$"} |
| table.pyhltable{border-collapse:separate;border:0;margin-bottom:0;background:none} |
| table.pyhltable td{vertical-align:top;padding-top:0;padding-bottom:0;line-height:1.45} |
| table.pyhltable td.code{padding-left:.75em;padding-right:0} |
| pre.pygments .lineno,table.pyhltable td:not(.code){color:#999;padding-left:0;padding-right:.5em;border-right:1px solid #ddddd8} |
| pre.pygments .lineno{display:inline-block;margin-right:.25em} |
| table.pyhltable .linenodiv{background:none!important;padding-right:0!important} |
| .quoteblock{margin:0 1em 1.25em 1.5em;display:table} |
| .quoteblock>.title{margin-left:-1.5em;margin-bottom:.75em} |
| .quoteblock blockquote,.quoteblock blockquote p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify} |
| .quoteblock blockquote{margin:0;padding:0;border:0} |
| .quoteblock blockquote:before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)} |
| .quoteblock blockquote>.paragraph:last-child p{margin-bottom:0} |
| .quoteblock .attribution{margin-top:.5em;margin-right:.5ex;text-align:right} |
| .quoteblock .quoteblock{margin-left:0;margin-right:0;padding:.5em 0;border-left:3px solid rgba(0,0,0,.6)} |
| .quoteblock .quoteblock blockquote{padding:0 0 0 .75em} |
| .quoteblock .quoteblock blockquote:before{display:none} |
| .verseblock{margin:0 1em 1.25em 1em} |
| .verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility} |
| .verseblock pre strong{font-weight:400} |
| .verseblock .attribution{margin-top:1.25rem;margin-left:.5ex} |
| .quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic} |
| .quoteblock .attribution br,.verseblock .attribution br{display:none} |
| .quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)} |
| .quoteblock.abstract{margin:0 0 1.25em 0;display:block} |
| .quoteblock.abstract blockquote,.quoteblock.abstract blockquote p{text-align:left;word-spacing:0} |
| .quoteblock.abstract blockquote:before,.quoteblock.abstract blockquote p:first-of-type:before{display:none} |
| table.tableblock{max-width:100%;border-collapse:separate} |
| table.tableblock td>.paragraph:last-child p>p:last-child,table.tableblock th>p:last-child,table.tableblock td>p:last-child{margin-bottom:0} |
| table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede} |
| table.grid-all th.tableblock,table.grid-all td.tableblock{border-width:0 1px 1px 0} |
| table.grid-all tfoot>tr>th.tableblock,table.grid-all tfoot>tr>td.tableblock{border-width:1px 1px 0 0} |
| table.grid-cols th.tableblock,table.grid-cols td.tableblock{border-width:0 1px 0 0} |
| table.grid-all *>tr>.tableblock:last-child,table.grid-cols *>tr>.tableblock:last-child{border-right-width:0} |
| table.grid-rows th.tableblock,table.grid-rows td.tableblock{border-width:0 0 1px 0} |
| table.grid-all tbody>tr:last-child>th.tableblock,table.grid-all tbody>tr:last-child>td.tableblock,table.grid-all thead:last-child>tr>th.tableblock,table.grid-rows tbody>tr:last-child>th.tableblock,table.grid-rows tbody>tr:last-child>td.tableblock,table.grid-rows thead:last-child>tr>th.tableblock{border-bottom-width:0} |
| table.grid-rows tfoot>tr>th.tableblock,table.grid-rows tfoot>tr>td.tableblock{border-width:1px 0 0 0} |
| table.frame-all{border-width:1px} |
| table.frame-sides{border-width:0 1px} |
| table.frame-topbot{border-width:1px 0} |
| th.halign-left,td.halign-left{text-align:left} |
| th.halign-right,td.halign-right{text-align:right} |
| th.halign-center,td.halign-center{text-align:center} |
| th.valign-top,td.valign-top{vertical-align:top} |
| th.valign-bottom,td.valign-bottom{vertical-align:bottom} |
| th.valign-middle,td.valign-middle{vertical-align:middle} |
| table thead th,table tfoot th{font-weight:bold} |
| tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7} |
| tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold} |
| p.tableblock>code:only-child{background:none;padding:0} |
| p.tableblock{font-size:1em} |
| td>div.verse{white-space:pre} |
| ol{margin-left:1.75em} |
| ul li ol{margin-left:1.5em} |
| dl dd{margin-left:1.125em} |
| dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0} |
| ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em} |
| ul.unstyled,ol.unnumbered,ul.checklist,ul.none{list-style-type:none} |
| ul.unstyled,ol.unnumbered,ul.checklist{margin-left:.625em} |
| ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1em;font-size:.85em} |
| ul.checklist li>p:first-child>input[type="checkbox"]:first-child{width:1em;position:relative;top:1px} |
| ul.inline{margin:0 auto .625em auto;margin-left:-1.375em;margin-right:0;padding:0;list-style:none;overflow:hidden} |
| ul.inline>li{list-style:none;float:left;margin-left:1.375em;display:block} |
| ul.inline>li>*{display:block} |
| .unstyled dl dt{font-weight:400;font-style:normal} |
| ol.arabic{list-style-type:decimal} |
| ol.decimal{list-style-type:decimal-leading-zero} |
| ol.loweralpha{list-style-type:lower-alpha} |
| ol.upperalpha{list-style-type:upper-alpha} |
| ol.lowerroman{list-style-type:lower-roman} |
| ol.upperroman{list-style-type:upper-roman} |
| ol.lowergreek{list-style-type:lower-greek} |
| .hdlist>table,.colist>table{border:0;background:none} |
| .hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none} |
| td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em} |
| td.hdlist1{font-weight:bold;padding-bottom:1.25em} |
| .literalblock+.colist,.listingblock+.colist{margin-top:-.5em} |
| .colist>table tr>td:first-of-type{padding:0 .75em;line-height:1} |
| .colist>table tr>td:last-of-type{padding:.25em 0} |
| .thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd} |
| .imageblock.left,.imageblock[style*="float: left"]{margin:.25em .625em 1.25em 0} |
| .imageblock.right,.imageblock[style*="float: right"]{margin:.25em 0 1.25em .625em} |
| .imageblock>.title{margin-bottom:0} |
| .imageblock.thumb,.imageblock.th{border-width:6px} |
| .imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em} |
| .image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0} |
| .image.left{margin-right:.625em} |
| .image.right{margin-left:.625em} |
| a.image{text-decoration:none;display:inline-block} |
| a.image object{pointer-events:none} |
| sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super} |
| sup.footnote a,sup.footnoteref a{text-decoration:none} |
| sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline} |
| #footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em} |
| #footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em 0;border-width:1px 0 0 0} |
| #footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;text-indent:-1.05em;margin-bottom:.2em} |
| #footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none} |
| #footnotes .footnote:last-of-type{margin-bottom:0} |
| #content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0} |
| .gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0} |
| .gist .file-data>table td.line-data{width:99%} |
| div.unbreakable{page-break-inside:avoid} |
| .big{font-size:larger} |
| .small{font-size:smaller} |
| .underline{text-decoration:underline} |
| .overline{text-decoration:overline} |
| .line-through{text-decoration:line-through} |
| .aqua{color:#00bfbf} |
| .aqua-background{background-color:#00fafa} |
| .black{color:#000} |
| .black-background{background-color:#000} |
| .blue{color:#0000bf} |
| .blue-background{background-color:#0000fa} |
| .fuchsia{color:#bf00bf} |
| .fuchsia-background{background-color:#fa00fa} |
| .gray{color:#606060} |
| .gray-background{background-color:#7d7d7d} |
| .green{color:#006000} |
| .green-background{background-color:#007d00} |
| .lime{color:#00bf00} |
| .lime-background{background-color:#00fa00} |
| .maroon{color:#600000} |
| .maroon-background{background-color:#7d0000} |
| .navy{color:#000060} |
| .navy-background{background-color:#00007d} |
| .olive{color:#606000} |
| .olive-background{background-color:#7d7d00} |
| .purple{color:#600060} |
| .purple-background{background-color:#7d007d} |
| .red{color:#bf0000} |
| .red-background{background-color:#fa0000} |
| .silver{color:#909090} |
| .silver-background{background-color:#bcbcbc} |
| .teal{color:#006060} |
| .teal-background{background-color:#007d7d} |
| .white{color:#bfbfbf} |
| .white-background{background-color:#fafafa} |
| .yellow{color:#bfbf00} |
| .yellow-background{background-color:#fafa00} |
| span.icon>.fa{cursor:default} |
| .admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default} |
| .admonitionblock td.icon .icon-note:before{content:"\f05a";color:#19407c} |
| .admonitionblock td.icon .icon-tip:before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111} |
| .admonitionblock td.icon .icon-warning:before{content:"\f071";color:#bf6900} |
| .admonitionblock td.icon .icon-caution:before{content:"\f06d";color:#bf3400} |
| .admonitionblock td.icon .icon-important:before{content:"\f06a";color:#bf0000} |
| .conum[data-value]{display:inline-block;color:#fff!important;background-color:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold} |
| .conum[data-value] *{color:#fff!important} |
| .conum[data-value]+b{display:none} |
| .conum[data-value]:after{content:attr(data-value)} |
| pre .conum[data-value]{position:relative;top:-.125em} |
| b.conum *{color:inherit!important} |
| .conum:not([data-value]):empty{display:none} |
| dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility} |
| h1,h2,p,td.content,span.alt{letter-spacing:-.01em} |
| p strong,td.content strong,div.footnote strong{letter-spacing:-.005em} |
| p,blockquote,dt,td.content,span.alt{font-size:1.0625rem} |
| p{margin-bottom:1.25rem} |
| .sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em} |
| .exampleblock>.content{background-color:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc} |
| .print-only{display:none!important} |
| @media print{@page{margin:1.25cm .75cm} |
| *{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important} |
| a{color:inherit!important;text-decoration:underline!important} |
| a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important} |
| a[href^="http:"]:not(.bare):after,a[href^="https:"]:not(.bare):after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em} |
| abbr[title]:after{content:" (" attr(title) ")"} |
| pre,blockquote,tr,img,object,svg{page-break-inside:avoid} |
| thead{display:table-header-group} |
| svg{max-width:100%} |
| p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3} |
| h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid} |
| #toc,.sidebarblock,.exampleblock>.content{background:none!important} |
| #toc{border-bottom:1px solid #ddddd8!important;padding-bottom:0!important} |
| .sect1{padding-bottom:0!important} |
| .sect1+.sect1{border:0!important} |
| #header>h1:first-child{margin-top:1.25rem} |
| body.book #header{text-align:center} |
| body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em 0} |
| body.book #header .details{border:0!important;display:block;padding:0!important} |
| body.book #header .details span:first-child{margin-left:0!important} |
| body.book #header .details br{display:block} |
| body.book #header .details br+span:before{content:none!important} |
| body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important} |
| body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always} |
| .listingblock code[data-lang]:before{display:block} |
| #footer{background:none!important;padding:0 .9375em} |
| #footer-text{color:rgba(0,0,0,.6)!important;font-size:.9em} |
| .hide-on-print{display:none!important} |
| .print-only{display:block!important} |
| .hide-for-print{display:none!important} |
| .show-for-print{display:inherit!important}} |
| </style> |
| </head> |
| <body class="article"> |
| <div id="header"> |
| </div> |
| <div id="content"> |
| <div class="paragraph"> |
| <p><a id="configuring"></a></p> |
| </div> |
| <div class="sect1"> |
| <h2 id="_configuration">Configuration</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Configuration</p> |
| </div> |
| <div class="paragraph"> |
| <p>You use configuration files in the <code>$SERVER_HOME/configuration</code> directory to configure Virgo. You can also configure the OSGi framework using files the same <code>$SERVER_HOME/configuration</code> directory. This section divides the configuration of the server into the following high-level tasks:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#configuring-osgi-framework">Configuring the OSGi framework</a></p> |
| </li> |
| <li> |
| <p><a href="#configuring-framework-extensions">Configuring framework extensions and fragments on the system bundle</a></p> |
| </li> |
| <li> |
| <p><a href="#configuring-serviceability">Configuring serviceability</a></p> |
| </li> |
| <li> |
| <p><a href="#configuring-provisioning-repository">Configuring the local provisioning repository</a></p> |
| </li> |
| <li> |
| <p><a href="#configuring-hosted-repo">Configuring the hosted repository</a></p> |
| </li> |
| <li> |
| <p><a href="#configuring-kernel">Configuring the kernel and User Region</a></p> |
| </li> |
| <li> |
| <p><a href="#configuring-tomcat">Configuring the embedded Tomcat servlet container</a></p> |
| </li> |
| <li> |
| <p><a href="#configuring-web">Configuring the web integration layer</a></p> |
| </li> |
| <li> |
| <p><a href="#configuring-jetty">Configuring the embedded Jetty servlet container</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="title">Why is there both a config and a configuration directory?</div> |
| <div class="paragraph"> |
| <p>The <strong>config</strong> directory has always contained Virgo configuration files. When Virgo Nano and its support for p2 provisioning was introduced in Virgo 3.5.0, a <strong>configuration</strong> directory replaced the old <strong>config</strong> one. Now all Virgo configurations are assembled in that directory providing a single point of configuration. The directory name <strong>configuration</strong> in the installation’s root is used by default in p2 to configure the OSGi framework during provisioning. |
| This chapter makes it clear which configuration goes in each directory.</p> |
| </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>Sections 4-6 and 8-9 does not apply for Virgo Nano.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-osgi-framework"></a></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_configuring_the_osgi_framework">Configuring the OSGi Framework</h3> |
| <div class="paragraph"> |
| <p>This section provides information about configuring the OSGi framework by updating the following files in the <code>$SERVER_HOME/configuration</code> directory:</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-osgi-framework-table"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 1. OSGi Framework Configuration Files</caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 33%;"> |
| <col style="width: 33%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property File</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| <th class="tableblock halign-left valign-top">Location</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>config.ini</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Configures <a href="#configuring-framework-properties">OSGi framework properties</a>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>$SERVER_HOME/configuration</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>bundles.info</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Configures <a href="#configuring-framework-bundles">OSGi framework bundles</a>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>$SERVER_HOME/configuration/org.eclipse.equinox.simpleconfigurator</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>java-server.profile</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Configures the <a href="#configuring-framework-profile">OSGi framework profile</a>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>$SERVER_HOME/configuration</code></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a id="configuring-framework-properties"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_configuring_osgi_framework_properties">Configuring OSGi Framework Properties</h4> |
| <div class="paragraph"> |
| <p>You specify the framework properties in the <code>$SERVER_HOME/configuration/config.ini</code> file. The |
| properties most relevant to users are described in the following table.</p> |
| </div> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Warning</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>We strongly recommend that you update only the |
| properties below; updating other properties could cause Virgo |
| to fail.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-framework-properties-table"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 2. Framework Properties</caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.virgo.kernel.startup.wait.limit</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the amount of time, in seconds, after which various operations time out out while trying to start the kernel. |
| The default value is 180.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.virgo.suppress.heap.dumps</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Set to 'false' by default this property will prevent heap dumps being contributed to dumps taken during a |
| First Failure Data Capture (FFDC) event. When the heap dumps are produced they will be located along with |
| the other dump artifacts in the <code>$SERVER_HOME/serviceability/dump/</code> folder.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>osgi.java.profile</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the profile to use using a <code>file:</code> URI with default value |
| <code>file:configuration/java-server.profile</code>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>osgi.bundlefile.limit</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies a limit on the number of jar files the framework will keep open. |
| The minimum value allowed is 10. Any value less than 10 will disable the bundle file limit, making the the number of jar files the framework keeps open unlimited. |
| By default the value is 100. |
| Increase the default value if you have many jar files in the bundle class path, expect a lot of file system operations etc.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a id="configuring-framework-bundles"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_configuring_osgi_framework_bundles">Configuring OSGi Framework Bundles</h4> |
| <div class="paragraph"> |
| <p>You specify the framework bundles in the <code>$SERVER_HOME/configuration/org.eclipse.equinox.simpleconfigurator/bundles.info</code> file. The syntax |
| that is accepted for listing bundles there is:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre><bsn>,<version>,<jar-location>,<start-level>,<toStart?> |
| bsn - the bundle's symbolic name string |
| version - the bundle's version string |
| jar-location - relative or absolute path to the jar file |
| start-level - a digit indicating the bundle's start level |
| toStart? - true or false value indicating whether a bundle should be started or not</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Here’s an example:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>org.eclipse.virgo.util.osgi,3.1.0.BUILD-20111031165127,plugins/org.eclipse.virgo.util.osgi_3.1.0.BUILD-20111031165127.jar,4,true</pre> |
| </div> |
| </div> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Warning</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>We strongly recommend that you don’t remove bundles already present in your bundles.info file as that may break your server. Add bundles here only if absolutely necessary.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-framework-profile"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_configuring_osgi_framework_profile">Configuring OSGi Framework Profile</h4> |
| <div class="paragraph"> |
| <p>You specify the framework profile in the <code>$SERVER_HOME/configuration/java6-server.profile</code> file. The |
| properties most relevant to users are described in the following table.</p> |
| </div> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Warning</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>We advise you not to change the framework profile unless you are sure you know exactly what |
| you are doing; updating the profile could cause Virgo to fail.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-framework-profile-table"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 3. Framework Profile Properties</caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.osgi.framework.bootdelegation</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This property specifies the packages which are loaded by delegation to the application class loader. |
| Bundles can load classes belonging to these packages without importing the packages. |
| The <code>.<strong></code> wildcard matches any package suffix. <code>java.</strong></code> is always |
| boot delegated and must not be specified in this property. |
| </p><p class="tableblock"> A common reason for adding packages to this property is to run Virgo under a performance profiler.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.osgi.framework.system.packages</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This property specifies the packages which are exported by the system bundle. |
| Although the system bundle is typically imported into the User Region, any additional packages will not be |
| visible in the User Region unless you also import them using the <code>packagedImports</code> property. |
| See <a href="#configuring-user-region">Configuring the User Region</a> for instructions. |
| </p><p class="tableblock"> It is very occasionally necessary to extend the set, for example when configuring email logging appenders since the |
| implementation of <code>javax.mail</code> is intimately related to the implementation of |
| <code>javax.activation</code>. |
| </p><p class="tableblock"> To make the corresponding classes available for loading, the relevant JAR file(s) should be placed in |
| <code>$SERVER_HOME/lib</code> so that they will be added to the application class path.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a id="configuring-framework-extensions"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_configuring_framework_extensions_and_fragments_on_the_system_bundle">Configuring Framework Extensions and Fragments on the System Bundle</h3> |
| <div class="paragraph"> |
| <p>This section provides information about configuring framework extensions and fragments on the system bundle. Deployment of such bundles is not allowed in |
| Virgo. This is because by refreshing or uninstalling them the system.bundle is also refreshed, which causes Virgo to crash.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>This only applies for fragments on the system bundle. All other fragment bundles have no deployment restrictions.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Generally it’s best to avoid usage of such fragment bundles as they are a common OSGi framework issue and often require restarting the framework. |
| However sometimes there are no other options and one has to use framework extensions or fragments on the system bundle.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You can configure framework extensions and system bundle fragments as follows:</p> |
| </div> |
| <div class="paragraph"> |
| <p><strong>1.</strong> Place your fragment bundle in the <code>/plugins</code> directory of your Virgo installation. |
| Lets say we have bundle with</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>symbolic name: *testFragment*, version: *1.0.0* and filename: *testFragmentBinary_1.0.0.jar*</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><strong>2.</strong> Configure the <code>bundles.info</code> file in <code>/configuration/org.eclipse.equinox.simpleconfigurator</code> to include the |
| just copied fragment or framework extension bundle.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Add a line at the end of the <code>bundles.info</code> file similar to this one:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>testFragment,1.0.0,plugins/testFragmentBinary_1.0.0.jar,4,false*</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><strong>3.</strong> Configure the <code>org.eclipse.virgo.kernel.userregion.properties</code> file in <code>/configuration</code> folder to import the fragment bundle or framework extension in the User Region.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Add to the <code>bundleImports</code> property a new line describing the fragment bundle using its symbolic name and version.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>bundleImports = org.eclipse.osgi;bundle-version="0",<emphasis role="bold">testFragment;bundle-version="0"*</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-serviceability"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_configuring_serviceability_and_diagnostics">Configuring Serviceability and Diagnostics</h3> |
| <div class="paragraph"> |
| <p>The serviceability features of Virgo allow you to gather and view data and information that you can then use to diagnose problems and failures. Serviceability data includes:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Service dumps: Contain a snapshot of all the important state from the running Virgo instance when an internal failure or thread deadlock is detected. |
| You configure service dumps for Virgo using the <a href="#configuring-serviceability-medic">org.eclipse.virgo.medic.properties</a> file in the <code>$SERVER_HOME/configuration</code> directory. This file also includes some additional logging configuration.</p> |
| </li> |
| <li> |
| <p>Event logs and server/application (trace) logging: Logging support in Virgo is based on <a href="http://logback.qos.ch/">Logback</a>. This means that you have complete control over the format of log output and have the complete range of Logback’s appenders available for your use. |
| You configure logging for Virgo using the <a href="#configuring-serviceability-logback">serviceability.xml</a> file in the <code>$SERVER_HOME/configuration</code> directory. This file is essentially the Logback <code>logback.xml</code> (or <code>logback-test.xml</code>) configuration file but renamed for Virgo.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For additional conceptual information about the serviceability subsystem, see xref:serviceability" />.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-serviceability-medic"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_the_org_eclipse_virgo_medic_properties_file">The org.eclipse.virgo.medic.properties File</h4> |
| <div class="paragraph"> |
| <p>The <code>$SERVER_HOME/configuration/org.eclipse.virgo.medic.properties</code> file configures Virgo service dumps and whether you want to capture <code>System.out</code> and <code>System.err</code> output to your application’s trace file. |
| The following table describes the properties you can include in the <code>$SERVER_HOME/configuration/org.eclipse.virgo.medic.properties</code> file. This file configures serviceability properties that Virgo includes in addition to those supplied by the Logback, configured in the <code>serviceability.xml</code> file.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="medic-properties-table"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 4. Serviceability Properties</caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>dump.root.directory</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the directory to which Virgo writes the service dumps. The directory name is relative to <code>$SERVER_HOME</code>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>log.wrapSysOut</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies whether you want to capture <code>System.out</code> output from your applications to the application trace file. The output is logged by Virgo’s root logger, which captures <code>INFO</code> level and above. |
| Valid values for this property are <code>true</code> to capture <code>System.out</code> output, or <code>false</code> to disable the capture. |
| For more information, see <a href="#sysout-and-syserr">System.out and System.err</a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>log.wrapSysErr</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies whether you want to capture <code>System.err</code> output from your applications to the application trace file. The output is logged by Virgo’s root logger, which captures <code>INFO</code> level and above. |
| Valid values for this property are <code>true</code> to capture <code>System.err</code> output, or <code>false</code> to disable the capture. |
| For more information, see <a href="#sysout-and-syserr">System.out and System.err</a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>log.jul.consoleHandler</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies whether you want to use the <code>ConsoleHandler</code> of Java Util Logging. The default JVM configuration uses the handler to write logs to <code>System.err</code>. |
| Valid values for this property are <code>true</code> to enable <code>ConsoleHandler</code> output, or <code>false</code> to disable it. The default value is <code>false</code>. |
| For more information, see <a href="http://download.oracle.com/javase/6/docs/technotes/guides/logging/overview.html">Java Logging Overview</a>.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a id="configuring-serviceability-logback"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_the_serviceability_xml_file">The serviceability.xml File</h4> |
| <div class="paragraph"> |
| <p>Logging support in Virgo is based on <a href="http://logback.qos.ch/">Logback</a>, which is a successor of the log4j project. The Logback logging framework is faster, more reliable, and easier to use than log4j and certain other logging systems. |
| You configure logging for Virgo using the <code>$SERVER_HOME/configuration/serviceability.xml</code> file. This file is the standard Logback <code>logback.xml</code> or <code>logback-test.xml</code> configuration file, but renamed for Virgo. |
| The following listing shows the default <code>serviceability.xml</code> file in a freshly-installed Virgo; see the text after the listing for a brief overview of the file:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xml" data-lang="xml"><configuration> |
| |
| <jmxConfigurator /> |
| |
| <contextListener class="ch.qos.logback.classic.jul.LevelChangePropagator"/> |
| |
| <appender name="SIFTED_LOG_FILE" class="ch.qos.logback.classic.sift.SiftingAppender"> |
| <discriminator> |
| <Key>applicationName</Key> |
| <DefaultValue>virgo-server</DefaultValue> |
| </discriminator> |
| <sift> |
| <appender name="${applicationName}_LOG_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> |
| <file>serviceability/logs/${applicationName}/log.log</file> |
| <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy"> |
| <FileNamePattern>serviceability/logs/${applicationName}/log_%i.log</FileNamePattern> |
| <MinIndex>1</MinIndex> |
| <MaxIndex>4</MaxIndex> |
| </rollingPolicy> |
| <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy"> |
| <MaxFileSize>10MB</MaxFileSize> |
| </triggeringPolicy> |
| <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder"> |
| <Pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-5level %-28.28thread %-64.64logger{64} %X{medic.eventCode} %msg %ex%n</Pattern> |
| </encoder> |
| </appender> |
| </sift> |
| </appender> |
| |
| <appender name="LOG_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> |
| <file>serviceability/logs/log.log</file> |
| <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy"> |
| <FileNamePattern>serviceability/logs/log_%i.log</FileNamePattern> |
| <MinIndex>1</MinIndex> |
| <MaxIndex>4</MaxIndex> |
| </rollingPolicy> |
| <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy"> |
| <MaxFileSize>10MB</MaxFileSize> |
| </triggeringPolicy> |
| <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder"> |
| <Pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-5level %-28.28thread %-64.64logger{64} %X{medic.eventCode} %msg %ex%n</Pattern> |
| </encoder> |
| </appender> |
| |
| <appender name="EVENT_LOG_STDOUT" class="org.eclipse.virgo.medic.log.logback.ReroutingAwareConsoleAppender"> |
| <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder"> |
| <Pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-28.28thread <%X{medic.eventCode}> %msg %ex%n</Pattern> |
| </encoder> |
| </appender> |
| |
| <appender name="EVENT_LOG_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> |
| <file>serviceability/eventlogs/eventlog.log</file> |
| <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy"> |
| <FileNamePattern>serviceability/eventlogs/eventlog_%i.log</FileNamePattern> |
| <MinIndex>1</MinIndex> |
| <MaxIndex>4</MaxIndex> |
| </rollingPolicy> |
| <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy"> |
| <MaxFileSize>10MB</MaxFileSize> |
| </triggeringPolicy> |
| <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder"> |
| <Pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-28.28thread <%X{medic.eventCode}> %msg %ex%n</Pattern> |
| </encoder> |
| </appender> |
| |
| <logger level="INFO" additivity="false" name="org.eclipse.virgo.medic.eventlog.localized"> |
| <appender-ref ref="EVENT_LOG_STDOUT" /> |
| <appender-ref ref="EVENT_LOG_FILE" /> |
| </logger> |
| |
| <logger level="INFO" additivity="false" name="org.eclipse.virgo.medic.eventlog.default"> |
| <appender-ref ref="SIFTED_LOG_FILE" /> |
| <appender-ref ref="LOG_FILE" /> |
| </logger> |
| |
| <root level="INFO"> |
| <appender-ref ref="SIFTED_LOG_FILE" /> |
| <appender-ref ref="LOG_FILE" /> |
| </root> |
| |
| </configuration></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Logback allows Virgo to use logger, appender, and encoder (layout) objects to log messages according to message type and level and to format these messages and define where they are written. The default <code>serviceability.xml</code> file shown above includes four appenders and three loggers (two user and one root.)</p> |
| </div> |
| <div class="paragraph"> |
| <p>The main information to get from this file is that Virgo writes log messages to four different locations that map to the four appenders:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The <code>jmxConfigurator</code> provides a possibility to configure logback via JMX. For more information see <a href="http://logback.qos.ch/manual/jmxConfig.html">JMX Configurator</a> documentation.</p> |
| </li> |
| <li> |
| <p>The <code>contextListener</code> propagates the changes made to the levels of logback loggers to Java Util Logging (JUL). For more information see <a href="http://logback.qos.ch/manual/configuration.html#LevelChangePropagator">LevelChangePropagator</a> documentation.</p> |
| </li> |
| <li> |
| <p>The <code>SIFTED_LOG_FILE</code> appender logs both global and application-specific messages to the <code>$SERVER_HOME/serviceability/logs/</code><strong><code>applicationName</code></strong><code>/log.log</code> file, where <strong><code>applicationName</code></strong> refers to the name of the application. The log messages for Virgo itself are logged to the <code>$SERVER_HOME/serviceability/logs/virgo-server/log.log</code> file. Because this appender creates different log files for each application, it is called a <strong>sifting appender</strong>. |
| The default behaviour of these trace files is that, once <code>log.log</code> reaches a 10Mb limit, it rolls into a series of files named |
| <code>log_</code><strong>i</strong><code>.log</code> where <strong>i</strong> ranges from 1 to 4, and logging continues in |
| a new <code>log.log</code> file. This is called its <strong>rolling policy</strong>.</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> The `<Pattern>` element defines the format of each log message; messages include the timestamp, the thread that generated the log message, the context-specific event code, and a stack trace of the exception, if any. For example: |
| `[2008-05-15 09:09:46.940] server-dm-2 org.apache.coyote.http11.Http11Protocol I Initializing Coyote HTTP/1.1 on http-48080`</pre> |
| </div> |
| </div> |
| </li> |
| <li> |
| <p>The <code>LOG_FILE</code> appender is very similar to the first one, but it logs <strong>all</strong> log messages to the <code>$SERVER_HOME/serviceability/log/log.log</code> file rather than sifting application-specific messages to their own log file. The rolling policy and message format for this appender is similar to that of the <code>SIFTED_LOG_FILE</code> appender.</p> |
| </li> |
| <li> |
| <p>The <code>EVENT_LOG_STDOUT</code> appender does not log messages to a file, but rather to the console window from which you started Virgo. For example: |
| <code>[2010-10-25 16:20:49.367] Thread-3 <WE0000I> Starting web bundle 'org.eclipse.virgo.apps.admin.web' version '2.1.0.RELEASE' with context path '/admin'.</code></p> |
| </li> |
| <li> |
| <p>The <code>EVENT_LOG_FILE</code> appender logs only important events to the <code>$SERVER_HOME/serviceability/eventlogs/eventlog.log</code> file, and thus the volume of information is much lower than with the first two appenders. The rolling policy for the event log is the same as with the first two appenders, but the format of the messages is similar to that of the <code>EVENT_LOG_STDOUT</code> appender.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The loggers and root logger specify the level of log that is written for each of the referenced appenders.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Typically, the default logging configuration as specified by the <code>serviceability.xml</code> file is adequate for all Virgo environments. However, if you want to customize logging further, you can edit this file as well as the <code>org.eclipse.virgo.medic.properties</code>. See the <a href="http://logback.qos.ch/manual/index.html">logback documentation</a> for detailed information about the architecture and the configuration of Logback.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-provisioning-repository"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_configuring_the_local_provisioning_repository">Configuring the Local Provisioning Repository</h3> |
| <div class="paragraph"> |
| <p>You configure the locations that Virgo includes in its provisioning repository |
| by editing the <code>org.eclipse.virgo.repository.properties</code> file in the <code>$SERVER_HOME/configuration</code> directory.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When you specify a property in the file, use the format <code>repository-name.property=value</code>, where:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>repository-name</code> refers to the name of the local repository.</p> |
| </li> |
| <li> |
| <p><code>property</code> refers to the name of a particular property.</p> |
| </li> |
| <li> |
| <p><code>value</code> refers to the value of the property.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For example, <code>ext.type=external</code> specifies that the <code>type</code> property of the repository |
| with name <code>ext</code> is <code>external</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>chain</code> property specifies the order in which Virgo searches the individual repositories |
| when it looks for dependencies. |
| The <code>chain</code> property uses the names of the individual repositories as specified in the individual repository properties; |
| for example, in the property <code>ext.type=external</code>, the name of the repository is <code>ext</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The default repository configuration for a newly installed Virgo instance is as follows:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">ext.type=external |
| ext.searchPattern=repository/ext/{artifact} |
| |
| usr.type=watched |
| usr.watchDirectory=repository/usr |
| |
| chain=ext,usr</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The default configuration shown above has two searchpaths corresponding to the two default sub-directories of the <code>$SERVER_HOME/repository</code> directory created when you first install Virgo: <code>ext</code> and <code>usr</code>. Virgo searches each of these individual repositories when locating entries for inclusion in the repository.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>chain</code> property shows the order in which Virgo searches the individual repositories: first <code>ext</code> and then <code>usr</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following table lists all the available properties that you can use to configure an individual repository. |
| Individual repositories as well as the repository search chain are configured in the file |
| <code>$SERVER_HOME/configuration/org.eclipse.virgo.repository.properties</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="repository-options-table"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 5. Repository Properties</caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 33%;"> |
| <col style="width: 33%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| <th class="tableblock halign-left valign-top">Default Value</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong><code>repository-name</code></strong><code>.type</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the type of path. You can set this property to one of the following three valid values: |
| * <code>external</code>: Specifies that this path points to a number of directories that satisfy a given search pattern |
| and are local to the current Virgo instance. |
| Use the <code>searchPattern</code> property to specify the directory search pattern. |
| * <code>watched</code>: Specifies that this path points to a single directory, local to the current Virgo instance. |
| Virgo regularly scans watched repositories so it automatically picks up any changes to the artifacts in the directory at runtime. |
| Virgo also scans its local watched repositories when deploying any artifact. |
| Use the <code>watchDirectory</code> property to specify the watched directory |
| and the <code>watchInterval</code> property to specify how often Virgo checks the directory. |
| * <code>remote</code>: Specifies that the path points to a remotely-hosted repository, |
| hosted by a remote instance of Virgo for Apache Tomcat. |
| Use the <code>uri</code> property to specify the full URI of the remote repository. |
| You can also specify the optional <code>indexRefreshInterval</code> property. |
| </p><p class="tableblock">See <a href="#configuring-repository-watched-versus-external">Watched or External Repository?</a> |
| for additional information about when to configure watched or external repositories for your particular environment.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>no default</strong></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong><code>repository-name</code></strong><code>.searchPattern</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the pattern that an external repository uses when deciding which local directories it should search |
| when identifying artifacts. Use this property together with <strong><code>repository-name</code></strong><code>.type=external</code>. |
| See <a href="#configuring-provisioning-repository-search-paths">Search Paths: Additional Information</a> |
| for detailed information about specifying a search pattern.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>no default</strong></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong><code>repository-name</code></strong><code>.watchDirectory</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the single directory of a watched repository. |
| You can specify either an absolute or relative pathname for the directory. |
| If you specify a relative pathname, it is relative to the root of the Virgo installation (<code>$SERVER_HOME</code>). |
| Use this property together with <strong><code>repository-name</code></strong><code>.type=watched</code>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>no default</strong></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong><code>repository-name</code></strong><code>.watchInterval</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the interval in seconds between checks of a watched directory by a watched repository. |
| Use this property together with <strong><code>repository-name</code></strong><code>.type=watched</code>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>5</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong><code>repository-name</code></strong><code>.uri</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the URI of the hosted repository to which a remote repository connects. |
| The value of this property takes the following format: |
| <code>http://</code><strong><code>host</code></strong><code>:</code><strong><code>port</code></strong><code>/org.eclipse.virgo.apps.repository/</code><strong><code>remote-repository-name</code></strong> |
| where: |
| * <strong><code>host</code></strong> refers to the computer on which the remote VTS |
| instance hosts the remote repository. |
| * <strong><code>port</code></strong> refers to a Tomcat listener port of the remote VTS |
| instance which hosts the remote repository. |
| * <strong><code>remote-repository-name</code></strong> refers to the name of the remote repository, |
| as specified in the <code>org.eclipse.virgo.apps.repository.properties</code> file of the remote VTS instance. |
| </p><p class="tableblock">Use this property together with <strong><code>repository-name</code></strong><code>.type=remote</code>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>no default</strong></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong><code>repository-name</code></strong><code>.indexRefreshInterval</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the interval in seconds between checks by a remote repository that |
| its local copy of the hosted repository index is up-to-date |
| (a remote repository acts as a proxy for a hosted repository and thus it holds a local copy of the hosted repository’s index). |
| </p><p class="tableblock"> Use this property together with <strong><code>repository-name</code></strong><code>.type=remote</code>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>5</code></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a id="configuring-repository-watched-versus-external"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_should_i_configure_a_watched_or_external_repository">Should I Configure a Watched or External Repository?</h4> |
| <div class="paragraph"> |
| <p>The main difference between a watched and an external repository is that Virgo regularly scans watched directories |
| and automatically picks up any changed artifacts, |
| while Virgo scans external directories only at startup, and then only if there is no cached index available. |
| This means that Virgo always performs a scan of an external repository when you start the server |
| with the <code>-clean</code> (as this deletes the index) and only scans during a normal startup if the index isn’t there because, |
| for example, this is the first time you start the server.</p> |
| </div> |
| <div class="paragraph"> |
| <p>There is a performance cost associated with using a watched repository due to Virgo using resources |
| to scan the directory at the configured interval. |
| The cost is small if the watched repository contains just a few artifacts; however, |
| the performance cost increases as the number of artifacts increases. |
| Note that Virgo re-scans its local watched repositories when deploying any artifact, so the scanning interval |
| can be configured to be relatively long.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> For this reason, we recommend that you put most of your dependencies in external repositories, |
| even when in development mode. |
| If you make any changes to the artifacts in the external repositories, |
| remember to restart {virgo-name} with the `-clean` option so that the server picks up any changes. |
| Use watched directories for artifacts that you are prototyping, actively updating, or when adding new dependencies |
| so that {virgo-name} quickly and easily picks them up. |
| To increase performance even during development, however, you can use an external repository for most of your dependencies, |
| in particular the ones that are fairly static.</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In production environments, where dependencies should not change, |
| we recommend that you use <strong>only</strong> external repositories.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-provisioning-repository-search-paths"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_search_paths_additional_information">Search Paths: Additional Information</h4> |
| <div class="paragraph"> |
| <p>The <strong><code>repository-name</code></strong><code>.searchPattern</code> and |
| <strong><code>repository-name</code></strong><code>.watchDirectory</code> properties specify search paths |
| for external and watched repositories, respectively, |
| that define a physical location that Virgo searches when looking for a library or bundle dependency. |
| If a search path is relative, its location is relative to the root of the installation, |
| in other words, the <code>$SERVER_HOME</code> directory.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-provisioning-repository-search-paths-wildcards"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_using_wildcards">Using Wildcards</h4> |
| <div class="paragraph"> |
| <p>Search paths specified with the <strong><code>repository-name</code></strong><code>.searchPattern</code> property |
| provide support for wildcards. |
| In the entries above, the path segments surrounded by curly braces, |
| for example <code>{bundle}</code> and <code>{library}</code>, |
| are wildcards entries for a directory with any name. |
| Allowing wildcards to be named in this way is intended to improve the readability of search path configuration.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In addition to supporting the above-described form of wildcards, Virgo also supports Ant-style paths, |
| that is <code>*</code> and <code>**</code> can be used to represent any directory and |
| any series of directories, respectively. |
| For example, <code>repository/usr/{bundle}</code> and <code>repository/usr/*</code> |
| are equivalent.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A common usage of the <code>**</code> wildcard is to allow dependencies stored in a directory structure of varying depth, |
| such as a local Maven repository, to be provisioned by the Virgo.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-provisioning-repository-using-system-properties"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_using_system_properties">Using System Properties</h4> |
| <div class="paragraph"> |
| <p>You can use system properties when specifying the values of the <strong><code>repository-name</code></strong><code>.searchPattern</code>, |
| <strong><code>repository-name</code></strong><code>.watchDirectory</code>, |
| <strong><code>repository-name</code></strong><code>.watchInterval</code>, |
| <strong><code>repository-name</code></strong><code>.uri</code>, |
| and <strong><code>repository-name</code></strong><code>.indexRefreshInterval</code> |
| properties. |
| You reference system properties as <code>${system.property.name}</code>; |
| for example, a search path of <code>${user.home}/repository/bundles</code> references the |
| <code>repository/bundles</code> directory in the user’s home directory.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-provisioning-repository-examples"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_example_repository_configurations">Example Repository Configurations</h4> |
| <div class="paragraph"> |
| <p>The following examples provide sample configuration that could be used for some common use cases.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-provisioning-repository-examples-ivy"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_add_an_ivy_cache_repository">Add an Ivy cache repository</h4> |
| <div class="paragraph"> |
| <p>The following example shows how to add an external repository whose location is actually an Ivy cache. |
| <strong>Note that Ivy repositories can contain bundles which will conflict with the normal operation of Virgo, so care should |
| be exercised when adding such an external repository.</strong></p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">ext.type=external |
| ext.searchPattern=repository/ext/{artifact} |
| |
| usr.type=watched |
| usr.watchDirectory=repository/usr |
| |
| ivy-repo.type=external |
| ivy-repo.searchPattern=${user.home}/.ivy2/cache/{org}/{name}/{version}/{bundle}.jar |
| |
| chain=ext,usr,ivy-repo</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-provisioning-repository-examples-maven"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_add_a_maven_local_repository">Add a Maven local repository</h4> |
| <div class="paragraph"> |
| <p>The following example shows how to add an external repository whose location is actually a Maven repository. |
| <strong>Note that Maven repositories can contain bundles which will conflict with the normal operation of Virgo, so care should |
| be exercised when adding such an external repository.</strong></p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">ext.type=external |
| ext.searchPattern=repository/ext/{artifact} |
| |
| usr.type=watched |
| usr.watchDirectory=repository/usr |
| |
| maven-repo.type=external |
| maven-repo.searchPattern=${user.home}/.m2/repository/**/{bundle}.jar |
| |
| chain=ext,usr,maven-repo</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-repository-examples-remote-watched"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_add_remote_and_watched_repositories">Add remote and watched repositories</h4> |
| <div class="paragraph"> |
| <p>The following example shows the default <code>org.eclipse.virgo.repository.properties</code> file |
| from a freshly-installed Virgo instance, but then updated to include new remote and watched repositories. |
| Both of these repositories are part of the repository chain.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The remote repository is called <code>remote-repo</code>. |
| The URI of the hosted repository from which <code>remote-repo</code> gets its artifacts is |
| <code><a href="http://my-host:8080/org.eclipse.virgo.apps.repository/my-hosted-repo" class="bare">http://my-host:8080/org.eclipse.virgo.apps.repository/my-hosted-repo</a></code>; |
| this means that there is a VTS instance running on host <code>my-host</code> |
| whose Tomcat server listens at the default port, <code>8080</code>, |
| and this server instance hosts a repository called <code>my-hosted-repo</code>, |
| configured in the <code>org.eclipse.virgo.apps.repository.properties</code> file of the remote server instance. |
| The remote repository checks for changes in the hosted repository every 30 seconds.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The watched repository is called <code>watched-repo</code> and the directory that holds the artifacts |
| is <code>repository/watched</code>, |
| relative to the installation directory of the VTS instance. |
| The server checks for changes in this watched repository every 5 seconds.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">ext.type=external |
| ext.searchPattern=repository/ext/{artifact} |
| |
| usr.type=watched |
| usr.watchDirectory=repository/usr |
| |
| remote-repo.type=remote |
| remote-repo.uri=http://my-host:8080/org.eclipse.virgo.apps.repository/my-hosted-repo |
| remote-repo.indexRefreshInterval=30 |
| |
| watched-repo.type=watched |
| watched-repo.watchedDirectory=repository/watched |
| watched-repo.watchedInterval=5 |
| |
| chain=ext,usr,remote-repo,watched-repo</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-hosted-repo"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_configuring_a_hosted_repository">Configuring a Hosted Repository</h3> |
| <div class="paragraph"> |
| <p>You configure a VTS instance to host a repository |
| by editing the <code>$SERVER_HOME/configuration/org.eclipse.virgo.apps.repository.properties</code> file; |
| remote clients can then access the artifacts in this hosted repository and use them locally.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When you specify a property in the file, use the format <code>repository-name.property=value</code>, where:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>repository-name</code> refers to the name of the hosted repository.</p> |
| </li> |
| <li> |
| <p><code>property</code> refers to the name of a particular property.</p> |
| </li> |
| <li> |
| <p><code>value</code> refers to the value of the property.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For example, <code>my-hosted-repo.type=external</code> specifies that the <code>type</code> property |
| of the <code>my-hosted-repo</code> repository is <code>external</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following table lists the properties that you can include in the <code>org.eclipse.virgo.apps.repository.properties</code> file.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="hosted-repository-properties-table"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 6. Hosted Repository Properties</caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong><code>repository-name</code></strong><code>.type</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the type of path of the hosted repository. |
| All paths are local to the current VTS instance. |
| You can set this property to one of the following valid values: |
| * <code>external</code>: Specifies that this path points to a number of directories that satisfy a given search pattern. |
| Use the <code>searchPattern</code> property to specify the directory search pattern. |
| * <code>watched</code>: Specifies that this path points to a single directory. |
| Virgo regularly scans watched repositories so it automatically picks up any changes to the artifacts in the directory at runtime. |
| Use the <code>watchDirectory</code> property to specify the actual watched directory and the <code>watchInterval</code> property |
| to specify how often VTS checks the directory. |
| </p><p class="tableblock">See <a href="#configuring-repository-watched-versus-external">Watched or External Repository?</a> |
| for additional information about when to configure watched or external repositories for your particular environment.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong><code>repository-name</code></strong><code>.searchPattern</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the pattern that an external hosted repository uses when deciding which |
| local directories it should search when identifying artifacts. |
| Use this property when <code>repository-name.type=external</code>. |
| See <a href="#configuring-provisioning-repository-search-paths">Search Paths: Additional Information</a> |
| for detailed information about specifying a search pattern.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong><code>repository-name</code></strong><code>.watchDirectory</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the single directory of a watched hosted repository. |
| You can specify either an absolute or relative pathname for the directory. |
| If you specify a relative pathname, it is relative to the root of the VTS installation (<code>$SERVER_HOME</code>). |
| Use this property when <code>repository-name.type=watched</code>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong><code>repository-name</code></strong><code>.watchInterval</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the interval in seconds between checks of a watched directory by a watched hosted repository. |
| This property is optional. Use this property when <code>repository-name.type=watched</code>.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The following sample shows a <code>org.eclipse.virgo.apps.repository.properties</code> file with a single external repository |
| called <code>my-hosted-repo</code> with search pattern <code>$SERVER_HOME/repository/hosted/*</code>.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>my-hosted-repo.type=external |
| my-hosted-repo.searchPattern=repository/hosted/*</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>See <a href="#configuring-repository-examples-remote-watched">Example of watched and remote repositories</a> |
| for details on how a local repository can remotely access the artifacts in this hosted repository.</p> |
| </div> |
| <div class="paragraph"> |
| <p>anchor:configuring-kernel</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_configuring_the_kernel_and_user_region">Configuring the Kernel and User Region</h3> |
| <div class="paragraph"> |
| <p>This section provides information about configuring the Virgo kernel and the User Region.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-kernel-properties"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_configuring_the_kernel">Configuring the Kernel</h4> |
| <div class="paragraph"> |
| <p>To change any of the kernel properties, provide the new value to the startup script. The following table describes all properties.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-kernel-table"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 7. Kernel Configuration Properties</caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 33%;"> |
| <col style="width: 33%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property (prefixed by <code>org.eclipse.virgo</code>)</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| <th class="tableblock halign-left valign-top">Default Value</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.kernel.home</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the location of the Virgo Kernel.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>$SERVER_HOME</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.kernel.config</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the location of the Virgo Kernel and User Region <a href="#configuring-kernel-files">configuration files</a>. |
| The location of the configuration files can also be specified using |
| <a href="#starting-stopping-configuration-directory">[starting-stopping-configuration-directory]</a> <code>-configDir</code> startup parameter].</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>$SERVER_HOME/configuration</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.kernel.domain</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the <a href="http://download.oracle.com/javase/6/docs/api/javax/management/ObjectName.html">JMX domain</a> that should be |
| used by the Virgo Kernel.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.virgo.kernel</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.kernel.startup.wait.limit</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the amount of time, in seconds, after which various operations time out out while trying to start the kernel. |
| See xreF:configuring-framework-properties[Configuring OSGi Framework Properties] for the recommended way |
| to configure this parameter.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>180</code></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a id="configuring-kernel-files"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_configuration_files">Configuration Files</h4> |
| <div class="paragraph"> |
| <p>The configuration of the Virgo Kernel and User Region by default is located in the <code>$SERVER_HOME/configuration</code> directory:</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-kernel-files-table"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 8. Kernel Configuration Files</caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property File</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.virgo.kernel.properties</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Configures <a href="#configuring-deployment">deployment</a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.virgo.kernel.userregion.properties</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Configures the <a href="#configuring-user-region">User Region</a> of Virgo.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.virgo.kernel.users.properties</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Configures the <a href="#configuring-authentication">users that are allowed to access</a> the Admin Console, and roles to which they map.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.virgo.kernel.jmxremote.access.properties</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Configures the <a href="#configuring-authentication">permissions for users</a> that are allowed to access the Admin Console.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.virgo.kernel.authentication.config</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Configures the <a href="#configuring-authentication">Java Authentication and Authorization Service (JAAS)</a> for the Tomcat server users.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>osgi.console.ssh.properties</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Configures the kernel SSH console. See <a href="#admin-shell-enable">[admin-shell-enable]</a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>osgi.console.telnet.properties</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Configures the kernel telnet console. See <a href="#admin-shell-enable">[admin-shell-enable]</a>.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a id="configuring-deployment"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_configuring_deployment">Configuring Deployment</h4> |
| <div class="paragraph"> |
| <p>You can configure various properties of deployment: the pickup directory into which you copy applications for hot-deployment, the deployment timeout, |
| and whether or not bundles are unpacked during deployment.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To change any of these properties, edit the <code>deployer.XXX</code> properties of the <code>$SERVER_HOME/configuration/org.eclipse.virgo.kernel.properties</code> file. The following table describes these properties.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-deployment-table"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 9. Deployment Configuration Properties</caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 33%;"> |
| <col style="width: 33%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| <th class="tableblock halign-left valign-top">Default Value</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>deployer.pickupDirectory</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the absolute or relative path to the pickup directory to which you copy applications for hot-deployment. |
| Relative paths are relative to <code>$SERVER_HOME</code>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>./pickup</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>deployer.timeout</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the amount of time, in seconds, after which Virgo times out while trying to deploy an artifact. |
| If you want to disable deployment timeout, specify <code>0</code>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>300</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>deployer.scanIntervalMillis</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the scan interval, in milliseconds, used to survey the pickup directory.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>1000</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>deployer.unpackBundles</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Determines whether or not bundles (with file extension <code>.jar</code> or <code>.war</code>) are unpacked |
| during deployment. The value must be either <code>true</code> or <code>false</code>. |
| </p><p class="tableblock"> If you want to deploy bundles packed, specify <code>false</code>. |
| This option can help alleviate a known issue with <a href="#long-work-paths">long work directory paths under Windows</a>. |
| </p><p class="tableblock"> Note that web applications may behave differently depending on whether they are deployed packed or unpacked. |
| Certain servlet API methods return <code>null</code> when a web application is deployed packed.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>true</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>WABHeaders</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This kernel property is only relevant for Virgo Nano Full. For the corresponding property in Virgo for Apache Tomcat, see <a href="#configuring-web">Configuring the Web Integration Layer</a>. |
| </p><p class="tableblock"> Specifies how Web Application Bundle manifest headers are processed. |
| See "Web Application Manifest Processing" in the |
| <a href="../../virgo-programmer-guide/html/index.html">Programmer Guide</a> for details. |
| </p><p class="tableblock"> A value of <code>strict</code> causes Virgo Nano Full to interpret certain headers in strict compliance with |
| the OSGi Web Applications specification if they are not specified. |
| </p><p class="tableblock"> A value of <code>defaulted</code> causes Virgo Nano Full to set certain headers to default values if they are not specified. |
| <strong>This value is provided as a migration aid and may not be supported in future releases.</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>strict</code></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The following listing displays the default configuration distributed with Virgo; only relevant sections of the <code>org.eclipse.virgo.kernel.properties</code> file are shown.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>deployer.timeout=300 |
| deployer.pickupDirectory=pickup |
| deployer.scanIntervalMillis=1000</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>So the default deployment timeout is 300 seconds, the default pickup directory is <code>$SERVER_HOME/pickup</code> and the default scan interval is <code>1000</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-user-region"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_configuring_the_user_region">Configuring the User Region</h4> |
| <div class="paragraph"> |
| <p>The User Region is the subsystem of Virgo that |
| supports deployed applications, both your own user applications and |
| those of the server itself, such as the Admin Console. The User Region |
| is deliberately isolated from the kernel, which protects the kernel from interference by applications.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You configure the User Region by updating properties in the |
| <code>$SERVER_HOME/configuration/org.eclipse.virgo.kernel.userregion.properties</code> |
| file; these properties are described in the following table.</p> |
| </div> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Warning</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>We strongly recommend that you update only the |
| <code>initialArtifacts</code> |
| property; updating other properties could cause |
| Virgo to fail. These properties are documented for your |
| information.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-user-region-table"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 10. User Region Configuration Properties</caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>baseBundles</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the hard-coded list of bundles that Virgo installs directly into the User Region. |
| Virgo does not perform any automatic dependency satisfaction for these bundles; in other words, you only get the bundles |
| in the list and nothing more.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>bundleImports</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the bundles in the kernel that Virgo imports into the User Region so that they are visible to bundles in the User Region. |
| This property supports an optional <code>bundle-version</code> attribute which specifies a version range. |
| By default only the system bundle is imported. |
| </p><p class="tableblock"> Note that packages exported by these bundles are <strong>not</strong> automatically made available in the User Region: these must be specified using the |
| <code>packageImports</code> property.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>packageImports</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the packages in the kernel that Virgo imports into the User Region so that they are in turn available to be |
| imported by bundles in the User Region. |
| This property supports a <code>.<strong></code> wildcard which is expanded based on the packages available in the kernel |
| when the User Region is created. |
| For example, <code>org.eclipse.virgo.util.</strong></code> will import all packages that start with |
| <code>org.eclipse.virgo.util.</code> (but <strong>not</strong> the package <code>org.eclipse.virgo.util</code> |
| which would need to be specified separately to be imported). |
| </p><p class="tableblock"> The property also supports matching attributes such as <code>version</code>, <code>bundle-symbolic-name</code>, |
| <code>bundle-version</code>, and user-defined attributes. This can be used to import all the packages of a bundle imported using the |
| <code>bundleImports</code> property. |
| For example the following imports all the packages of the system bundle: |
| </p><p class="tableblock">…​. |
| packageImports=*;bundle-symbolic-name="org.eclipse.osgi",\ |
| …​ |
| …​. |
| Note that if a package is specified more than once in <code>packageImports</code>, the last occurrence is used and the earlier |
| occurrences are ignored. |
| For this reason, it is recommended that imports specifying matching attributes are placed earlier in the list than other imports so that |
| if an import is specified with and without matching attributes, the form without the matching attributes is used.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>serviceImports</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the services in the kernel that are imported into the User Region so they are available to bundles in the User Region.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>serviceExports</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the services in the User Region that are exported to the kernel so they are available to bundles in the kernel.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>initialArtifacts</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the artifacts that Virgo deploys into the User Region when the server starts. |
| Virgo performs dependency satisfaction when it deploys these artifacts. |
| This means that you only need to list the top-level artifacts that you care about; Virgo automatically installs, |
| from the repository, any other artifacts upon which they depend. |
| </p><p class="tableblock"> The artifacts are specified as a comma separated list of URI strings of the form: |
| </p><p class="tableblock">…​. |
| repository:type/name[/version |
| …​. |
| </p><p class="tableblock"> where <code>type</code> is the artifact type (e.g. "plan", "par", "bundle", |
| "configuration"), <code>name</code> is the (symbolic) name of the artifact, and, optionally, |
| <code>version</code> is the version of the artifact. |
| If <code>version</code> is omitted and there is at least one artifact in the repository with the given type and name, then the |
| artifact with the highest version is selected. |
| So, for example, the following entries are valid: |
| …​. |
| initialArtifacts=…​,\ |
| repository:plan/APlan,\ |
| repository:bundle/ABundle/1.0 |
| …​.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a id="configuring-user-region-consoles"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_configurating_user_region_consoles">Configurating User Region Consoles</h4> |
| <div class="paragraph"> |
| <p>The configuration of the User Region consoles is located by default in the <code>$SERVER_HOME/repository/ext</code> directory:</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-user-region-consoles-table"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 11. User Region Console Configuration Files</caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>osgi.console.ssh.properties</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Configures the User Region SSH console. See <a href="#admin-shell-enable">[admin-shell-enable]</a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>osgi.console.telnet.properties</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Configures the User Region telnet console. See <a href="#admin-shell-enable">[admin-shell-enable]</a>.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a id="configuring-authentication"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_configuring_authentication">Configuring Authentication</h3> |
| <div class="paragraph"> |
| <p>Virgo uses the <a href="http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html">Java Authentication and Authorization Service (JAAS)</a> |
| framework to authenticate the administration user that connects to Web |
| Servers using the Admin Console. This section describes |
| how the authentication mechanism is configured by default, and the |
| files that you need to update if you want to change the administration |
| user, change their password, and so on.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>$SERVER_HOME/configuration/org.eclipse.virgo.kernel.authentication.config</code> file configures the underlying authentication technology for Virgo. The short file consists of the following entries:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>virgo-kernel { |
| org.eclipse.virgo.kernel.authentication.KernelLoginModule REQUIRED; |
| }; |
| equinox_console { |
| org.eclipse.virgo.kernel.authentication.KernelLoginModule REQUIRED; |
| };</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The entry named <code>virgo-kernel</code> corresponds to the <code><Realm></code> element in the <code>$SERVER_HOME/configuration/tomcat-server.xml</code> file that configures the JAAS authentication mechanism for the <code>Catalina</code> service of the <a href="#configuring-tomcat">Tomcat servlet container</a>. The <code>virgo-kernel</code> entry specifies that the JAAS LoginModule that Virgo uses to authenticate users is <code>org.eclipse.virgo.kernel.authentication.KernelLoginModule</code> and that this <code>KernelLoginModule</code> is required to "succeed" in order for authentication to be considered successful. The <code>KernelLoginModule</code> succeeds only if the name and password supplied by the user are the ones it expects. The default administration username/password pair for VTS is <code>admin/springsource</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The entry named <code>equinox_console</code> controls ssh authentication for the Virgo shell. It also uses the <code>KernelLoginModule</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You configure the administration user in the <code>org.eclipse.virgo.kernel.users.properties</code> file. The default file for a freshly installed Virgo is as follows:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>################## |
| # User definitions |
| ################## |
| user.admin=springsource |
| |
| ################## |
| # Role definitions |
| ################## |
| role.admin=admin</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The administration user that connect to the Admin Console must have the |
| <code>admin</code> |
| role. The preceding file shows how, by default, the |
| <code>admin</code> |
| role is assigned the |
| <code>admin</code> |
| user with password |
| <code>springsource</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If you want to change the administration user, update the <code>org.eclipse.virgo.kernel.users.properties</code> file. For example, if you want the <code>juliet</code> user, with password <code>supersecret</code>, to be the new adminstration user, update the file as shown:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>################## |
| # User definitions |
| ################## |
| user.juliet=supersecret |
| |
| ################## |
| # Role definitions |
| ################## |
| role.admin=juliet</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Be sure to restart Virgo after you make this change for it to take effect.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The final file involved in Virgo authentication is <code>$SERVER_HOME/configuration/org.eclipse.virgo.kernel.jmxremote.access.properties</code>. This file specifies the JMX access privileges that the administration user has; by default they are read and write, as shown in the following listing:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>admin=readwrite</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The only other value you can enter is |
| <code>readonly</code>, which means that the adminstration user would only be able to <strong>view</strong> |
| information using the Admin Console.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-tomcat"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_configuring_the_embedded_tomcat_servlet_container">Configuring the Embedded Tomcat Servlet Container</h3> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>Virgo Nano uses the default Gemini Web configuration. The details described below may still apply.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Virgo |
| embeds an OSGi-enhanced version of the <a href="http://tomcat.apache.org">Tomcat Servlet Container</a> |
| in order to provide support for deploying Java EE WARs and OSGi <strong>Web Application Bundles</strong>. |
| You configure the embedded Servlet container using the standard Apache Tomcat configuration. The main difference is that the configuration file is called <filename>tomcat-server.xml</filename> rather than <code>server.xml</code>. As with the other Virgo configuration files, the <code>tomcat-server.xml</code> file is located in the <code>$SERVER_HOME/configuration</code> directory. |
| Another difference is that not all standard Apache Tomcat configuration is supported in Virgo for Apache Tomcat: the restrictions are described in the |
| remainder of this section.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Here’s an extract of the default configuration distributed with the VTS.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xml" data-lang="xml">--- |
| <?xml version='1.0' encoding='utf-8'?> |
| <Server port="8005" shutdown="SHUTDOWN"> |
| <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" /> |
| <Listener className="org.apache.catalina.core.JasperListener" /> |
| <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" /> |
| <Listener className="org.eclipse.virgo.web.tomcat.ServerLifecycleLoggingListener"/> |
| <Service name="Catalina"> |
| <Connector port="8080" protocol="HTTP/1.1" |
| connectionTimeout="20000" |
| redirectPort="8443" /> |
| <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" |
| maxThreads="150" scheme="https" secure="true" |
| clientAuth="false" sslProtocol="TLS" |
| keystoreFile="configuration/keystore" |
| keystorePass="changeit"/> |
| <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" /> |
| <Engine name="Catalina" defaultHost="localhost"> |
| <Realm className="org.apache.catalina.realm.JAASRealm" appName="virgo-kernel" |
| userClassNames="org.eclipse.virgo.kernel.authentication.User" |
| roleClassNames="org.eclipse.virgo.kernel.authentication.Role"/> |
| <Host name="localhost" appBase="webapps" |
| unpackWARs="false" autoDeploy="false" |
| deployOnStartup="false" createDirs="false"> |
| <Valve className="org.apache.catalina.valves.AccessLogValve" directory="serviceability/logs/access" |
| prefix="localhost_access_log." suffix=".txt" pattern="common" resolveHosts="false"/> |
| <Valve className="org.eclipse.virgo.web.tomcat.ApplicationNameTrackingValve"/> |
| </Host> |
| </Engine> |
| </Service> |
| </Server> |
| ----</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="overview-tomcat-servlet-container"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_description_of_the_default_apache_tomcat_configuration">Description of the Default Apache Tomcat Configuration</h4> |
| <div class="paragraph"> |
| <p>The following bullets describe the main elements and attributes in the default <code>tomcat-server.xml</code> file; for details about updating this file to further configure the embedded Apache Tomcat server, see the <a href="http://tomcat.apache.org/tomcat-7.0-doc/config/index.html">Apache Tomcat Configuration Reference</a>.</p> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Tip</div> |
| </td> |
| <td class="content"> |
| <div class="title">Relative paths</div> |
| <div class="paragraph"> |
| <p>If the configured path to a directory or file does not represent an absolute path, Virgo typically interprets it as a path relative to the <filename>$SERVER_HOME</filename> directory.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The root element of the <code>tomcat-server.xml</code> file is <code><Server></code>. The attributes of this element represent the characteristics of the entire embedded Tomcat servlet container. The <code>shutdown</code> attribute specifies the command string that the shutdown port number receives via a TCP/IP connection in order to shut down the servlet container. The <code>port</code> attribute specifies the TCP/IP port number that listens for a shutdown message.</p> |
| </li> |
| <li> |
| <p>The <code><Listener></code> XML elements specify the list of lifecycle listeners that monitor and manage the embedded Tomcat servlet container. Each listener class is a Java Management Extensions (JMX) MBean that listens to a specific component of the servlet container and has been programmed to do something at certain lifecycle events of the component, such as before starting up, after stopping, and so on. |
| The first four <code><Listener></code> elements configure standard Tomcat lifecycle listeners. The listener implemented by the <code>org.eclipse.virgo.web.tomcat.ServerLifecycleLoggingListener</code> class is specific to Virgo for Apache Tomcat and manages server lifecycle logging.</p> |
| </li> |
| <li> |
| <p>The <code><Service></code> XML element groups together one or more connectors and a single engine. Connectors define a transport mechanism, such as HTTP, that clients use to to send and receive messages to and from the associated service. There are many transports that a client can use, which is why a <code><Service></code> element can have many <code><Connector></code> elements. The engine then defines how these requests and responses that the connector receives and sends are in turn handled by the servlet container; you can define only a single <code><Engine></code> element for any given <code><Service></code> element. |
| The sample <code>tomcat-server.xml</code> file above includes three <code><Connector></code> elements: one for the HTTP transport, one for the HTTPS transport, and one for the AJP transport. The file also includes a single <code><Engine></code> element, as required.</p> |
| </li> |
| <li> |
| <p>The first connector listens for HTTP requests at the <code>8080</code> TCP/IP port. The connector, after accepting a connection from a client, waits for a maximum of 20000 milliseconds for a request URI; if it does not receive one from the client by then, the connector times out. If this connector receives a request from the client that requires the SSL transport, the servlet container automatically redirects the request to port <code>8443</code>.</p> |
| </li> |
| <li> |
| <p>The second connector is for HTTPS requests. The TCP/IP port that users specify as the secure connection port is <code>8443</code>. Be sure that you set the value of the <code>redirectPort</code> attribute of your non-SSL connectors to this value to ensure that users that require a secure connection are redirected to the secure port, even if they initially start at the non-secure port. The <code>SSLEnabled</code> attribute specifies that SSL is enabled for this connector. The <code>secure</code> attribute ensures that a call to <code>request.isSecure()</code> from the connecting client always returns <code>true</code>. The <code>scheme</code> attribute ensures that a call to <code>request.getScheme()</code> from the connecting client always returns <code>https</code> when clients use this connector. |
| The <code>maxThreads</code> attribute specifies that the servlet container creates a maximum of 150 request processing threads, |
| which determines the maximum number of simultaneous requests that can be handled. |
| The <code>clientAuth</code> attribute specifies that the servlet container does not require a certificate chain |
| unless the client requests a resource protected by a security constraint that uses CLIENT-CERT authentication. |
| The <code>keystoreFile</code> attribute specifies the name of the file that contains the servlet container’s |
| private key and public certificate used in the SSL handshake, encryption, and decryption. |
| You use an alias and password to access this information. |
| In the example, this file is <code>$SERVER_HOME/configuration/keystore</code>. |
| The <code>keystorePass</code> attributes specify the password used to access the keystore.</p> |
| </li> |
| <li> |
| <p>The third AJP Connector element represents a Connector component that communicates with a web connector via the AJP protocol.</p> |
| </li> |
| <li> |
| <p>The engine has a logical name of <code>Catalina</code>; |
| this is the name used in all log and error messages so you can easily identify problems. |
| The value of the <code>defaultHost</code> attribute refers to the name of a <code><Host></code> |
| child element of <code><Engine></code>; |
| this host processes requests directed to host names on this servlet container.</p> |
| </li> |
| <li> |
| <p>The <code><Realm></code> child element of <code><Engine></code> represents a database of |
| users, passwords, and mapped roles used for authentication in this service. Virgo Web Server uses an implementation of the Tomcat 6 Realm interface that authenticates users through the Java Authentication and Authorization Service (JAAS) framework which is provided as part of the standard J2SE API. |
| With the JAASRealm, you can combine practically any conceivable security realm with Tomcat’s container managed authentication. For details, see <a href="http://tomcat.apache.org/tomcat-7.0-doc/realm-howto.html">Realm Configuration</a>.</p> |
| </li> |
| <li> |
| <p>The <code><Host></code> child element represents a virtual host, |
| which is an association of a network name for a server (such as <code>www.mycompany.com</code>) with the particular |
| server on which Catalina is running. |
| The servlet container unpacks Web applications into a directory hierarchy if they are deployed as WAR files. |
| Note that multiple <code><Host></code> elements are not supported in Virgo for Apache Tomcat.</p> |
| </li> |
| <li> |
| <p>Finally, the <code>org.apache.catalina.valves.AccessLogValve</code> valve creates log files |
| in the same format as those created by standard web servers. |
| The servlet container creates the log files in the <code>$SERVER_HOME/serviceability/logs/access</code> directory. |
| The log files are prefixed with the string <code>localhost_access_log.</code>, have a suffix of <code>.txt</code>, |
| use a standard format for identifying what should be logged, and do not include DNS lookups of the IP address of the remote host.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-tomcat-connectors"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_connector_configuration">Connector Configuration</h4> |
| <div class="paragraph"> |
| <p>The Virgo for Apache Tomcat supports the configuration of any connector supported by Apache Tomcat. |
| See the default configuration above for syntax examples, and for further details of the configuration properties |
| supported for various <code><Connector></code> implementations, |
| consult the official <a href="http://tomcat.apache.org/tomcat-7.0-doc/config/http.html">Tomcat HTTP Connector</a> documentation.</p> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Tip</div> |
| </td> |
| <td class="content"> |
| <div class="title">Configuring SSL for Tomcat</div> |
| <div class="paragraph"> |
| <p>The Virgo for Apache Tomcat distribution includes a preconfigured <code>$SERVER_HOME/configuration/keystore</code> |
| file that contains a single self-signed SSL Certificate. |
| The password for this <filename>keystore</filename> file is <code>changeit</code>. |
| This <filename>keystore</filename> file is intended for testing purposes only. |
| For detailed instructions on how to configure Tomcat’s SSL support, |
| consult the official <a href="http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html">Tomcat SSL Configuration HOW-TO</a>.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-tomcat-clustering"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_cluster_configuration">Cluster Configuration</h4> |
| <div class="paragraph"> |
| <p>Virgo for Apache Tomcat supports standard Apache Tomcat cluster configuration. |
| By default, clustering of the embedded servlet container is disabled, |
| and the default configuration does not include any clustering information. |
| See <a href="http://tomcat.apache.org/tomcat-7.0-doc/cluster-howto.html">Tomcat Clustering/Session Replication HOW-TO</a> |
| for detailed information about enabling and configuring clustering.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-default-web-xml"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_default_web_xml_configuration">Default web.xml Configuration</h4> |
| <div class="paragraph"> |
| <p>Java Servlet specification enables web applications to provide deployment descriptor (<code>web.xml</code>) in the <code>WEB-INF</code> directory. |
| Apache Tomcat introduces a default <code>web.xml</code> which is similar to web application’s <code>web.xml</code>, but provides configurations that are applied to all web applications. |
| When deploying a web application, Apache Tomcat uses the default <code>web.xml</code> file as a base configuration. |
| If the web application provides its own configurations via <code>web.xml</code> (the one located in the web application’s <code>WEB-INF</code>) or annotations, they overwrite the default ones. |
| In Virgo for Apache Tomcat you can also provide default configurations for all web applications. |
| If you want to change/extend the default configurations, you can provide the default <code>web.xml</code> file located in the <code>VTS_HOME/configuration</code> directory.</p> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Tip</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>Be careful when changing/extending the default <code>web.xml</code> as this will affect all web applications.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Here’s an extract of the default configuration distributed with the VTS.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xml" data-lang="xml"><?xml version="1.0" encoding="ISO-8859-1"?> |
| <web-app xmlns="http://java.sun.com/xml/ns/javaee" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" |
| version="3.0"> |
| |
| <servlet> |
| <servlet-name>default</servlet-name> |
| <servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class> |
| <init-param> |
| <param-name>debug</param-name> |
| <param-value>0</param-value> |
| </init-param> |
| <init-param> |
| <param-name>listings</param-name> |
| <param-value>false</param-value> |
| </init-param> |
| <load-on-startup>1</load-on-startup> |
| </servlet> |
| |
| <servlet> |
| <servlet-name>jsp</servlet-name> |
| <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class> |
| <init-param> |
| <param-name>fork</param-name> |
| <param-value>false</param-value> |
| </init-param> |
| <init-param> |
| <param-name>xpoweredBy</param-name> |
| <param-value>false</param-value> |
| </init-param> |
| <load-on-startup>3</load-on-startup> |
| </servlet> |
| |
| <servlet-mapping> |
| <servlet-name>default</servlet-name> |
| <url-pattern>/</url-pattern> |
| </servlet-mapping> |
| |
| <servlet-mapping> |
| <servlet-name>jsp</servlet-name> |
| <url-pattern>*.jsp</url-pattern> |
| </servlet-mapping> |
| |
| <servlet-mapping> |
| <servlet-name>jsp</servlet-name> |
| <url-pattern>*.jspx</url-pattern> |
| </servlet-mapping> |
| |
| <session-config> |
| <session-timeout>30</session-timeout> |
| </session-config> |
| |
| <mime-mapping> |
| <extension>abs</extension> |
| <mime-type>audio/x-mpeg</mime-type> |
| </mime-mapping> |
| ...... |
| <mime-mapping> |
| <extension>ppt</extension> |
| <mime-type>application/vnd.ms-powerpoint</mime-type> |
| </mime-mapping> |
| |
| <welcome-file-list> |
| <welcome-file>index.html</welcome-file> |
| <welcome-file>index.htm</welcome-file> |
| <welcome-file>index.jsp</welcome-file> |
| </welcome-file-list> |
| |
| </web-app></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The following bullets describe the main elements in the default <code>web.xml</code> file.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The <code><Servlet></code> XML element declares a given servlet and its configurations. The sample <code>web.xml</code> file above includes two <Servlet> elements. |
| The default servlet serves static resources and processes the requests that are not mapped to any servlet. |
| For details about default servlet configuration, see the <a href="http://tomcat.apache.org/tomcat-7.0-doc/default-servlet.html">Apache Tomcat Default Servlet Reference.</a>.</p> |
| </li> |
| <li> |
| <p>The jsp servlet serves the requests to JavaServer Pages. It is mapped to the URL pattern "<strong>.jsp" and "</strong>.jspx". |
| For details about jsp servlet configuration, see the <a href="http://tomcat.apache.org/tomcat-7.0-doc/jasper-howto.html">Apache Tomcat Jasper 2 JSP Engine.</a>.</p> |
| </li> |
| <li> |
| <p>The <code><servlet-mapping></code> XML element specifies the mapping between the servlet and URL pattern.</p> |
| </li> |
| <li> |
| <p>The <code><session-config></code> XML element defines the session configuration for one web application. |
| The sample <code>web.xml</code> file above specifies that the session timeout for all web applications will be 30 minutes by default.</p> |
| </li> |
| <li> |
| <p>The <code><mime-mapping></code> XML element defines a mapping between a filename extension and a mime type. |
| When serving static resources, a "Content-Type" header will be generated based on these mappings.</p> |
| </li> |
| <li> |
| <p>The <code><welcome-file-list></code> XML element specifies a list of welcome files. |
| When a request URI refers to a directory, the default servlet looks for a "welcome file" within that directory. |
| If the "welcome file" exists it will be served, otherwise 404 status or directory listing will be returned, depending on the default servlet configuration.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-tomcat-contexts"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_context_configuration">Context Configuration</h4> |
| <div class="paragraph"> |
| <p>Virgo for Apache Tomcat supports standard Apache Tomcat web application context configuration. |
| The <a href="http://tomcat.apache.org/tomcat-7.0-doc/config/index.html">Apache Tomcat Configuration Reference</a> has a section on |
| <a href="http://tomcat.apache.org/tomcat-7.0-doc/config/context.html">The Context Container</a> which describes the mechanism that |
| is used in VTS for searching context configuration files and details the context configuration properties.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Context configuration files may be placed in the following locations, |
| where <code>[enginename]</code> is the name of Tomcat’s engine ('Catalina' by default) and <code>[hostname]</code> names |
| a virtual host ('localhost' by default), both of which are configured in <code>tomcat-server.xml</code>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>$SERVER_HOME/configuration/context.xml</code> provides the default context configuration file for all web applications.</p> |
| </li> |
| <li> |
| <p>The <code>$SERVER_HOME/configuration/[enginename]/[hostname]</code> directory may contain:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The default context configuration for all web applications of a given virtual host in the file <code>context.xml.default</code>.</p> |
| </li> |
| <li> |
| <p>Individual web applications' context configuration files as described in the Apache Tomcat Configuration Reference. |
| For example, the context for a web application with |
| context path <code>foo</code> may be configured in <code>foo.xml</code>.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Note that the following context configuration features are not supported in Virgo for Apache Tomcat:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Custom class loaders.</p> |
| </li> |
| <li> |
| <p>Specifying the context path. This is specified using the <code>Web-ContextPath</code> header in the web application’s |
| <code>MANIFEST.MF</code> file.</p> |
| </li> |
| <li> |
| <p>Specifying the document base directory.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-jsp-compilation"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_jsp_compilation">JSP Compilation</h4> |
| <div class="paragraph"> |
| <p>By default Apache Tomcat compiles JSP files in web applications agains Java 1.6. |
| In order to enable JSP compilation against Java 1.7 for your web application, |
| additional init parameters (<code>compilerSourceVM</code> and <code>compilerTargetVM</code>) should be added for the <code>org.apache.jasper.servlet.JspServlet</code> configuration. |
| For details about <code>org.apache.jasper.servlet.JspServlet</code> configuration, see the <a href="http://tomcat.apache.org/tomcat-7.0-doc/jasper-howto.html">Apache Tomcat Jasper 2 JSP Engine</a>. |
| <code>org.apache.jasper.servlet.JspServlet</code> configuration can be provided with the web application’s web.xml.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xml" data-lang="xml"><?xml version="1.0" encoding="ISO-8859-1"?> |
| <servlet> |
| <servlet-name>jsp</servlet-name> |
| <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class> |
| <init-param> |
| <param-name>compilerSourceVM</param-name> |
| <param-value>1.7</param-value> |
| </init-param> |
| <init-param> |
| <param-name>compilerTargetVM</param-name> |
| <param-value>1.7</param-value> |
| </init-param> |
| <init-param> |
| <param-name>fork</param-name> |
| <param-value>false</param-value> |
| </init-param> |
| <init-param> |
| <param-name>xpoweredBy</param-name> |
| <param-value>false</param-value> |
| </init-param> |
| <load-on-startup>3</load-on-startup> |
| </servlet> |
| <servlet-mapping> |
| <servlet-name>jsp</servlet-name> |
| <url-pattern>*.jsp</url-pattern> |
| <url-pattern>*.jspx</url-pattern> |
| </servlet-mapping></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-web"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_configuring_the_web_integration_layer">Configuring the Web Integration Layer</h3> |
| <div class="paragraph"> |
| <p>Virgo for Apache Tomcat integrates an OSGi-enhanced version of the <a href="http://tomcat.apache.org/">Tomcat Servlet Container</a> |
| in order to provide support for deploying Java EE WARs and OSGi <strong>Web Application Bundles</strong>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For Virgo for Apache Tomcat you |
| configure the behaviour of the Web Integration Layer using the properties file called <code>org.eclipse.virgo.web.properties</code>. |
| The <code>org.eclipse.virgo.web.properties</code> file is located in the <code>$SERVER_HOME/repository/ext</code> directory.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following table describes the properties.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-web-integration-layer"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 12. Web Integration Layer Properties</caption> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 60%;"> |
| <col style="width: 20%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| <th class="tableblock halign-left valign-top">Default Value</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>WABHeaders</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies how Web Application Bundle manifest headers are processed. |
| See "Web Application Manifest Processing" in the |
| <a href="../../virgo-programmer-guide/html/index.html">Programmer Guide</a> for details. |
| </p><p class="tableblock"> A value of <code>strict</code> causes VTS to interpret certain headers in strict compliance with |
| the OSGi Web Applications specification if they are not specified. |
| </p><p class="tableblock"> A value of <code>defaulted</code> causes VTS to set certain headers to default values if they are not specified. |
| This was how VTS behaved prior to version 3. |
| <strong>This value is provided as a migration aid and may not be supported in future releases.</strong> |
| A warning event log message (WE0006W) is generated if this value is specified. |
| </p><p class="tableblock"> The Virgo Jetty Server will always operate in <code>strict</code> mode. |
| </p><p class="tableblock"> Virgo Nano Full does not have a Web Integration Layer, but has a corresponding kernel property. |
| See <a href="#configuring-deployment">Configuring Deployment</a>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>strict</code></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>There is no Web Integration Layer in Virgo Jetty Server. The relevant configuration is described in |
| <a href="#configuring-jetty">Configuring the Embedded Jetty Servlet Container</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring-jetty"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_configuring_the_embedded_jetty_servlet_container">Configuring the Embedded Jetty Servlet Container</h3> |
| <div class="paragraph"> |
| <p>Virgo Jetty Server supports <strong>Web Application Bundles</strong>, but does not provide support for Java EE WARs.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The Virgo Jetty Server contains a standard Jetty configuration file at <code>SERVER_HOME/jetty/etc/jetty.xml</code>. |
| This has been tailored to the Eclipse Virgo. To make modifications please refer to the |
| <a href="http://wiki.eclipse.org/Jetty/Howto/Configure_Jetty#Using_Jetty_XML">Jetty documentation</a>.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div id="footer"> |
| <div id="footer-text"> |
| Last updated 2017-02-08 16:40:17 +01:00 |
| </div> |
| </div> |
| </body> |
| </html> |
