| <!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>Virgo User Guide</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"> |
| <h1>Virgo User Guide</h1> |
| <div id="toc" class="toc"> |
| <div id="toctitle">Table of Contents</div> |
| <ul class="sectlevel1"> |
| <li><a href="#_introduction">Introduction</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_a_note_for_virgo_kernel_users">A Note for Virgo Kernel Users</a></li> |
| <li><a href="#_a_note_for_virgo_jetty_server_users">A Note for Virgo Jetty Server Users</a></li> |
| <li><a href="#_a_note_for_virgo_nano_users">A Note for Virgo Nano Users</a></li> |
| </ul> |
| </li> |
| <li><a href="#_concepts">Concepts</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_modular_runtimes_and_applications">Modular Runtimes and Applications</a></li> |
| <li><a href="#_osgi_concepts">OSGi Concepts</a></li> |
| <li><a href="#_blueprint_concepts">Blueprint Concepts</a></li> |
| <li><a href="#_virgo_concepts">Virgo Concepts</a></li> |
| <li><a href="#_p2_concepts">p2 Concepts</a></li> |
| </ul> |
| </li> |
| <li><a href="#_using_the_p2_director">Using the p2 director</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_prerequisites">Prerequisites</a></li> |
| <li><a href="#_installing_with_the_p2_director_from_eclipse">Installing with the p2 director from Eclipse</a></li> |
| </ul> |
| </li> |
| <li><a href="#_installing_virgo_for_apache_tomcat">Installing Virgo for Apache Tomcat</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_prerequisites_2">Prerequisites</a></li> |
| <li><a href="#_installing_from_the_zip_download">Installing from the ZIP Download</a></li> |
| <li><a href="#_installing_from_an_update_site">Installing from an update site</a></li> |
| <li><a href="#_post_installation_steps">Post-installation steps</a></li> |
| </ul> |
| </li> |
| <li><a href="#_installing_virgo_kernel">Installing Virgo Kernel</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_prerequisites_3">Prerequisites</a></li> |
| <li><a href="#_installing_from_the_zip_download_2">Installing from the ZIP Download</a></li> |
| <li><a href="#_installing_from_an_update_site_2">Installing from an update site</a></li> |
| <li><a href="#_post_installation_steps_2">Post-installation steps</a></li> |
| </ul> |
| </li> |
| <li><a href="#_installing_virgo_nano">Installing Virgo Nano</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_prerequisites_4">Prerequisites</a></li> |
| <li><a href="#_installing_from_the_zip_download_3">Installing from the ZIP Download</a></li> |
| <li><a href="#_installing_from_an_update_site_3">Installing from an update site</a></li> |
| <li><a href="#_post_installation_steps_3">Post-installation steps</a></li> |
| </ul> |
| </li> |
| <li><a href="#_starting_and_stopping_virgo_for_apache_tomcat">Starting and Stopping Virgo for Apache Tomcat</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_starting_virgo_for_apache_tomcat">Starting Virgo for Apache Tomcat</a></li> |
| <li><a href="#_starting_in_clean_mode">Starting in Clean Mode</a></li> |
| <li><a href="#_starting_in_debug_mode">Starting in Debug Mode</a></li> |
| <li><a href="#_starting_with_jmx_access_modifications">Starting with JMX Access Modifications</a></li> |
| <li><a href="#_starting_with_a_custom_configuration_directory">Starting with a Custom Configuration Directory</a></li> |
| <li><a href="#_stopping_virgo_for_apache_tomcat">Stopping Virgo for Apache Tomcat</a></li> |
| <li><a href="#_cleaning_virgo_for_apache_tomcat_without_starting_it">Cleaning Virgo for Apache Tomcat without Starting it</a></li> |
| <li><a href="#_using_equinox_launcher">Using Equinox Launcher</a></li> |
| </ul> |
| </li> |
| <li><a href="#_equinox_console">Equinox Console</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_enabling_the_equinox_console">Enabling the Equinox Console</a></li> |
| <li><a href="#_using_virgo_shell_commands">Using Virgo Shell Commands</a></li> |
| <li><a href="#_virgo_shell_command_reference">Virgo Shell Command Reference</a></li> |
| <li><a href="#_using_the_p2_for_extending_your_virgo_installation">Using the p2 for extending your Virgo installation</a></li> |
| </ul> |
| </li> |
| <li><a href="#_the_web_admin_console">The Web Admin Console</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_invoking_the_admin_console">Invoking the Admin Console</a></li> |
| <li><a href="#_typical_admin_console_use_cases">Typical Admin Console Use Cases</a></li> |
| <li><a href="#_viewing_properties_of_deployed_configuration_artifacts">Viewing Properties of Deployed Configuration Artifacts</a></li> |
| </ul> |
| </li> |
| <li><a href="#_the_provisioning_repository_2">The Provisioning Repository</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_overview_of_the_provisioning_repository">Overview of the Provisioning Repository</a></li> |
| <li><a href="#_downloading_bundles_from_the_ebr">Downloading Bundles from the EBR</a></li> |
| <li><a href="#_configuring_the_repository">Configuring the Repository</a></li> |
| </ul> |
| </li> |
| <li><a href="#_serviceability_and_diagnostics">Serviceability and Diagnostics</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_event_logging">Event Logging</a></li> |
| <li><a href="#__trace_logging">(Trace) Logging</a></li> |
| <li><a href="#_system_out_and_system_err">System.out and System.err</a></li> |
| <li><a href="#_service_dumps">Service Dumps</a></li> |
| </ul> |
| </li> |
| <li><a href="#_working_with_applications">Working with Applications</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_deploying_artifacts">Deploying Artifacts</a></li> |
| <li><a href="#_undeploying_artifacts">Undeploying Artifacts</a></li> |
| </ul> |
| </li> |
| <li><a href="#_configuration">Configuration</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_configuring_the_osgi_framework">Configuring the OSGi Framework</a></li> |
| <li><a href="#_configuring_framework_extensions_and_fragments_on_the_system_bundle">Configuring Framework Extensions and Fragments on the System Bundle</a></li> |
| <li><a href="#_configuring_serviceability_and_diagnostics">Configuring Serviceability and Diagnostics</a></li> |
| <li><a href="#_configuring_the_local_provisioning_repository">Configuring the Local Provisioning Repository</a></li> |
| <li><a href="#_configuring_a_hosted_repository">Configuring a Hosted Repository</a></li> |
| <li><a href="#_configuring_the_kernel_and_user_region">Configuring the Kernel and User Region</a></li> |
| <li><a href="#_configuring_authentication">Configuring Authentication</a></li> |
| <li><a href="#_configuring_the_embedded_tomcat_servlet_container">Configuring the Embedded Tomcat Servlet Container</a></li> |
| <li><a href="#_configuring_the_web_integration_layer">Configuring the Web Integration Layer</a></li> |
| <li><a href="#_configuring_the_embedded_jetty_servlet_container">Configuring the Embedded Jetty Servlet Container</a></li> |
| </ul> |
| </li> |
| <li><a href="#_event_log_codes">Event log codes</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_format_of_the_event_log_codes">Format of the event log codes</a></li> |
| </ul> |
| </li> |
| <li><a href="#_known_issues">Known Issues</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_timeout_during_startup_due_to_firewall_settings">Timeout During Startup Due to Firewall Settings</a></li> |
| <li><a href="#_timeout_during_startup_due_to_insufficient_resources">Timeout During Startup Due to Insufficient Resources</a></li> |
| <li><a href="#_outofmemoryerror_permgen_space_running_on_sun_jvm">OutOfMemoryError: PermGen Space Running on Sun JVM</a></li> |
| <li><a href="#_alternate_code_serviceability_code_and_code_work_code_directories">Alternate <code>serviceability</code> and <code>work</code> Directories</a></li> |
| <li><a href="#_problem_deleting_installation_directory_under_windows">Problem Deleting Installation Directory under Windows</a></li> |
| <li><a href="#_long_work_directory_paths_under_windows">Long Work Directory Paths under Windows</a></li> |
| <li><a href="#_virgo_jetty_server_restrictions">Virgo Jetty Server Restrictions</a></li> |
| <li><a href="#_shutdown_log_messages_in_telnet_shell">Shutdown Log Messages in Telnet Shell</a></li> |
| </ul> |
| </li> |
| <li><a href="#_further_reading">Further Reading</a></li> |
| </ul> |
| </div> |
| </div> |
| <div id="content"> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Rob Harrop<br> |
| Paul Kuzan<br> |
| Sam Brannen<br> |
| Paul Harris<br> |
| Christopher Frost<br> |
| Ben Hale<br> |
| Glyn Normington<br> |
| Juliet Shackell<br> |
| Steve Powell<br> |
| Violeta Georgieva<br> |
| Hristo Iliev<br> |
| Borislav Kapukaranov<br> |
| Florian Waibel</p> |
| </div> |
| <div class="imageblock" style="float: right"> |
| <div class="content"> |
| <img src="assets/images/virgo-logo-small.png" alt="Eclipse Virgo"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Eclipse Virgo<br> |
| 3.7.0.RC01<br> |
| Copyright © 2009, 2011 VMware Inc. and others</p> |
| </div> |
| <div class="paragraph"> |
| <p>Contributors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>VMware Inc. - initial contribution and subsequent updates</p> |
| </li> |
| <li> |
| <p>Violeta Georgieva, SAP AG - Apache Tomcat configuration</p> |
| </li> |
| <li> |
| <p>Hristo Iliev, SAP AG - Setting jmx.properties permissions</p> |
| </li> |
| <li> |
| <p>Borislav Kapukaranov, SAP AG - Configuring framework extensions and fragments on system bundle; Added Virgo Nano references and tips</p> |
| </li> |
| </ul> |
| </div> |
| <hr> |
| <div class="paragraph"> |
| <p><a id="introduction"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_introduction">Introduction</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>This User Guide covers the Virgo for Apache Tomcat (VTS), the Virgo Jetty Server |
| (VJS) and the Virgo Kernel (VK), although it emphasises the |
| VTS since that is likely to apply to more users.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_a_note_for_virgo_kernel_users">A Note for Virgo Kernel Users</h3> |
| <div class="paragraph"> |
| <p>Virgo Kernel users can be reassured that the majority of the information |
| in this Guide is directly applicable to the Virgo Kernel and they can simply ignore the web-related sections.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_a_note_for_virgo_jetty_server_users">A Note for Virgo Jetty Server Users</h3> |
| <div class="paragraph"> |
| <p>Virgo Jetty Server users can be reassured that the majority of the information |
| in this Guide is directly applicable to the Virgo Jetty Server and they can simply ignore the Virgo for Apache Tomcat specific sections.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_a_note_for_virgo_nano_users">A Note for Virgo Nano Users</h3> |
| <div class="paragraph"> |
| <p>Virgo Nano is a bit different than VK and VTS. |
| It is the smallest Virgo offering and takes performance to its limits, almost instantly booting up. |
| Virgo Nano users will find a number of sections in this guide useful but sections that refer to |
| <strong>plans, PARs and configuration deployment, regions, application scoping and libraries support</strong> |
| are NOT relevant for Virgo Nano or VN and should be ignored. |
| This Virgo distribution relies on p2 for its provisioning, therefore is bound to p2 concepts such as <strong>p2 features and update sites</strong>. |
| Note also that Virgo Nano includes Gemini.Web as its default web container implementation and uses its default configuration.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="concepts"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_concepts">Concepts</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>This chapter introduces some basic concepts that will help you to use Virgo.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="concepts.modular"></a></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_modular_runtimes_and_applications">Modular Runtimes and Applications</h3> |
| <div class="paragraph"> |
| <p>Virgo for Apache Tomcat, Virgo Jetty Server, Virgo Kernel and Virgo Nano are Java runtimes each composed of |
| a collection of modules and supporting applications which are also composed of a |
| collection of modules. |
| Modules can be shared between applications and multiple versions of modules |
| can co-exist.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="concepts.osgi"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_osgi_concepts">OSGi Concepts</h3> |
| <div class="paragraph"> |
| <p>Modules in Virgo are represented using a standard Java |
| module system known as <strong>OSGi</strong>. |
| Modules in OSGi are known as <strong>bundles</strong>. |
| Bundles consist of programs and resources organised by Java package together |
| with metadata which declares imported and exported packages. |
| A bundle <strong>exports</strong> a package to make the corresponding programs and resources |
| available for use by other bundles. |
| A bundle <strong>imports</strong> a package to use the corresponding programs and resources of |
| another bundle.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Representing a program as a collection of bundles makes it easier for the |
| programmer to manage it and modify it and for teams of programmers to divide |
| responsibilities between themselves. |
| A bundle is similar to a Java class in this respect. Design principles similar to those for |
| organising data and programs into classes can be applied |
| to organising applications into bundles.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An industry consortium known as the |
| <strong>OSGi Alliance</strong> develops OSGi |
| specifications, reference implementations, and compliance tests. |
| Virgo is built on the Equinox OSGi framework which is also |
| the reference implementation for the OSGi framework specification.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_bundles">Bundles</h4> |
| <div class="paragraph"> |
| <p>Each bundle is stored in a file which conforms to the JAR file format and |
| can contain Java classes, a manifest (in <code>META-INF/MANIFEST.MF</code>), |
| and further resource files.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The OSGi framework enables bundles to be installed and run.</p> |
| </div> |
| <div class="paragraph"> |
| <p>OSGi identifies bundles "by name" and "by identifier" (id).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <strong>symbolic name</strong> and |
| <strong>version</strong> of a bundle are attributes of the bundle which identify the bundle. |
| A bundle declares its <strong>symbolic name</strong> and <strong>version</strong> |
| in its manifest (a file called <code>MANIFEST.MF</code>) like this:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">Bundle-SymbolicName: org.foo.bundle |
| Bundle-Version: 1.2.3.BUILD-2009-06-04</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Additionally, the OSGi framework |
| assigns a distinct number, known as a <strong>bundle id</strong>, to each bundle |
| as it is installed. Bundles may be referred to "by identifier" using this number. |
| The OSGi framework itself resides in a |
| bundle with bundle id <code>0</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The dependencies between bundles are expressed statically in terms of packages and |
| dynamically in terms of services. A package is familiar to Java programmers. |
| For example, a Java program may depend on a class <code>org.foo.X</code>, |
| from package <code>org.foo</code>, and a bundle |
| containing that program |
| would either need to contain <code>org.foo.X</code> or depend on the |
| package <code>org.foo</code>. |
| Package dependencies are specified in the bundle manifest, for example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">Import-Package: org.foo</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>A bundle which provides a package for use by other bundles <strong>must</strong> |
| export the package in its manifest. For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">Export-Package: org.foo</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The OSGi framework ensures that a given bundle’s package dependencies |
| can be <strong>satisfied</strong> before the bundle runs. This process is known as |
| <strong>resolution</strong>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>After a bundle is resolved, its classes and resources are available for |
| loading. |
| In OSGi, bundles and their packages do not appear on the application classpath. |
| Instead, each bundle has a class loader which loads its own classes and loads classes belonging to each of its |
| imported packages by deferring to the bundle class loader that exports the package.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_life_cycle">Life Cycle</h4> |
| <div class="paragraph"> |
| <p>The OSGi framework manages the <strong>life cycle</strong> of each bundle. A bundle is |
| first of all <strong>installed</strong> and will be in the INSTALLED state. |
| If a request is made to <strong>start</strong> the bundle, the OSGi framework <strong>resolves</strong> the bundle |
| and, if resolution was successful, will subsequently move the bundle to the ACTIVE state. |
| If a request is made to <strong>stop</strong> the bundle, the OSGi framework will move the |
| bundle back to the RESOLVED state. A request may then be made to <strong>uninstall</strong> |
| the bundle.</p> |
| </div> |
| <div class="paragraph"> |
| <p>While the bundle is INSTALLED, ACTIVE or RESOLVED, it may be <strong>updated</strong> to pick up |
| some changes. These changes are not detected by bundles which were depending |
| on the bundle before it was updated. |
| A "refresh packages" operation may be performed to ripple the |
| changes out to those bundles. (See <a href="#concepts.services">Services concepts</a>.) |
| The life cycle of a bundle can be summarised by a state transition diagram. |
| This diagram shows some more of the intermediate states of a bundle not described in the overview above:</p> |
| </div> |
| <div class="paragraph"> |
| <div class="title">Bundle life cycle</div> |
| <p><span class="image center"><img src="assets/images/concepts/bundle-lifecycle.png" alt="bundle lifecycle"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="concepts.services"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_services">Services</h4> |
| <div class="paragraph"> |
| <p>Bundles may publish Java objects, known as <strong>services</strong>, |
| to a registry managed by the OSGi framework. Other bundles running in |
| the same OSGi framework can then find and use those services. Services |
| are typically instances of some shared Java interface. A bundle which |
| provides a service need not then export the package containing the |
| <strong>implementation</strong> |
| class of the service.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example, a bundle could export a package containing the interface |
| <code>org.bar.SomeInterface</code>, thus:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">Export-Package: org.bar</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>…implement the interface with a class <code>SomeImpl</code>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-java" data-lang="java">package org.bar.impl; |
| |
| class SomeImpl implements SomeInterface { |
| … |
| }</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>…create an instance of <code>SomeImpl</code> and |
| then publish this instance (as an instance of the interface <code>SomeInterface</code>).</p> |
| </div> |
| <div class="paragraph"> |
| <p>An OSGi framework publishes a number of standard services. For example, the |
| <strong>Package Admin</strong> service provides the "refresh packages" life cycle operation |
| mentioned above.</p> |
| </div> |
| <div class="paragraph"> |
| <p>OSGi provides an <strong>API</strong> which can be used to publish and find services, |
| but it is much simpler to use Blueprint to accomplish this. (See <a href="#concepts.blueprint">Gemini Blueprint</a>.)</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_versioning">Versioning</h4> |
| <div class="paragraph"> |
| <p>OSGi allows different versions of bundles, packages, and several |
| other entities, to co-exist in the same framework |
| and provides some mechanisms for managing these versions.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_version_numbers">Version Numbers</h4> |
| <div class="paragraph"> |
| <p>An OSGi <strong>version number</strong> consists of up to three numeric components, |
| or exactly three |
| numeric components followed by a string component. These components are |
| separated by a period (“.”) and |
| are called the <strong>major</strong>, <strong>minor</strong>, <strong>micro</strong>, |
| and <strong>qualifier</strong> components, respectively.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example, the version <code>2.4.1.ga</code> has major component <code>2</code>, minor component |
| <code>4</code>, micro component <code>1</code>, |
| and a qualifier component <code>ga</code>. (There are restrictions on the characters that can appear in |
| a qualifier. For example: letters, digits, underscores and hyphens are allowed; periods and commas are not.)</p> |
| </div> |
| <div class="paragraph"> |
| <p>Trailing components may be omitted along with their period (<code>.</code>). So, for example, the version |
| numbers <code>2</code>, <code>2.0</code>, and <code>2.0.0</code> |
| all denote the same version. This example demonstrates that <code>0</code> is assumed if a numeric component is omitted, |
| and the empty string is assumed for an omitted qualifier.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_version_ranges">Version Ranges</h4> |
| <div class="paragraph"> |
| <p>Dependencies on bundles and packages have an associated <strong>version range</strong> |
| which is specified using an interval notation: a square bracket |
| “[” or “]” denotes |
| an <strong>inclusive</strong> end of the range and a round bracket |
| “(” or “)” denotes |
| an <strong>exclusive</strong> end of the range. Where one end of the range is to be included and the other excluded, it is permitted to |
| pair a round bracket with a square bracket. |
| The examples below make this clear.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If a single version number is used where a version <strong>range</strong> is |
| required this does <strong>not</strong> indicate a single version, but the range <strong>starting</strong> from that version and |
| including all higher versions.</p> |
| </div> |
| <div class="paragraph"> |
| <p>There are three common cases:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>A "strict" version range, such as <code>[1.2,1.2]</code>, which |
| denotes that version and only that version.</p> |
| </li> |
| <li> |
| <p>A "half-open" range, such as |
| <code>[1.2,2)</code>, which has an inclusive lower limit |
| and an exclusive upper limit, denoting version <code>1.2.0</code> and any version after this, up |
| to, <strong>but not including</strong>, version <code>2.0.0</code>.</p> |
| </li> |
| <li> |
| <p>An "unbounded" version range, such as <code>1.2</code>, which |
| denotes version <code>1.2</code> and <strong>all</strong> later versions.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_versioning_policies">Versioning Policies</h4> |
| <div class="paragraph"> |
| <p>A <strong>versioning policy</strong> is a way of using version numbers to indicate compatible |
| and incompatible changes. |
| OSGi does not mandate a particular versioning policy. |
| Instead, a specific versioning policy may be implemented using version ranges. |
| Strict and half-open version ranges are most useful in representing versioning |
| policies. |
| Unbounded version ranges can lead to problems as they (unrealistically) assume that |
| compatibility will be preserved indefinitely.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example, a conservative versioning policy might assume that any change, other than |
| in the qualifier component of a version, implies an incompatible |
| change to the object. |
| Such a policy would employ version ranges such as <code>[1.2.1.beta,1.2.2)</code> |
| which accept any version from <code>1.2.1.beta</code> (inclusive) up to but not including |
| <code>1.2.2</code> (exclusive).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Alternatively, a relaxed versioning policy might assume that only changes in the major component of |
| a version denote an incompatible change. |
| Such a policy would employ version ranges such as <code>[1.2,2)</code> to capture this.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The OSGi Alliance has published a <a href="http://www.osgi.org/wiki/uploads/Links/SemanticVersioning.pdf">Semantic |
| Versioning white paper</a> which provides some recommendations and guidance on versioning policies.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_bundle_version">Bundle Version</h4> |
| <div class="paragraph"> |
| <p>Each bundle has a version. |
| The bundle’s version may be specified in the manifest using a |
| <code>Bundle-Version</code> header:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Bundle-Version: 1.4.3.BUILD-20090302</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If not specified the bundle version is assumed to be <code>0</code>.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_package_version">Package Version</h4> |
| <div class="paragraph"> |
| <p>Each exported package has a version. |
| The exported package’s version may be specified on the Export-Package manifest header. For example</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Export-Package: org.foo;version="2.9",org.bar;version="1"</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>exports two packages: <code>org.foo</code>, at version <code>2.9.0</code> and |
| <code>org.bar</code>, at version <code>1.0.0</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the version attribute is omitted, the version is assumed to be <code>0</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Each package <strong>import</strong> has a version <strong>range</strong>. |
| The package import version range may be specified on the <code>Import-Package</code> manifest header. |
| If interval notation is used, the version range must be enclosed in double quotes, for example:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Import-Package: org.foo;version="[2,3)",org.bar;version="[1,1]"</programlisting></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>seeks to import a package <code>org.foo</code> in the range <code>[2.0.0,3.0.0)</code> and a package |
| <code>org.bar</code> with the (exact) version <code>1.0.0</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If a version range is not specified on an import, the range <code>0</code> is assumed, meaning that |
| any version of this package would satisfy the import.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_bundle_manifest_version">Bundle Manifest Version</h4> |
| <div class="paragraph"> |
| <p>Bundle manifests have a version which is <code>1</code> by default, |
| indicating OSGi Release 3 semantics. |
| Virgo is based on OSGi Release 4 and therefore expects bundle manifests to be |
| at version <code>2</code>, indicating OSGi Release 4 semantics. |
| The bundle manifest’s version should be specified on the Bundle-ManifestVersion manifest header, exactly as follows:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Bundle-ManifestVersion: 2</pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_manifest_version">Manifest Version</h4> |
| <div class="paragraph"> |
| <p>Manifests themselves also have a version which <strong>must</strong> be specified as <code>1.0</code>. |
| This is not an OSGi definition but part of the |
| (<a href="http://docs.oracle.com/javase/6/docs/technotes/guides/jar/jar.html">JAR file specification</a>).</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Manifest-Version: 1.0</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="concepts.blueprint"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_blueprint_concepts">Blueprint Concepts</h3> |
| <div class="paragraph"> |
| <p>Spring DM (the predecessor of Gemini Bluprint) is a project which enables <strong>services</strong> to be published and consumed |
| using descriptions written in XML.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The XML descriptions reside in files with extension <code>.xml</code> in the |
| bundle’s <code>META-INF/spring</code> sub-directory.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To publish a service, an <code><osgi:service></code> tag is used, specifying the |
| implementation class of the service and the interface class to be used. |
| Spring DM constructs an instance of the implementation class and |
| publishes that instance in the OSGi service registry under the interface when the bundle is started.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To consume a service, an <code><osgi:reference></code> tag is used and the |
| service may be passed into other Spring beans using Spring’s dependency |
| injection facilities.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Spring DM automatically creates proxies for OSGi services so that the actual service |
| object may come and go at runtime. |
| If a service disappears, any proxies to the service will wait for the service to re-appear. |
| This effect is known as <strong>damping</strong>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When a bundle is started, Spring DM builds the application contexts |
| specified by the XML descriptions, creates proxies for the specified services, and publishes |
| the specified services to the OSGi service registry.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When a bundle is stopped, Spring DM retracts any services it published on behalf of the bundle |
| and closes the bundle’s application contexts. |
| Virgo turns off damping of a service proxy while the proxy’s application context |
| is being closed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Spring DM was contributed to Eclipse as the <strong>Gemini Blueprint</strong> project. |
| Virgo has Gemini Blueprint built-in.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Gemini Blueprint supports both Spring DM and Blueprint programming models. |
| Blueprint, known formally as the "OSGi Blueprint Container", provides some of the basic facilities of Spring DM, |
| including all those just mentioned, but in an OSGi standard form. |
| See <a href="#furtherreading">Further Reading</a> for the Blueprint specification.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="concepts.virgo"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_virgo_concepts">Virgo Concepts</h3> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>This section is not relevant for Virgo Nano.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a id="concepts.repositories"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_the_provisioning_repository">The Provisioning Repository</h4> |
| <div class="paragraph"> |
| <p>The Virgo provisioning repository contains artifacts and metadata indexed by the artifact type, name, and version. There are three kinds of repository: <strong>external</strong>, <strong>watched</strong>, and <strong>remote</strong>. Repositories are passive in the sense that changes to repository content do not cause artifacts to be deployed into Virgo, refreshed, or undeployed.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_artifact_types">Artifact Types</h4> |
| <div class="paragraph"> |
| <p>In addition to the standard OSGi bundle, artifact types in Virgo include configuration (properties file), PAR, plan, and library. |
| PARs, plans, and libraries are discussed in <a href="#concepts.grouping">Grouping Bundles</a>.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_external_repositories">External Repositories</h4> |
| <div class="paragraph"> |
| <p>External repositories are created by scanning a directory which contains artifacts, possibly in nested directories. The repository configuration specifies a pattern which |
| says which files should be treated as artifacts. After the repository is created, changes to the directory do not affect the repository content.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Virgo’s default repository configuration, in <code>configuration/org.eclipse.virgo.repository.properties</code>, specifies an external repository created from the |
| <code>repository/ext</code> directory.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_watched_repositories">Watched Repositories</h4> |
| <div class="paragraph"> |
| <p>Watched repositories are created by scanning a directory which contains artifacts but no nested directories. All files in the directory are treated as artifacts. |
| The directory is re-scanned periodically and the interval between re-scans is specified in the repository configuration. |
| The directory is also re-scanned when an artifact is deployed into Virgo. |
| Changes detected by re-scanning are reflected in the repository content. Note that changing the content of a watched repository does not cause artifacts to be deployed |
| into Virgo, refreshed, or undeployed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Virgo’s default repository configuration specifies a watched repository based on the contents of the <code>repository/usr</code> directory.</p> |
| </div> |
| <div class="sect4"> |
| <h5 id="_remote_repositories">Remote Repositories</h5> |
| <div class="paragraph"> |
| <p>A remote repository refers to a repository hosted by a Virgo instance sometimes known as a <strong>repository server</strong>. |
| The hosted repository is configured using the file <code>configuration/org.eclipse.virgo.apps.repository.properties</code> and may be either an external or a watched |
| repository.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The remote repository is accessed by a Virgo instance sometimes known as a <strong>repository client</strong>. |
| The repository client is normally a different instance of Virgo to the instance hosting the repository, but it can be the same instance (which is handy for |
| testing). The remote repository periodically downloads its index from the hosted repository. The period between downloads may be configured in the repository |
| configuration. The remote repository also caches artifacts which have secure hashes associated with them in the hosted repository. Only bundles currently have secure |
| hashes associated with them. The secure hash is used to determine when a cached artifact is stale and needs to be freshly downloaded.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_repository_chains">Repository Chains</h4> |
| <div class="paragraph"> |
| <p>The Virgo repository is configured as a <strong>chain</strong> of external, watched, and remote repositories. |
| The chain is a list which is searched in the configured order. |
| The effect of this search order is that an artifact with a given type, name, and version which appears in more than one repository in the chain is only accessed from the |
| first repository in the chain in which it appears. Abstractly, the repository chain behaves as a single repository, but its content may mutate in quite a different way to |
| the content of an individual external, watched, or remote repository.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="concepts.grouping"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_grouping_bundles">Grouping Bundles</h4> |
| <div class="paragraph"> |
| <p>Virgo provides a way of grouping together a collection |
| of OSGi bundles and other artifacts which comprise a single application. |
| These artifacts are placed in a JAR file with extension “.par”. This is called a PAR file.</p> |
| </div> |
| <div class="paragraph"> |
| <p>All the bundles in a PAR file are resolved together and so mutual dependencies are permitted.</p> |
| </div> |
| <div class="paragraph"> |
| <p>At runtime a PAR file provides a <strong>scope</strong> in the sense that bundles |
| inside the PAR file may depend on packages and services outside the PAR file, |
| but bundles outside the PAR file may not depend on packages and services |
| provided by the PAR file.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Virgo also provides the plan artifact as another way of grouping bundles and other artifacts into an application. |
| A <strong>plan</strong> is a file (in XML format) listing a collection of artifacts. |
| The artifacts referred to by a plan reside in the Virgo provisioning repository.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In addition to PARs and plans, which are used for deploying groups of artifacts, Virgo provides libraries as a way of grouping together a collection |
| of bundles that can then be imported into an application using the Virgo-specific <code>Import-Library</code> manifes header.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="kernel.user.region"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_kernel_and_user_region">Kernel and User Region</h4> |
| <div class="paragraph"> |
| <p>Conceptually, VTS can be divided into two separate subsystems, one of which actually encompases the other:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The <strong>kernel</strong>, which is the heart of VTS. It makes up most of VTS, except for the part that supports Web applications. In other words, the kernel provides full OSGi modular support for your applications, as long as they are not Web-based. |
| See <a href="#kernel-overview">The Virgo Kernel</a> for additional information.</p> |
| </li> |
| <li> |
| <p>The <strong>user region</strong> is the subsystem that manages user applications. It deliberately isolates the kernel from both your applications and those of the VTS itself, such as the Admin Console, which protects the kernel from interference by applications. |
| See <a href="#user-region-overview">The User Region</a> for additional information.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>When you download and install Virgo for Apache Tomcat you get both the kernel and web server support (configured in the user region). You can also <a href="http://www.eclipse.org/virgo/download/">download and use the kernel</a> on its own if you do not plan on deploying Web applications or using the |
| web-based Admin Console and you’ll get the kernel and a minimal user region (with no web support).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following graphic shows how the kernel and user region make up VTS:</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/kernel-user-region.png" alt="kernel user region"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="kernel-overview"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_the_virgo_kernel">The Virgo Kernel</h4> |
| <div class="paragraph"> |
| <p>The Virgo Kernel encapsulates almost all of VTS except for the deployment of Web applications. In sum, the kernel provides the following VTS features:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Deployment of non-Web artifacts, such as OSGi bundles, PARs, plans, |
| and configuration artifacts.</p> |
| </li> |
| <li> |
| <p>Local and hosted repositories</p> |
| </li> |
| <li> |
| <p>Scoping</p> |
| </li> |
| <li> |
| <p>Hot deployment</p> |
| </li> |
| <li> |
| <p>User region</p> |
| </li> |
| <li> |
| <p>Auto-provisioning</p> |
| </li> |
| <li> |
| <p>System and application tracing and dump support</p> |
| </li> |
| <li> |
| <p>Spring beans and Blueprint support</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>See <a href="#configuring">Configuring VTS</a> for details about configuring the kernel to better suit your environment.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="user-region-overview"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_the_user_region">The User Region</h4> |
| <div class="paragraph"> |
| <p>The user region isolates the kernel from deployed applications, |
| including both your own user applications and the user-oriented |
| VTS applications such as the Admin Console. This means |
| that the kernel is mostly invisible to applications and to application |
| management. This is because most of the kernel bundles are not |
| installed in the user region (apart from a few needed for region |
| management). The necessary function to support the kernel runs in the |
| OSGi framework, but the user region applications cannot see it, except |
| for the services that are normally offered.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This isolation has many benefits. For example, it is not necessary for the kernel and user applications to use the same version of the Spring Framework. In fact the kernel installs only those parts of the Spring Framework that it needs. If you update the kernel, it is far less likely that you will also need to upgrade or adjust the applications to accomodate a new version of the kernel. The kernel implementation is therefore much more stable and resilient and applications are much more likely to survive kernel upgrades between releases. |
| When you install VTS, the kernel creates a single user region. |
| The kernel and the user region are configured independently of each other; see <a href="#configuring">Configuring VTS</a> for details.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Finally, the isolation provided by the user region together with scoped applications and plans solve common dependency problems that occur when using OSGi.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="concepts.p2"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_p2_concepts">p2 Concepts</h3> |
| <div class="paragraph"> |
| <p>At EclipseCon 2011 there was a great introductory presentation on p2. It gives a nice overview of the whole provisioning system. |
| You can find it recorded <a href="http://fosslc.org/drupal/content/gentle-introduction-p2">here(video).</a></p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="http://bkapukaranov.wordpress.com/2011/07/12/rt-meets-p2/">This blog post</a> |
| provides some background on why p2 was created as well as a brief overview of what p2 repositories |
| are and how this relates to a runtime.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This <a href="http://www.slideshare.net/PascalRapicault/understanding-and-extending-p2-for-fun-and-profit">presentation(slides only)</a> |
| sheds light on more advanced p2 features and turns our attention to its extension points.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Finally, the <a href="http://wiki.eclipse.org/Equinox/p2">p2 wiki</a> |
| also provides both getting started guides as well as information on more advanced features.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="using-the-p2-director"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_using_the_p2_director">Using the p2 director</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p><a id="prereqs"></a></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_prerequisites">Prerequisites</h3> |
| <div class="paragraph"> |
| <p>The Virgo for Apache Tomcat, or VTS for short, requires Java SE 6 or later to be installed. Java is available from |
| <a href="http://www.java.com/">http://www.java.com/</a> and elsewhere.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Since you’re going to use the p2 director you’ll need to get it. The easiest way is to download Eclipse from <a href="http://www.eclipse.org/downloads/">here</a>. |
| It has built-in p2 director and other p2 applications.</p> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Important</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>Setting the Target Platform</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Before using the director make sure you have a proper target platform set. Otherwise you may not see the director application. Here’s how to do that: |
| Go to Eclipse’s Preferences→Plug-in Development→Target Platform. Below is shown how the view looks like when a default target platform is set.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/target-platform-view.png" alt="target platform view"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>If for some reason you don’t have any target platform set or it’s not the default one you must set the default target platform from the image above. |
| If the default target platform is missing then add a new one via the <strong>Add…​</strong> button and select the <strong>Default</strong> radio button as shown below:</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/default-target-create.png" alt="default target create"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>You can now click <strong>Next</strong> and then <strong>Finish</strong>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="using-director"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_installing_with_the_p2_director_from_eclipse">Installing with the p2 director from Eclipse</h3> |
| <div class="paragraph"> |
| <p>This section covers briefly using the p2 director for installing. |
| A helpful page is the p2 director’s <a href="http://help.eclipse.org/indigo/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/p2_director.html">documentation at help.eclipse.org</a>. |
| There you can find more information on the different supported arguments.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Here’s how to use the GUI version of the director built-in Eclipse.</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Go to the <strong>Run</strong> context menu and select <strong>Run Configurations</strong></p> |
| </li> |
| <li> |
| <p>Create a new one and choose the director application as shown below, then switch to the <strong>Arguments</strong> tab</p> |
| </li> |
| </ol> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Important</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>In the image below the "Location:" text box’s value is managed by your IDE, don’t type anything in there.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/run_configuration.png" alt="run configuration"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>In the <strong>Program Arguments</strong> section append the director arguments. Here’s an example I used:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>-repository <yourP2repo> |
| -installIU nano.product |
| -tag InitialState |
| -destination /Users/<youruser>/install/virgo |
| -profile VirgoProfile |
| -roaming |
| -p2.os ${target.os} |
| -p2.ws ${target.ws} |
| -p2.arch ${target.arch}</pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Important</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>The <strong>-repository</strong> argument accepts any valid p2 repository. |
| The <strong>-destination</strong> argument accepts any valid absolute location. It defines the location where your Virgo installation will be provisioned. |
| If the directory does not exist, it will be created by the director.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>These arguments produce a Virgo Nano installation. For the <strong>p2.</strong>* arguments use the same properties from the example above. Eclipse will substitute them later with real values.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The passed value for <strong>-installIU</strong> determines which Virgo product is going to be installed. Here’s a list of all Virgo product install IUs: |
| <strong>nano.product</strong> - Virgo Nano |
| <strong>nano-full.product</strong> - Virgo Nano Full (VN ` p2 ` GW) |
| <strong>kernel.product</strong> - Virgo Kernel |
| <strong>tomcat-server.product</strong> - Virgo for Apache Tomcat |
| <strong>jetty-server.product</strong> - Virgo Jetty Server</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/director_args.png" alt="director args"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>Finally, run the created configuration. You should see the following output in Eclipse’s Console</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/director_result.png" alt="director result"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="installation"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_installing_virgo_for_apache_tomcat">Installing Virgo for Apache Tomcat</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p><a id="installation-prereqs"></a></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_prerequisites_2">Prerequisites</h3> |
| <div class="paragraph"> |
| <p>The Virgo for Apache Tomcat, or VTS for short, requires Java SE 6 or later to be installed. Java is available from |
| <a href="http://www.java.com/">http://www.java.com/</a> and elsewhere.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In case you are installing via a p2 director you’ll need to get it. The easiest way is to download Eclipse from <a href="http://www.eclipse.org/downloads/">here</a>. |
| It has built-in p2 director and other p2 applications.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="installation-zip"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_installing_from_the_zip_download">Installing from the ZIP Download</h3> |
| <div class="sect3"> |
| <h4 id="_downloading_the_zip_file">Downloading the ZIP file</h4> |
| <div class="paragraph"> |
| <p>Virgo for Apache Tomcat is distributed as a ZIP file. This can be downloaded from |
| <a href="http://www.eclipse.org/virgo/download/">here</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="installation-zip-installing"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_installing">Installing</h4> |
| <div class="paragraph"> |
| <p><a id="installation-zip-installing-linux"></a></p> |
| </div> |
| <div class="sect4"> |
| <h5 id="_linux">Linux</h5> |
| <div class="paragraph"> |
| <p>To install Virgo for Apache Tomcat on Linux, unzip the distribution package to the desired installation directory. |
| For example, to install into <code>/opt</code>:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ unzip virgo-web-server-{version}.zip -d /opt</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This creates a directory called <code>virgo-web-server-3.7.0.RC01</code> under <code>/opt</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Virgo for Apache Tomcat requires write access to the installation directory, in this case <code>/opt/virgo-web-server-3.7.0.RC01</code>. |
| Typically this means it must be run as the user that installed it, or the installation directory’s ownership must be changed.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="installation-zip-installing-win"></a></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="_microsoft_windows">Microsoft Windows</h5> |
| <div class="paragraph"> |
| <p>To install the Virgo for Apache Tomcat on Windows, unzip the distribution package to the desired installation directory. |
| You should use a zip application such as 7zip, not the built-in folder decompression. Note that both Windows and |
| Java have some issues with long file names and file paths, so we recommend installing to the root directory of |
| your chosen drive.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="installation-updatesite"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_installing_from_an_update_site">Installing from an update site</h3> |
| <div class="sect3"> |
| <h4 id="_the_repository_location">The repository location</h4> |
| <div class="paragraph"> |
| <p>Virgo has a single p2 repository that contains all Virgo distributions. The repository for version 3.7.0.RC01 can be found {p2repo}[here]. |
| There is a repository for each released version.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_using_the_p2_director_2">Using the p2 director</h4> |
| <div class="paragraph"> |
| <p>As shown in <a href="#using-director">Installing with the p2 director from Eclipse</a> you can easily install VTS in a desired destination. |
| The only director argument that needs to be adjusted is <strong>-installIU</strong>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For VTS the right value is <strong>tomcat-server.product</strong>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="installation-post"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_post_installation_steps">Post-installation steps</h3> |
| <div class="paragraph"> |
| <p><a id="installation-post-env"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_set_environment_variable_variables">Set environment variable variables</h4> |
| <div class="paragraph"> |
| <p><a id="installation-post-env-java"></a></p> |
| </div> |
| <div class="sect4"> |
| <h5 id="_java_home">JAVA_HOME</h5> |
| <div class="paragraph"> |
| <p>Virgo for Apache Tomcat uses the <code>JAVA_HOME</code> environment variable to locate the <code>java</code> |
| executable. Configure this environment variable to point to the home directory of the Java 6 installation on your computer.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="installation-post-env-server"></a></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="_server_home">SERVER_HOME</h5> |
| <div class="paragraph"> |
| <p>As a convenience it is recommended that you create an environment variable that points |
| to the Virgo for Apache Tomcat installation directory. Note that the Virgo for Apache Tomcat does not require that |
| such an environment variable has been set. This variable may have any name of your |
| choosing. The Virgo for Apache Tomcat’s documentation assumes that the variable is named |
| <code>SERVER_HOME</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="installation-post-env-server-linux"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_linux_2">Linux</h4> |
| <div class="paragraph"> |
| <p>Edit the <code>.profile</code> file in your home directory to |
| add the <code>SERVER_HOME</code> and <code>JAVA_HOME</code> environment variables. For |
| example, if you installed into <code>/opt</code>:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ export SERVER_HOME=/opt/virgo-web-server-{version}/ |
| $ export JAVA_HOME=/user/java/jdk1.6.0_17 |
| $ export PATH=$JAVA_HOME/bin:$PATH</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>To verify the setting of <code>JAVA_HOME</code>, issue the command <code>$JAVA_HOME/bin/java -version</code> from a new terminal window |
| and ensure that the command completes successfully and reports |
| a Java version <code>1.6.</code><strong>x</strong> (denoting Java 6) or greater.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="installation-post-env-server-win"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_microsoft_windows_2">Microsoft Windows</h4> |
| <div class="paragraph"> |
| <p>This section shows how to add <code>SERVER_HOME</code> as a system variable on Windows. Follow the same procedure to add or update the <code>JAVA_HOME</code> environment variable.</p> |
| </div> |
| <div class="paragraph"> |
| <p>From the Start menu, open the Control Panel and double-click on ‘System'.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/system-props.png" alt="system props"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>Click the 'Advanced' tab and select 'Environment Variables'. Next, |
| click the 'New' button in the 'System Variables' section.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/env-variables.png" alt="env variables"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>This will display the ‘New System Variable' window. Enter |
| <code>SERVER_HOME</code> as the ‘Variable name' and |
| the installation directory as the ‘Variable value'. Click OK.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/system-variable.png" alt="system variable"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>To verify the setting of <code>JAVA_HOME</code>, issue the command <code>"%JAVA_HOME%"\bin\java -version</code> from |
| a new command prompt and ensure that the command completes successfully and reports |
| a Java version <code>1.6.</code><strong>x</strong> (denoting Java 6) or greater.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="installation-post-env-server-win-troubleshooting"></a></p> |
| </div> |
| <div class="sect4"> |
| <h5 id="_microsoft_windows_troubleshooting_security_permissions">Microsoft Windows - Troubleshooting Security Permissions</h5> |
| <div class="paragraph"> |
| <p>When starting Virgo for Apache Tomcat on some variants of Windows you might encounter a problem with file permissions. |
| The error looks like this.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>WARNING: jmxPermissions.vbs did not update the permissions of C:\virgo\configuration\org.eclipse.virgo.kernel.jmxremote.access.properties. Check the file has the correct permissions.</screen></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If VTS starts correctly (see <a href="#starting-stopping">[starting-stopping]</a>) you can skip this section and carry on. However to secure your |
| installation you have to set correct permissions. To do so, go to the ‘configuration' directory of the installation |
| in Windows Explorer.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/install-windows-1-FileListing.png" alt="install windows 1 FileListing"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>Right click on the 'org.eclipse.virgo.kernel.jmxremote.access.properties' file and view its properties, |
| then select the 'Security' tab. Remove all groups and users from the list and select 'Apply'.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/install-windows-2-SecuritySettings.png" alt="install windows 2 SecuritySettings"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>Within the security page select the ‘Advanced' options. On the ‘Owner' tab, choose the owner |
| that you are trying to run the VTS as and select ‘Apply'.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/install-windows-3-AdvanceSettingsOwner.png" alt="install windows 3 AdvanceSettingsOwner"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>Once this is done select ‘OK' to return to the ‘Security' tab |
| and now add the owner to the list of groups and users that have permission to access the file.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/install-windows-4-AllSetReadAndExecute.png" alt="install windows 4 AllSetReadAndExecute"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>Once all these steps are complete you can proceed to start the VTS.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>C:\dev\virgo-web-server-{version}>bin\startup.bat |
| [2009-12-08 13:09:09.545] startup-tracker <KE0001I> Kernel starting.</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="kernel-installation"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_installing_virgo_kernel">Installing Virgo Kernel</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p><a id="kernel-installation-prereqs"></a></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_prerequisites_3">Prerequisites</h3> |
| <div class="paragraph"> |
| <p>The Virgo Kernel, or VK for short, requires Java SE 6 or later to be installed. Java is available from |
| <a href="http://www.java.com/">http://www.java.com/</a> and elsewhere.</p> |
| </div> |
| <div class="paragraph"> |
| <p>anchor:kernel-installation-zip</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_installing_from_the_zip_download_2">Installing from the ZIP Download</h3> |
| <div class="sect3"> |
| <h4 id="_downloading_the_zip_file_2">Downloading the ZIP file</h4> |
| <div class="paragraph"> |
| <p>Virgo Kernel is distributed as a ZIP file. This can be downloaded from |
| <a href="http://www.eclipse.org/virgo/download/">here</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>anchor:kernel-installation-zip-installing</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_installing_2">Installing</h4> |
| <div class="paragraph"> |
| <p><a id="kernel-installation-zip-installing-linux"></a></p> |
| </div> |
| <div class="sect4"> |
| <h5 id="_linux_3">Linux</h5> |
| <div class="paragraph"> |
| <p>To install the Virgo Kernel on Linux, unzip the distribution package to the desired installation directory. |
| For example, to install into <code>/opt</code>:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ unzip virgo-kernel-{version}.zip -d /opt</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This creates a directory called <code>virgo-kernel-3.7.0.RC01</code> under <code>/opt</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Virgo Kernel requires write access to the installation directory, in this case <code>/opt/virgo-kernel-3.7.0.RC01</code>. |
| Typically this means it must be run as the user that installed it, or the installation directory’s ownership must be changed.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="kernel-installation-zip-installing-win"></a></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="_microsoft_windows_3">Microsoft Windows</h5> |
| <div class="paragraph"> |
| <p>To install the Virgo Kernel on Windows, unzip the distribution package to the desired installation directory. |
| You should use a zip application such as 7zip, not the built-in folder decompression. Note that both Windows and |
| Java have some issues with long file names and file paths, so we recommend installing to the root directory of |
| your chosen drive.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="kernel-installation-updatesite"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_installing_from_an_update_site_2">Installing from an update site</h3> |
| <div class="sect3"> |
| <h4 id="_the_repository_location_2">The repository location</h4> |
| <div class="paragraph"> |
| <p>Virgo has a single p2 repository that contains all Virgo distributions. The repository for version 3.7.0.RC01 can be found {p2repo}[here]. |
| There is a repository for each released version.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_using_the_p2_director_3">Using the p2 director</h4> |
| <div class="paragraph"> |
| <p>As shown in <a href="#using-director">Installing with the p2 director from Eclipse</a> you can easily install VK in a desired destination. |
| The only director argument that needs to be adjusted is <strong>-installIU</strong>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For VK the right value is <strong>kernel.product</strong>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="kernel-installation-post"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_post_installation_steps_2">Post-installation steps</h3> |
| <div class="paragraph"> |
| <p>Follow the same <a href="#installation-post">Post-installation steps</a> as for Virgo for Apache Tomcat.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="nano-installation"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_installing_virgo_nano">Installing Virgo Nano</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p><a id="nano-installation-prereqs"></a></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_prerequisites_4">Prerequisites</h3> |
| <div class="paragraph"> |
| <p>The Virgo Nano, or VN for short, requires Java SE 6 or later to be installed. Java is available from |
| <a href="http://www.java.com/">http://www.java.com/</a> and elsewhere.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="nano-installation-zip"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_installing_from_the_zip_download_3">Installing from the ZIP Download</h3> |
| <div class="sect3"> |
| <h4 id="_downloading_the_zip_file_3">Downloading the ZIP file</h4> |
| <div class="paragraph"> |
| <p>Virgo Nano is distributed as a ZIP file. This can be downloaded from |
| <a href="http://www.eclipse.org/virgo/download/">here</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="nano-installation-zip-installing"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_installing_3">Installing</h4> |
| <div class="paragraph"> |
| <p><a id="nano-installation-zip-installing-linux"></a></p> |
| </div> |
| <div class="sect4"> |
| <h5 id="_linux_4">Linux</h5> |
| <div class="paragraph"> |
| <p>To install the Virgo Nano on Linux, unzip the distribution package to the desired installation directory. |
| For example, to install into <code>/opt</code>:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ unzip virgo-nano-{version}.zip -d /opt</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This creates a directory called <code>virgo-nano-3.7.0.RC01</code> under <code>/opt</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Virgo Nano requires write access to the installation directory, in this case <code>/opt/virgo-nano-3.7.0.RC01</code>. |
| Typically this means it must be run as the user that installed it, or the installation directory’s ownership must be changed.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="nano-installation-zip-installing-win"></a></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="_microsoft_windows_4">Microsoft Windows</h5> |
| <div class="paragraph"> |
| <p>To install the Virgo Nano on Windows, unzip the distribution package to the desired installation directory. |
| You should use a zip application such as 7zip, not the built-in folder decompression. Note that both Windows and |
| Java have some issues with long file names and file paths, so we recommend installing to the root directory of |
| your chosen drive.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="nano-installation-updatesite"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_installing_from_an_update_site_3">Installing from an update site</h3> |
| <div class="sect3"> |
| <h4 id="_the_repository_location_3">The repository location</h4> |
| <div class="paragraph"> |
| <p>Virgo has a single p2 repository that contains all Virgo distributions. The repository for version 3.7.0.RC01 can be found {p2repo}[here]. |
| There is a repository for each released version.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_using_the_p2_director_4">Using the p2 director</h4> |
| <div class="paragraph"> |
| <p>As shown in <a href="#using-director">Installing with the p2 director from Eclipse</a> you can easily install VN in a desired destination. |
| The only director argument that needs to be adjusted is <strong>-installIU</strong>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For VN the right value is <strong>nano.product</strong>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="nano-installation-post"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_post_installation_steps_3">Post-installation steps</h3> |
| <div class="paragraph"> |
| <p>Follow the same <a href="#installation-post">Post-installation steps</a> as for Virgo for Apache Tomcat.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="starting-stopping""></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_starting_and_stopping_virgo_for_apache_tomcat">Starting and Stopping Virgo for Apache Tomcat</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Starting and Stopping VTS</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_starting_virgo_for_apache_tomcat">Starting Virgo for Apache Tomcat</h3> |
| <div class="paragraph"> |
| <p>To start Virgo for Apache Tomcat run the <code>startup.sh</code> (Linux) or <code>startup.bat</code> (Windows) script. |
| For both platforms, the script is located in the <code>SERVER_HOME/bin</code> directory.</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 chapter applies to Virgo Nano too. Note that since VN |
| has a single region you can ignore the console output from the user region and focus on the instructions. |
| A successful startup of VN is as simple as that:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>[2011-12-28 11:41:31.528] startup-tracker <KE0001I> Kernel starting. |
| [2011-12-28 11:41:31.602] startup-tracker <KE0002I> Kernel started.</pre> |
| </div> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="sect3"> |
| <h4 id="_linux_5">Linux</h4> |
| <div class="paragraph"> |
| <p>To start Virgo for Apache Tomcat, open a terminal window and run <code>startup.sh</code>:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ cd $SERVER_HOME |
| $ bin/startup.sh</screen></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Once Virgo for Apache Tomcat has started, the console will display a log message |
| similar to the one shown below, along with other status messages:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>[2009-11-30 12:12:12.111] Thread-2 <UR0001I> User region ready.</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The preceding message indicates that you can start using VTS.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_microsoft_windows_5">Microsoft Windows</h4> |
| <div class="paragraph"> |
| <p>To start Virgo for Apache Tomcat, open a command-window and run <code>startup.bat</code>:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>c:> cd %SERVER_HOME% |
| c:> bin\startup.bat</screen></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Once Virgo for Apache Tomcat has started, the console will display a log message |
| similar to the one shown below, along with other status messages:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>[2009-11-30 12:12:12.111] Thread-2 <UR0001I> User region ready.</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The preceding message indicates that you can start using VTS.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_starting_in_clean_mode">Starting in Clean Mode</h3> |
| <div class="paragraph"> |
| <p>When you start Virgo for Apache Tomcat in clean mode, the startup script removes the <code>SERVER_HOME/work</code> directory (and hence all |
| running applications) as well as all trace, log and dump files. It leaves the |
| <code>SERVER_HOME/repository</code> and <code>SERVER_HOME/pickup</code> directories untouched, |
| which means that any applications previously hot deployed will be automatically reinstalled.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_linux_6">Linux</h4> |
| <div class="paragraph"> |
| <p>To start Virgo for Apache Tomcat in clean mode, open a terminal window and run <code>startup.sh -clean</code>:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ cd $SERVER_HOME |
| $ bin/startup.sh -clean</pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_microsoft_windows_6">Microsoft Windows</h4> |
| <div class="paragraph"> |
| <p>To start Virgo for Apache Tomcat in clean mode, open a command window and run <code>startup.bat -clean</code>:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>C:> cd %SERVER_HOME% |
| C:> bin\startup.bat -clean</pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_starting_in_debug_mode">Starting in Debug Mode</h3> |
| <div class="sect3"> |
| <h4 id="_linux_7">Linux</h4> |
| <div class="paragraph"> |
| <p>To start Virgo for Apache Tomcat in debug mode, run |
| <code>startup.sh</code> passing in the |
| <code>-debug</code> argument:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ cd $SERVER_HOME |
| $ bin/startup.sh -debug</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This will start the debug agent listening on port |
| <code>8000</code> which is the default remote debug port used |
| by Eclipse. To start in debug mode with a specific port number, pass |
| this in as the value for the <code>-debug</code> argument:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ cd $SERVER_HOME |
| $ bin/startup.sh -debug 8001</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This will start the debug agent listening on port |
| <code>8001</code>. To start in debug mode and suspend the VM |
| until a debugger attaches, pass in the <code>-suspend</code> |
| argument along with the <code>-debug</code> argument:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ cd $SERVER_HOME |
| $ bin/startup.sh -debug -suspend</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This starts the debug agent, but prevents Virgo for Apache Tomcat from actually |
| starting until a debugger attaches to the agent. This can be useful |
| when trying to diagnose problems that occur during startup.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_microsoft_windows_7">Microsoft Windows</h4> |
| <div class="paragraph"> |
| <p>To start Virgo for Apache Tomcat in debug mode, run |
| <code>startup.bat</code> passing in the |
| <code>-debug</code> argument:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>C:> cd %SERVER_HOME% |
| C:> bin\startup.bat -debug</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This will start the debug agent listening on port |
| <code>8000</code> which is the default remote debug port used |
| by Eclipse. To start in debug mode with a specific port number, pass |
| this in as the value for the <code>-debug</code> argument:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>C:> cd %SERVER_HOME% |
| C:> bin\startup.bat -debug 8001</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This will start the debug agent listening on port |
| <code>8001</code>. To start in debug mode and suspend the VM |
| until a debugger attaches, pass in the <code>-suspend</code> |
| argument along with the <code>-debug</code> argument:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>C:> cd %SERVER_HOME% |
| C:> bin\startup.bat -debug -suspend</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This starts the debug agent, but prevents Virgo for Apache Tomcat from actually |
| starting until a debugger attaches to the agent. This can be useful |
| when trying to diagnose problems that occur during startup.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_starting_with_jmx_access_modifications">Starting with JMX Access Modifications</h3> |
| <div class="paragraph"> |
| <p>The Virgo for Apache Tomcat always starts with JMX access enabled, allowing you to use a management tool such as JConsole |
| to attach to the Web Server instance. |
| By default both local access and remote access over SSL with username and password |
| authentication are provided. The default port for secure JMX access is <code>9875</code> |
| and the default username and password are <code>admin</code> and <code>springsource</code>.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_linux_8">Linux</h4> |
| <div class="paragraph"> |
| <p>To start Virgo for Apache Tomcat with default JMX access enabled, run <code>startup.sh</code> passing |
| in no arguments:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ cd $SERVER_HOME |
| $ bin/startup.sh</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>To start JConsole, run the <code>jconsole.sh</code> script, located in the <code>bin</code> directory, as shown:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ cd $SERVER_HOME |
| $ bin/jconsole.sh</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The following image shows how to specify a local connection using JConsole.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/jmx-local-attach.png" alt="jmx local attach"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>The following image shows how to specify a remote connection in JConsole that uses SSL with the default |
| username/password (<code>admin/springsource</code> and default secure port of <code>9875</code>).</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/jmx-remote-attach-default.png" alt="jmx remote attach default"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>To start with the JMX remote access on a specific port number other than the default <code>9875</code>, |
| pass this port number in as the value |
| of the <code>-jmxport</code> argument:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ cd $SERVER_HOME |
| $ bin/startup.sh -jmxport 9090</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This will start the Virgo for Apache Tomcat with JMX enabled for remote connections on port <code>9090</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/jmx-remote-attach-jmxport.png" alt="jmx remote attach jmxport"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>To start the JMX remote access with a custom username and password, update the <code>$SERVER_HOME/configuration/org.eclipse.virgo.kernel.users.properties</code> file. First specify the custom username by changing the value of the <code>role.admin</code> property. Then set the password of this new user by adding a new property called <code>user.<strong>username</strong></code>, where <code><strong>username</strong></code> refers to the actual name of the user. Finally, restart VTS for the changes to take effect. |
| For example, if you want change the JMX remote access username to <code>zebedee</code> with password <code>florence</code>, change the file as follows:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">################## |
| # User definitions |
| ################## |
| user.zebedee=florence |
| |
| |
| ################## |
| # Role definitions |
| ################## |
| role.admin=zebedee</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Specify the custom username in JConsole as shown.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/jmx-remote-attach-jmxusers.png" alt="jmx remote attach jmxusers"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>To start the JMX remote access using a custom SSL certificate, edit the file located at |
| <code>$SERVER_HOME/configuration/keystore</code>. If you wish to use a different keystore, |
| pass this filename in as the value for the <code>-keystore</code> argument and the keystore |
| password in as the value for the <code>-keystorePassword</code> argument:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ cd $SERVER_HOME |
| $ bin/startup.sh -keystore customKeystore -keystorePassword customKeystorePassword</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This will start the Virgo for Apache Tomcat with JMX enabled for remote connections using an SSL certificate from |
| <code>customKeystore</code> with a password of <code>customKeystorePassword</code>.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_microsoft_windows_8">Microsoft Windows</h4> |
| <div class="paragraph"> |
| <p>To start Virgo for Apache Tomcat with default JMX access enabled, run <code>startup.bat</code> passing |
| in no arguments:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>C:> cd %SERVER_HOME% |
| C:> bin\startup.bat</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>To start JConsole, run the <code>jconsole.bat</code> script, located in the <code>bin</code> directory, as shown:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>C:> cd %SERVER_HOME% |
| C:> bin\jconsole.bat</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The following image shows how to specify a local connection using JConsole.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/jmx-local-attach.png" alt="jmx local attach"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>The following image shows how to specify a remote connection in JConsole that uses SSL with the default |
| username/password (<code>admin/springsource</code> and default secure port of <code>9875</code>).</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/jmx-remote-attach-default.png" alt="jmx remote attach default"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>To start with the JMX remote access on a specific port number other than the default <code>9875</code>, |
| pass this port number in as the value of the <code>-jmxport</code> argument:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>C:> cd %SERVER_HOME% |
| C:> bin\startup.bat -jmxport 9090</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This will start the Virgo for Apache Tomcat with JMX enabled for remote connections on port |
| <code>9090</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/jmx-remote-attach-jmxport.png" alt="jmx remote attach jmxport"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>To start the JMX remote access with a custom username and password, update the <code>%SERVER_HOME%\configuration\org.eclipse.virgo.kernel.users.properties</code> file. First specify the custom username by changing the value of the <code>role.admin</code> property. Then set the password of this new user by adding a new property called <code>user.<strong>username</strong></code>, where <code><strong>username</strong></code> refers to the actual name of the user. Finally, restart VTS for the changes to take effect. |
| For example, if you want change the JMX remote access username to <code>zebedee</code> with password <code>florence</code>, change the file as follows:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">################## |
| # User definitions |
| ################## |
| user.zebedee=florence |
| |
| |
| ################## |
| # Role definitions |
| ################## |
| role.admin=zebedee</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Specify the custom username in JConsole as shown.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/jmx-remote-attach-jmxusers.png" alt="jmx remote attach jmxusers"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>To start the JMX remote access using a custom SSL certificate, edit the file located at |
| <code>%SERVER_HOME%\configuration\keystore</code>. If you wish to use a different |
| keystore, pass this filename in as the value for the <code>-keystore</code> argument and the |
| keystore password in as the value for the <code>-keystorePassword</code> argument:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>C:> cd %SERVER_HOME% |
| C:> bin\startup.bat -keystore customKeystore -keystorePassword customKeystorePassword</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This will start the Virgo for Apache Tomcat with JMX enabled for remote attach using an SSL certificate from |
| <code>customKeystore</code> with a password of <code>customKeystorePassword</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="starting-stopping-configuration-directory"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_starting_with_a_custom_configuration_directory">Starting with a Custom Configuration Directory</h3> |
| <div class="paragraph"> |
| <p>Use the <code>-configDir</code> option to specify an alternate <code>configuration</code> directory, different from the |
| default <code>SERVER_HOME/configuration</code> directory. This option allows you to use the same Virgo for Apache Tomcat |
| installation to run multiple instances of VTS. Simply create a configuration directory for each |
| instance, specify unique port numbers, logging and tracing directories, and so on, and then specify that directory |
| when starting VTS.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If you specify a relative path for the <code>-configDir</code> parameter, |
| the startup script interprets the path as relative to the root of the Virgo for Apache Tomcat installation, |
| and not relative to the directory from which you execute the <code>startup</code> script.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See <a href="#alternate-serviceability-work">Alternate <code>serviceability</code> and <code>work</code> |
| Directories</a> for a known issue related to specifying an alternate <code>configuration</code> directory.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_linux_9">Linux</h4> |
| <div class="paragraph"> |
| <p>To start Virgo for Apache Tomcat using a configuration directory of <code>/configuration/node1</code>:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ cd $SERVER_HOME |
| $ bin/startup.sh -configDir /configuration/node1</pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_windows">Windows</h4> |
| <div class="paragraph"> |
| <p>To start Virgo for Apache Tomcat using a configuration directory of <code>c:\configuration\node1</code>:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>C:> cd %SERVER_HOME% |
| C:> bin\startup.bat -configDir c:\configuration\node1</pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_stopping_virgo_for_apache_tomcat">Stopping Virgo for Apache Tomcat</h3> |
| <div class="sect3"> |
| <h4 id="_linux_10">Linux</h4> |
| <div class="paragraph"> |
| <p>To stop a running instance of Virgo for Apache Tomcat, start a new terminal window and run the <code>shutdown.sh</code> script:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ cd $SERVER_HOME |
| $ bin/shutdown.sh</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>To stop a running instance of Virgo for Apache Tomcat immediately, bypassing normal shutdown |
| processing, run <code>shutdown.sh</code> with the <code>-immediate</code> option:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ cd $SERVER_HOME |
| $ bin/shutdown.sh -immediate</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If, when you started the Web Server instance, you used the <code>-jmxport</code> option to specify a non-default JMX port number, |
| then you must pass this port number to the <code>-jmxport</code> of the <code>shutdown.sh</code> script |
| to gracefully shut it down. |
| For example, if you specified <code>9090</code> as the JMX port, use the following to shut down the Web Server instance:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ cd $SERVER_HOME |
| $ bin/shutdown.sh -jmxport 9090</pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_microsoft_windows_9">Microsoft Windows</h4> |
| <div class="paragraph"> |
| <p>To stop a running instance of Virgo for Apache Tomcat, start a new console window and run the <code>shutdown.bat</code> script:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>C:> cd %SERVER_HOME% |
| C:> bin\shutdown.bat</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>To stop a running instance of Virgo for Apache Tomcat immediately, bypassing normal shutdown |
| processing, run <code>shutdown.bat</code> with the <code>-immediate</code> option:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>C:> cd %SERVER_HOME% |
| C:> bin\shutdown.bat -immediate</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If, when you started the Web Server instance, you used the <code>-jmxport</code> option to specify a non-default JMX port number, |
| then you must pass this port number to the <code>-jmxport</code> of the <code>shutdown.bat</code> script to gracefully shut it down. |
| For example, if you specified <code>9090</code> as the JMX port, use the following to shut down the Web Server instance:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>C:> cd %SERVER_HOME% |
| C:> bin\shutdown.bat -jmxport 9090</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="cleaning-without-starting"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_cleaning_virgo_for_apache_tomcat_without_starting_it">Cleaning Virgo for Apache Tomcat without Starting it</h3> |
| <div class="paragraph"> |
| <p>When you clean Virgo for Apache Tomcat, the startup script removes the <code>SERVER_HOME/work</code> directory (and hence all |
| running applications) as well as all trace, log and dump files. It leaves the |
| <code>SERVER_HOME/repository</code> and <code>SERVER_HOME/pickup</code> directories untouched, |
| which means that any applications previously hot deployed will be automatically reinstalled next time the Web Server is started.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Cleaning is useful when you want to start the Web Server from a clean state next time, but you don’t want to start the Web Server yet.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Cleaning is also useful for tidying up the directory structure. For example, sometimes Microsoft Windows won’t let you delete the Web |
| Server installation directory. |
| See <a href="#windows-deletion">Problem Deleting Installation Directory under Windows</a> for more details.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_linux_11">Linux</h4> |
| <div class="paragraph"> |
| <p>To clean Virgo for Apache Tomcat, open a terminal window and run <code>startup.sh -clean -noStart</code>:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ cd $SERVER_HOME |
| $ bin/startup.sh -clean -noStart</pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_microsoft_windows_10">Microsoft Windows</h4> |
| <div class="paragraph"> |
| <p>To clean Virgo for Apache Tomcat, open a command window and run <code>startup.bat -clean -noStart</code>:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>C:> cd %SERVER_HOME% |
| C:> bin\startup.bat -clean -noStart</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="equinox-launcher"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_using_equinox_launcher">Using Equinox Launcher</h3> |
| <div class="paragraph"> |
| <p>Since version 3.5 Virgo uses the standard Equinox Launcher as its default launcher. |
| As a result in addition to all the launcher options described so far users can also pass arguments specific to the Equinox launcher.</p> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Important</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>The Equinox Launcher arguments must be placed at the end of the startup call. Here’s an example</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ ./startup.sh "virgo-args" "equinox-launcher-args" |
| $ ./startup.sh -clean -console 2222</screen></pre> |
| </div> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>A full list of the accepted Equinox Launcher arguments is available at <a href="http://help.eclipse.org/">help.eclipse.org</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-shell"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_equinox_console">Equinox Console</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p><a id="admin-shell-enable"></a></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_enabling_the_equinox_console">Enabling the Equinox Console</h3> |
| <div class="paragraph"> |
| <p>Shells are provided for both user region and kernel, although they are disabled by default and need enabling before |
| they can be used.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The user region shell ports may be reconfigured by editing the file |
| <code>osgi.console.properties</code> in the <code>repository/ext</code> directory, and |
| then restarting Virgo. The telnet properties in the file are prefixed with <strong>telnet.</strong>, and the ssh properties are prefixed with <strong>ssh.</strong>. |
| The kernel shell ports may be reconfigured by editing the file <code>osgi.console.properties</code> in the <code>configuration</code> directory, and then restarting Virgo.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To enable any of these shell ports, change the <code>enabled</code> setting from <code>false</code> to <code>true</code></p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">enabled=true</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>in the corresponding properties files.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If you wish to change a port, any free port can be used, but the usual defaults are, for telnet, 2501 for the user region and 2401 for the kernel, and |
| for ssh, 2502 for the user region and 2402 for the kernel.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Access is via ssh or telnet. |
| The simplest way to access the shell is via telnet to port 2501 or 2401 for user region or kernel, respectively.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ telnet localhost 2501 |
| Trying ::1... |
| Connected to localhost. |
| Escape character is '^]'. |
| |
| osgi></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Alternatively, you can ssh to port 2502 or 2402 for user region or kernel, respectively. |
| The users and passwords for ssh are configured in <code>configuration/org.eclipse.virgo.kernel.users.properties</code> as described |
| in <a href="#configuring-authentication">Configuring Authentication</a>. The default user and password are <code>admin</code> |
| and <code>admin</code>.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>Currently the Virgo Nano Equinox Console is enabled by default. Telnet is accesible on <strong>2401</strong> and SSH on <strong>2402</strong>. In future these will be configurable.</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>If you use the <code>shutdown</code> shell command to stop Virgo Server for Apache Tomcat, the shutdown messages appear in the shell terminal instead of in the terminal in which Virgo runs. This is due to the |
| mechanisms which the shell implementation uses to redirect standard output.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-shell-using-vsh"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_using_virgo_shell_commands">Using Virgo Shell Commands</h3> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>This section is not applicable to Virgo Nano.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Virgo provides shell commands |
| that allow you to examine artifacts |
| currently installed in a particular Virgo Kernel instance, manage the lifecycle of the installed artifacts, install new artifacts, and shut down |
| the Virgo Kernel. You can install, examine, and manage the lifecycle of the following artifacts:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Bundles</p> |
| </li> |
| <li> |
| <p>Configuration Artifacts</p> |
| </li> |
| <li> |
| <p>PARs</p> |
| </li> |
| <li> |
| <p>Plans</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>and can examine:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Exported packages</p> |
| </li> |
| <li> |
| <p>Services in the OSGi service registry</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Virgo also provides shell commands to list all bundles that contain, export, or load a particular class.</p> |
| </div> |
| <div class="paragraph"> |
| <p>These commands are provided <strong>for the user region shells only</strong> and are grouped together in |
| the <code>vsh</code> <strong>scope</strong>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You invoke commands using the <code>vsh:</code> scope. For example:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> vsh:plan list |
| |
| Name Version State |
| org.eclipse.virgo.apps.admin.plan 2.1.0 ACTIVE |
| org.eclipse.virgo.kernel.userregion.springdm 2.1.0 ACTIVE |
| org.eclipse.virgo.web 2.1.0 ACTIVE</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-shell-vsh-using-command-list"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_virgo_shell_commands">Virgo Shell Commands</h4> |
| <div class="paragraph"> |
| <p>The following table lists the Virgo shell commands; each command in turn has a variety of options that you can specify, depending on what you want to do, such as start a bundle or refresh a plan. The reference documentation about each command provides the full list of available options.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-shell-vsh-commands-table"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 1. Virgo Shell Commands</caption> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 80%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Command</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#admin-shell-vsh-bundle-command">bundle</a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Manages and displays information about bundle artifacts.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#admin-shell-cl-clhas">clhas</a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Lists all bundles that <emphasis role="bold">contain* a class or resource.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#admin-shell-cl-clexport">clexport</a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Lists all bundles that <emphasis role="bold">export* a class or package.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#admin-shell-cl-clload">clload</a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Lists all bundles that can <emphasis role="bold">load* a class.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#admin-shell-vsh-config-command">config</a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Manages and displays information about configuration artifacts.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#admin-shell-vsh-package-command">packages</a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Displays information about exported packages.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#admin-shell-vsh-par-command">par</a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Manages and displays information about PAR artifacts.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#admin-shell-vsh-plan-command">plan</a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Manages and displays information about plan artifacts.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#admin-shell-vsh-service-command">service</a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Displays information about services in the OSGi service registry.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#admin-shell-vsh-install-command">install</a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Installs an artifact to Virgo Kernel.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#admin-shell-vsh-shutdown-command">shutdown</a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Shuts down the Virgo Kernel instance to which the Equinox Console is connected.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a id="admin-shell-vsh-command-reference"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_virgo_shell_command_reference">Virgo Shell Command Reference</h3> |
| <div class="paragraph"> |
| <p>This section contains reference information about the Virgo shell commands</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#admin-shell-vsh-bundle-command">bundle</a>, |
| <a href="#admin-shell-cl-clhas">clhas</a>, |
| <a href="#admin-shell-cl-clexport">clexport</a>, |
| <a href="#admin-shell-cl-clload">clload</a>, |
| <a href="#admin-shell-vsh-config-command">config</a>, |
| <a href="#admin-shell-vsh-package-command">packages</a>, |
| <a href="#admin-shell-vsh-par-command">par</a>, |
| <a href="#admin-shell-vsh-plan-command">plan</a>, |
| <a href="#admin-shell-vsh-service-command">service</a>, |
| <a href="#admin-shell-vsh-install-command">install</a>, |
| <a href="#admin-shell-vsh-shutdown-command">shutdown</a>, |
| <a href="#admin-shell-vsh-help-command">help</a> and |
| <a href="#admin-shell-vsh-exit-command">exit</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-shell-vsh-bundle-command"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_bundle_command">bundle Command</h4> |
| <div class="paragraph"> |
| <p>Use the <code>bundle</code> command to manage the lifecycle of bundles deployed in Virgo Kernel and to gather information about deployed bundles, such as diagnostic information, header information, and so on. |
| The following table lists the options you can specify for this command.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-shell-vsh-bundle-command-table"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 2. Options of the bundle Command</caption> |
| <colgroup> |
| <col style="width: 16%;"> |
| <col style="width: 83%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Option</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Displays the list of bundles that are currently installed in the current Virgo Kernel instance. With the exception of a few kernel bundles and their services, which Virgo Kernel uses to administer the user region, none of the kernel is visible to user installed artifacts; rather, only the bundles installed in the user region are visible. |
| Each bundle is identified by an internal <code>ID</code> which you can then use with the other <code>bundle</code> commands that manage a particular bundle, such as <code>start `<strong>`id</code></strong>. The <code>list</code> command also displays the version of the bundle, along with its state, which is one of the following standard OSGi lifecycle states: |
| <strong>Installed</strong>: The bundle is installed but its dependencies have not yet been resolved. |
| <strong>Resolved</strong>: The bundle is resolved and you can now start it. |
| <strong>Uninstalled</strong>: The bundle is uninstalled and you cannot use it. |
| <strong>Starting</strong>: The bundle is in the process of starting. |
| <strong>Active</strong>: The bundle is running and you can now use it. |
| <strong>Stopping</strong>: The bundle is in the process of stopping. |
| Use one of the other <code>bundle</code> commands to change the state of a bundle. For example, use the <code>bundle start `<strong>`id</code></strong> command to change the state of a bundle from <code>Installed</code> to <code>Active</code>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">examine <strong>id</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Displays detailed information about the specified bundle. Use the <code>bundle list</code> command to get the internal id of a particular bundle. |
| In addition to the information provided by the <code>bundle list</code> command (id, full name, version, and state), the <code>examine</code> command specifies whether the bundle includes a Spring application context (or is <strong>Spring Powered</strong>) and the exact physical location of the bundle JAR file. |
| The <code>examine</code> also provides the full list of packages that the bundle imports, as well as the bundles that in turn export these imported packages. Finally, the command displays the packages that the current bundle exports, and then in turn the list of other installed bundles that are currently importing these exported packages.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">start <strong>id</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Starts the specified bundle. Use the <code>bundle list</code> command to get the internal id of a particular bundle. |
| After Virgo Kernel successfully starts the bundle, it is listed in the <code>Active</code> state.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">stop <strong>id</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Stops the specified bundle. Use the <code>bundle list</code> command to get the internal id of a particular bundle. |
| When you stop a bundle, it goes from the <code>Active</code> state to the <code>Resolved</code> state, and you must re-start it if you want to use the application that the bundle contains.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">refresh <strong>id</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Updates the contents of the specified bundle. Use the <code>bundle list</code> command to get the internal id of a particular bundle. Use this command if you have changed the contents of the bundle JAR file and you want to refresh the artifact as installed in the OSGi framework.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">uninstall <strong>id</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Uninstalls the specified bundle from Virgo Kernel. Use the <code>bundle list</code> command to get the internal id of a particular bundle. |
| When the uninstall process is complete, the bundle does not show up in the list of bundles displayed by the <code>bundle list</code> command. If you want to use the application in the bundle, you must re-install it using the <code>install</code> command.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">diag <strong>id</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Provides diagnostic information about the specified bundle. |
| In particular, this command displays information about the imported packages that Virgo Kernel could not resolve. |
| Use the <code>bundle list</code> command to get the internal id of a particular bundle. |
| Note that Virgo does not install unresolvable bundles. |
| Instead is takes a state dump (for offline analysis using the web administration console) and fails the deployment. |
| So bundles are only likely to become unresolvable in Virgo after an update operation.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">headers <strong>id</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Displays the complete list of manifest headers of the specified bundle. Use the <code>bundle list</code> command to get the internal id of a particular bundle. |
| The manifest headers include: <code>Import-Package</code>, <code>Export-Package</code>, <code>Bundle-SymbolicName</code>, and so on.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The following examples show how to use this command.</p> |
| </div> |
| <div class="paragraph"> |
| <p>First, use the <code>bundle list</code> command to view all the installed bundles:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> vsh:bundle list |
| |
| Id Name Version State |
| 40 org.eclipse.virgo.kernel.userregionfactory 3.0.0.RELEASE ACTIVE |
| 47 org.eclipse.equinox.cm 1.0.300.v20101204 ACTIVE |
| 48 org.eclipse.virgo.kernel.userregion 3.0.0.RELEASE ACTIVE |
| 49 org.eclipse.virgo.kernel.osgicommand 3.0.0.RELEASE ACTIVE |
| 50 org.eclipse.osgi.services 3.3.0.v20110110 ACTIVE |
| 51 com.springsource.org.apache.mina.core 2.0.2 ACTIVE |
| 52 org.apache.felix.gogo.command 0.8.0.v201105062003 ACTIVE |
| 53 org.apache.felix.gogo.runtime 0.8.0.v201105062003 ACTIVE |
| 54 org.apache.felix.gogo.shell 0.8.0.v201107131313 ACTIVE |
| 55 org.eclipse.equinox.console.supportability 1.0.0.20110722-2 ACTIVE |
| 56 com.springsource.org.apache.sshd.core 0.5.0 ACTIVE |
| 57 org.springframework.osgi.core 1.2.1 ACTIVE |
| 58 S org.springframework.osgi.extender 1.2.1 ACTIVE |
| 59 org.springframework.osgi.io 1.2.1 ACTIVE |
| 60 org.eclipse.virgo.kernel.agent.dm 3.0.0.RELEASE ACTIVE |
| 61 S org.eclipse.virgo.kernel.deployer.dm 3.0.0.RELEASE ACTIVE |
| 62 org.eclipse.equinox.ds 1.3.0.v20110124-0830 ACTIVE |
| 63 org.eclipse.equinox.util 1.0.200.v20100503 ACTIVE |
| 64 com.springsource.org.aopalliance 1.0.0 ACTIVE |
| 65 org.eclipse.virgo.kernel.dmfragment 3.0.0.RELEASE RESOLVED |
| 66 org.springframework.aop 3.0.5.RELEASE ACTIVE |
| 67 org.springframework.asm 3.0.5.RELEASE ACTIVE |
| 68 org.springframework.beans 3.0.5.RELEASE ACTIVE |
| 69 org.springframework.context 3.0.5.RELEASE ACTIVE |
| 70 org.springframework.core 3.0.5.RELEASE ACTIVE |
| 71 org.springframework.expression 3.0.5.RELEASE ACTIVE</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The following example shows how to view the headers of the <code>org.springframework.osgi.extender</code> bundle (only the first few lines are shown):</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> vsh:bundle examine 5 |
| |
| Id: 5 |
| Name: org.springframework.osgi.extender |
| Version 1.2.1 |
| State: ACTIVE |
| Spring Powered: true |
| Bundle Location: file:<... omitted ...>/org.springframework.osgi.extender-1.2.1.jar/ |
| |
| Imported Packages: |
| org.springframework.osgi.context [1.2.1, 1.2.1] |
| exported by org.springframework.osgi.core 1.2.1 [4] |
| <... remainder omitted ...> |
| |
| Exported Packages: |
| org.springframework.osgi.extender 1.2.1 |
| <... remainder omitted ...> |
| |
| Published services: |
| 58 org.springframework.beans.factory.xml.NamespaceHandlerResolver |
| consumed by org.springframework.osgi.extender 1.2.1 [5] |
| consumed by org.eclipse.virgo.kernel.deployer.dm 2.1.0.RELEASE [8] |
| <... remainder omitted ...> |
| |
| Consumed services: |
| 1 org.osgi.service.packageadmin.PackageAdmin |
| published by org.eclipse.osgi 3.7.0.v20110224 [0] |
| <... remainder omitted ...> |
| |
| Fragments: |
| org.eclipse.virgo.kernel.dmfragment 2.1.0.RELEASE [10]</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-shell-vsh-config-command"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_config_command">config Command</h4> |
| <div class="paragraph"> |
| <p>Use the <code>config</code> command to view and manage the configuration artifacts that have been installed in Virgo Kernel. A <strong>configuration artifact</strong> is simply a properties file that is associated with a user application that is contained in a bundle. Using configuration artifacts, you can manage the configuration of a user application completely separately from the bundle that contains the application. |
| The following table lists the options you can specify for this command.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-shell-vsh-config-command-table"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 3. Options of the config Command</caption> |
| <colgroup> |
| <col style="width: 25%;"> |
| <col style="width: 75%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Option</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Lists the configuration artifacts that are currently installed in Virgo Kernel. |
| The <code>list</code> option displays the full name of each installed configuration artifact, its version, and its current state. Configuration artifacts have similar lifecycles to other artifacts, such as bundles, and so the list of states in which a configuration can be in is the same as those of bundles; see <a href="#admin-shell-bundle-command">the bundle command</a> for the list of possible states.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">examine <strong>name [version]</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Displays information about the specified configuration artifact. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed. Use the <code>config list</code> command to view all configuration artifacts and versions currently installed in Virgo Kernel. |
| A configuration artifact must be active for you to examine it; if it is not currently active, use <code>config start</code> to start it and thus change its state to <code>Active</code>. |
| The command first displays the factory pid of the configuration artifact as well as the complete location of the bundle to which the configuration artifact is associated. The command then lists all the properties that make up the configuration, as well as their current value.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">start <strong>name [version]</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Starts the specified configuration artifact and makes it visible to Virgo Kernel. |
| Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the |
| configuration artifact installed (which Virgo does not currently support). |
| Use the <code>config list</code> command to view all configuration artifacts and versions currently installed in Virgo Kernel. |
| Starting the configuration sets its state to <code>Active</code>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">stop <strong>name [version]</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Stops the specified configuration artifact and makes it invisible to Virgo Kernel. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed (which Virgo does not currently support). Use the <code>config list</code> command to view all configuration artifacts and versions currently installed in Virgo Kernel. |
| Stopping the configuration sets its state to <code>Resolved</code>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">refresh <strong>name [version]</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Updates the contents of the specified configuration artifact to Virgo Kernel. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed (which Virgo does not currently support). Use the <code>config list</code> command to view all configuration artifacts and versions currently installed in Virgo Kernel. |
| Use this command if you have changed the contents of the configuration artifact, and you want to make this information known to Virgo Kernel and the associated bundle.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">uninstall <strong>name [version]</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Uninstalls the specified configuration artifact and make it completely unavailable to Virgo Kernel. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed (which Virgo does not currently support). Use the <code>config list</code> command to view all configuration artifacts and versions currently installed in Virgo Kernel. |
| Stopping the configuration removes it from Virgo Kernel’s list of deployed artifacts and it will not show up when you perform a <code>config list</code>.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The following example shows how to use this command to list the installed configuration artifacts.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> vsh:config list |
| |
| Name Version State |
| org.eclipse.virgo.kernel 0.0.0 ACTIVE |
| org.eclipse.virgo.kernel.jmxremote.access 0.0.0 ACTIVE |
| org.eclipse.virgo.kernel.userregion 0.0.0 ACTIVE |
| org.eclipse.virgo.kernel.users 0.0.0 ACTIVE |
| org.eclipse.virgo.medic 0.0.0 ACTIVE |
| org.eclipse.virgo.repository 0.0.0 ACTIVE |
| osgi.console.ssh 0.0.0 ACTIVE |
| osgi.console.telnet 0.0.0 ACTIVE</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>To view the properties of a configuration artifact, and their current values, use <code>config examine</code>:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> vsh:config examine org.eclipse.virgo.repository |
| |
| Factory pid: |
| Bundle Location: file:plugins/org.eclipse.virgo.kernel.services-{version}.jar |
| |
| Properties: |
| chain: |
| ext,usr |
| ext.searchPattern: |
| repository/ext/{artifact} |
| ext.type: |
| external |
| service.pid: |
| org.eclipse.virgo.repository |
| usr.type: |
| watched |
| usr.watchDirectory: |
| repository/usr</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-shell-vsh-package-command"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_packages_command">packages Command</h4> |
| <div class="paragraph"> |
| <p>Use the <code>packages</code> command to view the complete list of packages exported by all bundles installed in Virgo Kernel, as well as examine a particular exported package in more detail.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following table lists the options you can specify for this command.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-shell-vsh-package-command-table"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 4. Options of the packages Command</caption> |
| <colgroup> |
| <col style="width: 25%;"> |
| <col style="width: 75%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Option</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Displays all the exported packages for all bundles in the uer region of Virgo Kernel. In addition to the package name, the command displays the version of the exported package and the <code>id</code> of the bundle that contains the exported package. You can examine the bundle by using the command <code>bundle examine</code> <strong>id</strong>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">examine <strong>name version</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Displays details about the exported package. You must specify both the name of the exported package and its version; use <code>packages list</code> to view the exact names and version.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The <code>examine</code> command provides the following additional information about the exported package:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The name and version of the bundle that exports the package. This means that the package name is explicitly listed in the bundle’s <code>MANIFEST.MF</code> file as part of the <code>Export-Package</code> header.</p> |
| </li> |
| <li> |
| <p>Any attributes that are part of the <code>Export-Package</code>, in addition to <code>version</code>.</p> |
| </li> |
| <li> |
| <p>The directives that are part of the <code>Export-Package</code> header. A typical directive is <code>uses</code>, which declares up-front constraints on a number of other packages.</p> |
| </li> |
| <li> |
| <p>The list of all bundles that import the package.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following example shows how to list all the exported packages for all bundles installed:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> vsh:packages list |
| |
| Name Version Providing Bundle |
| javax.accessibility 0.0.0 0 |
| javax.activation 0.0.0 0 |
| javax.activation 1.1.1 0 |
| <... remainder omitted ...></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The following example shows how to examine a particular exported package:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> vsh:packages examine org.slf4j 1.6.1 |
| |
| Exporter: org.eclipse.virgo.region.user 0.0.0 [1] |
| |
| Attributes: |
| None |
| |
| Directives: |
| uses: |
| org.slf4j.spi |
| x-equinox-ee: |
| -1 |
| x-internal: |
| false |
| |
| Importer(s): |
| org.eclipse.virgo.kernel.agent.dm 2.1.0.RELEASE [7] |
| Import-Package attributes: |
| bundle-version: |
| 0.0.0 |
| version: |
| [1.6.1,2.0.0) |
| Import-Package directives: |
| resolution: |
| static |
| <... remainder omitted ...></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-shell-vsh-par-command"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_par_command">par Command</h4> |
| <div class="paragraph"> |
| <p>Use the <code>par</code> command to view all the PARs currently installed in Virgo Kernel, view details about a particular PAR and manage its lifecycle, such as starting, stopping, refreshing, and uninstalling it. |
| The following table lists the options you can specify for this command.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-shell-vsh-par-command-table"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 5. Options of the par Command</caption> |
| <colgroup> |
| <col style="width: 25%;"> |
| <col style="width: 75%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Option</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Displays all the PARs that are currently installed in Virgo Kernel. |
| The <code>list</code> option displays the full name of each installed PAR, its version, and its current state. PARs have similar lifecycles to other artifacts, such as bundles, and so the list of states in which a PAR can be in is the same as those of bundles; see <a href="#admin-shell-bundle-command">the bundle command</a> for the list of possible states.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">examine <strong>name version</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Displays information about the specified PAR; you are required to identify the PAR with both its name and its version. Use the <code>par list</code> command to view all installed PAR files and their versions. The command displays the following information: |
| The current state of the PAR (see <a href="#admin-shell-vsh-bundle-command">the bundle command</a> for the full list of possible states). |
| Whether the PAR is <strong>scoped</strong>. Scoping specifies whether Virgo Kernel should deploy the members of the PAR in their own scope; when scoping is disabled, Virgo Kernel deploys the artifacts into the global scope and they are accessible for access by all other artifacts. |
| Whether the PAR is <strong>atomic</strong>. When a PAR is atomic, Virgo Kernel manages the lifecycle of all its member artifacts as a single entity, which means if one artifact member is started, then Virgo Kernel starts <strong>all</strong> the PAR artifacts. If one artifact fails to start, then Virgo Kernel stops all other artifacts in the PAR. |
| The individual members, or children, of the PAR. These could be plans, bundles, configuration artifacts, and so on.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">start <strong>name version</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Starts the specified PAR. You must specify both the full name of the PAR as well as the version you want to start. Use the <code>par list</code> command to get the list of PARs currently installed in Virgo Kernel. |
| To start a PAR, it must have already been resolved by Virgo Kernel, or in other words, be in the <code>Resolved</code> state. After Virgo Kernel successfully starts the PAR, it is listed in the <code>Active</code> state.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">stop <strong>name version</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Stops the specified PAR. You must specify both the full name of the PAR as well as the version you want to stop. Use the <code>par list</code> command to get the list of PARs currently installed in Virgo Kernel. |
| When you stop a PAR, it goes from the <code>Active</code> state to the <code>Resolved</code> state, and you must re-start it if you want to use the application that the PAR contains.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">refresh <strong>name version</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Updates the contents of the specified PAR. You must specify both the name and version of the PAR you want to refresh. Use the <code>par list</code> command to this information. |
| Use this command if you have changed the contents of the PAR file and you want to refresh the artifact as installed in the OSGi framework.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">uninstall <strong>name version</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Uninstalls the specified PAR. You must specify both the name and version of the PAR you want to refresh. Use the <code>par list</code> command to this information. |
| When the uninstall process is complete, the PAR will not show up in the list of PARs displayed by the <code>par list</code> command. If you want to use the application in the PAR, you must re-install it using the <code>install</code> command.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The following example shows how to list the PARs that have been installed in Virgo Kernel:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> vsh:par list |
| |
| Name Version State |
| |
| org.eclipse.virgo.server.repository.hosted 2.1.0.RELEASE ACTIVE</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The following example shows how to examine a particular PAR file:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> vsh:par examine org.eclipse.virgo.server.repository.hosted 2.1.0.RELEASE |
| |
| State: ACTIVE |
| Scoped: true |
| Atomic: true |
| |
| Children: |
| bundle org.eclipse.virgo.server.repository.hosted.core 2.1.0.RELEASE |
| bundle org.eclipse.virgo.server.repository.hosted.web 2.1.0.RELEASE |
| bundle org.eclipse.virgo.server.repository.hosted-synthetic.context 2.1.0.RELEASE</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Finally, the following example shows how to refresh an installed PAR file:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> vsh:par refresh my.exciting.par 1.2.0 |
| |
| par my.exciting.par 1.2.0 refreshed successfully</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-shell-vsh-plan-command"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_plan_command">plan Command</h4> |
| <div class="paragraph"> |
| <p>Use the <code>plan</code> command to view all the plans currently installed in Virgo Kernel, view details about a particular plan and manage its lifecycle, such as starting, stopping, refreshing, and uninstalling it. |
| The following table lists the options you can specify for this command.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-shell-vsh-plan-command-table"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 6. Options of the plan Command</caption> |
| <colgroup> |
| <col style="width: 25%;"> |
| <col style="width: 75%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Option</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Displays all the plans that are currently installed in Virgo Kernel. |
| The <code>list</code> option displays the full name of each installed plan, its version, and its current state. Plans have similar lifecycles to other artifacts, such as bundles, and so the list of states in which a plan can be in is the same as those of bundles; see <a href="#admin-shell-bundle-command">the bundle command</a> for the list of possible states.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">examine <strong>name version</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Displays information about the specified plan; you are required to identify the plan with both its name and its version. Use the <code>plan list</code> command to view all installed plans and their versions. The command displays the following information: |
| The current state of the plan (see <a href="#admin-shell-vsh-bundle-command">the bundle command</a> for the full list of possible states). |
| Whether the plan is <strong>scoped</strong>. Scoping specifies whether Virgo Kernel should deploy the members of the plan in their own scope; when scoping is disabled, Virgo Kernel deploys the artifacts into the global scope and they are accessible for access by all other artifacts. |
| Whether the plan is <strong>atomic</strong>. When a plan is atomic, Virgo Kernel manages the lifecycle of all its member artifacts as a single entity, which means if one artifact member is started, then Virgo Kernel starts <strong>all</strong> the plan artifacts. If one artifact fails to start, then Virgo Kernel stops all other artifacts in the plan. |
| The individual members, or children, of the plan. These could be other plans, PARs, bundles, configuration artifacts, and so on.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">start <strong>name version</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Starts the specified plan. You must specify both the full name of the plan as well as the version you want to start. Use the <code>plan list</code> command to get the list of plans currently installed in Virgo Kernel. |
| To start a plan, it must have already been resolved by Virgo Kernel, or in other words, be in the <code>Resolved</code> state. After Virgo Kernel successfully starts the plan, it is listed in the <code>Active</code> state.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">stop <strong>name version</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Stops the specified plan. You must specify both the full name of the plan as well as the version you want to stop. Use the <code>plan list</code> command to get the list of plans currently installed in Virgo Kernel. |
| When you stop a plan, it goes from the <code>Active</code> state to the <code>Resolved</code> state, and you must re-start it if you want to use the application that the plan contains.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">refresh <strong>name version</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Updates the contents of the specified plan. You must specify both the name and version of the plan you want to refresh. Use the <code>plan list</code> command to this information. |
| Use this command if you have changed the contents of the plan file and you want to refresh the artifact as installed in the OSGi framework.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">uninstall <strong>name version</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Uninstalls the specified plan. You must specify both the name and version of the plan you want to refresh. Use the <code>plan list</code> command to this information. |
| When the uninstall process is complete, the plan will not show up in the list of plans displayed by the <code>plan list</code> command. If you want to use the application in the plan, you must re-install it using the <code>install</code> command.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The following example shows how to list the plans that have been installed in Virgo Kernel:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> vsh:plan list |
| |
| Name Version State |
| org.eclipse.virgo.apps.admin.plan 2.1.0 ACTIVE |
| org.eclipse.virgo.kernel.userregion.springdm 2.1.0 ACTIVE |
| org.eclipse.virgo.web 2.1.0 ACTIVE</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The following example shows how to examine a particular plan:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> vsh:plan examine org.eclipse.virgo.kernel.userregion.springdm 2.1.0 |
| |
| State: ACTIVE |
| Scoped: false |
| Atomic: false |
| |
| Children: |
| bundle org.eclipse.virgo.kernel.agent.dm 2.1.0.RELEASE |
| bundle org.springframework.osgi.io 1.2.1 |
| bundle org.springframework.osgi.extender 1.2.1 |
| bundle org.springframework.osgi.core 1.2.1 |
| bundle org.eclipse.virgo.kernel.deployer.dm 2.1.0.RELEASE</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The following example shows how to stop a currently Active plan:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> vsh:plan stop org.eclipse.virgo.web 2.1.0 |
| |
| plan org.eclipse.virgo.web:2.1.0 stopped successfully</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The following example shows how to start a plan:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> vsh:plan start org.eclipse.virgo.web 2.1.0 |
| |
| plan org.eclipse.virgo.web:2.1.0 started successfully</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-shell-vsh-service-command"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_service_command">service Command</h4> |
| <div class="paragraph"> |
| <p>Use the <code>service</code> command to view all the services that have been registered in the OSGi service registry of Virgo Kernel. You can also examine a specific service to discover its properties, the bundle that publishes the service, and any bundles that consume the service. |
| The following table lists the options you can specify for this command.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-shell-vsh-service-command-table"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 7. Options of the service Command</caption> |
| <colgroup> |
| <col style="width: 25%;"> |
| <col style="width: 75%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Option</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Displays the list of services that are currently registered in the OSGi service registry of Virgo Kernel. |
| Each service is identified by an internal <code>ID</code> which you can then use with the <code>service examine</code> command to view the details about a particular service. The <code>list</code> option also displays the object class that implements the service and the internal <code>id</code> of the bundle that provides the service.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">examine <strong>id</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Displays detailed information about the specified service. Use the <code>service list</code> command to get the internal id of a particular service. |
| This command displays the properties of the service, such as the object class that implements the service, the name of the bundle that publishes the service and any bundles that consume the service.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The following example shows how to list the services currently registered in the OSGi service registry:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> vsh:service list |
| |
| Id Object Class(es) Providing Bundle |
| |
| 1 org.osgi.service.packageadmin.PackageAdmin 0 |
| 2 org.osgi.service.permissionadmin.PermissionAdmin, ... 0 |
| 3 org.osgi.service.startlevel.StartLevel 0 |
| 4 org.eclipse.osgi.service.debug.DebugOptions 0 |
| 5 java.lang.ClassLoader 0 |
| 6 org.eclipse.osgi.framework.log.FrameworkLog 0 |
| 7 org.eclipse.osgi.framework.log.FrameworkLog 0 |
| <... remainder omitted ...> |
| |
| 72 org.eclipse.gemini.web.core.spi.ServletContainer 38 |
| 73 org.eclipse.gemini.web.core.WebContainer 37 |
| 74 org.eclipse.virgo.web.core.WebApplicationRegistry 39 |
| <... remainder omitted ...></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The following example shows how to examine a particular service:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> vsh:service examine 73 |
| |
| Properties: |
| objectClass: |
| org.eclipse.gemini.web.core.WebContainer |
| service.id: |
| 73 |
| |
| Publisher: org.eclipse.gemini.web.core 1.1.0.RELEASE [37] |
| |
| Consumer(s): |
| org.eclipse.virgo.web.core 2.1.0.RELEASE [39]</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-shell-vsh-install-command"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_install_command">install Command</h4> |
| <div class="paragraph"> |
| <p>Use the <code>install</code> command to deploy an artifact to Virgo Kernel. The artifact can be a bundle, PAR, plan, or configuration artifact.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>install</code> command takes a single parameter: the URI of the artifact you want to deploy. For example, to deploy a bundle on the local computer, use the <code>file</code> scheme:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>file://full-pathname-to-artifact</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>After you execute the <code>install</code> command, Virgo Kernel attempts to resolve the artifact’s dependencies, and if it is successful, puts it in the <code>Resolved</code> state. At that point, you must start the artifact to be able to actually use it.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following example shows how to install a bundle called <code>swf-booking-mvc.war</code> located in the <code>/home/apps</code> directory of the computer on which the Equinox Console Extension is being run:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> vsh:install file://home/apps/swf-booking-mvc.war |
| ... |
| Artifact bundle swf-booking-mvc.war 0.0.0 installed</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This command is particularly useful for installing an artifact from the Virgo repository, in which case use the <code>repository:</code> scheme:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>repository:artifact-type/bundle-symbolic-name/bundle-version</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>For example:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> vsh:install repository:bundle/my.bundle/1.0 |
| ... |
| Artifact bundle my.bundle 1.0.0 installed</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The following example shows how to use the <code>bundle list</code> command to ensure that the bundle was indeed installed in Virgo Kernel; if you had installed a different kind of artifact, for example a plan, then you would use the appropriate command (such as <code>plan list</code>):</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> vsh:bundle list |
| |
| Id Name Version State |
| |
| 0 org.eclipse.osgi 3.6.1.R36x_v20100806 ACTIVE |
| 1 org.eclipse.virgo.region.user 0.0.0 ACTIVE |
| <... remainder omitted ...> |
| |
| 59 org.eclipse.virgo.server.splash 2.1.0.RELEASE ACTIVE |
| 60 swf-booking-mvc.war 0.0.0 RESOLVED</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Note that the <code>swf-booking-mvc.war</code> file is in the <code>Resolved</code> state. The following examples start the bundle, and then examine it to ensure that it is in the <code>Active</code> state:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> vsh:bundle start 60 |
| |
| bundle swf-booking-mvc.war:0.0.0 started successfully |
| |
| |
| osgi> vsh:bundle examine 60 |
| |
| Id: 60 |
| Name: swf-booking-mvc.war |
| Version 0.0.0 |
| State: ACTIVE |
| Spring Powered: true |
| Bundle Location: file:<... omitted ...>/swf-booking-mvc.war/ |
| |
| Imported Packages: |
| javax.crypto.interfaces [0.0.0, 0.0.0] |
| exported by org.eclipse.osgi 3.6.1.R36x_v20100806 [0] |
| org.omg.CosNaming.NamingContextPackage [0.0.0, 0.0.0] |
| exported by org.eclipse.osgi 3.6.1.R36x_v20100806 [0] |
| org.omg.DynamicAny.DynAnyFactoryPackage [0.0.0, 0.0.0] |
| exported by org.eclipse.osgi 3.6.1.R36x_v20100806 [0] |
| <... remainder omitted ...> |
| |
| osgi></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-shell-vsh-shutdown-command"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_shutdown_command">shutdown Command</h4> |
| <div class="paragraph"> |
| <p>Use the <code>shutdown</code> command to shut down the Virgo Kernel instance to which you are connected. When Virgo Kernel is shut down, the shell returns you to the operating system prompt. |
| The <code>shutdown</code> command does not have any options.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following example shows how to use this command.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> vsh:shutdown |
| osgi> ... |
| Connection closed by foreign host. |
| $</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-shell-cl-clhas"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_clhas_command">clhas command</h4> |
| <div class="paragraph"> |
| <p>Use the <code>clhas</code> command to list the entries contained in the bundles deployed in Virgo and to solve class loading issues. |
| The command accepts as a parameter a search pattern in the form <strong>path/resource</strong>. The resource part of the pattern can contain wildcards. |
| The output contains all bundles that have resources or classes matching the pattern. Since wildcards are allowed, the matching entities are listed as well.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following examples show how to use this command. |
| Use the <code>clhas</code> to view all bundles that contain <code>Servlet</code> class:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi>clhas /javax/servlet/Servlet.class |
| |
| Bundles containing [/javax/servlet/Servlet.class]: |
| 76 javax.servlet |
| /javax/servlet/Servlet.class</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Use the wildcard <code>*</code> with <code>clhas</code> to view all classes starting with <code>Servlet</code>:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> clhas /javax/servlet/Servlet* |
| |
| Bundles containing [/javax/servlet/Servlet*]: |
| 76 javax.servlet |
| /javax/servlet/ServletRequestAttributeEvent.class |
| /javax/servlet/ServletRequest.class |
| <... remainder omitted ...> |
| /javax/servlet/Servlet.class |
| <... remainder omitted ...></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>clhas</code> command can also be used with class name instead of resource path:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> clhas javax.servlet.Servlet |
| |
| Bundles containing [javax/servlet/Servlet.class]: |
| 76 javax.servlet |
| /javax/servlet/Servlet.class</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Please note that the command converts the class name to a path and appends <code>class</code> extension by default. |
| To search for a resource with an extension different than <code>class</code> you should use the resource path form:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> clhas /LocalStrings.properties |
| |
| Bundles containing [/LocalStrings.properties]: |
| 96 com.springsource.org.apache.catalina |
| /org/apache/catalina/core/LocalStrings.properties |
| /org/apache/tomcat/util/http/mapper/LocalStrings.properties |
| /org/apache/catalina/loader/LocalStrings.properties |
| <... remainder omitted ...></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The following example shows how to identify a possible <code>ClassCastException</code> due to wrong packaging:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi>clhas /javax/servlet/Servlet.class |
| |
| Bundles containing [/javax/servlet/Servlet.class]: |
| 76 javax.servlet |
| /javax/servlet/Servlet.class |
| 107 myapp |
| /WEB-INF/classes/javax/servlet/Servlet.class</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>It’s obvious that the <code>javax.servlet</code> package should not be present in <code>myapp</code> application and its packaging has to be changed. This problem can often be seen in WAR or web bundles that package Servlet/JSP classes by accident.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-shell-cl-clexport"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_clexport_command">clexport command</h4> |
| <div class="paragraph"> |
| <p>Use the <code>clexport</code> command to list the bundles that export a class or package. |
| The command accepts as a parameter the fully qualified class name (in the form <strong>package.class</strong>). |
| The command checks to see if the provided class is actually contained in a bundle. If the class is not found in a bundle but its package is exported, then a hint <code>[class not found, package only]</code> is displayed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following examples show how to use this command. |
| Use the <code>clexport</code> to view all bundles that contain <code>Servlet</code> class:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> clexport javax.servlet.Servlet |
| |
| Bundles exporting [javax.servlet.Servlet]: |
| 14 com.springsource.javax.servlet</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If a bundle exports a package but does not contain the requested class, the output of the command will be similar to this:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> clexport javax.servlet.ServletX |
| |
| Bundles exporting [javax.servlet.ServletX]: |
| 14 com.springsource.javax.servlet [class not found, package only]</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-shell-cl-clload"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_clload_command">clload command</h4> |
| <div class="paragraph"> |
| <p>Use the <code>clload</code> command to list the bundles that can load a class or to check if a specific bundle can load a class. |
| The command accepts as parameters either:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>the fully qualified class name (in the form <strong>package.class</strong>)</p> |
| </li> |
| <li> |
| <p>the fully qualified class name (in the form <strong>package.class</strong>) and the symbolic name or id of the bundle that is to be tested</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The command lists not only the bundle that successfully loaded the class, but also the one that actually provides the class. This is visualized with hints like <code>[exported by 14 com.springsource.javax.servlet]</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following examples show how to use this command. |
| You can use the <code>clload</code> to view all bundles that can load <code>Servlet</code> class:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> clload javax.servlet.Servlet |
| |
| Successfully loaded [javax.servlet.Servlet] from: |
| 56 com.springsource.org.apache.taglibs.standard |
| [exported by 14 com.springsource.javax.servlet] |
| 54 org.eclipse.virgo.apps.admin.web |
| [exported by 14 com.springsource.javax.servlet] |
| 19 com.springsource.org.apache.commons.fileupload |
| [exported by 14 com.springsource.javax.servlet] |
| <... remainder omitted ...></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If a bundle is to be tested, then its id can be used as a command parameter:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> clload javax.servlet.Servlet 19 |
| |
| Successfully loaded [javax.servlet.Servlet] using class loader from: |
| 19 com.springsource.org.apache.commons.fileupload |
| [exported by 14 com.springsource.javax.servlet]</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Or the same class load test can specify the symbolic name of the bundle:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> clload javax.servlet.Servlet com.springsource.org.apache.commons.fileupload |
| |
| Successfully loaded [javax.servlet.Servlet] using class loader from: |
| 19 com.springsource.org.apache.commons.fileupload |
| [exported by 14 com.springsource.javax.servlet]</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="p2-commands"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_using_the_p2_for_extending_your_virgo_installation">Using the p2 for extending your Virgo installation</h3> |
| <div class="sect3"> |
| <h4 id="_extending_with_the_p2_director">Extending with the p2 director</h4> |
| <div class="paragraph"> |
| <p>You can provision new features on top of your Virgo installation using the p2 director. It can be used both for initial provisioning and extending an existing installtion.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For extending an existing installation you can use these director arguments:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>-repository http://download.eclipse.org/rt/ecf/3.5.3/site.p2 |
| -installIU org.eclipse.ecf.remoteservice.feature.feature.group |
| -destination <your {virgo-name} installation folder></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This installs the <strong>latest</strong> version of the specified p2 feature in your Virgo installation’s p2 profile.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_extending_via_the_p2_shell_commands">Extending via the p2 shell commands</h4> |
| <div class="paragraph"> |
| <p>Another way to achieve the same results is to use the p2 commands. The commands are available only in VN as it includes p2 by default.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>For the other distributions only the director is supported and the operation only extends their kernel region.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Here’s a list of the most commonly used p2 commands:</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="p2-common-commands-table"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 8. p2 Common Shell Commands</caption> |
| <colgroup> |
| <col style="width: 25%;"> |
| <col style="width: 75%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Command</th> |
| <th class="tableblock halign-left valign-top">Help</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>provaddrepo <repository URI></code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Add specified URI as metadata and artifact repository. Note that if you pass a wrong URL you’ll get an error saying: |
| <code>Repository not modifiable: <a href="http://wrongURL" class="bare">http://wrongURL</a></code>. The default behavior of this command is to create an empty repository at the |
| specified location if there isn’t any. That won’t work for remote locations so keep in mind that if you see this you probably passed a wrong URL.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>provdelrepo <repository URI></code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Remove specified metadata and artifact repository.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>provinstall <InstallableUnit> <version> <profileid></code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Install an IU to the profileid. If no profileid is given, installs into default profile.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>provremove <InstallableUnit> <version> <profileid></code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Uninstall an IU from the profileid. If no profileid is given, uninstalls form default profile.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>provlg [<repository URI | *> <iu id | *> <version range | *>]</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Lists all IUs with group capabilities in the given repo or in all repos if URI is omitted.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>provliu [<repository URI | *> <iu id | *> <version range | *>]</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Lists the IUs that match the pattern in the given repo. * matches all.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>confapply</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This is a Simple Configurator command, not a p2 one. However it is relevant because it applies dynamically, at runtime, the installed p2 features. |
| What the command does is to apply to the running OSGi framework the current content in the bundles.info file. When using the provinstall command it takes care of updating the bundles.info file.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Here’s an example showing how to install the ECF remote services but with the p2 commands this time:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>osgi> provaddrepo http://download.eclipse.org/rt/ecf/3.5.3/site.p2 |
| |
| osgi> provlg |
| |
| org.eclipse.ecf.core.feature.group 3.5.3.v20111109-2142 |
| org.eclipse.ecf.core.featurepatch.feature.group 3.5.3.v20111109-2142 |
| org.eclipse.ecf.core.featurepatch.source.feature.group 3.5.3.v20111109-2142 |
| org.eclipse.ecf.core.source.feature.group 3.5.3.v20111109-2142 |
| org.eclipse.ecf.datashare.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.datashare.source.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.discovery.dnssd.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.discovery.dnssd.source.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.discovery.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.discovery.jmdns.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.discovery.jmdns.source.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.discovery.slp.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.discovery.slp.source.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.discovery.source.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.discovery.zookeeper.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.discovery.zookeeper.source.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.eventadmin.examples.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.eventadmin.examples.source.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.eventadmin.feature.feature.group 2.0.0.v20111109-2142 |
| org.eclipse.ecf.eventadmin.source.feature.feature.group 2.0.0.v20111109-2142 |
| org.eclipse.ecf.osgi.services.feature.feature.group 2.0.1.v20111109-2142 |
| org.eclipse.ecf.osgi.services.source.feature.feature.group 2.0.1.v20111109-2142 |
| org.eclipse.ecf.remoteservice.examples.feature.feature.group 1.1.0.v20111109-2142 |
| org.eclipse.ecf.remoteservice.examples.source.feature.feature.group 1.1.0.v20111109-2142 |
| org.eclipse.ecf.remoteservice.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.remoteservice.rest.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.remoteservice.rest.source.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.remoteservice.rosgi.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.remoteservice.rosgi.source.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.remoteservice.sdk.feature.feature.group 3.5.3.v20111109-2142 |
| org.eclipse.ecf.remoteservice.sdk.source.feature.feature.group 3.5.3.v20111109-2142 |
| org.eclipse.ecf.remoteservice.soap.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.remoteservice.soap.source.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.remoteservice.source.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.server.generic.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.server.generic.source.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.xmpp.feature.feature.group 1.0.0.v20111109-2142 |
| org.eclipse.ecf.xmpp.source.feature.feature.group 1.0.0.v20111109-2142 |
| |
| osgi> provinstall org.eclipse.ecf.remoteservice.feature.feature.group 1.0.0.v20111109-2142 |
| Installation complete for org.eclipse.ecf.remoteservice.feature.feature.group 1.0.0.v20111109-2142 |
| |
| osgi> confapply |
| |
| osgi> ss |
| |
| "Framework is launched." |
| |
| |
| id State Bundle |
| 0 ACTIVE org.eclipse.osgi_3.7.1.R37x_v20110808-1106 |
| ... |
| 92 RESOLVED org.springframework.osgi.io_1.2.1 |
| 93 RESOLVED org.eclipse.ecf.console_1.0.0.v20111109-2142 |
| 94 RESOLVED org.eclipse.ecf.discovery_4.0.0.v20111109-2142 |
| 95 RESOLVED org.eclipse.ecf.provider_4.2.100.v20111109-2142 |
| 96 RESOLVED org.eclipse.ecf.provider.discovery_2.1.200.v20111109-2142 |
| 97 RESOLVED org.eclipse.ecf.provider.remoteservice_4.0.0.v20111109-2142 |
| 98 RESOLVED org.eclipse.ecf.remoteservice_6.0.200.v20111109-2142 |
| 99 RESOLVED org.eclipse.ecf.sharedobject_2.2.100.v20111109-2142 |
| 100 RESOLVED org.eclipse.equinox.concurrent_1.0.200.v20110502</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>You can see that after applying the changes with <strong>confapply</strong> the remote services bundles and their dependencies are installed in VN. |
| :virgo-name: Virgo |
| :version: 3.7.0.RC01</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-console"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_the_web_admin_console">The Web Admin Console</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The Admin Console</p> |
| </div> |
| <div class="paragraph"> |
| <p>The Web Server Admin Console is a Web application for managing a single instance of Virgo for Apache Tomcat or Virgo Jetty Server |
| (referred to, generically, as "Web Server" below). Using the Admin Console, you can:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#admin-console-login">View an overview of the Web Server properties</a>.</p> |
| </li> |
| <li> |
| <p><a href="#admin-console-manage-artifacts">View and manage the lifecycle</a> of artifacts already deployed to the Web Server instance. Artifacts include bundles, configuration files, PARs, and plans. Lifecycle management tasks include starting, stopping, refreshing, and uninstalling the artifacts.</p> |
| </li> |
| <li> |
| <p><a href="#admin-console-install-artifacts">Install new artifacts to Web Server</a>.</p> |
| </li> |
| <li> |
| <p><a href="#admin-console-view-properties">View the properties of the configuration artifacts</a> deployed to Web Server.</p> |
| </li> |
| <li> |
| <p><a href="#admin-console-view-dumps">View details of dump files</a> that Web Server might have generated after encountering a problem. This feature is particularly valuable if Web Server fails to install a new artifact due to resolution failures; the OSGi state inspector can help you discover the exact artifact causing the resolution failure.</p> |
| </li> |
| <li> |
| <p><a href="#admin-console-view-osgi-state">View an overview and details of the OSGi State</a> of Web Server, or in other words, a list of all bundles currently installed in Web Server and their state. You can then drill down into the details of each bundle, such as its symbolic name, packages it imports and exports, services it provides and consumes, and so on. You can also view the bundles that were deployed when an exception that generated a dump occurred.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>This section is not applicable to Virgo Nano.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>ancor:admin-console-login[]</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_invoking_the_admin_console">Invoking the Admin Console</h3> |
| <div class="paragraph"> |
| <p>To use the Admin Console, start the |
| Virgo for Apache Tomcat and then enter the following URL in your |
| browser of choice.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>http://localhost:8080/admin</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Replace <code>localhost</code> with the hostname of the computer on which the Virgo for Apache Tomcat is running if it is not the same as the computer on which you are running your browser. |
| The Admin Console uses basic authentication, therefore you will need to enter the default administration ID and password.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>ID: admin |
| Password: admin</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The following graphic shows the main page of the Admin Console.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/console-main-page.png"" alt="console main page"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>Use the links at the top of the console to perform various tasks, such as viewing and managing artifacts (<emphasis role="bold">Artifacts*), viewing the properties of deployed configuration artifacts (<emphasis role="bold">Configuration*), viewing details of dumps (<emphasis role="bold">Dump Inspector*), and viewing the OSGi state of the Web Server instance (<emphasis role="bold">OSGi State*).</p> |
| </div> |
| <div class="paragraph"> |
| <p>You can always return to the main Admin Console page by clicking <emphasis role="bold">Information* in the top right-hand corner.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>The `Server Properties` section provides information about Web Server itself, such as details about the Java Virtual Machine (JVM), the operating system on which Web Server is installed, the time zone configured for the computer, and the complete version of Web Server.</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-console-auth"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_changing_the_admin_user">Changing the Admin User</h4> |
| <div class="paragraph"> |
| <p>To change the ID and password for the Admin Console, update the <code>SERVER_HOME/configuration/org.eclipse.virgo.kernel.users.properties</code> file. First specify the administration username by changing the value of the <code>role.admin</code> property. Then set the password of this new user by adding a new property called <code>user.<strong>username</strong></code>, where <code><strong>username</strong></code> refers to the actual name of the user. Finally, restart Web Server for the changes to take effect. |
| For example, if you want change the administration username to <code>juliet</code> with password <code>capulet</code>, change the file as follows:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">################## |
| # User definitions |
| ################## |
| user.juliet=capulet |
| |
| |
| ################## |
| # Role definitions |
| ################## |
| role.admin=juliet</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The Admin Console always runs against the <code>admin</code> role.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-console-tasks"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_typical_admin_console_use_cases">Typical Admin Console Use Cases</h3> |
| <div class="paragraph"> |
| <p>The following use cases describe the typical tasks that you can perform with the Admin Console:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#admin-console-manage-artifacts">View and Manage the Lifecycle of Deployed Artifacts</a></p> |
| </li> |
| <li> |
| <p><a href="#admin-console-install-artifacts">Install a New Artifact</a></p> |
| </li> |
| <li> |
| <p><a href="#admin-console-view-properties">View the Properties of Deployed Configuration Artifacts</a></p> |
| </li> |
| <li> |
| <p><a href="#admin-console-view-dumps">View Details of Dump Files</a></p> |
| </li> |
| <li> |
| <p><a href="#admin-console-view-osgi-state">View Overview and Details of the OSGi State</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-console-manage-artifacts"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_viewing_and_managing_the_lifecycle_of_deployed_artifacts">Viewing and Managing the Lifecycle of Deployed Artifacts</h4> |
| <div class="paragraph"> |
| <p>The following procedure describes how to view the list of artifacts that are currently deployed in the user region of Web Server. It then describes how to stop, start, refresh, and uninstall the deployed artifacts.</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>From the main Admin Console page, click the <strong>Artifacts</strong> link at the top. |
| In the lower part of the page, the console displays a tree structure that displays the four kinds of artifacts that you can deploy to the user region of Web Server: bundles, configuration files, PARs, and plans. When you first install Web Server, there will already be a number of artifacts deployed related to the Admin console itself, the main splash screen, the repository, and so on. |
| The following graphic shows an expanded tree that displays a few of the deployed artifacts: |
| <span class="image"><img src="assets/images/console-artifacts.png" alt="console artifacts"></span></p> |
| </li> |
| <li> |
| <p>To view details of a particular artifact, click the "`" to the left of the artifact to expand the tree. The following graphic shows an expanded <code>org.eclipse.virgo.apps.admin.web</code> bundle: |
| <span class="image"><img src="assets/images/console-bundle-details.png" alt="console bundle details"></span> |
| The particular details that the Admin Console displays depends on the artifact. For example, for all artifacts you can view their state and how it was installed (such as by a user using the Admin Console or programmatically). The two most common states are Active (running and ready to be used) and Resolved (all dependencies resolved but you must start it before you can use it). An artifact can also be in one of the transition states, such as Starting and Stopping. |
| As shown in the preceding graphic, the Admin Console provides a link for Web modules that you can click on to actually invoke the application (<code>org.eclipse.virgo.web.contextPath:/admin</code> in the example above). |
| For PARs and plans, the Admin Console also displays whether the artifact is:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>Scoped</strong>. Scoping specifies whether Web Server should deploy the members of the PAR/plan in their own scope; when scoping is disabled, Web Server deploys the artifacts into the global scope and they are accessible by all other artifacts.</p> |
| </li> |
| <li> |
| <p><strong>Atomic</strong>. When a PAR/plan is atomic, Web Server manages the lifecycle of all its member artifacts as a single entity, which means if one artifact member is started, then Web Server starts all the PAR/plan artifacts. If one artifact fails to start, then Web Server stops all other artifacts in the PAR/plan.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>The following graphic shows details of a PAR, in particular that it is both scoped and atomic: |
| <span class="image"><img src="assets/images/console-par-details.png" alt="console par details"></span> |
| Finally, for bundles, PARs, and plans, you can see the list of bundles that they depend on; this typically means the bundles that export the packages that they import.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To manage the lifecycle of an artifact, click on its name in the expanded tree to enable the lifecycle buttons. Then, depending on the current state of the artifact, you can:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Start the artifact. All dependencies of the artifact must have been resolved for you to start it. After successfully starting the artifact, it is in the Active state and you can use the application associated with the artifact.</p> |
| </li> |
| <li> |
| <p>Stop the artifact. This moves the artifact from an Active to Resolved state, and you cannot use the application associated with the artifact.</p> |
| </li> |
| <li> |
| <p>Refresh the artifact. This action updates the physical contents of the artifact; use this button when you have changed the artifact in some way and you want your changes to take effect.</p> |
| </li> |
| <li> |
| <p>Uninstall the artifact. This action removes the artifact from Web Server and it does not show up in the Admin Console any more. To use the application associated with this artifact, you must re-install the artifact.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-console-install-artifacts"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_installing_a_new_artifact">Installing a New Artifact</h4> |
| <div class="paragraph"> |
| <p>The following procedure describes how to install a new artifact (bundle, PAR, plan, or configuration file.) The procedure is similar for all types of artifacts; the procedure uses a WAR file as an example.</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>From the main Admin Console page, click the <strong>Artifacts</strong> link at the top.</p> |
| </li> |
| <li> |
| <p>Click the <strong>Browse</strong> button to invoke the file loader application for your platform. Note that the Browse button searches the computer that is running the browser in which you invoked the Admin Console and <strong>not</strong> the computer on which Web Server is running, in the case where they are different. |
| Use the file loader to find the artifact. This can be a WAR or JAR file bundle, a configuration artifact that contains properties, an XML file that corresponds to a plan, or a PAR file.</p> |
| </li> |
| <li> |
| <p>Click <strong>Upload</strong> to actually upload the artifact to Web Server. |
| Web Server automatically attempts to resolve all dependencies, and then puts the artifact in an Active state if possible. If all is successful, the message <code>Artifact Deployed</code> appears next to the <emphasis role="bold">Artifact Console* header. If there is an error, a message to that effect is displayed; to get more details about the error, see the terminal window from which you started Web Server.</p> |
| </li> |
| <li> |
| <p>Expand the artifact tree to view your newly deployed artifact. If Web Server installed it without errors, it should show up in the appropriate section and be in an Active state.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-console-view-properties"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_viewing_properties_of_deployed_configuration_artifacts">Viewing Properties of Deployed Configuration Artifacts</h3> |
| <div class="paragraph"> |
| <p>The following procedure describes how you can view the list of configuration artifacts that are currently deployed to Web Server, and then view the specific properties that are defined for a particular configuration artifact.</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>From the main Admin Console page, click the <emphasis role="bold">Configuration* link at the top. |
| The Admin Console displays all the configuration artifacts that are currently deployed, as shown in the following graphic: |
| <span class="image"><img src="assets/images/console-configuration-details.png" alt="console configuration details"></span></p> |
| </li> |
| <li> |
| <p>To view the properties defined for a particular configuration artifact click the arrow to the left of its name.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-console-view-dumps"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_viewing_the_details_of_dump_files">Viewing the Details of Dump Files</h4> |
| <div class="paragraph"> |
| <p>The following procedure describes how to view the details of any service dumps that have occurred in Web Server. Each time a dump is triggered for Web Server, the server creates a directory in <code>$SERVER_HOME/serviceability/dump</code> with a name corresponding to the time the dump occurred, and then the server populates the directory with detailed information. Using the Admin Console, you can easily view this information. |
| A service dump is triggered when there is either a failure in the Web Server code or Web Server detects a thread deadlock in either its own code or a user application. The service dump contains a snapshot of all the important state from the running Web Server instance. <emphasis role="bold">NOTE:* This snapshot is not intended for end user consumption but is useful for service personnel.</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>From the main Admin Console page, click the <strong>Dump Inspector</strong> link at the top.</p> |
| </li> |
| <li> |
| <p>In the drop-down box on the left, select the dump you want to inspect based on its timestamp.</p> |
| </li> |
| <li> |
| <p>Click <strong>Select Dump</strong>.</p> |
| </li> |
| <li> |
| <p>In the right drop-down box, select the type of dump information you want to view. |
| For example, <code>summary.txt</code> provides a short summary of why the dump might have occurred. The <code>thread.txt</code> option provides information about the state of the Web Server threads at the time of the dump, including any that were deadlocked. The <code>repository</code> options provide information about what was in the external and user repositories at the time of the dump. The <code>configurationAdmin.properties</code> option provides a snapshot of the complete configuration of Web Server, including the kernel and repositories.</p> |
| </li> |
| <li> |
| <p>Click <strong>Select Entry</strong>. |
| The Admin Console displays the information in the Dump Entry Viewer, as shown in the following graphic: |
| <span class="image"><img src="assets/images/console-dump-details.png" alt="console dump details"></span></p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>Note that the dump entry <code>osgi.zip</code> is a binary OSGi state dump which should be viewed as described in |
| <a href="#admin-console-view-osgi-state">Viewing Overview and Details of the OSGi State</a>. |
| Dumps may contain other binary entries which are not intended for viewing via the dump inspector. |
| For example, <code>heap.out</code> contains a dump of the Java heap and <code>region.digraph</code> |
| contains a dump of the sharing policy between kernel and use region (this is used by the OSGi state dump inspector).</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="admin-console-view-osgi-state"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_viewing_overview_and_details_of_the_osgi_state">Viewing Overview and Details of the OSGi State</h4> |
| <div class="paragraph"> |
| <p>The following procedure describes how you can view the OSGi state of the Web Server, either currently or at the time that a particular service dump |
| occurred.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The OSGi state is a list of bundles that are currently installed. When viewing the current state, additional information is available |
| such as whether each bundle is Spring powered and a list of services in the OSGi service registry. This additional information is not available |
| when viewing a state dump.</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>From the main Admin Console page, click the <strong>OSGi State</strong> link at the top. |
| By default, the Admin Console displays the complete list of bundles that are currently installed in Web Server. |
| For each bundle, the console displays its internal ID, its symbolic name, its version, and its current state (usually either Active or Resolved.)</p> |
| </li> |
| <li> |
| <p>To view the bundles that were installed at the time of a service dump, select the service dump based on its timestamp from the drop-down box on the |
| right and click <strong>Go</strong>.</p> |
| </li> |
| <li> |
| <p>To view details about a particular bundle, click on its bundle ID. A full description of the bundle is displayed, as shown in the following graphic: |
| <span class="image"><img src="assets/images/console-osgi-state.png" alt="console osgi state"></span> |
| The console displays again the symbolic name, version, and internal ID of the bundle. It then displays whether the bundle is Spring powered and the exact physical location of the bundle JAR file on the computer that hosts Web Server. |
| The console then displays the full list of packages that the bundle imports, as well as the bundles that in turn export these imported packages. The console also displays the packages that the current bundle exports, and then in turn the list of other installed bundles that are currently importing these exported packages. For each package, you can drill down and view details of the corresponding bundle. |
| Similarly, the console displays the consumed and provided OSGi services. |
| Finally, the console also displays information about the Spring context, if the bundle is Spring powered.</p> |
| </li> |
| <li> |
| <p>To view the full list of OSGi services, click the <code>Services Overview</code> link from the main OSGi state page</p> |
| </li> |
| <li> |
| <p>Typically, the list of bundles and services can be very long, making it difficult to find a particular bundle. Use the <strong>Search</strong> box at the top right corner to narrow down the list of displayed bundles.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>Enter a package name with wildcards '*' representing part of a package name (excluding periods) and |
| '*' representing one or more components of a package name separated by periods. |
| For example, <code>*.virgo.*</code> displays Virgo packages. |
| :virgo-name: Virgo |
| :version: 3.7.0.RC01</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="repository"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_the_provisioning_repository_2">The Provisioning Repository</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p><a id="repository-introduction"></a></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_overview_of_the_provisioning_repository">Overview of the Provisioning Repository</h3> |
| <div class="paragraph"> |
| <p>This section describes the provisioning repository feature of Virgo, the reasons for using it, and how to configure it.</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 section is not applicable to Virgo Nano. The provisioning mechanism used there is p2.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>In most use cases, your application has a dependency on one or more separate artifacts; these artifacts might include OSGi bundles, configuration artifacts, third-party libraries, PARs or plans. A typical example is a Spring application that depends on a third-party library such as Spring Framework or Hibernate.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The way you express this dependency depends on the artifact. For example, a plan is by definition a list of dependent bundles.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Libraries are another example. Some third-party dependencies consist of multiple bundles but are logically one unit. To support this, Virgo has a concept of a library. A library is a collection of related bundles that can be referenced as a whole. You typically express the dependencies between your application and third-party libraries using the <code>Import-Package</code>, <code>Import-Bundle</code>, or <code>Import-Library</code> manifest header in the <code>MANIFEST.MF</code> file of your application. The <code>Import-Package</code> header is standard to OSGi; <code>Import-Bundle</code> and <code>Import-Library</code>, however, are specific to Virgo.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For additional details about the creation and usage of libraries, as well as general information about dependencies, see {programer-guide}.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In Virgo, you store all third-party dependencies required by your applications, such as Spring Framework and Hibernate, as artifacts in the provisioning repository. As mentioned above, you can store the following types of artifacts in the repository:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>OSGi bundles</p> |
| </li> |
| <li> |
| <p>Libraries</p> |
| </li> |
| <li> |
| <p>PARs</p> |
| </li> |
| <li> |
| <p>Plans</p> |
| </li> |
| <li> |
| <p>Configuration Artifacts</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>When you deploy your application, Virgo installs the bundle(s) comprising the application to the Virgo runtime; part of this internal installation procedure is to satisfy all the application’s dependencies. If your application has a dependency that cannot be satisfied from the bundles that you have already deployed (and Virgo has thus installed), then Virgo searches the provisioning repository for an artifact that can satisfy that dependency.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The provisioning repository for a particular instance of Virgo can include artifacts in the following general locations:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Local: This means that artifacts have been physically installed in the provisioning repository directory structure of the local Virgo instance. The artifacts in a local repository include installed third-party libraries, bundles supplied by Virgo, bundles supplied by an end user, and internal bundles used only by Virgo. You can further categorize this location into <code>external</code> directories that adhere to a specified search pattern and are scanned by Virgo just on a clean startup, or <code>watched</code> directories that point to a single directory location and which Virgo scans on a regular basis.</p> |
| </li> |
| <li> |
| <p>Remote: This means that a local instance of Virgo gets the artifact from a remotely-hosted repository that is physically located on a remote Virgo for Apache Tomcat instance.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>You configure the provisioning repository using the <code>$SERVER_HOME/configuration/org.eclipse.virgo.repository.properties</code> file.</p> |
| </div> |
| <div class="paragraph"> |
| <p>As previously described, a particular instance of Virgo for Apache Tomcat can itself also act as a repository host for remote server instances to use when satisfying the dependencies of the applications deployed to it. In this case, you configure a hosted repository using the <code>$SERVER_HOME/configuration/org.eclipse.virgo.apps.repository.properties</code> file. Typically, only remote clients use hosted repositories and their contents; the Virgo for Apache Tomcat instance that actually hosts the repository does not typically use the artifacts in it. Rather, it uses artifacts in its local repository.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Making a third-party dependency available to your application is simply a matter of adding its artifact to the appropriate location in the provisioning repository. This could be either in the local directories or the remote ones if you are getting artifacts from a remotely-hosted repository.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="repository-structure"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_local_repository_structure">Local Repository Structure</h4> |
| <div class="paragraph"> |
| <p>When you first install Virgo, the local provisioning repository is located at <code>$SERVER_HOME/repository</code> by default and consists of two main directories: <code>ext</code> and <code>usr</code>. The <code>ext</code> directory contains artifacts supplied with the Virgo and <code>usr</code> contains artifacts supplied by the user and is initially empty.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="repository-installing-bundles"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_installing_artifacts_to_a_repository">Installing Artifacts to a Repository</h4> |
| <div class="paragraph"> |
| <p>To install an artifact into the default repository, simply copy it into the <code>$SERVER_HOME/repository/usr</code> directory.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If you have configured additional watched or external repositories (additional, that is, to the default ones already configured in a freshly-installed Virgo instance), you install the artifacts in the same way: simply copy the files to the configured directories. You configure additional watched or external repositories in the same file as the default repositories: <code>$SERVER_HOME/configuration/org.eclipse.virgo.repository.properties</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When you install a plan or a library into the repository, you must ensure that all referenced artifacts within the plan or library have been installed as well.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Artifacts must have unique names so it is considered best practice to include the version number in the file name, |
| allowing for multiple versions of the artifact to be installed at the same time. For example, a bundle file name might be <code>my-exciting-bundle.2.1.0.jar</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For watched repositories, such as <code>$SERVER_HOME/repository/usr</code>, Virgo automatically detects changes |
| at runtime, thereby avoiding the need to restart Virgo.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Of specific relevance during development is picking up changes to an application’s direct dependencies during deployment of the application. For example, if you deploy an application and receive a message that a dependency is missing, you can simply add the dependency to the repository and then redeploy the application. The redeploy will cause the new dependency to be picked up, allowing progress to be made without restarting Virgo. For other changes such as addition of optional dependencies, Virgo must be restarted to pick up any changes to the provisioning repository.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="repository-brits"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_downloading_bundles_from_the_ebr">Downloading Bundles from the EBR</h3> |
| <div class="paragraph"> |
| <p>The <a href="http://www.eclipse.org/ebr">EBR</a> is a public collection of open source libraries commonly used for developing enterprise Java applications with the Spring Framework and Virgo. It contains hundreds of the most popular enterprise Java libraries made available for general use in an OSGi-ready format. You can browse the collection and then download the bundles that you need into your own local repository.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <a href="http://www.eclipse.org/ebr">EBR</a> is located <a href="http://www.springsource.com/repository">here</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/bundle-repository.png" alt="bundle repository"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>You can find bundles in the repository using a number of options. You use the ‘Search' facility by typing in a keyword. The matching criteria returned can be explored by name, symbolic name, class, package or resource.</p> |
| </div> |
| <div class="paragraph"> |
| <p>There is also the option of clicking on ‘Browse by Bundle'. This gives an alphabetical list of bundles. You can select the desired bundle to see details and find the download link. Finally, you can also choose to ‘Browse by Library', which allows you to browse the alphabetical list of libraries in the repository.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="repository-configuration"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_configuring_the_repository">Configuring the Repository</h3> |
| <div class="paragraph"> |
| <p>Details of how to configure a Virgo installation’s provisioning repository can be found in <a href="#configuring-provisioning-repository">Configuring the Provisioning Repository</a>. See <a href="#configuring-hosted-repo">Configuring a Hosted Repository</a> for details of how to configure a repository that remote clients can access, also called a hosted repository.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The two configuration sections describe the format of the repository properties files of Virgo, how to add new directories to the local repository, how to configure the repository to get artifacts from a remote repository hosted on a remote VTS instance, and how to configure the local VTS instance to host a repository that other remote servers access. |
| :virgo-name: Virgo |
| :version: 3.7.0.RC01</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="serviceability"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_serviceability_and_diagnostics">Serviceability and Diagnostics</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Virgo supports two kinds of logging: <strong>Event Logging</strong> and <strong>Trace logging</strong> which is usually referred |
| to simply as <strong>Logging</strong>. The difference between Event Logging and Logging is explained below, but both are configured in the |
| <code>serviceability.xml</code> file in the <code>configuration</code> directory. This file takes the form of a Logback configuration, Virgo |
| uses a Logback implementation behind the SLF4J logging interface.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For a description of the syntax and facilities provided by <code>serviceability.xml</code> |
| see the <strong>Logback</strong> documentation (referenced in <a href="#furtherreading">Further Reading</a>).</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="serviceability-info-log"></a></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_event_logging">Event Logging</h3> |
| <div class="paragraph"> |
| <p>Event logging records important events in Virgo. Each event is logged to |
| an event log file and is accompanied by a code enclosed in angle brackets. |
| An example is shown below:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>[2010-10-25 16:20:45.897] system-artifacts <TC0010I> Creating HTTP/1.1 connector with scheme http on port 8080.</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>(For a description of the log code syntax, see <a href="#log-codes">[log-codes]</a>.) |
| The format of event log messages is fully configurable.</p> |
| </div> |
| <div class="paragraph"> |
| <p>By default, event log messages are stored in <code>$SERVER_HOME/serviceability/eventlogs/eventlog.log</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The default behaviour is that, once <code>eventlog.log</code> reaches a 10Mb limit, it rolls into a series of files named |
| <code>eventlog_</code><strong>i</strong><code>.log</code> where <strong>i</strong> ranges from 1 to 4, and event logging continues in |
| a new <code>eventlog.log</code> file.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="serviceability-info-trace"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="__trace_logging">(Trace) Logging</h3> |
| <div class="paragraph"> |
| <p>The Virgo’s (trace) logging support serves two main purposes:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>It provides global trace files that capture high-volume information regarding the Virgo’s internal events. |
| The files are intended for use by support personnel to diagnose runtime problems.</p> |
| </li> |
| <li> |
| <p>It provides application trace files that contain application-generated output. This includes output generated using popular logging and |
| tracing APIs including the OSGi LogService, as well as output generated by calls to <code>System.out</code> and <code>System.err</code>. |
| These files are intended for use by application developers and system administrators. An application is defined as a scope so a single bundle will |
| not get its own log file unless it is a Web application Bundle or is included in a scoped plan or a par file.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>By default, the Virgo trace file is called <code>$SERVER_HOME/serviceability/logs/log.log</code>, |
| and, again by default, the application trace files are called <code>$SERVER_HOME/serviceability/logs/</code><strong>application_name</strong> |
| <code>/log.log</code>, where <strong>application_name</strong> is automatically set by Virgo for each application artifact |
| installed and run (it is a combination of the artifact name and the version).</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Entries in trace files are by default of the form <timestamp> <thread-name> <source> <level> <entry-text>. For example:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>[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> |
| <div class="paragraph"> |
| <p>although this format is completely determined by the Logback configuration file <code>serviceability.xml</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="serviceability-info-trace-app"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_application_output">Application Output</h4> |
| <div class="paragraph"> |
| <p>Virgo provides advanced support for capturing and tracing application-generated output by automatically separating trace output on a |
| per-application basis and will also capture any <code>System.out</code> and <code>System.err</code> output.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="per-application-trace"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_per_application_trace">Per-application trace</h4> |
| <div class="paragraph"> |
| <p>Virgo uses SLF4J interfaces to Logback, and the root logger (by default) captures all logging output |
| and appends it to the application-specific trace files as described above. |
| To modify this, define application-specific loggers in the <code>serviceability.xml</code> file in the normal way.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="sysout-and-syserr"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_system_out_and_system_err">System.out and System.err</h3> |
| <div class="paragraph"> |
| <p><code>System.out</code> and <code>System.err</code> output from applications is, by default, captured in the |
| application’s trace file. |
| This happens because the output streams are intercepted and written to the loggers named |
| <code>System.out</code> and <code>System.err</code> respectively. |
| Since there are no explicit loggers defined with these names in the <code>serviceability.xml</code> file, |
| this output is logged by the root logger (which captures <code>INFO</code> level and above).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The capture of <code>System.out</code> and <code>System.err</code> output is configured in the |
| <code>configuration/org.eclipse.virgo.medic.properties</code> file by the <code>log.wrapSysOut</code> and |
| <code>log.wrapSysErr</code> properties. By default the properties have a value of <code>true</code> |
| and capture is enabled. Capture can be disabled by configuring the properties with a value of <code>false</code>. |
| The third and last accepted value is <code>tee</code> which captures the System streams output in the logs |
| while at the same time allows printing output to the System streams. Thus this output will appear both in the logs |
| and in the System stream output - an example could be the Equinox console, launched with <code>-console</code> startup argument.</p> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Important</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>If you provide value different than 'true | tee | false' then the server will default to 'tee' and print out a warning.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The trace entries for <code>System.out</code> and <code>System.err</code> |
| output are of the form:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>[2008-05-16 09:28:45.874] server-tomcat-thread-1 System.out Hello world! |
| [2008-05-16 09:28:45.874] server-tomcat-thread-1 System.err Hello world!</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The third column indicates where the output came from (<code>System.out</code> or <code>System.err</code>).</p> |
| </div> |
| <div class="paragraph"> |
| <p>To over-ride this behaviour, simply define explicit loggers named <code>System.out</code> |
| and/or <code>System.err</code> in the configuration file to send this output to an appender of your choice. |
| Be aware that all applications' output streams will be caught by these loggers, and that a sifting appender might be useful to separate them.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="janino"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_janino">Janino</h4> |
| <div class="paragraph"> |
| <p>Janino can be used to define trace filters as Java expressions. This adds a significant overhead to tracing, so should be used with care.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example, the addition of the following filter element to the sifting appender in <code>serviceability.xml</code> |
| suppresses per-application trace output that is not associated with a particular application and is normally written to |
| <code>serviceability/logs/virgo-kernel/log.log</code>.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xml" data-lang="xml"><appender name="SIFTED_LOG_FILE" class="ch.qos.logback.classic.sift.SiftingAppender"> |
| <discriminator> |
| <Key>applicationName</Key> |
| <DefaultValue>virgo-kernel</DefaultValue> |
| </discriminator> |
| <sift> |
| <appender name="${applicationName}_LOG_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> |
| <filter class="ch.qos.logback.core.filter.EvaluatorFilter"> |
| <evaluator class="ch.qos.logback.classic.boolex.JaninoEventEvaluator"> |
| <expression> |
| (mdc == null) || (mdc.get("applicationName") == null) |
| </expression> |
| </evaluator> |
| <OnMismatch>NEUTRAL</OnMismatch> |
| <OnMatch>DENY</OnMatch> |
| </filter> |
| <file>serviceability/logs/${applicationName}/log.log</file> |
| ... |
| </appender> |
| </sift> |
| </appender></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>To enable Janino in Virgo, place the Janino and commons compiler JARs, converted to OSGi bundles, in <code>plugins</code>. |
| For example these bundles are available at v2.6.1 from the SpringSource Enterprise Bundle Repository. |
| Then add the following lines to |
| <code>configuration/org.eclipse.equinox.simpleconfigurator/bundles.info</code> |
| (as described in <a href="#configuring-framework-bundles">Configuring OSGi Framework Bundles</a>):</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">com.springsource.org.codehaus.janino,2.6.1,plugins/com.springsource.org.codehaus.janino-2.6.1.jar,4,false |
| com.springsource.org.codehaus.commons.compiler,2.6.1,plugins/com.springsource.org.codehaus.commons.compiler-2.6.1.jar,4,false]]></programlisting></code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Important</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>Current versions of Logback, including 0.9.28 to 1.0, do not set Janino’s "parent" class loader correctly. |
| This bug is covered by the Logback issue <a href="http://jira.qos.ch/browse/LBCORE-244">LBCORE-244</a>. |
| With such versions, it is necessary to attach a fragment bundle to Janino. Place the fragment bundle in <code>plugins</code> and list it in |
| <code>configuration/org.eclipse.equinox.simpleconfigurator/bundles.info</code>. |
| The fragment’s contents are described in <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=333920#c15">bug 333920</a>.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a id="serviceability-info-dump"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_service_dumps">Service Dumps</h3> |
| <div class="paragraph"> |
| <p>A service dump is triggered when one of the following events |
| occurs:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>A failure is detected in the Virgo code, or</p> |
| </li> |
| <li> |
| <p>a thread deadlock is detected.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>A service dump contains a snapshot of all the important state from |
| the running Virgo instance. This snapshot is not intended |
| for end user consumption but is useful for service personnel.</p> |
| </div> |
| <div class="paragraph"> |
| <p>By default, service dumps are created in <code>$SERVER_HOME/serviceability/dump</code>. |
| :virgo-name: Virgo |
| :version: 3.7.0.RC01</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="deployment"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_working_with_applications">Working with Applications</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p><a id="deployment-deploying"></a></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_deploying_artifacts">Deploying Artifacts</h3> |
| <div class="paragraph"> |
| <p>In the context of Virgo for Apache Tomcat, <strong>deploying</strong> refers to installing an artifact to the server and then starting it to make it available to users. Typically, when you install an artifact, VTS automatically starts it as long as the server is able to successfully resolve all its dependencies. For this reason, the terms <strong>deploying</strong> and <strong>installing</strong> are often used interchangeably.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You deploy artifacts to Virgo for Apache Tomcat using either the hot-deploy directory on the file system or by using the Admin Console. The artifacts that you can deploy to VTS are:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Bundles, including Web Application Bundles</p> |
| </li> |
| <li> |
| <p>WARs</p> |
| </li> |
| <li> |
| <p>PARs</p> |
| </li> |
| <li> |
| <p>Plans</p> |
| </li> |
| <li> |
| <p>Configuration Files</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a id="deployment-deploying-nested-contexts"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_deploying_wars_with_nested_web_contextpaths">Deploying WARs with nested Web-ContextPaths</h4> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>This section currently is ONLY relevant for Virgo Nano.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Virgo Nano Web supports deployment of WAR files which are transformed into Web Application Bundles. This process involves automatic creation of an OSGi manifest with all relevant OSGi header plus the very important Web-ContextPath header. Its value defines how the deployed WAR file can be requested. There is a limitation about this process that the automatic generation only creates a flat context path which equals the name of your WAR file. Virgo Nano Web supports generation of a nested one.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In order to benefit from this flexibility all you need to do is just to add hashes '#' to your WAR file name in the places where you want to have slashes in your web context path. Here is an example:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>myWarFile.war would result into "/myWarFile" web context path</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>my#War#File.war would result into "/my/War/File" web context path</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The symbolic name of the resulting WAB file is the same as the WAR file name but the hashes '#' are replaced with dots '.'.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="initial-deployment-deploying-bulk"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_initial_bulk_hot_deploy">Initial Bulk Hot Deploy</h4> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>This section currently is ONLY relevant for Virgo Nano.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>To hot deploy an artifact initially in bulk mode, copy it into the pickup directory (by default <code>$SERVER_HOME/pickup</code>) and start up the server. Upon this startup all the artifacts in the <code>pickup</code> directory will get first installed and resolved and only then they will be started.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This solves the problem where artifacts depend on each other and when not in bulk mode the install order is not guaranteed therefore errors could occur.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This is only available as part of the initial scan of the <code>pickup</code> directory. Subsequently it goes back to the known mode of single file handled at a time.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ cd /home/applications |
| $ cp BundleA.jar $SERVER_HOME/pickup |
| $ cp BundleWithDependencyOnA.jar $SERVER_HOME/pickup |
| $ cd $SERVER_HOME/bin |
| $ ./startup.sh</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>When the server is started, artifacts are hot deployed and messages similar to the following appear in the log file:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>[2009-12-10 06:41:01.021] fs-watcher <HD0001I> Hot deployer processing 'INITIAL' event for file 'BundleA.jar; BundleWithDependencyOnA.jar; '. |
| [2009-12-10 06:41:01.087] fs-watcher <DE0000I> Installing bundle 'BundleA' version '0.0.0'. |
| [2009-12-10 06:41:01.274] fs-watcher <DE0001I> Installed bundle 'BundleA' version '0.0.0'. |
| [2009-12-10 06:41:01.087] fs-watcher <DE0000I> Installing bundle 'BundleWithDependencyOnA' version '0.0.0'. |
| [2009-12-10 06:41:01.274] fs-watcher <DE0001I> Installed bundle 'BundleWithDependencyOnA' version '0.0.0'. |
| [2009-12-10 06:41:01.397] fs-watcher <DE0004I> Starting bundle 'BundleA' version '0.0.0'. |
| [2009-12-10 06:41:01.550] start-signalling-1 <DE0005I> Started bundle 'BundleA' version '0.0.0'. |
| [2009-12-10 06:41:01.397] fs-watcher <DE0004I> Starting bundle 'BundleWithDependencyOnA' version '0.0.0'. |
| [2009-12-10 06:41:01.550] start-signalling-1 <DE0005I> Started bundle 'BundleWithDependencyOnA' version '0.0.0'.</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If there is a problem with the deployment, such as the server being unable to resolve all dependencies, the console and log both show an error message to help you with troubleshooting.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If there are no problems, Virgo Nano automatically starts the artifacts so that they are immediately available to users.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Bulk deployment can be disabled and reverted back to the old one-file-at-a-time processing by removing this line from <code>$SERVER_HOME/configuration/config.ini</code>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">org.eclipse.virgo.fschecker.initialEventMode=bulk</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="deployment-deploying-hot"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_hot_deploy">Hot Deploy</h4> |
| <div class="paragraph"> |
| <p>To hot deploy an artifact, copy it into the pickup directory (by default <code>$SERVER_HOME/pickup</code>):</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ cd /home/applications |
| $ cp helloWorld.war $SERVER_HOME/pickup</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>When the artifact is hot deployed, messages similar to the following appear in the log file:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>[2009-12-10 06:41:01.021] fs-watcher <HD0001I> Hot deployer processing 'CREATED' event for file 'helloWorld.war'. |
| [2009-12-10 06:41:01.087] fs-watcher <DE0000I> Installing bundle 'helloWorld' version '0.0.0'. |
| [2009-12-10 06:41:01.274] fs-watcher <DE0001I> Installed bundle 'helloWorld' version '0.0.0'. |
| [2009-12-10 06:41:01.397] fs-watcher <DE0004I> Starting bundle 'helloWorld' version '0.0.0'. |
| [2009-12-10 06:41:01.414] Thread-3 <WE0000I> Starting web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'. |
| [2009-12-10 06:41:01.537] Thread-3 <WE0001I> Started web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'. |
| [2009-12-10 06:41:01.550] start-signalling-1 <DE0005I> Started bundle 'helloWorld' version '0.0.0'.</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If there is a problem with the deployment, such as the server being unable to resolve all dependencies, the console and log both show an error message to help you with troubleshooting.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If there are no problems, VTS automatically starts the artifact so that it is immediately available to users.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="deployment-redeploy-hot"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_hot_redeploy">Hot Redeploy</h4> |
| <div class="paragraph"> |
| <p>To hot redeploy an artifact which is already hot deployed, copy the updated artifact into the pickup directory (by default <code>$SERVER_HOME/pickup</code>), |
| just as for hot deploy. When the artifact is redeployed, messages similar to the following appear in the log file:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>[2013-01-09 14:08:12.422] fs-watcher <HD0001I> Hot deployer processing 'MODIFIED' event for file 'helloWorld.war'. |
| [2013-01-09 14:08:12.422] fs-watcher <DE0007I> Refreshing bundle 'helloWorld' version '0.0.0'. |
| [2013-01-09 14:08:12.469] fs-watcher <WE0002I> Stopping web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'. |
| [2013-01-09 14:08:13.094] fs-watcher <WE0003I> Stopped web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'. |
| [2013-01-09 14:08:13.094] fs-watcher <DE0010I> Stopping bundle 'helloWorld' version '0.0.0'. |
| [2013-01-09 14:08:13.110] fs-watcher <DE0011I> Stopped bundle 'helloWorld' version '0.0.0'. |
| [2013-01-09 14:08:13.250] fs-watcher <DE0004I> Starting bundle 'helloWorld' version '0.0.0'. |
| [2013-01-09 14:08:13.250] start-signalling-2 <WE0000I> Starting web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'. |
| [2013-01-09 14:08:13.860] start-signalling-2 <WE0001I> Started web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'. |
| [2013-01-09 14:08:13.860] start-signalling-2 <DE0005I> Started bundle 'helloWorld' version '0.0.0'. |
| [2013-01-09 14:08:13.860] fs-watcher <DE0008I> Refreshed bundle 'helloWorld' version '0.0.0'.</pre> |
| </div> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>The following paragraph is ONLY relevant for Virgo Nano.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The redeploy waits for any previous operations on the artifact being redeployed to finish. The wait timeout could be configured through the following property in <code>$SERVER_HOME/configuration/config.ini</code>:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>org.eclipse.virgo.update.timeout</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="deployment-deploying-manual"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_deploying_using_the_admin_console">Deploying Using the Admin Console</h4> |
| <div class="paragraph"> |
| <p>The Admin Console allows you to upload a file, which will be deployed automatically, from your local file system to the Virgo for Apache Tomcat. As soon as Virgo for Apache Tomcat deploys the artifact, it appears in the list of artifacts in the Admin Console. Note that the GUI for uploading varies according to the browser and operating system you use.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See <a href="#admin-console-install-artifacts">Installing a New Artifact</a> for details about using the Admin Console to install (deploy) an artifact. See xreF:admin-console[The Web Admin Console] for general information about the Admin Console.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="deployment-deploying-happens"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_what_happens_when_you_deploy">What Happens When You Deploy</h4> |
| <div class="paragraph"> |
| <p>When you deploy an artifact, either using hot-deployment or the Admin Console, Web Server copies the file to its work directory (<code>SERVER_HOME/work</code>) and registers it in its internal registry. |
| The server then checks any dependencies the artifact might have to see if |
| deployment can go ahead, and if all dependencies are resolved, Virgo for Apache Tomcat starts the artifact. |
| Because of all these additional internal activities, you should NOT simply copy the artifact into the <code>work</code> directory and assume it will be deployed, because Virgo for Apache Tomcat will not do so.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="deployment-deploying-ordering"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_deployment_ordering">Deployment Ordering</h4> |
| <div class="paragraph"> |
| <p>When deploying bundles that have dependencies, it is important |
| that you deploy them in the correct order. Virgo for Apache Tomcat |
| honors this ordering when it redeploys the artifacts on startup.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If you use hot deployment to deploy your artifacts, be sure to copy the corresponding files into the pickup |
| directory one-by-one. Copying the files in one group, for example by using a single <code>cp</code> command, provides no guarantee of ordering.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="deployment-deploying-shared"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_deploying_shared_artifacts">Deploying Shared Artifacts</h4> |
| <div class="paragraph"> |
| <p>Artifacts may be shared by plans. |
| Sharing occurs when a plan is deployed which references an artifact that was previously deployed or is a child artifact |
| of a plan that was previously deployed. |
| Sharing also occurs when an artifact is deployed which is already a child of a deployed plan, but in this case the shared |
| artifact may <strong>not</strong> appear as a top-level artifact, for example, in the Admin Console, in the shell, |
| and in JMX.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Sharing is taken into account when artifacts are stopped. |
| A shared artifact is stopped only when all the artifacts referencing the shared artifact have been stopped |
| and, if the shared artifact was deployed in its own right, the artifact itself has been stopped.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="deployment-deploying-restrictions"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_restrictions">Restrictions</h4> |
| <div class="paragraph"> |
| <p>Virgo for Apache Tomcat does not support deploying fragment bundles. Typically, fragment bundles should be placed in <code>$SERVER_HOME/repository/ext</code> |
| or <code>$SERVER_HOME/repository/usr</code> so that they will be installed automatically with their host bundles.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="deployment-undeploy"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_undeploying_artifacts">Undeploying Artifacts</h3> |
| <div class="paragraph"> |
| <p>You undeploy artifacts from Virgo for Apache Tomcat by using either the hot-deploy directory on the file system, or the Admin Console.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>As with deploying, in this guide the terms <strong>undeploying</strong> and <strong>uninstalling</strong> are used interchangeably.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a id="deployment-undeploy-hot"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_hot_undeploy">Hot Undeploy</h4> |
| <div class="paragraph"> |
| <p>To hot-undeploy an artifact, remove the corresponding file from the pickup directory (by default <code>$SERVER_HOME/pickup</code>):</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ cd $SERVER_HOME/pickup |
| $ rm helloWorld.war</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>When Virgo for Apache Tomcat completes the undeployment of the artifact, messages similar to the following appear in the log:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>[2009-12-10 06:46:33.254] fs-watcher <HD0001I> Hot deployer processing 'DELETED' event for file 'helloWorld.war'. |
| [2009-12-10 06:46:33.259] Thread-3 <WE0002I> Stopping web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'. |
| [2009-12-10 06:46:33.285] Thread-3 <WE0003I> Stopped web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'. |
| [2009-12-10 06:46:33.290] fs-watcher <DE0010I> Stopping bundle 'helloWorld' version '0.0.0'. |
| [2009-12-10 06:46:33.295] fs-watcher <DE0011I> Stopped bundle 'helloWorld' version '0.0.0'. |
| [2009-12-10 06:46:33.302] fs-watcher <DE0013I> Uninstalling bundle 'helloWorld' version '0.0.0'. |
| [2009-12-10 06:46:33.319] fs-watcher <DE0014I> Uninstalled bundle 'helloWorld' version '0.0.0'.</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="deployment-undeploy-manual"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_undeploying_using_the_admin_console">Undeploying Using the Admin Console</h4> |
| <div class="paragraph"> |
| <p>You can undeploy only whole artifacts from the Admin Console, or in other words, you cannot undeploy the separate modules or bundles that make up an artifact.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The only artifact that you cannot undeploy from the Admin Console is the Admin Console itself. If you need to undeploy this application, you must remove it from the pickup directory (by default <code>SERVER_HOME/pickup</code>); the name of the artifact is |
| <code>org.eclipse.virgo.server.admin-3.7.0.RC01.plan</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See <a href="#admin-console-manage-artifacts">Viewing and Managing the Lifecycle of Deployed Artifacts</a> for details about uninstalling (undeploying) an artifact using the Admin Console. The high-level steps are to highlight the artifact in the artifact tree then click <code>Uninstall</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="deployment-undeploying-shared"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_undeploying_shared_artifacts">Undeploying Shared Artifacts</h4> |
| <div class="paragraph"> |
| <p>Sharing is taken into account when artifacts are undeployed. |
| A shared artifact is undeployed only when all the artifacts referencing the shared artifact have been undeployed |
| and, if the shared artifact was deployed in its own right, the artifact itself has been undeployed. |
| :virgo-name: Virgo |
| :version: 3.7.0.RC01</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="configuring"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </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 9. 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 10. 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 11. 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 12. 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 13. 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 14. 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 15. 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 16. 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">Enabling the Equinox Console</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">Enabling the Equinox Console</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 17. 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 18. 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 19. 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">Enabling the Equinox Console</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">Enabling the Equinox Console</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 20. 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>. |
| :virgo-name: Virgo |
| :version: 3.7.0.RC01</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="log-codes"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_event_log_codes">Event log codes</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p><a id="event-log-codes-format"></a></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_format_of_the_event_log_codes">Format of the event log codes</h3> |
| <div class="paragraph"> |
| <p>Event log codes issued by Virgo have the general syntax |
| <code><XXnnnnL></code> where:</p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <colgroup> |
| <col style="width: 14%;"> |
| <col style="width: 85%;"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>XX</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">is a two-letter code (upper-case) identifying the area of the Virgo code which issued the log message;</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>nnnn</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">is a four-digit message number; and</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>L</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">is a single-letter (upper-case) code identifying the level of the message.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The two-letter codes are (this list is not complete):</p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <colgroup> |
| <col style="width: 14%;"> |
| <col style="width: 85%;"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>AG</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.virgo.kernel.agent.dm</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>DE</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.virgo.kernel.deployer.core</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>HD</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.virgo.kernel.deployer.hot</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>HR</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.virgo.apps.repository.core</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>KE</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.virgo.kernel.core</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>KS</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.virgo.kernel.services</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>OF</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.virgo.kernel.osgi</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>RP</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.virgo.repository</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>TC</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.virgo.web.tomcat</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>UR</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.virgo.kernel.userregion</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>WE</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.virgo.web.core</code></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The four-digit numbers identify the message text (with placeholders for inserted values). These are not listed here, but can be discovered by examining the files called |
| <code>EventLogMessages.properties</code>, found in the relevant packages.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The single-digit level code is one of:</p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <colgroup> |
| <col style="width: 14%;"> |
| <col style="width: 85%;"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>E</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Error level: enabled if level is <code>ERROR</code>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>W</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Warning level: enabled if level is <code>WARNING</code> or above.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>I</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Info level: enabled if level is <code>INFO</code> or above.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>D</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Debug level: enabled if level is <code>DEBUG</code> or above.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>T</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Trace level: always enabled.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>There are never two messages with the same prefix and number, but with different levels. |
| :virgo-name: Virgo |
| :version: 3.7.0.RC01</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="known-issues"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_known_issues">Known Issues</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>This section describes known issues that you might run into, along with corresponding workarounds.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For the full list of known issues, see <a href="https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;order=Importance;classification=RT;product=Virgo">Virgo bugs in Eclipse Bugzilla</a>. |
| The bugs are organised by component as well as by release. |
| You can also use bugzilla to enter a new issue if you cannot find an existing issue that describes the problem you are running into, but it’s probably worth asking on the <a href="http://www.eclipse.org/forums/index.php?t=thread&frm_id=159">Virgo community forum</a> first.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="known-issues-firewall-timeout"></a></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_timeout_during_startup_due_to_firewall_settings">Timeout During Startup Due to Firewall Settings</h3> |
| <div class="paragraph"> |
| <p>Virgo will fail to start correctly if it is prevented from |
| connecting to needed ports by the firewall. Typically this manifests |
| as error <code>SPPM0003E</code> . Configuring the firewall to |
| allow Virgo process to bind to the necessary ports will prevent |
| this error from occurring.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="known-issues-startup-timeout"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_timeout_during_startup_due_to_insufficient_resources">Timeout During Startup Due to Insufficient Resources</h3> |
| <div class="paragraph"> |
| <p>Virgo will fail to start correctly if it is running on slow hardware or |
| on a system with insufficient resources. Typically this manifests as error <code>KE0004E</code> . |
| Configuring the <a href="#configuring-kernel-properties">startup wait limit</a> will provide |
| Virgo with more time for initialisation.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="known-issues-perm-gen-sun-vm"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_outofmemoryerror_permgen_space_running_on_sun_jvm">OutOfMemoryError: PermGen Space Running on Sun JVM</h3> |
| <div class="paragraph"> |
| <p>As a result of Sun Java bug |
| <a href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4957990">4957990</a>, |
| the Virgo may consume more PermGen space than expected when running with the |
| server HotSpot compiler. This problem may be resolved by configuring the |
| <code>JAVA_OPTS</code> environment variable to specify an increased |
| <code>MaxPermSize</code>, for example <code>-XX:MaxPermSize=128M</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="alternate-serviceability-work"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_alternate_code_serviceability_code_and_code_work_code_directories">Alternate <code>serviceability</code> and <code>work</code> Directories</h3> |
| <div class="paragraph"> |
| <p>Although an alternate <code>configuration</code> directory may be specified on startup, there is no way to specify |
| alternate <code>serviceability</code> or <code>work</code> directories. This is covered by |
| <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=307737">bug 307737</a> which also describes a workaround.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="windows-deletion"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_problem_deleting_installation_directory_under_windows">Problem Deleting Installation Directory under Windows</h3> |
| <div class="paragraph"> |
| <p>Sometimes Microsoft Windows won’t let you delete the Virgo Server installation directory, typically because of long paths |
| inside the <code>work</code> directory.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You can return the Virgo instance to a clean state by stopping Virgo if necessary and then running the startup script with the options |
| <code>-clean -noStart</code>, after which you should be able to delete the installation directory. |
| See <a href="#cleaning-without-starting">Cleaning Virgo for Apache Tomcat without Starting it</a> for more information.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="long-work-paths"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_long_work_directory_paths_under_windows">Long Work Directory Paths under Windows</h3> |
| <div class="paragraph"> |
| <p>Problems can arise under Windows when long paths are created in the <code>work</code> directory as artefacts are deployed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You can shorten some of these paths by preventing bundles from being unpacked during deployment. |
| See <a href="#configuring-deployment">Configuring Deployment</a> for more information.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="known-issues-jetty-restrictions"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_virgo_jetty_server_restrictions">Virgo Jetty Server Restrictions</h3> |
| <div class="paragraph"> |
| <p>When using the Virgo Jetty Server the Hosted Repository application and the Snaps modular web technology are not supported.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="known-issues-shutdown-logs-shell"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_shutdown_log_messages_in_telnet_shell">Shutdown Log Messages in Telnet Shell</h3> |
| <div class="paragraph"> |
| <p>When you use the <code>shutdown</code> shell command to stop Virgo Server for Apache Tomcat, the shutdown log messages appear in the shell terminal instead of in the terminal in which Virgo runs. |
| See <a href="#admin-shell-enable">Enabling Equinox Console</a> for more information. This is covered also by <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=351533">bug 351533</a>. |
| :virgo-name: Virgo |
| :version: 3.7.0.RC01</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="furtherreading"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_further_reading">Further Reading</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p><a href="../../virgo-programmer-guide/html/index.html">Programmer Guide</a></p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="http://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/">Spring Framework Reference Documentation</a></p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="http://www.osgi.org/Specifications/HomePage">Blueprint Container Specification</a>(in the OSGi 4.2 and 5.0 Enterprise Specifications)</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="http://logback.qos.ch/manual">The Logback Manual</a></p> |
| </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> |
