| <!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"> |
| <
|
