Google Git
Sign in
eclipse / www.eclipse.org / virgo / c22819a1f094720da530ea7b15d7b28625ddf779 / . / documentation / virgo-documentation-3.6.2.RELEASE / docs / virgo-user-guide / htmlsingle / virgo-user-guide.html
blob: 629f338fc869fc959cd38b85067ffd0c2045d097 [file] [log] [blame]
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Virgo User Guide</title><link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"><!--Begin Google Analytics code--><script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script><script type="text/javascript">
var pageTracker = _gat._getTracker("UA-2728886-3");
pageTracker._setDomainName("none");
pageTracker._setAllowLinker(true);
pageTracker._trackPageview();
</script><!--End Google Analytics code--></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="d0e1"></a>Virgo User Guide</h1></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Rob</span> <span class="surname">Harrop</span></h3></div><div class="author"><h3 class="author"><span class="firstname">Paul</span> <span class="surname">Kuzan</span></h3></div><div class="author"><h3 class="author"><span class="firstname">Sam</span> <span class="surname">Brannen</span></h3></div><div class="author"><h3 class="author"><span class="firstname">Paul</span> <span class="surname">Harris</span></h3></div><div class="author"><h3 class="author"><span class="firstname">Christopher</span> <span class="surname">Frost</span></h3></div><div class="author"><h3 class="author"><span class="firstname">Ben</span> <span class="surname">Hale</span></h3></div><div class="author"><h3 class="author"><span class="firstname">Glyn</span> <span class="surname">Normington</span></h3></div><div class="author"><h3 class="author"><span class="firstname">Juliet</span> <span class="surname">Shackell</span></h3></div><div class="author"><h3 class="author"><span class="firstname">Steve</span> <span class="surname">Powell</span></h3></div><div class="author"><h3 class="author"><span class="firstname">Violeta</span> <span class="surname">Georgieva</span></h3></div><div class="author"><h3 class="author"><span class="firstname">Hristo</span> <span class="surname">Iliev</span></h3></div><div class="author"><h3 class="author"><span class="firstname">Borislav</span> <span class="surname">Kapukaranov</span></h3></div></div></div><div><div class="mediaobject" align="right"><img src="images/virgo-logo-small.png" align="right"></div></div><div><span class="productname">Virgo<br></span></div><div><p class="releaseinfo">3.6.2.RELEASE</p></div></div><div><div><div class="legalnotice"><a name="d0e77"></a><p>
Copyright &copy; 2009, 2011 VMware Inc. and others
</p><p>
Contributors:
</p><div class="itemizedlist"><ul type="disc"><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><p>
</p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#introduction">1. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e102">1.1. A Note for Virgo Kernel Users</a></span></dt><dt><span class="section"><a href="#d0e107">1.2. A Note for Virgo Jetty Server Users</a></span></dt><dt><span class="section"><a href="#d0e112">1.3. A Note for Virgo Nano Users</a></span></dt></dl></dd><dt><span class="chapter"><a href="#concepts">2. Concepts</a></span></dt><dd><dl><dt><span class="section"><a href="#concepts.modular">2.1. Modular Runtimes and Applications</a></span></dt><dt><span class="section"><a href="#concepts.osgi">2.2. OSGi Concepts</a></span></dt><dt><span class="section"><a href="#concepts.springdm">2.3. Spring DM and Blueprint Concepts</a></span></dt><dt><span class="section"><a href="#concepts.virgo">2.4. Virgo Concepts</a></span></dt><dt><span class="section"><a href="#concepts.p2">2.5. p2 Concepts</a></span></dt></dl></dd><dt><span class="chapter"><a href="#using-the-p2-director">3. Using the p2 director</a></span></dt><dd><dl><dt><span class="section"><a href="#prereqs">3.1. Prerequisites</a></span></dt><dt><span class="section"><a href="#using-director">3.2. Installing with the p2 director from Eclipse</a></span></dt></dl></dd><dt><span class="chapter"><a href="#installation">4. Installing Virgo Server for Apache Tomcat</a></span></dt><dd><dl><dt><span class="section"><a href="#installation-prereqs">4.1. Prerequisites</a></span></dt><dt><span class="section"><a href="#installation-zip">4.2. Installing from the ZIP Download</a></span></dt><dt><span class="section"><a href="#installation-updatesite">4.3. Installing from an update site</a></span></dt><dt><span class="section"><a href="#installation-post">4.4. Post-installation steps</a></span></dt></dl></dd><dt><span class="chapter"><a href="#kernel-installation">5. Installing Virgo Kernel</a></span></dt><dd><dl><dt><span class="section"><a href="#kernel-installation-prereqs">5.1. Prerequisites</a></span></dt><dt><span class="section"><a href="#kernel-installation-zip">5.2. Installing from the ZIP Download</a></span></dt><dt><span class="section"><a href="#kernel-installation-updatesite">5.3. Installing from an update site</a></span></dt><dt><span class="section"><a href="#kernel-installation-post">5.4. Post-installation steps</a></span></dt></dl></dd><dt><span class="chapter"><a href="#nano-installation">6. Installing Virgo Nano</a></span></dt><dd><dl><dt><span class="section"><a href="#nano-installation-prereqs">6.1. Prerequisites</a></span></dt><dt><span class="section"><a href="#nano-installation-zip">6.2. Installing from the ZIP Download</a></span></dt><dt><span class="section"><a href="#nano-installation-updatesite">6.3. Installing from an update site</a></span></dt><dt><span class="section"><a href="#nano-installation-post">6.4. Post-installation steps</a></span></dt></dl></dd><dt><span class="chapter"><a href="#starting-stopping">7. Starting and Stopping VTS</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e1429">7.1. Starting Virgo Server for Apache Tomcat</a></span></dt><dt><span class="section"><a href="#d0e1481">7.2. Starting in Clean Mode</a></span></dt><dt><span class="section"><a href="#d0e1515">7.3. Starting in Debug Mode</a></span></dt><dt><span class="section"><a href="#d0e1594">7.4. Starting with JMX Access Modifications</a></span></dt><dt><span class="section"><a href="#starting-stopping-configuration-directory">7.5. Starting with a Custom Configuration Directory</a></span></dt><dt><span class="section"><a href="#d0e1883">7.6. Stopping Virgo Server for Apache Tomcat</a></span></dt><dt><span class="section"><a href="#cleaning-without-starting">7.7. Cleaning Virgo Server for Apache Tomcat without Starting it</a></span></dt><dt><span class="section"><a href="#equinox-launcher">7.8. Using Equinox Launcher</a></span></dt></dl></dd><dt><span class="chapter"><a href="#admin-shell">8. Equinox Console</a></span></dt><dd><dl><dt><span class="section"><a href="#admin-shell-enable">8.1. Enabling the Equinox Console</a></span></dt><dt><span class="section"><a href="#admin-shell-using-vsh">8.2. Using Virgo Shell Commands</a></span></dt><dt><span class="section"><a href="#admin-shell-vsh-command-reference">8.3. Virgo Shell Command Reference</a></span></dt><dt><span class="section"><a href="#p2-commands">8.4. Using the p2 for extending your Virgo installation</a></span></dt></dl></dd><dt><span class="chapter"><a href="#admin-console">9. The Admin Console</a></span></dt><dd><dl><dt><span class="section"><a href="#admin-console-login">9.1. Invoking the Admin Console</a></span></dt><dt><span class="section"><a href="#admin-console-tasks">9.2. Typical Admin Console Use Cases</a></span></dt></dl></dd><dt><span class="chapter"><a href="#repository">10. The Provisioning Repository</a></span></dt><dd><dl><dt><span class="section"><a href="#repository-introduction">10.1. Overview of the Provisioning Repository</a></span></dt><dt><span class="section"><a href="#repository-brits">10.2. Downloading Bundles from the SpringSource Enterprise Bundle Repository</a></span></dt><dt><span class="section"><a href="#repository-configuration">10.3. Configuring the Repository</a></span></dt></dl></dd><dt><span class="chapter"><a href="#serviceability">11. Serviceability and Diagnostics</a></span></dt><dd><dl><dt><span class="section"><a href="#serviceability-info-log">11.1. Event Logging</a></span></dt><dt><span class="section"><a href="#serviceability-info-trace">11.2. (Trace) Logging</a></span></dt><dt><span class="section"><a href="#serviceability-info-dump">11.3. Service Dumps</a></span></dt></dl></dd><dt><span class="chapter"><a href="#deployment">12. Working with Applications</a></span></dt><dd><dl><dt><span class="section"><a href="#deployment-deploying">12.1. Deploying Artifacts</a></span></dt><dt><span class="section"><a href="#deployment-undeploy">12.2. Undeploying Artifacts</a></span></dt></dl></dd><dt><span class="chapter"><a href="#configuring">13. Configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#configuring-osgi-framework">13.1. Configuring the OSGi Framework</a></span></dt><dt><span class="section"><a href="#configuring-framework-extensions">13.2. Configuring Framework Extensions and Fragments on the System Bundle</a></span></dt><dt><span class="section"><a href="#configuring-serviceability">13.3. Configuring Serviceability and Diagnostics</a></span></dt><dt><span class="section"><a href="#configuring-provisioning-repository">13.4. Configuring the Local Provisioning Repository</a></span></dt><dt><span class="section"><a href="#configuring-hosted-repo">13.5. Configuring a Hosted Repository</a></span></dt><dt><span class="section"><a href="#configuring-kernel">13.6. Configuring the Kernel and User Region</a></span></dt><dt><span class="section"><a href="#configuring-tomcat">13.7. Configuring the Embedded Tomcat Servlet Container</a></span></dt><dt><span class="section"><a href="#configuring-web">13.8. Configuring the Web Integration Layer</a></span></dt><dt><span class="section"><a href="#configuring-jetty">13.9. Configuring the Embedded Jetty Servlet Container</a></span></dt></dl></dd><dt><span class="appendix"><a href="#log-codes">A. Event log codes</a></span></dt><dd><dl><dt><span class="section"><a href="#event-log-codes-format">A.1. Format of the event log codes</a></span></dt></dl></dd><dt><span class="appendix"><a href="#known-issues">B. Known Issues</a></span></dt><dd><dl><dt><span class="section"><a href="#known-issues-firewall-timeout">B.1. Timeout During Startup Due to Firewall Settings</a></span></dt><dt><span class="section"><a href="#known-issues-startup-timeout">B.2. Timeout During Startup Due to Insufficient Resources</a></span></dt><dt><span class="section"><a href="#known-issues-perm-gen-sun-vm">B.3. OutOfMemoryError: PermGen Space Running on Sun JVM</a></span></dt><dt><span class="section"><a href="#alternate-serviceability-work">B.4. Alternate serviceability and work Directories</a></span></dt><dt><span class="section"><a href="#windows-deletion">B.5. Problem Deleting Installation Directory under Windows</a></span></dt><dt><span class="section"><a href="#long-work-paths">B.6. Long Work Directory Paths under Windows</a></span></dt><dt><span class="section"><a href="#known-issues-jetty-restrictions">B.7. Virgo Jetty Server Restrictions</a></span></dt><dt><span class="section"><a href="#known-issues-shutdown-logs-shell">B.8. Shutdown Log Messages in Telnet Shell</a></span></dt></dl></dd><dt><span class="appendix"><a href="#furtherreading">C.
Further Reading
</a></span></dt></dl></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="introduction"></a>1.&nbsp;Introduction</h2></div></div></div><p>
This User Guide covers the Virgo Server 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 class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e102"></a>1.1&nbsp;A Note for Virgo Kernel Users</h2></div></div></div><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 class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e107"></a>1.2&nbsp;A Note for Virgo Jetty Server Users</h2></div></div></div><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 Server for Apache Tomcat specific sections.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e112"></a>1.3&nbsp;A Note for Virgo Nano Users</h2></div></div></div><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
<span class="emphasis"><em>plans, PARs and configuration deployment, regions, application scoping and libraries support</em></span>
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 <span class="emphasis"><em>p2 features and update sites</em></span>.
Note also that Virgo Nano includes Gemini.Web as its default web container implementation and uses its default configuration.
</p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="concepts"></a>2.&nbsp;Concepts</h2></div></div></div><p>This chapter introduces some basic concepts that will help you to use Virgo.</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="concepts.modular"></a>2.1&nbsp;Modular Runtimes and Applications</h2></div></div></div><p>
Virgo Server 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="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="concepts.osgi"></a>2.2&nbsp;OSGi Concepts</h2></div></div></div><p>Modules in Virgo are represented using a standard Java
module system known as <span class="emphasis"><em>OSGi</em></span>.
Modules in OSGi are known as <span class="emphasis"><em>bundles</em></span>.
Bundles consist of programs and resources organised by Java package together
with metadata which declares imported and exported packages.
A bundle <span class="emphasis"><em>exports</em></span> a package to make the corresponding programs and resources
available for use by other bundles.
A bundle <span class="emphasis"><em>imports</em></span> a package to use the corresponding programs and resources of
another bundle.</p><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><p>
An industry consortium known as the
<span class="emphasis"><em>OSGi Alliance</em></span> 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 class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e161"></a>Bundles</h3></div></div></div><p>
Each bundle is stored in a file which conforms to the JAR file format and
can contain Java classes, a manifest (in <code class="literal">META-INF/MANIFEST.MF</code>),
and further resource files.</p><p>The OSGi framework enables bundles to be installed and run.</p><p>OSGi identifies bundles &#8220;<span class="quote">by name</span>&#8221; and &#8220;<span class="quote">by identifier</span>&#8221; (id).</p><p>The <span class="emphasis"><em>symbolic name</em></span> and
<span class="emphasis"><em>version</em></span> of a bundle are attributes of the bundle which identify the bundle.
A bundle declares its <span class="emphasis"><em>symbolic name</em></span> and <span class="emphasis"><em>version</em></span>
in its manifest (a file called <code class="literal">MANIFEST.MF</code>) like this:
</p><pre class="programlisting">Bundle-SymbolicName: org.foo.bundle
Bundle-Version: 1.2.3.BUILD-2009-06-04
</pre><p>
</p><p>Additionally, the OSGi framework
assigns a distinct number, known as a <span class="emphasis"><em>bundle id</em></span>, to each bundle
as it is installed. Bundles may be referred to &#8220;<span class="quote">by identifier</span>&#8221; using this number.
The OSGi framework itself resides in a
bundle with bundle id <code class="literal">0</code>.</p><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 class="literal">org.foo.X</code>,
from package <code class="literal">org.foo</code>, and a bundle
containing that program
would either need to contain <code class="literal">org.foo.X</code> or depend on the
package <code class="literal">org.foo</code>.
Package dependencies are specified in the bundle manifest, for example:
</p><pre class="programlisting">Import-Package: org.foo
</pre><p>
</p><p>A bundle which provides a package for use by other bundles <span class="emphasis"><em>must</em></span>
export the package in its manifest. For example:
</p><pre class="programlisting">Export-Package: org.foo
</pre><p>
</p><p>The OSGi framework ensures that a given bundle&#8217;s package dependencies
can be <span class="emphasis"><em>satisfied</em></span> before the bundle runs. This process is known as
<span class="emphasis"><em>resolution</em></span>.</p><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 class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e246"></a>Life Cycle</h3></div></div></div><p>The OSGi framework manages the <span class="emphasis"><em>life cycle</em></span> of each bundle. A bundle is
first of all <span class="emphasis"><em>install</em></span>ed and will be in the INSTALLED state.
If a request is made to <span class="emphasis"><em>start</em></span> the bundle, the OSGi framework <span class="emphasis"><em>resolve</em></span>s the bundle
and, if resolution was successful, will subsequently move the bundle to the ACTIVE state.
If a request is made to <span class="emphasis"><em>stop</em></span> the bundle, the OSGi framework will move the
bundle back to the RESOLVED state. A request may then be made to <span class="emphasis"><em>uninstall</em></span>
the bundle.</p><p>While the bundle is INSTALLED, ACTIVE or RESOLVED, it may be <span class="emphasis"><em>updated</em></span> to pick up
some changes. These changes are not detected by bundles which were depending
on the bundle before it was updated.
A &#8220;<span class="quote">refresh packages</span>&#8221; operation may be performed to ripple the
changes out to those bundles. (See <a class="xref" href="#concepts.services" title="Services">Services concepts</a>.)</p><p>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 class="figure"><a name="d0e281"></a><p class="title"><b>Figure&nbsp;2.1.&nbsp;Bundle life cycle</b></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/concepts/bundle-lifecycle.png" align="middle" alt="Bundle life cycle"></div></div></div><p><br class="figure-break"></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="concepts.services"></a>Services</h3></div></div></div><p>Bundles may publish Java objects, known as <span class="emphasis"><em>services</em></span>,
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
<span class="emphasis"><em>implementation</em></span>
class of the service.
</p><p>For example, a bundle could export a package containing the interface
<code class="literal">org.bar.SomeInterface</code>, thus:
</p><pre class="programlisting">Export-Package: org.bar
</pre><p>
</p><p>&#8230;implement the interface with a class <code class="literal">SomeImpl</code>:
</p><pre class="programlisting">package org.bar.impl;
class SomeImpl implements SomeInterface {
&#8230;
}
</pre><p>
</p><p>&#8230;create an instance of <code class="literal">SomeImpl</code> and
then publish this instance (as an instance of the interface <code class="literal">SomeInterface</code>).
</p><p>An OSGi framework publishes a number of standard services. For example, the
<span class="emphasis"><em>Package Admin</em></span> service provides the &#8220;<span class="quote">refresh packages</span>&#8221; life cycle operation
mentioned above.</p><p>OSGi provides an <em class="glossterm">API</em> which can be used to publish and find services,
but it is much simpler to use Spring DM or Blueprint to accomplish this. (See <a class="xref" href="#concepts.springdm" title="2.3&nbsp;Spring DM and Blueprint Concepts">Spring DM concepts</a>.)</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e341"></a>Versioning</h3></div></div></div><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 class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e346"></a>Version Numbers</h4></div></div></div><p>An OSGi <span class="emphasis"><em>version number</em></span> consists of up to three numeric components,
or exactly three
numeric components followed by a string component. These components are
separated by a period (&#8220;<span class="quote"><code class="literal">.</code></span>&#8221;) and
are called the <span class="emphasis"><em>major</em></span>, <span class="emphasis"><em>minor</em></span>, <span class="emphasis"><em>micro</em></span>,
and <span class="emphasis"><em>qualifier</em></span> components, respectively.
</p><p>For example, the version <code class="literal">2.4.1.ga</code> has major component <code class="literal">2</code>, minor component
<code class="literal">4</code>, micro component <code class="literal">1</code>,
and a qualifier component <code class="literal">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><p>Trailing components may be omitted along with their period (<code class="literal">.</code>). So, for example, the version
numbers <code class="literal">2</code>, <code class="literal">2.0</code>, and <code class="literal">2.0.0</code>
all denote the same version. This example demonstrates that <code class="literal">0</code> is assumed if a numeric component is omitted,
and the empty string is assumed for an omitted qualifier.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e404"></a>Version Ranges</h4></div></div></div><p>Dependencies on bundles and packages have an associated <span class="emphasis"><em>version range</em></span>
which is specified using an interval notation: a square bracket
&#8220;<span class="quote"><code class="literal">[</code></span>&#8221; or &#8220;<span class="quote"><code class="literal">]</code></span>&#8221; denotes
an <span class="emphasis"><em>inclusive</em></span> end of the range and a round bracket
&#8220;<span class="quote"><code class="literal">(</code></span>&#8221; or &#8220;<span class="quote"><code class="literal">)</code></span>&#8221; denotes
an <span class="emphasis"><em>exclusive</em></span> 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><p>If a single version number is used where a version <span class="emphasis"><em>range</em></span> is
required this does <span class="emphasis"><em>not</em></span> indicate a single version, but the range <span class="emphasis"><em>starting</em></span> from that version and
including all higher versions.</p><p>There are three common cases:
</p><div class="itemizedlist"><ul type="disc"><li><p>A &#8220;<span class="quote">strict</span>&#8221; version range, such as <code class="literal">[1.2,1.2]</code>, which
denotes that version and only that version.</p></li><li><p>A &#8220;<span class="quote">half-open</span>&#8221; range, such as
<code class="literal">[1.2,2)</code>, which has an inclusive lower limit
and an exclusive upper limit, denoting version <code class="literal">1.2.0</code> and any version after this, up
to, <span class="emphasis"><em>but not including</em></span>, version <code class="literal">2.0.0</code>.
</p></li><li><p>An &#8220;<span class="quote">unbounded</span>&#8221; version range, such as <code class="literal">1.2</code>, which
denotes version <code class="literal">1.2</code> and <span class="emphasis"><em>all</em></span> later versions.</p></li></ul></div><p>
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e491"></a>Versioning Policies</h4></div></div></div><p>A <span class="emphasis"><em>versioning policy</em></span> 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.</p><p>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><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 class="literal">[1.2.1.beta,1.2.2)</code>
which accept any version from <code class="literal">1.2.1.beta</code> (inclusive) up to but not including
<code class="literal">1.2.2</code> (exclusive).
</p><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 class="literal">[1.2,2)</code> to capture this.</p><p>
The OSGi Alliance has published a <a class="ulink" href="http://www.osgi.org/wiki/uploads/Links/SemanticVersioning.pdf" target="_top">Semantic
Versioning white paper</a> which provides some recommendations and guidance on versioning policies.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e523"></a>Bundle Version</h4></div></div></div><p>Each bundle has a version.
The bundle&#8217;s version may be specified in the manifest using a
<code class="literal">Bundle-Version</code> header:
</p><div class="informalexample"><pre class="programlisting">Bundle-Version: 1.4.3.BUILD-20090302
</pre></div><p>
If not specified the bundle version is assumed to be <code class="literal">0</code>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e539"></a>Package Version</h4></div></div></div><p>Each exported package has a version.
The exported package&#8217;s version may be specified on the Export-Package manifest header. For example
</p><div class="informalexample"><pre class="programlisting">Export-Package: org.foo;version="2.9",org.bar;version="1"
</pre></div><p>
exports two packages: <code class="literal">org.foo</code>, at version <code class="literal">2.9.0</code> and
<code class="literal">org.bar</code>, at version <code class="literal">1.0.0</code>.
</p><p>If the version attribute is omitted, the version is assumed to be <code class="literal">0</code>.</p><p>Each package <span class="emphasis"><em>import</em></span> has a version <span class="emphasis"><em>range</em></span>.
The package import version range may be specified on the <code class="literal">Import-Package</code> manifest header.
If interval notation is used, the version range must be enclosed in double quotes, for example:
</p><div class="informalexample"><pre class="programlisting">Import-Package: org.foo;version="[2,3)",org.bar;version="[1,1]"</pre></div><p>
seeks to import a package <code class="literal">org.foo</code> in the range <code class="literal">[2.0.0,3.0.0)</code> and a package
<code class="literal">org.bar</code> with the (exact) version <code class="literal">1.0.0</code>.
</p><p>If a version range is not specified on an import, the range <code class="literal">0</code> is assumed, meaning that
any version of this package would satisfy the import.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e598"></a>Bundle Manifest Version</h4></div></div></div><p>Bundle manifests have a version which is <code class="literal">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 class="literal">2</code>, indicating OSGi Release 4 semantics.
The bundle manifest&#8217;s version should be specified on the Bundle-ManifestVersion manifest header, exactly as follows:
</p><div class="informalexample"><pre class="programlisting">Bundle-ManifestVersion: 2
</pre></div><p>
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e614"></a>Manifest Version</h4></div></div></div><p>Manifests themselves also have a version which <span class="emphasis"><em>must</em></span> be specified as <code class="literal">1.0</code>.
This is not an OSGi definition but part of the
(<a class="ulink" href="http://java.sun.com/javase/6/docs/technotes/guides/jar/jar.html" target="_top">JAR file specification</a>).
</p><div class="informalexample"><pre class="programlisting">Manifest-Version: 1.0
</pre></div><p>
</p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="concepts.springdm"></a>2.3&nbsp;Spring DM and Blueprint Concepts</h2></div></div></div><p>Spring DM is a project which enables <span class="emphasis"><em>services</em></span> to be published and consumed
using descriptions written in XML.</p><p>The XML descriptions reside in files with extension <code class="literal">.xml</code> in the
bundle&#8217;s <code class="literal">META-INF/spring</code> sub-directory.</p><p>
To publish a service, an <code class="literal">&lt;osgi:service&gt;</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><p>To consume a service, an <code class="literal">&lt;osgi:reference&gt;</code> tag is used and the
service may be passed into other Spring beans using Spring&#8217;s dependency
injection facilities.</p><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 <span class="emphasis"><em>damping</em></span>.</p><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><p>When a bundle is stopped, Spring DM retracts any services it published on behalf of the bundle
and closes the bundle&#8217;s application contexts.
Virgo turns off damping of a service proxy while the proxy&#8217;s application context
is being closed.</p><p>Spring DM was contributed to Eclipse as the <span class="emphasis"><em>Gemini Blueprint</em></span> project.
Virgo has Gemini Blueprint built-in.</p><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 class="xref" href="#furtherreading" title="Appendix&nbsp;C.&nbsp; Further Reading">Appendix&nbsp;C, <i>
Further Reading
</i></a> for the Blueprint specification.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="concepts.virgo"></a>2.4&nbsp;Virgo Concepts</h2></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">
This section is not relevant for Virgo Nano.
</td></tr></table></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="concepts.repositories"></a>The Provisioning Repository</h3></div></div></div>
The Virgo provisioning repository contains artifacts and metadata indexed by the artifact type, name, and version. There are three kinds of repository: <span class="emphasis"><em>external</em></span>, <span class="emphasis"><em>watched</em></span>, and <span class="emphasis"><em>remote</em></span>. Repositories are passive in the sense that changes to repository content do not cause artifacts to be deployed into Virgo, refreshed, or undeployed.
<div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e697"></a>Artifact Types</h4></div></div></div>
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 class="xref" href="#concepts.grouping" title="Grouping Bundles">Grouping Bundles</a>.
</div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e703"></a>External Repositories</h4></div></div></div><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><p>
Virgo's default repository configuration, in <code class="literal">configuration/org.eclipse.virgo.repository.properties</code>, specifies an external repository created from the
<code class="literal">repository/ext</code> directory.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e716"></a>Watched Repositories</h4></div></div></div><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><p>
Virgo's default repository configuration specifies a watched repository based on the contents of the <code class="literal">repository/usr</code> directory.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e726"></a>Remote Repositories</h4></div></div></div><p>
A remote repository refers to a repository hosted by a Virgo instance sometimes known as a <span class="emphasis"><em>repository server</em></span>.
The hosted repository is configured using the file <code class="literal">configuration/org.eclipse.virgo.apps.repository.properties</code> and may be either an external or a watched
repository.
</p><p>
The remote repository is accessed by a Virgo instance sometimes known as a <span class="emphasis"><em>repository client</em></span>.
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 class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e742"></a>Repository Chains</h4></div></div></div><p>
The Virgo repository is configured as a <span class="emphasis"><em>chain</em></span> 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="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="concepts.grouping"></a>Grouping Bundles</h4></div></div></div><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 &#8220;<span class="quote"><code class="literal">.par</code></span>&#8221;. This is called a PAR file.</p><p>All the bundles in a PAR file are resolved together and so mutual dependencies are permitted.</p><p>At runtime a PAR file provides a <span class="emphasis"><em>scope</em></span> 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><p>Virgo also provides the plan artifact as another way of grouping bundles and other artifacts into an application.
A <span class="emphasis"><em>plan</em></span> 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><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 class="literal">Import-Library</code> manifes header.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="kernel.user.region"></a>Kernel and User Region</h4></div></div></div><p>Conceptually, VTS can be divided into two separate subsystems, one of which actually encompases the other:</p><div class="itemizedlist"><ul type="disc"><li>The <span class="emphasis"><em>kernel</em></span>, 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.
<p>See <a class="link" href="#kernel-overview" title="The Virgo Kernel">The Virgo Kernel</a> for additional information.</p></li><li>The <span class="emphasis"><em>user region</em></span> 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.
<p>See <a class="link" href="#user-region-overview" title="The User Region">The User Region</a> for additional information.</p></li></ul></div><p>When you download and install Virgo Server for Apache Tomcat you get both the kernel and web server support (configured in the user region). You can also <a class="ulink" href="http://www.eclipse.org/virgo/download/" target="_top">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><p>The following graphic shows how the kernel and user region make up VTS:</p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="885"><tr style="height: 805px"><td><img src="images/kernel-user-region.png" width="885"></td></tr></table><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="kernel-overview"></a>The Virgo Kernel</h5></div></div></div><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 class="itemizedlist"><ul type="disc"><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 Spring DM support
</p></li></ul></div><p>See <a class="link" href="#configuring" title="13.&nbsp;Configuration">Configuring VTS</a> for details about configuring the kernel to better suit your environment. </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="user-region-overview"></a>The User Region</h5></div></div></div><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><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. </p><p>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 class="link" href="#configuring" title="13.&nbsp;Configuration">Configuring VTS</a> for details.
</p><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></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="concepts.p2"></a>2.5&nbsp;p2 Concepts</h2></div></div></div><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 class="ulink" href="http://fosslc.org/drupal/content/gentle-introduction-p2" target="_top">here(video).</a>
</p><p>
<a class="ulink" href="http://bkapukaranov.wordpress.com/2011/07/12/rt-meets-p2/" target="_top">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><p>
This <a class="ulink" href="http://www.slideshare.net/PascalRapicault/understanding-and-extending-p2-for-fun-and-profit" target="_top">presentation(slides only)</a>
sheds light on more advanced p2 features and turns our attention to its extension points.
</p><p>
Finally, the <a class="ulink" href="http://wiki.eclipse.org/Equinox/p2" target="_top">p2 wiki</a>
also provides both getting started guides as well as information on more advanced features.
</p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="using-the-p2-director"></a>3.&nbsp;Using the p2 director</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="prereqs"></a>3.1&nbsp;Prerequisites</h2></div></div></div><p>
The Virgo Server for Apache Tomcat, or VTS for short, requires Java SE 6 or later to be installed. Java is available from
<a class="ulink" href="http://www.java.com/" target="_top">http://www.java.com/</a> and elsewhere.
</p><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 class="ulink" href="http://www.eclipse.org/downloads/" target="_top">here</a>.
It has built-in p2 director and other p2 applications.
</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important: Setting the Target Platform"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.gif"></td><th align="left">Setting the Target Platform</th></tr><tr><td align="left" valign="top"></td></tr></table></div><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:</p><p>Go to Eclipse's Preferences-&gt;Plug-in Development-&gt;Target Platform. Below is shown how the view looks like when a default target platform is set.</p><p>
<img src="images/target-platform-view.png">
</p><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.</p><p>If the default target platform is missing then add a new one via the <span class="emphasis"><em>Add...</em></span> button and select the <span class="emphasis"><em>Default</em></span> radio button as shown below:</p><p>
<img src="images/default-target-create.png">
</p><p>You can now click <span class="emphasis"><em>Next</em></span> and then <span class="emphasis"><em>Finish</em></span>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="using-director"></a>3.2&nbsp;Installing with the p2 director from Eclipse</h2></div></div></div><p>
This section covers briefly using the p2 director for installing.
A helpful page is the p2 director's <a class="ulink" href="http://help.eclipse.org/indigo/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/p2_director.html" target="_top">documentation at help.eclipse.org</a>.
There you can find more information on the different supported arguments.
</p><p>
Here's how to use the GUI version of the director built-in Eclipse.
</p><p>
1. Go to the <span class="emphasis"><em>Run</em></span> context menu and select <span class="emphasis"><em>Run Configurations</em></span>
</p><p>
2. Create a new one and choose the director application as shown below, then switch to the <span class="emphasis"><em>Arguments</em></span> tab
</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.gif"></td><th align="left">Important</th></tr><tr><td align="left" valign="top">In the image below the "Location:" text box's value is managed by your IDE, don't type anything in there.</td></tr></table></div><p>
<img src="images/run_configuration.png">
</p><p>
In the <span class="emphasis"><em>Program Arguments</em></span> section append the director arguments. Here's an example I used:
</p><pre class="screen">-repository http://download.eclipse.org/virgo/updatesite/3.6.2.RELEASE
-installIU nano.product
-tag InitialState
-destination <span class="bold"><strong>/Users/&lt;youruser&gt;/install/virgo</strong></span>
-profile VirgoProfile
-roaming
-p2.os ${target.os}
-p2.ws ${target.ws}
-p2.arch ${target.arch}
</pre><p>
</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.gif"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>The <span class="emphasis"><em>-repository</em></span> argument accepts any valid p2 repository.</p><p>The <span class="emphasis"><em>-destination</em></span> 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></td></tr></table></div><p>
These arguments produce a Virgo Nano installation. For the <span class="emphasis"><em>p2.*</em></span> arguments use the same properties from the example above. Eclipse will substitute them later with real values.
</p><p>
The passed value for <span class="emphasis"><em>-installIU</em></span> determines which Virgo product is going to be installed. Here's a list of all Virgo product install IUs:
</p><p><span class="emphasis"><em>nano.product</em></span> - Virgo Nano</p><p>
</p><p><span class="emphasis"><em>nano-full.product</em></span> - Virgo Nano Full (VN + p2 + GW)</p><p>
</p><p><span class="emphasis"><em>kernel.product</em></span> - Virgo Kernel</p><p>
</p><p><span class="emphasis"><em>tomcat-server.product</em></span> - Virgo Server for Apache Tomcat</p><p>
</p><p><span class="emphasis"><em>jetty-server.product</em></span> - Virgo Jetty Server</p><p>
</p><p>
<img src="images/director_args.png">
</p><p>
3. Finally, run the created configuration. You should see the following output in Eclipse's Console
</p><p>
<img src="images/director_result.png">
</p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="installation"></a>4.&nbsp;Installing Virgo Server for Apache Tomcat</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="installation-prereqs"></a>4.1&nbsp;Prerequisites</h2></div></div></div><p>
The Virgo Server for Apache Tomcat, or VTS for short, requires Java SE 6 or later to be installed. Java is available from
<a class="ulink" href="http://www.java.com/" target="_top">http://www.java.com/</a> and elsewhere.
</p><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 class="ulink" href="http://www.eclipse.org/downloads/" target="_top">here</a>.
It has built-in p2 director and other p2 applications.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="installation-zip"></a>4.2&nbsp;Installing from the ZIP Download</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1048"></a>Downloading the ZIP file</h3></div></div></div><p>
Virgo Server for Apache Tomcat is distributed as a ZIP file. This can be downloaded from
<a class="ulink" href="http://www.eclipse.org/virgo/download/" target="_top">here</a>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="installation-zip-installing"></a>Installing</h3></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="installation-zip-installing-linux"></a>Linux</h4></div></div></div><p>
To install Virgo Server for Apache Tomcat on Linux, unzip the distribution package to the desired installation directory.
For example, to install into <code class="literal">/opt</code>:
</p><pre class="screen">prompt$ unzip virgo-web-server-3.6.2.RELEASE.zip -d /opt</pre><p>
This creates a directory called <code class="literal">virgo-web-server-3.6.2.RELEASE</code> under <code class="literal">/opt</code>.
</p><p>
Virgo Server for Apache Tomcat requires write access to the installation directory, in this case <code class="literal">/opt/virgo-web-server-3.6.2.RELEASE</code>.
Typically this means it must be run as the user that installed it, or the installation directory&#8217;s ownership must be changed.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="installation-zip-installing-win"></a>Microsoft Windows</h4></div></div></div><p>
To install the Virgo Server 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></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="installation-updatesite"></a>4.3&nbsp;Installing from an update site</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1090"></a>The repository location</h3></div></div></div><p>
Virgo has a single p2 repository that contains all Virgo distributions. The repository for version 3.6.2.RELEASE can be found <a class="ulink" href="http://download.eclipse.org/virgo/updatesite/3.6.2.RELEASE" target="_top">here</a>.
There is a repository for each released version.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1098"></a>Using the p2 director</h3></div></div></div><p>
As shown in <a class="xref" href="#using-director" title="3.2&nbsp;Installing with the p2 director from Eclipse">Section&nbsp;3.2, &#8220;Installing with the p2 director from Eclipse&#8221;</a> you can easily install VTS in a desired destination.
The only director argument that needs to be adjusted is <span class="emphasis"><em>-installIU</em></span>.
</p><p>
For VTS the right value is <span class="emphasis"><em>tomcat-server.product</em></span>.
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="installation-post"></a>4.4&nbsp;Post-installation steps</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="installation-post-env"></a>Set environment variable variables</h3></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="installation-post-env-java"></a>JAVA_HOME</h4></div></div></div><p>
Virgo Server for Apache Tomcat uses the <code class="literal">JAVA_HOME</code> environment variable to locate the <code class="literal">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="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="installation-post-env-server"></a>SERVER_HOME</h4></div></div></div><p>
As a convenience it is recommended that you create an environment variable that points
to the Virgo Server for Apache Tomcat installation directory. Note that the Virgo Server 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 Server for Apache Tomcat&#8217;s documentation assumes that the variable is named
<code class="literal">SERVER_HOME</code>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="installation-post-env-server-linux"></a>Linux</h4></div></div></div><p>
Edit the <code class="literal">.profile</code> file in your home directory to
add the <code class="literal">SERVER_HOME</code> and <code class="literal">JAVA_HOME</code> environment variables. For
example, if you installed into <code class="literal">/opt</code>:
</p><pre class="screen">export SERVER_HOME=/opt/virgo-web-server-3.6.2.RELEASE/
export JAVA_HOME=/user/java/jdk1.6.0_17
export PATH=$JAVA_HOME/bin:$PATH</pre><p>
To verify the setting of <code class="literal">JAVA_HOME</code>, issue the command <code class="literal">$JAVA_HOME/bin/java -version</code> from a new terminal window
and ensure that the command completes successfully and reports
a Java version <code class="literal">1.6.</code><span class="emphasis"><em>x</em></span> (denoting Java 6) or greater.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="installation-post-env-server-win"></a>Microsoft Windows</h4></div></div></div><p>
This section shows how to add <code class="literal">SERVER_HOME</code> as a system variable on Windows. Follow the same procedure to add or update the <code class="literal">JAVA_HOME</code> environment variable.
</p><p>
From the Start menu, open the Control Panel and double-click on &#8216;System&#8217;.
</p><p>
<img src="images/system-props.png">
</p><p>
Click the &#8216;Advanced&#8217; tab and select &#8216;Environment Variables&#8217;. Next,
click the &#8216;New&#8217; button in the &#8216;System Variables&#8217; section.
</p><p>
<img src="images/env-variables.png">
</p><p>
This will display the &#8216;New System Variable&#8217; window. Enter
<code class="literal">SERVER_HOME</code> as the &#8216;Variable name&#8217; and
the installation directory as the &#8216;Variable value&#8217;. Click OK.
</p><p>
<img src="images/system-variable.png">
</p><p>
To verify the setting of <code class="literal">JAVA_HOME</code>, issue the command <code class="literal">"%JAVA_HOME%"\bin\java -version</code> from
a new command prompt and ensure that the command completes successfully and reports
a Java version <code class="literal">1.6.</code><span class="emphasis"><em>x</em></span> (denoting Java 6) or greater.
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="installation-post-env-server-win-troubleshooting"></a>Microsoft Windows - Troubleshooting Security Permissions</h3></div></div></div><p>
When starting Virgo Server for Apache Tomcat on some variants of Windows you might encounter a problem with file permissions.
The error looks like this.
</p><pre class="screen">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.</pre><p>
If VTS starts correctly (see <a class="xref" href="#starting-stopping" title="7.&nbsp;Starting and Stopping Virgo Server for Apache Tomcat">Starting and Stopping Virgo Server for Apache Tomcat</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 &#8216;configuration&#8217; directory of the installation
in Windows Explorer.
</p><p>
<img src="images/install-windows-1-FileListing.png">
</p><p>
Right click on the &#8216;org.eclipse.virgo.kernel.jmxremote.access.properties&#8217; file and view its properties,
then select the &#8216;Security&#8217; tab. Remove all groups and users from the list and select &#8216;Apply&#8217;.
</p><p>
<img src="images/install-windows-2-SecuritySettings.png">
</p><p>
Within the security page select the &#8216;Advanced&#8217; options. On the &#8216;Owner&#8217; tab, choose the owner
that you are trying to run the VTS as and select &#8216;Apply&#8217;.
</p><p>
<img src="images/install-windows-3-AdvanceSettingsOwner.png">
</p><p>
Once this is done select &#8216;OK&#8217; to return to the &#8216;Security&#8217; tab
and now add the owner to the list of groups and users that have permission to access the file.
</p><p>
<img src="images/install-windows-4-AllSetReadAndExecute.png">
</p><p>
Once all these steps are complete you can proceed to start the VTS.
</p><pre class="screen">C:\dev\virgo-web-server-3.6.2.RELEASE&gt;bin\startup.bat
[2009-12-08 13:09:09.545] startup-tracker &lt;KE0001I&gt; Kernel starting.</pre></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="kernel-installation"></a>5.&nbsp;Installing Virgo Kernel</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="kernel-installation-prereqs"></a>5.1&nbsp;Prerequisites</h2></div></div></div><p>
The Virgo Kernel, or VK for short, requires Java SE 6 or later to be installed. Java is available from
<a class="ulink" href="http://www.java.com/" target="_top">http://www.java.com/</a> and elsewhere.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="kernel-installation-zip"></a>5.2&nbsp;Installing from the ZIP Download</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1266"></a>Downloading the ZIP file</h3></div></div></div><p>
Virgo Kernel is distributed as a ZIP file. This can be downloaded from
<a class="ulink" href="http://www.eclipse.org/virgo/download/" target="_top">here</a>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="kernel-installation-zip-installing"></a>Installing</h3></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="kernel-installation-zip-installing-linux"></a>Linux</h4></div></div></div><p>
To install the Virgo Kernel on Linux, unzip the distribution package to the desired installation directory.
For example, to install into <code class="literal">/opt</code>:
</p><pre class="screen">prompt$ unzip virgo-kernel-3.6.2.RELEASE.zip -d /opt</pre><p>
This creates a directory called <code class="literal">virgo-kernel-3.6.2.RELEASE</code> under <code class="literal">/opt</code>.
</p><p>
Virgo Kernel requires write access to the installation directory, in this case <code class="literal">/opt/virgo-kernel-3.6.2.RELEASE</code>.
Typically this means it must be run as the user that installed it, or the installation directory&#8217;s ownership must be changed.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="kernel-installation-zip-installing-win"></a>Microsoft Windows</h4></div></div></div><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></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="kernel-installation-updatesite"></a>5.3&nbsp;Installing from an update site</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1308"></a>The repository location</h3></div></div></div><p>
Virgo has a single p2 repository that contains all Virgo distributions. The repository for version 3.6.2.RELEASE can be found <a class="ulink" href="http://download.eclipse.org/virgo/updatesite/3.6.2.RELEASE" target="_top">here</a>.
There is a repository for each released version.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1316"></a>Using the p2 director</h3></div></div></div><p>
As shown in <a class="xref" href="#using-director" title="3.2&nbsp;Installing with the p2 director from Eclipse">Section&nbsp;3.2, &#8220;Installing with the p2 director from Eclipse&#8221;</a> you can easily install VK in a desired destination.
The only director argument that needs to be adjusted is <span class="emphasis"><em>-installIU</em></span>.
</p><p>
For VK the right value is <span class="emphasis"><em>kernel.product</em></span>.
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="kernel-installation-post"></a>5.4&nbsp;Post-installation steps</h2></div></div></div>
Follow the same <a class="link" href="#installation-post" title="4.4&nbsp;Post-installation steps">Post-installation steps</a> as for Virgo Server for Apache Tomcat.
</div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="nano-installation"></a>6.&nbsp;Installing Virgo Nano</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="nano-installation-prereqs"></a>6.1&nbsp;Prerequisites</h2></div></div></div><p>
The Virgo Nano, or VN for short, requires Java SE 6 or later to be installed. Java is available from
<a class="ulink" href="http://www.java.com/" target="_top">http://www.java.com/</a> and elsewhere.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="nano-installation-zip"></a>6.2&nbsp;Installing from the ZIP Download</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1352"></a>Downloading the ZIP file</h3></div></div></div><p>
Virgo Nano is distributed as a ZIP file. This can be downloaded from
<a class="ulink" href="http://www.eclipse.org/virgo/download/" target="_top">here</a>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="nano-installation-zip-installing"></a>Installing</h3></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="nano-installation-zip-installing-linux"></a>Linux</h4></div></div></div><p>
To install the Virgo Nano on Linux, unzip the distribution package to the desired installation directory.
For example, to install into <code class="literal">/opt</code>:
</p><pre class="screen">prompt$ unzip virgo-nano-3.6.2.RELEASE.zip -d /opt</pre><p>
This creates a directory called <code class="literal">virgo-nano-3.6.2.RELEASE</code> under <code class="literal">/opt</code>.
</p><p>
Virgo Nano requires write access to the installation directory, in this case <code class="literal">/opt/virgo-nano-3.6.2.RELEASE</code>.
Typically this means it must be run as the user that installed it, or the installation directory&#8217;s ownership must be changed.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="nano-installation-zip-installing-win"></a>Microsoft Windows</h4></div></div></div><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></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="nano-installation-updatesite"></a>6.3&nbsp;Installing from an update site</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1394"></a>The repository location</h3></div></div></div><p>
Virgo has a single p2 repository that contains all Virgo distributions. The repository for version 3.6.2.RELEASE can be found <a class="ulink" href="http://download.eclipse.org/virgo/updatesite/3.6.2.RELEASE" target="_top">here</a>.
There is a repository for each released version.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1402"></a>Using the p2 director</h3></div></div></div><p>
As shown in <a class="xref" href="#using-director" title="3.2&nbsp;Installing with the p2 director from Eclipse">Section&nbsp;3.2, &#8220;Installing with the p2 director from Eclipse&#8221;</a> you can easily install VN in a desired destination.
The only director argument that needs to be adjusted is <span class="emphasis"><em>-installIU</em></span>.
</p><p>
For VN the right value is <span class="emphasis"><em>nano.product</em></span>.
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="nano-installation-post"></a>6.4&nbsp;Post-installation steps</h2></div></div></div>
Follow the same <a class="link" href="#installation-post" title="4.4&nbsp;Post-installation steps">Post-installation steps</a> as for Virgo Server for Apache Tomcat.
</div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="starting-stopping"></a>7.&nbsp;Starting and Stopping Virgo Server for Apache Tomcat</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1429"></a>7.1&nbsp;Starting Virgo Server for Apache Tomcat</h2></div></div></div><p>
To start Virgo Server for Apache Tomcat run the <code class="literal">startup.sh</code> (Linux) or <code class="literal">startup.bat</code> (Windows) script.
For both platforms, the script is located in the <code class="literal">SERVER_HOME/bin</code> directory.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">
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:
<pre class="screen">[2011-12-28 11:41:31.528] startup-tracker &lt;KE0001I&gt; Kernel starting.
[2011-12-28 11:41:31.602] startup-tracker &lt;KE0002I&gt; Kernel started.
</pre></td></tr></table></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1447"></a>Linux</h3></div></div></div><p>
To start Virgo Server for Apache Tomcat, open a terminal window and run <code class="literal">startup.sh</code>:
</p><pre class="screen">prompt$ cd $SERVER_HOME
prompt$ bin/startup.sh</pre><p>
Once Virgo Server for Apache Tomcat has started, the console will display a log message
similar to the one shown below, along with other status messages:
</p><pre class="screen">[2009-11-30 12:12:12.111] Thread-2 &lt;UR0001I&gt; User region ready.</pre><p>The preceding message indicates that you can start using VTS.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1463"></a>Microsoft Windows</h3></div></div></div><p>
To start Virgo Server for Apache Tomcat, open a command-window and run <code class="literal">startup.bat</code>:
</p><pre class="screen">prompt&gt; cd %SERVER_HOME%
prompt&gt; bin\startup.bat</pre><p>
Once Virgo Server for Apache Tomcat has started, the console will display a log message
similar to the one shown below, along with other status messages:
</p><pre class="screen">[2009-11-30 12:12:12.111] Thread-2 &lt;UR0001I&gt; User region ready.</pre><p>
</p><p>The preceding message indicates that you can start using VTS.</p><p>
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1481"></a>7.2&nbsp;Starting in Clean Mode</h2></div></div></div><p>
When you start Virgo Server for Apache Tomcat in clean mode, the startup script removes the <code class="literal">SERVER_HOME/work</code> directory (and hence all
running applications) as well as all trace, log and dump files. It leaves the
<code class="literal">SERVER_HOME/repository</code> and <code class="literal">SERVER_HOME/pickup</code> directories untouched,
which means that any applications previously hot deployed will be automatically reinstalled.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1495"></a>Linux</h3></div></div></div><p>
To start Virgo Server for Apache Tomcat in clean mode, open a terminal window and run <code class="literal">startup.sh -clean</code>:
</p><pre class="screen">prompt$ cd $SERVER_HOME
prompt$ bin/startup.sh -clean </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1505"></a>Microsoft Windows</h3></div></div></div><p>
To start Virgo Server for Apache Tomcat in clean mode, open a command window and run <code class="literal">startup.bat -clean</code>:
</p><pre class="screen">prompt&gt; cd %SERVER_HOME%
prompt&gt; bin\startup.bat -clean</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1515"></a>7.3&nbsp;Starting in Debug Mode</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1518"></a>Linux</h3></div></div></div><p>
To start Virgo Server for Apache Tomcat in debug mode, run
<code class="literal">startup.sh</code> passing in the
<code class="literal">-debug</code> argument:
</p><pre class="screen">prompt$ cd $SERVER_HOME
prompt$ bin/startup.sh -debug</pre><p>
This will start the debug agent listening on port
<code class="literal">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 class="literal">-debug</code> argument:
</p><pre class="screen">prompt$ cd $SERVER_HOME
prompt$ bin/startup.sh -debug 8001</pre><p>
This will start the debug agent listening on port
<code class="literal">8001</code>. To start in debug mode and suspend the VM
until a debugger attaches, pass in the <code class="literal">-suspend</code>
argument along with the <code class="literal">-debug</code> argument:
</p><pre class="screen">prompt$ cd $SERVER_HOME
prompt$ bin/startup.sh -debug -suspend</pre><p>
This starts the debug agent, but prevents Virgo Server 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 class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1556"></a>Microsoft Windows</h3></div></div></div><p>
To start Virgo Server for Apache Tomcat in debug mode, run
<code class="literal">startup.bat</code> passing in the
<code class="literal">-debug</code> argument:
</p><pre class="screen">prompt&gt; cd %SERVER_HOME%
prompt&gt; bin\startup.bat -debug</pre><p>
This will start the debug agent listening on port
<code class="literal">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 class="literal">-debug</code> argument:
</p><pre class="screen">prompt&gt; cd %SERVER_HOME%
prompt&gt; bin\startup.bat -debug 8001</pre><p>
This will start the debug agent listening on port
<code class="literal">8001</code>. To start in debug mode and suspend the VM
until a debugger attaches, pass in the <code class="literal">-suspend</code>
argument along with the <code class="literal">-debug</code> argument:
</p><pre class="screen">prompt&gt; cd %SERVER_HOME%
prompt&gt; bin\startup.bat -debug -suspend</pre><p>
This starts the debug agent, but prevents Virgo Server 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="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1594"></a>7.4&nbsp;Starting with JMX Access Modifications</h2></div></div></div>
The Virgo Server 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 class="literal">9875</code>
and the default username and password are <code class="literal">admin</code> and <code class="literal">springsource</code>.
<div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1607"></a>Linux</h3></div></div></div><p>
To start Virgo Server for Apache Tomcat with default JMX access enabled, run <code class="literal">startup.sh</code> passing
in no arguments:
</p><pre class="screen">prompt$ cd $SERVER_HOME
prompt$ bin/startup.sh </pre><p>
To start JConsole, run the <code class="literal">jconsole.sh</code> script, located in the <code class="literal">bin</code> directory, as shown:
</p><pre class="screen">prompt$ cd $SERVER_HOME
prompt$ bin/jconsole.sh </pre><p>
The following image shows how to specify a local connection using JConsole.
</p><p>
<img src="images/jmx-local-attach.png">
</p><p>
The following image shows how to specify a remote connection in JConsole that uses SSL with the default
username/password (<code class="literal">admin/springsource</code> and default secure port of <code class="literal">9875</code>).
</p><p>
<img src="images/jmx-remote-attach-default.png">
</p><p>
To start with the JMX remote access on a specific port number other than the default <code class="literal">9875</code>,
pass this port number in as the value
of the <code class="literal">-jmxport</code> argument:
</p><pre class="screen">prompt$ cd $SERVER_HOME
prompt$ bin/startup.sh -jmxport 9090</pre><p>
This will start the Virgo Server for Apache Tomcat with JMX enabled for remote connections on port <code class="literal">9090</code>.
</p><p>
<img src="images/jmx-remote-attach-jmxport.png">
</p><p>To start the JMX remote access with a custom username and password, update the <code class="literal">$SERVER_HOME/configuration/org.eclipse.virgo.kernel.users.properties</code> file. First specify the custom username by changing the value of the <code class="literal">role.admin</code> property. Then set the password of this new user by adding a new property called <code class="literal">user.<span class="emphasis"><em>username</em></span></code>, where <code class="literal"><span class="emphasis"><em>username</em></span></code> refers to the actual name of the user. Finally, restart VTS for the changes to take effect.</p><p>For example, if you want change the JMX remote access username to <code class="literal">zebedee</code> with password <code class="literal">florence</code>, change the file as follows:
</p><pre class="programlisting">##################
# User definitions
##################
user.zebedee=florence
##################
# Role definitions
##################
role.admin=zebedee</pre><p>Specify the custom username in JConsole as shown. </p><p>
<img src="images/jmx-remote-attach-jmxusers.png">
</p><p>
To start the JMX remote access using a custom SSL certificate, edit the file located at
<code class="literal">$SERVER_HOME/configuration/keystore</code>. If you wish to use a different keystore,
pass this filename in as the value for the <code class="literal">-keystore</code> argument and the keystore
password in as the value for the <code class="literal">-keystorePassword</code> argument:
</p><pre class="screen">prompt$ cd $SERVER_HOME
prompt$ bin/startup.sh -keystore customKeystore -keystorePassword customKeystorePassword</pre><p>
This will start the Virgo Server for Apache Tomcat with JMX enabled for remote connections using an SSL certificate from
<code class="literal">customKeystore</code> with a password of <code class="literal">customKeystorePassword</code>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1718"></a>Microsoft Windows</h3></div></div></div><p>
To start Virgo Server for Apache Tomcat with default JMX access enabled, run <code class="literal">startup.bat</code> passing
in no arguments:
</p><pre class="screen">prompt&gt; cd %SERVER_HOME%
prompt&gt; bin\startup.bat</pre><p>
To start JConsole, run the <code class="literal">jconsole.bat</code> script, located in the <code class="literal">bin</code> directory, as shown:
</p><pre class="screen">prompt&gt; cd %SERVER_HOME%
prompt&gt; bin\jconsole.bat </pre><p>
The following image shows how to specify a local connection using JConsole.
</p><p>
<img src="images/jmx-local-attach.png">
</p><p>
The following image shows how to specify a remote connection in JConsole that uses SSL with the default
username/password (<code class="literal">admin/springsource</code> and default secure port of <code class="literal">9875</code>).
</p><p>
<img src="images/jmx-remote-attach-default.png">
</p><p>
To start with the JMX remote access on a specific port number other than the default <code class="literal">9875</code>,
pass this port number in as the value of the <code class="literal">-jmxport</code> argument:
</p><pre class="screen">prompt&gt; cd %SERVER_HOME%
prompt&gt; bin\startup.bat -jmxport 9090</pre><p>
This will start the Virgo Server for Apache Tomcat with JMX enabled for remote connections on port
<code class="literal">9090</code>.
</p><p>
<img src="images/jmx-remote-attach-jmxport.png">
</p><p>To start the JMX remote access with a custom username and password, update the <code class="literal">%SERVER_HOME%\configuration\org.eclipse.virgo.kernel.users.properties</code> file. First specify the custom username by changing the value of the <code class="literal">role.admin</code> property. Then set the password of this new user by adding a new property called <code class="literal">user.<span class="emphasis"><em>username</em></span></code>, where <code class="literal"><span class="emphasis"><em>username</em></span></code> refers to the actual name of the user. Finally, restart VTS for the changes to take effect.</p><p>For example, if you want change the JMX remote access username to <code class="literal">zebedee</code> with password <code class="literal">florence</code>, change the file as follows:
</p><pre class="programlisting">##################
# User definitions
##################
user.zebedee=florence
##################
# Role definitions
##################
role.admin=zebedee</pre><p>Specify the custom username in JConsole as shown. </p><p>
<img src="images/jmx-remote-attach-jmxusers.png">
</p><p>
To start the JMX remote access using a custom SSL certificate, edit the file located at
<code class="literal">%SERVER_HOME%\configuration\keystore</code>. If you wish to use a different
keystore, pass this filename in as the value for the <code class="literal">-keystore</code> argument and the
keystore password in as the value for the <code class="literal">-keystorePassword</code> argument:
</p><pre class="screen">prompt&gt; cd %SERVER_HOME%
prompt&gt; bin\startup.bat -keystore customKeystore -keystorePassword customKeystorePassword</pre><p>
This will start the Virgo Server for Apache Tomcat with JMX enabled for remote attach using an SSL certificate from
<code class="literal">customKeystore</code> with a password of <code class="literal">customKeystorePassword</code>.
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="starting-stopping-configuration-directory"></a>7.5&nbsp;Starting with a Custom Configuration Directory</h2></div></div></div><p>
Use the <code class="literal">-configDir</code> option to specify an alternate <code class="literal">configuration</code> directory, different from the
default <code class="literal">SERVER_HOME/configuration</code> directory. This option allows you to use the same Virgo Server 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><p>
If you specify a relative path for the <code class="literal">-configDir</code> parameter,
the startup script interprets the path as relative to the root of the Virgo Server for Apache Tomcat installation,
and not relative to the directory from which you execute the <code class="literal">startup</code> script.
</p><p>
See <a class="link" href="#alternate-serviceability-work" title="B.4&nbsp;Alternate serviceability and work Directories">Alternate <code class="literal">serviceability</code> and <code class="literal">work</code>
Directories</a> for a known issue related to specifying an alternate <code class="literal">configuration</code> directory.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1865"></a>Linux</h3></div></div></div>
To start Virgo Server for Apache Tomcat using a configuration directory of <code class="literal">/configuration/node1</code>:
<pre class="screen">prompt$ cd $SERVER_HOME
prompt$ bin/startup.sh -configDir /configuration/node1</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1874"></a>Windows</h3></div></div></div>
To start Virgo Server for Apache Tomcat using a configuration directory of <code class="literal">c:\configuration\node1</code>:
<pre class="screen">prompt&gt; cd %SERVER_HOME%
prompt&gt; bin\startup.bat -configDir c:\configuration\node1</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1883"></a>7.6&nbsp;Stopping Virgo Server for Apache Tomcat</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1886"></a>Linux</h3></div></div></div><p>
To stop a running instance of Virgo Server for Apache Tomcat, start a new terminal window and run the <code class="literal">shutdown.sh</code> script:
</p><pre class="screen">prompt$ cd $SERVER_HOME
prompt$ bin/shutdown.sh</pre><p>
To stop a running instance of Virgo Server for Apache Tomcat immediately, bypassing normal shutdown
processing, run <code class="literal">shutdown.sh</code> with the <code class="literal">-immediate</code> option:
</p><pre class="screen">prompt$ cd $SERVER_HOME
prompt$ bin/shutdown.sh -immediate</pre><p>
If, when you started the Web Server instance, you used the <code class="literal">-jmxport</code> option to specify a non-default JMX port number,
then you must pass this port number to the <code class="literal">-jmxport</code> of the <code class="literal">shutdown.sh</code> script
to gracefully shut it down.
For example, if you specified <code class="literal">9090</code> as the JMX port, use the following to shut down the Web Server instance:
</p><pre class="screen">prompt$ cd $SERVER_HOME
prompt$ bin/shutdown.sh -jmxport 9090</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1922"></a>Microsoft Windows</h3></div></div></div><p>
To stop a running instance of Virgo Server for Apache Tomcat, start a new console window and run the <code class="literal">shutdown.bat</code> script:
</p><pre class="screen">prompt&gt; cd %SERVER_HOME%
prompt&gt; bin\shutdown.bat</pre><p>
To stop a running instance of Virgo Server for Apache Tomcat immediately, bypassing normal shutdown
processing, run <code class="literal">shutdown.bat</code> with the <code class="literal">-immediate</code> option:
</p><pre class="screen">prompt&gt; cd %SERVER_HOME%
prompt&gt; bin\shutdown.bat -immediate</pre><p>
If, when you started the Web Server instance, you used the <code class="literal">-jmxport</code> option to specify a non-default JMX port number,
then you must pass this port number to the <code class="literal">-jmxport</code> of the <code class="literal">shutdown.bat</code> script to gracefully shut it down.
For example, if you specified <code class="literal">9090</code> as the JMX port, use the following to shut down the Web Server instance:
</p><pre class="screen">prompt&gt; cd %SERVER_HOME%
prompt&gt; bin\shutdown.bat -jmxport 9090</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cleaning-without-starting"></a>7.7&nbsp;Cleaning Virgo Server for Apache Tomcat without Starting it</h2></div></div></div><p>
When you clean Virgo Server for Apache Tomcat, the startup script removes the <code class="literal">SERVER_HOME/work</code> directory (and hence all
running applications) as well as all trace, log and dump files. It leaves the
<code class="literal">SERVER_HOME/repository</code> and <code class="literal">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><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><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 class="link" href="#windows-deletion" title="B.5&nbsp;Problem Deleting Installation Directory under Windows">Problem Deleting Installation Directory under Windows</a> for more details.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1979"></a>Linux</h3></div></div></div><p>
To clean Virgo Server for Apache Tomcat, open a terminal window and run <code class="literal">startup.sh -clean -noStart</code>:
</p><pre class="screen">prompt$ cd $SERVER_HOME
prompt$ bin/startup.sh -clean -noStart</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1989"></a>Microsoft Windows</h3></div></div></div><p>
To clean Virgo Server for Apache Tomcat, open a command window and run <code class="literal">startup.bat -clean -noStart</code>:
</p><pre class="screen">prompt&gt; cd %SERVER_HOME%
prompt&gt; bin\startup.bat -clean -noStart</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="equinox-launcher"></a>7.8&nbsp;Using Equinox Launcher</h2></div></div></div><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 class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.gif"></td><th align="left">Important</th></tr><tr><td align="left" valign="top">The Equinox Launcher arguments must be placed at the end of the startup call. Here's an example
<pre class="screen">./startup.sh "virgo-args" "equinox-launcher-args"
./startup.sh -clean -console 2222</pre></td></tr></table></div><p>
</p><p>
A full list of the accepted Equinox Launcher arguments is available at <a class="ulink" href="http://help.eclipse.org/indigo/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fmisc%2Fruntime-options.html" target="_top">help.eclipse.org</a>.
</p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="admin-shell"></a>8.&nbsp;Equinox Console</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="admin-shell-enable"></a>8.1&nbsp;Enabling the Equinox Console</h2></div></div></div><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><p>
The user region shell ports may be reconfigured by editing the file
<code class="literal">osgi.console.properties</code> in the <code class="literal">repository/ext</code> directory, and
then restarting Virgo. The telnet properties in the file are prefixed with <span class="emphasis"><em>telnet.</em></span>, and the ssh properties are prefixed with <span class="emphasis"><em>ssh.</em></span>.
The kernel shell ports may be reconfigured by editing the file <code class="literal">osgi.console.properties</code> in the <code class="literal">configuration</code> directory, and then restarting Virgo.
</p><p>
To enable any of these shell ports, change the <code class="literal">enabled</code> setting from <code class="literal">false</code> to <code class="literal">true</code>
</p><pre class="programlisting">enabled=true</pre><p>
in the corresponding properties files.
</p><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><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><pre class="programlisting">prompt$ telnet localhost 2501
Trying ::1...
Connected to localhost.
Escape character is '^]'.
osgi&gt; </pre><p>
</p><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 class="literal">configuration/org.eclipse.virgo.kernel.users.properties</code> as described
in <a class="link" href="#configuring-authentication" title="Configuring Authentication">Configuring Authentication</a>. The default user and password are <code class="literal">admin</code>
and <code class="literal">springsource</code>.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">
Currently the Virgo Nano Equinox Console is enabled by default. Telnet is accesible on <span class="emphasis"><em>2401</em></span> and SSH on <span class="emphasis"><em>2402</em></span>. In future these will be configurable.
</td></tr></table></div><p>
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">
If you use the <code class="literal">shutdown</code> shell command to stop Virgo Tomcat Server, 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.
</td></tr></table></div><p>
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="admin-shell-using-vsh"></a>8.2&nbsp;Using Virgo Shell Commands</h2></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">
This section is not applicable to Virgo Nano.
</td></tr></table></div><p>Virgo provides shell commands
that allow you to examine artifacts
currently installed in a particular Virgo Kernel instance, manage the lifecycle of the installed artifacts, install new artifacts, and shut down
the Virgo Kernel. You can install, examine, and manage the lifecycle of the following artifacts:
</p><div class="itemizedlist"><ul type="disc"><li><p>Bundles</p></li><li><p>Configuration Artifacts</p></li><li><p>PARs</p></li><li><p>Plans</p></li></ul></div><p>
</p><p>
and can examine:
</p><div class="itemizedlist"><ul type="disc"><li><p>Exported packages</p></li><li><p>Services in the OSGi service registry</p></li></ul></div><p>
</p><p>
Virgo also provides shell commands to list all bundles that contain, export, or load a particular class.
</p><p>
These commands are provided <span class="emphasis"><em>for the user region shells only</em></span> and are grouped together in
the <code class="literal">vsh</code> <span class="emphasis"><em>scope</em></span>.
</p><p>You invoke commands using the <code class="literal">vsh:</code> scope. For example:</p><pre class="programlisting">
osgi&gt; vsh:plan list
Name Version State
org.eclipse.virgo.apps.admin.plan 2.1.0 ACTIVE
org.eclipse.virgo.kernel.userregion.springdm 2.1.0 ACTIVE
org.eclipse.virgo.web 2.1.0 ACTIVE
osgi&gt; </pre><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="admin-shell-vsh-using-command-list"></a>Virgo Shell Commands</h3></div></div></div><p>The following table lists the Virgo shell commands; each command in turn has a variety of options that you can specify, depending on what you want to do, such as start a bundle or refresh a plan. The reference documentation about each command provides the full list of available options. </p><div class="table"><a name="admin-shell-vsh-commands-table"></a><p class="title"><b>Table&nbsp;8.1.&nbsp;Virgo Shell Commands</b></p><div class="table-contents"><table summary="Virgo Shell Commands" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Command </th><th style="border-bottom: 1.0pt solid ; ">Description</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><a class="link" href="#admin-shell-vsh-bundle-command" title="bundle Command">bundle</a></td><td style="border-bottom: 1.0pt solid ; ">Manages and displays information about bundle artifacts.</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><a class="link" href="#admin-shell-cl-clhas" title="clhas command">clhas</a></td><td style="border-bottom: 1.0pt solid ; ">Lists all bundles that <span class="bold"><strong>contain</strong></span> a class or resource.</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><a class="link" href="#admin-shell-cl-clexport" title="clexport command">clexport</a></td><td style="border-bottom: 1.0pt solid ; ">Lists all bundles that <span class="bold"><strong>export</strong></span> a class or package.</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><a class="link" href="#admin-shell-cl-clload" title="clload command">clload</a></td><td style="border-bottom: 1.0pt solid ; ">Lists all bundles that can <span class="bold"><strong>load</strong></span> a class.</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><a class="link" href="#admin-shell-vsh-config-command" title="config Command">config</a></td><td style="border-bottom: 1.0pt solid ; ">Manages and displays information about configuration artifacts.</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><a class="link" href="#admin-shell-vsh-package-command" title="packages Command">packages</a></td><td style="border-bottom: 1.0pt solid ; ">Displays information about exported packages.</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><a class="link" href="#admin-shell-vsh-par-command" title="par Command">par</a></td><td style="border-bottom: 1.0pt solid ; ">Manages and displays information about PAR artifacts.</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><a class="link" href="#admin-shell-vsh-plan-command" title="plan Command">plan</a></td><td style="border-bottom: 1.0pt solid ; ">Manages and displays information about plan artifacts.</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><a class="link" href="#admin-shell-vsh-service-command" title="service Command">service</a></td><td style="border-bottom: 1.0pt solid ; ">Displays information about services in the OSGi service registry.</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><a class="link" href="#admin-shell-vsh-install-command" title="install Command">install</a></td><td style="border-bottom: 1.0pt solid ; ">Installs an artifact to Virgo Kernel. </td></tr><tr><td style="border-right: 1.0pt solid ; "><a class="link" href="#admin-shell-vsh-shutdown-command" title="shutdown Command">shutdown</a></td><td style="">Shuts down the Virgo Kernel instance to which the Equinox Console is connected.</td></tr></tbody></table></div></div><br class="table-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="admin-shell-vsh-command-reference"></a>8.3&nbsp;Virgo Shell Command Reference</h2></div></div></div><p>
This section contains reference information about the Virgo shell commands
<a class="link" href="#admin-shell-vsh-bundle-command" title="bundle Command">bundle</a>,
<a class="link" href="#admin-shell-cl-clhas" title="clhas command">clhas</a>,
<a class="link" href="#admin-shell-cl-clexport" title="clexport command">clexport</a>,
<a class="link" href="#admin-shell-cl-clload" title="clload command">clload</a>,
<a class="link" href="#admin-shell-vsh-config-command" title="config Command">config</a>,
<a class="link" href="#admin-shell-vsh-package-command" title="packages Command">packages</a>,
<a class="link" href="#admin-shell-vsh-par-command" title="par Command">par</a>,
<a class="link" href="#admin-shell-vsh-plan-command" title="plan Command">plan</a>,
<a class="link" href="#admin-shell-vsh-service-command" title="service Command">service</a>,
<a class="link" href="#admin-shell-vsh-install-command" title="install Command">install</a>,
<a class="link" href="#admin-shell-vsh-shutdown-command" title="shutdown Command">shutdown</a>,
<a class="link" href="#">help</a>, and
<a class="link" href="#">exit</a>.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="admin-shell-vsh-bundle-command"></a>bundle Command</h3></div></div></div><p>Use the <code class="literal">bundle</code> command to manage the lifecycle of bundles deployed in Virgo Kernel and to gather information about deployed bundles, such as diagnostic information, header information, and so on. </p><p>The following table lists the options you can specify for this command.</p><div class="table"><a name="admin-shell-vsh-bundle-command-table"></a><p class="title"><b>Table&nbsp;8.2.&nbsp;Options of the bundle Command</b></p><div class="table-contents"><table summary="Options of the bundle Command" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Option </th><th style="border-bottom: 1.0pt solid ; ">Description</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">list</td><td style="border-bottom: 1.0pt solid ; ">Displays the list of bundles that are currently installed in the current Virgo Kernel instance. With the exception of a few kernel bundles and their services, which Virgo Kernel uses to administer the user region, none of the kernel is visible to user installed artifacts; rather, only the bundles installed in the user region are visible.
<p>Each bundle is identified by an internal <code class="literal">ID</code> which you can then use with the other <code class="literal">bundle</code> commands that manage a particular bundle, such as <code class="literal">start </code><span class="emphasis"><em><code class="literal">id</code></em></span>. The <code class="literal">list</code> command also displays the version of the bundle, along with its state, which is one of the following standard OSGi lifecycle states:</p>
<div class="itemizedlist"><ul type="disc"><li><p><span class="bold"><strong>Installed</strong></span>: The bundle is installed but its dependencies have not yet been resolved.</p></li><li><p><span class="bold"><strong>Resolved</strong></span>: The bundle is resolved and you can now start it.</p></li><li><p><span class="bold"><strong>Uninstalled</strong></span>: The bundle is uninstalled and you cannot use it.</p></li><li><p><span class="bold"><strong>Starting</strong></span>: The bundle is in the process of starting.</p></li><li><p><span class="bold"><strong>Active</strong></span>: The bundle is running and you can now use it.</p></li><li><p><span class="bold"><strong>Stopping</strong></span>: The bundle is in the process of stopping.</p></li></ul></div>
<p>Use one of the other <code class="literal">bundle</code> commands to change the state of a bundle. For example, use the <code class="literal">bundle start </code><span class="emphasis"><em><code class="literal">id</code></em></span> command to change the state of a bundle from <code class="literal">Installed</code> to <code class="literal">Active</code>.</p>
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">examine <span class="emphasis"><em>id</em></span></td><td style="border-bottom: 1.0pt solid ; ">Displays detailed information about the specified bundle. Use the <code class="literal">bundle list</code> command to get the internal id of a particular bundle.
<p>In addition to the information provided by the <code class="literal">bundle list</code> command (id, full name, version, and state), the <code class="literal">examine</code> command specifies whether the bundle includes a Spring application context (or is <span class="emphasis"><em>Spring Powered</em></span>) and the exact physical location of the bundle JAR file. </p>
<p>The <code class="literal">examine</code> also provides the full list of packages that the bundle imports, as well as the bundles that in turn export these imported packages. Finally, the command displays the packages that the current bundle exports, and then in turn the list of other installed bundles that are currently importing these exported packages. </p>
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">start <span class="emphasis"><em>id</em></span></td><td style="border-bottom: 1.0pt solid ; ">Starts the specified bundle. Use the <code class="literal">bundle list</code> command to get the internal id of a particular bundle.
<p>After Virgo Kernel successfully starts the bundle, it is listed in the <code class="literal">Active</code> state. </p>
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">stop <span class="emphasis"><em>id</em></span></td><td style="border-bottom: 1.0pt solid ; ">Stops the specified bundle. Use the <code class="literal">bundle list</code> command to get the internal id of a particular bundle.
<p>When you stop a bundle, it goes from the <code class="literal">Active</code> state to the <code class="literal">Resolved</code> state, and you must re-start it if you want to use the application that the bundle contains.</p> </td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">refresh <span class="emphasis"><em>id</em></span></td><td style="border-bottom: 1.0pt solid ; ">Updates the contents of the specified bundle. Use the <code class="literal">bundle list</code> command to get the internal id of a particular bundle. Use this command if you have changed the contents of the bundle JAR file and you want to refresh the artifact as installed in the OSGi framework.
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">uninstall <span class="emphasis"><em>id</em></span></td><td style="border-bottom: 1.0pt solid ; ">Uninstalls the specified bundle from Virgo Kernel. Use the <code class="literal">bundle list</code> command to get the internal id of a particular bundle.
<p>When the uninstall process is complete, the bundle does not show up in the list of bundles displayed by the <code class="literal">bundle list</code> command. If you want to use the application in the bundle, you must re-install it using the <code class="literal">install</code> command.</p>
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">diag <span class="emphasis"><em>id</em></span></td><td style="border-bottom: 1.0pt solid ; ">
<p>
Provides diagnostic information about the specified bundle.
In particular, this command displays information about the imported packages that Virgo Kernel could not resolve.
Use the <code class="literal">bundle list</code> command to get the internal id of a particular bundle.
</p>
<p>
Note that Virgo does not install unresolvable bundles.
Instead is takes a state dump (for offline analysis using the web administration console) and fails the deployment.
So bundles are only likely to become unresolvable in Virgo after an update operation.
</p>
</td></tr><tr><td style="border-right: 1.0pt solid ; ">headers <span class="emphasis"><em>id</em></span></td><td style="">Displays the complete list of manifest headers of the specified bundle. Use the <code class="literal">bundle list</code> command to get the internal id of a particular bundle.
<p>The manifest headers include: <code class="literal">Import-Package</code>, <code class="literal">Export-Package</code>, <code class="literal">Bundle-SymbolicName</code>, and so on. </p>
</td></tr></tbody></table></div></div><br class="table-break"><p>The following examples show how to use this command.</p><p>First, use the <code class="literal">bundle list</code> command to view all the installed bundles:</p><pre class="programlisting">osgi&gt; vsh:bundle list
Id Name Version State
40 org.eclipse.virgo.kernel.userregionfactory 3.0.0.RELEASE ACTIVE
47 org.eclipse.equinox.cm 1.0.300.v20101204 ACTIVE
48 org.eclipse.virgo.kernel.userregion 3.0.0.RELEASE ACTIVE
49 org.eclipse.virgo.kernel.osgicommand 3.0.0.RELEASE ACTIVE
50 org.eclipse.osgi.services 3.3.0.v20110110 ACTIVE
51 com.springsource.org.apache.mina.core 2.0.2 ACTIVE
52 org.apache.felix.gogo.command 0.8.0.v201105062003 ACTIVE
53 org.apache.felix.gogo.runtime 0.8.0.v201105062003 ACTIVE
54 org.apache.felix.gogo.shell 0.8.0.v201107131313 ACTIVE
55 org.eclipse.equinox.console.supportability 1.0.0.20110722-2 ACTIVE
56 com.springsource.org.apache.sshd.core 0.5.0 ACTIVE
57 org.springframework.osgi.core 1.2.1 ACTIVE
58 S org.springframework.osgi.extender 1.2.1 ACTIVE
59 org.springframework.osgi.io 1.2.1 ACTIVE
60 org.eclipse.virgo.kernel.agent.dm 3.0.0.RELEASE ACTIVE
61 S org.eclipse.virgo.kernel.deployer.dm 3.0.0.RELEASE ACTIVE
62 org.eclipse.equinox.ds 1.3.0.v20110124-0830 ACTIVE
63 org.eclipse.equinox.util 1.0.200.v20100503 ACTIVE
64 com.springsource.org.aopalliance 1.0.0 ACTIVE
65 org.eclipse.virgo.kernel.dmfragment 3.0.0.RELEASE RESOLVED
66 org.springframework.aop 3.0.5.RELEASE ACTIVE
67 org.springframework.asm 3.0.5.RELEASE ACTIVE
68 org.springframework.beans 3.0.5.RELEASE ACTIVE
69 org.springframework.context 3.0.5.RELEASE ACTIVE
70 org.springframework.core 3.0.5.RELEASE ACTIVE
71 org.springframework.expression 3.0.5.RELEASE ACTIVE
osgi&gt; </pre><p>The following example shows how to view the headers of the <code class="literal">org.springframework.osgi.extender</code> bundle (only the first few lines are shown):</p><pre class="programlisting">osgi&gt; vsh:bundle examine 5
Id: 5
Name: org.springframework.osgi.extender
Version 1.2.1
State: ACTIVE
Spring Powered: true
Bundle Location: file:&lt;... omitted ...&gt;/org.springframework.osgi.extender-1.2.1.jar/
Imported Packages:
org.springframework.osgi.context [1.2.1, 1.2.1]
exported by org.springframework.osgi.core 1.2.1 [4]
&lt;... remainder omitted ...&gt;
Exported Packages:
org.springframework.osgi.extender 1.2.1
&lt;... remainder omitted ...&gt;
Published services:
58 org.springframework.beans.factory.xml.NamespaceHandlerResolver
consumed by org.springframework.osgi.extender 1.2.1 [5]
consumed by org.eclipse.virgo.kernel.deployer.dm 2.1.0.RELEASE [8]
&lt;... remainder omitted ...&gt;
Consumed services:
1 org.osgi.service.packageadmin.PackageAdmin
published by org.eclipse.osgi 3.7.0.v20110224 [0]
&lt;... remainder omitted ...&gt;
Fragments:
org.eclipse.virgo.kernel.dmfragment 2.1.0.RELEASE [10]
osgi&gt; </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="admin-shell-vsh-config-command"></a>config Command</h3></div></div></div><p>Use the <code class="literal">config</code> command to view and manage the configuration artifacts that have been installed in Virgo Kernel. A <span class="emphasis"><em>configuration artifact</em></span> is simply a properties file that is associated with a user application that is contained in a bundle. Using configuration artifacts, you can manage the configuration of a user application completely separately from the bundle that contains the application. </p><p>The following table lists the options you can specify for this command.</p><div class="table"><a name="admin-shell-vsh-config-command-table"></a><p class="title"><b>Table&nbsp;8.3.&nbsp;Options of the config Command</b></p><div class="table-contents"><table summary="Options of the config Command" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Option </th><th style="border-bottom: 1.0pt solid ; ">Description</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">list</td><td style="border-bottom: 1.0pt solid ; ">Lists the configuration artifacts that are currently installed in Virgo Kernel.
<p>The <code class="literal">list</code> option displays the full name of each installed configuration artifact, its version, and its current state. Configuration artifacts have similar lifecycles to other artifacts, such as bundles, and so the list of states in which a configuration can be in is the same as those of bundles; see <a class="link" href="#">the bundle command</a> for the list of possible states. </p>
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">examine <span class="emphasis"><em>name [version]</em></span></td><td style="border-bottom: 1.0pt solid ; ">Displays information about the specified configuration artifact. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed. Use the <code class="literal">config list</code> command to view all configuration artifacts and versions currently installed in Virgo Kernel.
<p>A configuration artifact must be active for you to examine it; if it is not currently active, use <code class="literal">config start</code> to start it and thus change its state to <code class="literal">Active</code>.</p>
<p>The command first displays the factory pid of the configuration artifact as well as the complete location of the bundle to which the configuration artifact is associated. The command then lists all the properties that make up the configuration, as well as their current value. </p> </td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">start <span class="emphasis"><em>name [version]</em></span></td><td style="border-bottom: 1.0pt solid ; ">
<p>
Starts the specified configuration artifact and makes it visible to Virgo Kernel.
Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the
configuration artifact installed (which Virgo does not currently support).
Use the <code class="literal">config list</code> command to view all configuration artifacts and versions currently installed in Virgo Kernel.
</p>
<p>
Starting the configuration sets its state to <code class="literal">Active</code>.
</p>
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">stop <span class="emphasis"><em>name [version]</em></span></td><td style="border-bottom: 1.0pt solid ; ">Stops the specified configuration artifact and makes it invisible to Virgo Kernel. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed (which Virgo does not currently support). Use the <code class="literal">config list</code> command to view all configuration artifacts and versions currently installed in Virgo Kernel.
<p>Stopping the configuration sets its state to <code class="literal">Resolved</code>.</p></td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">refresh <span class="emphasis"><em>name [version]</em></span></td><td style="border-bottom: 1.0pt solid ; ">Updates the contents of the specified configuration artifact to Virgo Kernel. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed (which Virgo does not currently support). Use the <code class="literal">config list</code> command to view all configuration artifacts and versions currently installed in Virgo Kernel.
<p>Use this command if you have changed the contents of the configuration artifact, and you want to make this information known to Virgo Kernel and the associated bundle. </p></td></tr><tr><td style="border-right: 1.0pt solid ; ">uninstall <span class="emphasis"><em>name [version]</em></span></td><td style="">Uninstalls the specified configuration artifact and make it completely unavailable to Virgo Kernel. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed (which Virgo does not currently support). Use the <code class="literal">config list</code> command to view all configuration artifacts and versions currently installed in Virgo Kernel.
<p>Stopping the configuration removes it from Virgo Kernel's list of deployed artifacts and it will not show up when you perform a <code class="literal">config list</code>.</p></td></tr></tbody></table></div></div><br class="table-break"><p>The following example shows how to use this command to list the installed configuration artifacts.</p><pre class="programlisting">osgi&gt; vsh:config list
Name Version State
org.eclipse.virgo.kernel 0.0.0 ACTIVE
org.eclipse.virgo.kernel.jmxremote.access 0.0.0 ACTIVE
org.eclipse.virgo.kernel.userregion 0.0.0 ACTIVE
org.eclipse.virgo.kernel.users 0.0.0 ACTIVE
org.eclipse.virgo.medic 0.0.0 ACTIVE
org.eclipse.virgo.repository 0.0.0 ACTIVE
osgi.console.ssh 0.0.0 ACTIVE
osgi.console.telnet 0.0.0 ACTIVE
osgi&gt; </pre><p>To view the properties of a configuration artifact, and their current values, use <code class="literal">config examine</code>:</p><pre class="programlisting">osgi&gt; vsh:config examine org.eclipse.virgo.repository
Factory pid:
Bundle Location: file:plugins/org.eclipse.virgo.kernel.services-3.6.2.RELEASE.jar
Properties:
chain:
ext,usr
ext.searchPattern:
repository/ext/{artifact}
ext.type:
external
service.pid:
org.eclipse.virgo.repository
usr.type:
watched
usr.watchDirectory:
repository/usr
osgi&gt; </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="admin-shell-vsh-package-command"></a>packages Command</h3></div></div></div><p>Use the <code class="literal">packages</code> command to view the complete list of packages exported by all bundles installed in Virgo Kernel, as well as examine a particular exported package in more detail.</p><p>The following table lists the options you can specify for this command.</p><div class="table"><a name="admin-shell-vsh-package-command-table"></a><p class="title"><b>Table&nbsp;8.4.&nbsp;Options of the packages Command</b></p><div class="table-contents"><table summary="Options of the packages Command" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Option </th><th style="border-bottom: 1.0pt solid ; ">Description</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">list</td><td style="border-bottom: 1.0pt solid ; ">Displays all the exported packages for all bundles in the uer region of Virgo Kernel. In addition to the package name, the command displays the version of the exported package and the <code class="literal">id</code> of the bundle that contains the exported package. You can examine the bundle by using the command <code class="literal">bundle examine </code><span class="emphasis"><em><code class="literal">id</code></em></span>.</td></tr><tr><td style="border-right: 1.0pt solid ; ">examine <span class="emphasis"><em>name version</em></span></td><td style="">Displays details about the exported package. You must specify both the name of the exported package and its version; use <code class="literal">packages list</code> to view the exact names and version.
<p>This command provides the following additional information about the exported package:</p>
<div class="itemizedlist"><ul type="disc"><li><p>The name and version of the bundle that exports the package. This means that the package name is explicitly listed in the bundle's <code class="literal">MANIFEST.MF</code> file as part of the <code class="literal">Export-Package</code> header.</p></li><li><p>Any attributes that are part of the <code class="literal">Export-Package</code>, in addition to <code class="literal">version</code>.</p></li><li><p>The directives that are part of the <code class="literal">Export-Package</code> header. A typical directive is <code class="literal">uses</code>, which declares up-front constraints on a number of other packages.</p></li><li><p>The list of all bundles that import the package.</p></li></ul></div>
</td></tr></tbody></table></div></div><br class="table-break"><p>The following example shows how to list all the exported packages for all bundles installed:</p><pre class="programlisting">osgi&gt; vsh:packages list
Name Version Providing Bundle
javax.accessibility 0.0.0 0
javax.activation 0.0.0 0
javax.activation 1.1.1 0
&lt;... remainder omitted ...&gt;
osgi&gt; </pre><p>The following example shows how to examine a particular exported package:</p><pre class="programlisting">osgi&gt; vsh:packages examine org.slf4j 1.6.1
Exporter: org.eclipse.virgo.region.user 0.0.0 [1]
Attributes:
None
Directives:
uses:
org.slf4j.spi
x-equinox-ee:
-1
x-internal:
false
Importer(s):
org.eclipse.virgo.kernel.agent.dm 2.1.0.RELEASE [7]
Import-Package attributes:
bundle-version:
0.0.0
version:
[1.6.1,2.0.0)
Import-Package directives:
resolution:
static
&lt;... remainder omitted ...&gt;
osgi&gt; </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="admin-shell-vsh-par-command"></a>par Command</h3></div></div></div><p>Use the <code class="literal">par</code> command to view all the PARs currently installed in Virgo Kernel, view details about a particular PAR and manage its lifecycle, such as starting, stopping, refreshing, and uninstalling it.</p><p>The following table lists the options you can specify for this command.</p><div class="table"><a name="admin-shell-vsh-par-command-table"></a><p class="title"><b>Table&nbsp;8.5.&nbsp;Options of the par Command</b></p><div class="table-contents"><table summary="Options of the par Command" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Option </th><th style="border-bottom: 1.0pt solid ; ">Description</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">list</td><td style="border-bottom: 1.0pt solid ; ">Displays all the PARs that are currently installed in Virgo Kernel.
<p>The <code class="literal">list</code> option displays the full name of each installed PAR, its version, and its current state. PARs have similar lifecycles to other artifacts, such as bundles, and so the list of states in which a PAR can be in is the same as those of bundles; see <a class="link" href="#">the bundle command</a> for the list of possible states. </p></td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">examine <span class="emphasis"><em>name version</em></span></td><td style="border-bottom: 1.0pt solid ; ">Displays information about the specified PAR; you are required to identify the PAR with both its name and its version. Use the <code class="literal">par list</code> command to view all installed PAR files and their versions. The command displays the following information:
<div class="itemizedlist"><ul type="disc"><li><p>The current state of the PAR (see <a class="link" href="#admin-shell-vsh-bundle-command" title="bundle Command">the bundle command</a> for the full list of possible states).</p></li><li><p>Whether the PAR is <span class="emphasis"><em>scoped</em></span>. Scoping specifies whether Virgo Kernel should deploy the members of the PAR in their own scope; when scoping is disabled, Virgo Kernel deploys the artifacts into the global scope and they are accessible for access by all other artifacts.</p></li><li><p>Whether the PAR is <span class="emphasis"><em>atomic</em></span>. When a PAR is atomic, Virgo Kernel manages the lifecycle of all its member artifacts as a single entity, which means if one artifact member is started, then Virgo Kernel starts <span class="emphasis"><em>all</em></span> the PAR artifacts. If one artifact fails to start, then Virgo Kernel stops all other artifacts in the PAR.</p></li><li><p>The individual members, or children, of the PAR. These could be plans, bundles, configuration artifacts, and so on.</p></li></ul></div>
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">start <span class="emphasis"><em>name version</em></span></td><td style="border-bottom: 1.0pt solid ; ">Starts the specified PAR. You must specify both the full name of the PAR as well as the version you want to start. Use the <code class="literal">par list</code> command to get the list of PARs currently installed in Virgo Kernel.
<p>To start a PAR, it must have already been resolved by Virgo Kernel, or in other words, be in the <code class="literal">Resolved</code> state. After Virgo Kernel successfully starts the PAR, it is listed in the <code class="literal">Active</code> state. </p></td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">stop <span class="emphasis"><em>name version</em></span></td><td style="border-bottom: 1.0pt solid ; ">Stops the specified PAR. You must specify both the full name of the PAR as well as the version you want to stop. Use the <code class="literal">par list</code> command to get the list of PARs currently installed in Virgo Kernel.
<p>When you stop a PAR, it goes from the <code class="literal">Active</code> state to the <code class="literal">Resolved</code> state, and you must re-start it if you want to use the application that the PAR contains.</p> </td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">refresh <span class="emphasis"><em>name version</em></span></td><td style="border-bottom: 1.0pt solid ; ">Updates the contents of the specified PAR. You must specify both the name and version of the PAR you want to refresh. Use the <code class="literal">par list</code> command to this information.
<p>Use this command if you have changed the contents of the PAR file and you want to refresh the artifact as installed in the OSGi framework.</p></td></tr><tr><td style="border-right: 1.0pt solid ; ">uninstall <span class="emphasis"><em>name version</em></span></td><td style="">Uninstalls the specified PAR. You must specify both the name and version of the PAR you want to refresh. Use the <code class="literal">par list</code> command to this information.
<p>When the uninstall process is complete, the PAR will not show up in the list of PARs displayed by the <code class="literal">par list</code> command. If you want to use the application in the PAR, you must re-install it using the <code class="literal">install</code> command.</p></td></tr></tbody></table></div></div><br class="table-break"><p>The following example shows how to list the PARs that have been installed in Virgo Kernel:</p><pre class="programlisting">osgi&gt; vsh:par list
Name Version State
org.eclipse.virgo.server.repository.hosted 2.1.0.RELEASE ACTIVE
osgi&gt; </pre><p>The following example shows how to examine a particular PAR file:</p><pre class="programlisting">osgi&gt; vsh:par examine org.eclipse.virgo.server.repository.hosted 2.1.0.RELEASE
State: ACTIVE
Scoped: true
Atomic: true
Children:
bundle org.eclipse.virgo.server.repository.hosted.core 2.1.0.RELEASE
bundle org.eclipse.virgo.server.repository.hosted.web 2.1.0.RELEASE
bundle org.eclipse.virgo.server.repository.hosted-synthetic.context 2.1.0.RELEASE
osgi&gt; </pre><p>Finally, the following example shows how to refresh an installed PAR file:</p><pre class="programlisting">osgi&gt; vsh:par refresh my.exciting.par 1.2.0
par my.exciting.par 1.2.0 refreshed successfully
osgi&gt; </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="admin-shell-vsh-plan-command"></a>plan Command</h3></div></div></div><p>Use the <code class="literal">plan</code> command to view all the plans currently installed in Virgo Kernel, view details about a particular plan and manage its lifecycle, such as starting, stopping, refreshing, and uninstalling it.</p><p>The following table lists the options you can specify for this command.</p><div class="table"><a name="admin-shell-vsh-plan-command-table"></a><p class="title"><b>Table&nbsp;8.6.&nbsp;Options of the plan Command</b></p><div class="table-contents"><table summary="Options of the plan Command" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Option </th><th style="border-bottom: 1.0pt solid ; ">Description</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">list</td><td style="border-bottom: 1.0pt solid ; ">Displays all the plans that are currently installed in Virgo Kernel.
<p>The <code class="literal">list</code> option displays the full name of each installed plan, its version, and its current state. Plans have similar lifecycles to other artifacts, such as bundles, and so the list of states in which a plan can be in is the same as those of bundles; see <a class="link" href="#">the bundle command</a> for the list of possible states. </p></td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">examine <span class="emphasis"><em>name version</em></span></td><td style="border-bottom: 1.0pt solid ; ">Displays information about the specified plan; you are required to identify the plan with both its name and its version. Use the <code class="literal">plan list</code> command to view all installed plans and their versions. The command displays the following information:
<div class="itemizedlist"><ul type="disc"><li><p>The current state of the plan (see <a class="link" href="#admin-shell-vsh-bundle-command" title="bundle Command">the bundle command</a> for the full list of possible states).</p></li><li><p>Whether the plan is <span class="emphasis"><em>scoped</em></span>. Scoping specifies whether Virgo Kernel should deploy the members of the plan in their own scope; when scoping is disabled, Virgo Kernel deploys the artifacts into the global scope and they are accessible for access by all other artifacts.</p></li><li><p>Whether the plan is <span class="emphasis"><em>atomic</em></span>. When a plan is atomic, Virgo Kernel manages the lifecycle of all its member artifacts as a single entity, which means if one artifact member is started, then Virgo Kernel starts <span class="emphasis"><em>all</em></span> the plan artifacts. If one artifact fails to start, then Virgo Kernel stops all other artifacts in the plan.</p></li><li><p>The individual members, or children, of the plan. These could be other plans, PARs, bundles, configuration artifacts, and so on.</p></li></ul></div>
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">start <span class="emphasis"><em>name version</em></span></td><td style="border-bottom: 1.0pt solid ; ">Starts the specified plan. You must specify both the full name of the plan as well as the version you want to start. Use the <code class="literal">plan list</code> command to get the list of plans currently installed in Virgo Kernel.
<p>To start a plan, it must have already been resolved by Virgo Kernel, or in other words, be in the <code class="literal">Resolved</code> state. After Virgo Kernel successfully starts the plan, it is listed in the <code class="literal">Active</code> state. </p></td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">stop <span class="emphasis"><em>name version</em></span></td><td style="border-bottom: 1.0pt solid ; ">Stops the specified plan. You must specify both the full name of the plan as well as the version you want to stop. Use the <code class="literal">plan list</code> command to get the list of plans currently installed in Virgo Kernel.
<p>When you stop a plan, it goes from the <code class="literal">Active</code> state to the <code class="literal">Resolved</code> state, and you must re-start it if you want to use the application that the plan contains.</p> </td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">refresh <span class="emphasis"><em>name version</em></span></td><td style="border-bottom: 1.0pt solid ; ">Updates the contents of the specified plan. You must specify both the name and version of the plan you want to refresh. Use the <code class="literal">plan list</code> command to this information.
<p>Use this command if you have changed the contents of the plan file and you want to refresh the artifact as installed in the OSGi framework.</p></td></tr><tr><td style="border-right: 1.0pt solid ; ">uninstall <span class="emphasis"><em>name version</em></span></td><td style="">Uninstalls the specified plan. You must specify both the name and version of the plan you want to refresh. Use the <code class="literal">plan list</code> command to this information.
<p>When the uninstall process is complete, the plan will not show up in the list of plans displayed by the <code class="literal">plan list</code> command. If you want to use the application in the plan, you must re-install it using the <code class="literal">install</code> command.</p></td></tr></tbody></table></div></div><br class="table-break"><p>The following example shows how to list the plans that have been installed in Virgo Kernel:</p><pre class="programlisting">
osgi&gt; vsh:plan list
Name Version State
org.eclipse.virgo.apps.admin.plan 2.1.0 ACTIVE
org.eclipse.virgo.kernel.userregion.springdm 2.1.0 ACTIVE
org.eclipse.virgo.web 2.1.0 ACTIVE
osgi&gt; </pre><p>The following example shows how to examine a particular plan:</p><pre class="programlisting">osgi&gt; vsh:plan examine org.eclipse.virgo.kernel.userregion.springdm 2.1.0
State: ACTIVE
Scoped: false
Atomic: false
Children:
bundle org.eclipse.virgo.kernel.agent.dm 2.1.0.RELEASE
bundle org.springframework.osgi.io 1.2.1
bundle org.springframework.osgi.extender 1.2.1
bundle org.springframework.osgi.core 1.2.1
bundle org.eclipse.virgo.kernel.deployer.dm 2.1.0.RELEASE
osgi&gt; </pre><p>The following example shows how to stop a currently Active plan:</p><pre class="programlisting">osgi&gt; vsh:plan stop org.eclipse.virgo.web 2.1.0
plan org.eclipse.virgo.web:2.1.0 stopped successfully
osgi&gt; </pre><p>The following example shows how to start a plan:</p><pre class="programlisting">osgi&gt; vsh:plan start org.eclipse.virgo.web 2.1.0
plan org.eclipse.virgo.web:2.1.0 started successfully
osgi&gt; </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="admin-shell-vsh-service-command"></a>service Command</h3></div></div></div><p>Use the <code class="literal">service</code> command to view all the services that have been registered in the OSGi service registry of Virgo Kernel. You can also examine a specific service to discover its properties, the bundle that publishes the service, and any bundles that consume the service.</p><p>The following table lists the options you can specify for this command.</p><div class="table"><a name="admin-shell-vsh-service-command-table"></a><p class="title"><b>Table&nbsp;8.7.&nbsp;Options of the service Command</b></p><div class="table-contents"><table summary="Options of the service Command" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Option </th><th style="border-bottom: 1.0pt solid ; ">Description</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">list</td><td style="border-bottom: 1.0pt solid ; ">Displays the list of services that are currently registered in the OSGi service registry of Virgo Kernel.
<p>Each service is identified by an internal <code class="literal">ID</code> which you can then use with the <code class="literal">service examine</code> command to view the details about a particular service. The <code class="literal">list</code> option also displays the object class that implements the service and the internal <code class="literal">id</code> of the bundle that provides the service. </p></td></tr><tr><td style="border-right: 1.0pt solid ; ">examine <span class="emphasis"><em>id</em></span></td><td style="">Displays detailed information about the specified service. Use the <code class="literal">service list</code> command to get the internal id of a particular service.
<p>This command displays the properties of the service, such as the object class that implements the service, the name of the bundle that publishes the service and any bundles that consume the service. </p></td></tr></tbody></table></div></div><br class="table-break"><p>The following example shows how to list the services currently registered in the OSGi service registry:</p><pre class="programlisting">osgi&gt; vsh:service list
Id Object Class(es) Providing Bundle
1 org.osgi.service.packageadmin.PackageAdmin 0
2 org.osgi.service.permissionadmin.PermissionAdmin, ... 0
3 org.osgi.service.startlevel.StartLevel 0
4 org.eclipse.osgi.service.debug.DebugOptions 0
5 java.lang.ClassLoader 0
6 org.eclipse.osgi.framework.log.FrameworkLog 0
7 org.eclipse.osgi.framework.log.FrameworkLog 0
&lt;... remainder omitted ...&gt;
72 org.eclipse.gemini.web.core.spi.ServletContainer 38
73 org.eclipse.gemini.web.core.WebContainer 37
74 org.eclipse.virgo.web.core.WebApplicationRegistry 39
&lt;... remainder omitted ...&gt;
osgi&gt; </pre><p>The following example shows how to examine a particular service:</p><pre class="programlisting">osgi&gt; vsh:service examine 73
Properties:
objectClass:
org.eclipse.gemini.web.core.WebContainer
service.id:
73
Publisher: org.eclipse.gemini.web.core 1.1.0.RELEASE [37]
Consumer(s):
org.eclipse.virgo.web.core 2.1.0.RELEASE [39]
osgi&gt; </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="admin-shell-vsh-install-command"></a>install Command</h3></div></div></div><p>Use the <code class="literal">install</code> command to deploy an artifact to Virgo Kernel. The artifact can be a bundle, PAR, plan, or configuration artifact.</p><p>The <code class="literal">install</code> command takes a single parameter: the URI of the artifact you want to deploy. For example, to deploy a bundle on the local computer, use the <code class="literal">file</code> scheme:</p><pre class="programlisting">file://full-pathname-to-artifact</pre><p>After you execute the <code class="literal">install</code> command, Virgo Kernel attempts to resolve the artifact's dependencies, and if it is successful, puts it in the <code class="literal">Resolved</code> state. At that point, you must start the artifact to be able to actually use it. </p><p>The following example shows how to install a bundle called <code class="literal">swf-booking-mvc.war</code> located in the <code class="literal">/home/apps</code> directory of the computer on which the Equinox Console Extension is being run:</p><pre class="programlisting">osgi&gt; vsh:install file://home/apps/swf-booking-mvc.war
...
Artifact bundle swf-booking-mvc.war 0.0.0 installed</pre><p>
This command is particularly useful for installing an artifact from the Virgo repository, in which case use the <code class="literal">repository:</code> scheme:
</p><pre class="programlisting">repository:artifact-type/bundle-symbolic-name/bundle-version</pre><p>
For example:
</p><pre class="programlisting">osgi&gt; vsh:install repository:bundle/my.bundle/1.0
...
Artifact bundle my.bundle 1.0.0 installed
osgi&gt;</pre><p>The following example shows how to use the <code class="literal">bundle list</code> command to ensure that the bundle was indeed installed in Virgo Kernel; if you had installed a different kind of artifact, for example a plan, then you would use the appropriate command (such as <code class="literal">plan list</code>):</p><pre class="programlisting">osgi&gt; vsh:bundle list
Id Name Version State
0 org.eclipse.osgi 3.6.1.R36x_v20100806 ACTIVE
1 org.eclipse.virgo.region.user 0.0.0 ACTIVE
&lt;... remainder omitted ...&gt;
59 org.eclipse.virgo.server.splash 2.1.0.RELEASE ACTIVE
60 swf-booking-mvc.war 0.0.0 RESOLVED
osgi&gt; </pre><p>Note that the <code class="literal">swf-booking-mvc.war</code> file is in the <code class="literal">Resolved</code> state. The following examples start the bundle, and then examine it to ensure that it is in the <code class="literal">Active</code> state:</p><pre class="programlisting">osgi&gt; vsh:bundle start 60
bundle swf-booking-mvc.war:0.0.0 started successfully
osgi&gt; vsh:bundle examine 60
Id: 60
Name: swf-booking-mvc.war
Version 0.0.0
State: ACTIVE
Spring Powered: true
Bundle Location: file:&lt;... omitted ...&gt;/swf-booking-mvc.war/
Imported Packages:
javax.crypto.interfaces [0.0.0, 0.0.0]
exported by org.eclipse.osgi 3.6.1.R36x_v20100806 [0]
org.omg.CosNaming.NamingContextPackage [0.0.0, 0.0.0]
exported by org.eclipse.osgi 3.6.1.R36x_v20100806 [0]
org.omg.DynamicAny.DynAnyFactoryPackage [0.0.0, 0.0.0]
exported by org.eclipse.osgi 3.6.1.R36x_v20100806 [0]
&lt;... remainder omitted ...&gt;
osgi&gt; </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="admin-shell-vsh-shutdown-command"></a>shutdown Command</h3></div></div></div><p>Use the <code class="literal">shutdown</code> command to shut down the Virgo Kernel instance to which you are connected. When Virgo Kernel is shut down, the shell returns you to the operating system prompt. </p><p>The <code class="literal">shutdown</code> command does not have any options.</p><p>The following example shows how to use this command.</p><pre class="programlisting">osgi&gt; vsh:shutdown
osgi&gt; ...
Connection closed by foreign host.
prompt$</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="admin-shell-cl-clhas"></a>clhas command</h3></div></div></div><p>Use the <code class="literal">clhas</code> command to list the entries contained in the bundles deployed in Virgo and to solve class loading issues.</p><p>The command accepts as a parameter a search pattern in the form <span class="emphasis"><em>path/resource</em></span>. The resource part of the pattern can contain wildcards.</p><p>The output contains all bundles that have resources or classes matching the pattern. Since wildcards are allowed, the matching entities are listed as well.</p><p>The following examples show how to use this command.</p><p>Use the <code class="literal">clhas</code> to view all bundles that contain <code class="literal">Servlet</code> class:</p><pre class="programlisting">osgi&gt;clhas /javax/servlet/Servlet.class
Bundles containing [/javax/servlet/Servlet.class]:
76 javax.servlet
/javax/servlet/Servlet.class</pre><p>Use the wildcard <code class="literal">*</code> with <code class="literal">clhas</code> to view all classes starting with <code class="literal">Servlet</code>:</p><pre class="programlisting">osgi&gt; clhas /javax/servlet/Servlet*
Bundles containing [/javax/servlet/Servlet*]:
76 javax.servlet
/javax/servlet/ServletRequestAttributeEvent.class
/javax/servlet/ServletRequest.class
&lt;... remainder omitted ...&gt;
/javax/servlet/Servlet.class
&lt;... remainder omitted ...&gt;</pre><p>The <code class="literal">clhas</code> command can also be used with class name instead of resource path:</p><pre class="programlisting">osgi&gt; clhas javax.servlet.Servlet
Bundles containing [javax/servlet/Servlet.class]:
76 javax.servlet
/javax/servlet/Servlet.class</pre><p>Please note that the command converts the class name to a path and appends <code class="literal">class</code> extension by default.</p><p>To search for a resource with an extension different than <code class="literal">class</code> you should use the resource path form:</p><pre class="programlisting">osgi&gt; clhas /LocalStrings.properties
Bundles containing [/LocalStrings.properties]:
96 com.springsource.org.apache.catalina
/org/apache/catalina/core/LocalStrings.properties
/org/apache/tomcat/util/http/mapper/LocalStrings.properties
/org/apache/catalina/loader/LocalStrings.properties
&lt;... remainder omitted ...&gt;</pre><p>The following example shows how to identify a possible <code class="literal">ClassCastException</code> due to wrong packaging:</p><pre class="programlisting">osgi&gt;clhas /javax/servlet/Servlet.class
Bundles containing [/javax/servlet/Servlet.class]:
76 javax.servlet
/javax/servlet/Servlet.class
107 myapp
/WEB-INF/classes/javax/servlet/Servlet.class</pre><p>It's obvious that the <code class="literal">javax.servlet</code> package should not be present in <code class="literal">myapp</code> application and its packaging has to be changed. This problem can often be seen in WAR or web bundles that package Servlet/JSP classes by accident.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="admin-shell-cl-clexport"></a>clexport command</h3></div></div></div><p>Use the <code class="literal">clexport</code> command to list the bundles that export a class or package.</p><p>The command accepts as a parameter the fully qualified class name (in the form <span class="emphasis"><em>package.class</em></span>).</p><p>The command checks to see if the provided class is actually contained in a bundle. If the class is not found in a bundle but its package is exported, then a hint <code class="literal">[class not found, package only]</code> is displayed.</p><p>The following examples show how to use this command.</p><p>Use the <code class="literal">clexport</code> to view all bundles that contain <code class="literal">Servlet</code> class:</p><pre class="programlisting">osgi&gt; clexport javax.servlet.Servlet
Bundles exporting [javax.servlet.Servlet]:
14 com.springsource.javax.servlet</pre><p>If a bundle exports a package but does not contain the requested class, the output of the command will be similar to this:</p><pre class="programlisting">osgi&gt; clexport javax.servlet.ServletX
Bundles exporting [javax.servlet.ServletX]:
14 com.springsource.javax.servlet [class not found, package only]</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="admin-shell-cl-clload"></a>clload command</h3></div></div></div><p>Use the <code class="literal">clload</code> command to list the bundles that can load a class or to check if a specific bundle can load a class.</p><p>The command accepts as parameters either:
</p><div class="itemizedlist"><ul type="disc"><li><p>the fully qualified class name (in the form <span class="emphasis"><em>package.class</em></span>)</p></li><li><p>the fully qualified class name (in the form <span class="emphasis"><em>package.class</em></span>) and the symbolic name or id of the bundle that is to be tested</p></li></ul></div><p>
</p><p>The command lists not only the bundle that successfully loaded the class, but also the one that actually provides the class. This is visualized with hints like <code class="literal">[exported by 14 com.springsource.javax.servlet]</code>.</p><p>The following examples show how to use this command.</p><p>You can use the <code class="literal">clload</code> to view all bundles that can load <code class="literal">Servlet</code> class:</p><pre class="programlisting">osgi&gt; clload javax.servlet.Servlet
Successfully loaded [javax.servlet.Servlet] from:
56 com.springsource.org.apache.taglibs.standard
[exported by 14 com.springsource.javax.servlet]
54 org.eclipse.virgo.apps.admin.web
[exported by 14 com.springsource.javax.servlet]
19 com.springsource.org.apache.commons.fileupload
[exported by 14 com.springsource.javax.servlet]
&lt;... remainder omitted ...&gt;</pre><p>If a bundle is to be tested, then its id can be used as a command parameter:</p><pre class="programlisting">osgi&gt; clload javax.servlet.Servlet 19
Successfully loaded [javax.servlet.Servlet] using class loader from:
19 com.springsource.org.apache.commons.fileupload
[exported by 14 com.springsource.javax.servlet]</pre><p>Or the same class load test can specify the symbolic name of the bundle:</p><pre class="programlisting">osgi&gt; clload javax.servlet.Servlet com.springsource.org.apache.commons.fileupload
Successfully loaded [javax.servlet.Servlet] using class loader from:
19 com.springsource.org.apache.commons.fileupload
[exported by 14 com.springsource.javax.servlet]</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="p2-commands"></a>8.4&nbsp;Using the p2 for extending your Virgo installation</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3347"></a>Extending with the p2 director</h3></div></div></div><p>
You can provision new features on top of your Virgo installation using the p2 director. It can be used both for initial provisioning and extending an existing installtion.
</p><p>For extending an existing installation you can use these director arguments:
</p><pre class="screen">-repository http://download.eclipse.org/rt/ecf/3.5.3/site.p2
-installIU org.eclipse.ecf.remoteservice.feature.feature.group
-destination &lt;your Virgo installation folder&gt;</pre><p>This installs the <span class="bold"><strong>latest</strong></span> version of the specified p2 feature in your Virgo installation's p2 profile.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3361"></a>Extending via the p2 shell commands</h3></div></div></div><p>Another way to achieve the same results is to use the p2 commands. The commands are available only in VN as it includes p2 by default.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">For the other distributions only the director is supported and the operation only extends their kernel region.</td></tr></table></div><p>
</p><p>Here's a list of the most commonly used p2 commands:</p><div class="table"><a name="p2-common-commands-table"></a><p class="title"><b>Table&nbsp;8.8.&nbsp;p2 Common Shell Commands</b></p><div class="table-contents"><table summary="p2 Common Shell Commands" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Command</th><th style="border-bottom: 1.0pt solid ; ">Help</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">provaddrepo &lt;repository URI&gt;</code></td><td style="border-bottom: 1.0pt solid ; ">
Add specified URI as metadata and artifact repository. Note that if you pass a wrong URL you'll get an error saying:
<code class="literal">Repository not modifiable: http://wrongURL</code>. The default behavior of this command is to create an empty repository at the
specified location if there isn't any. That won't work for remote locations so keep in mind that if you see this you probably passed a wrong URL.
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">provdelrepo &lt;repository URI&gt;</code></td><td style="border-bottom: 1.0pt solid ; ">
Remove specified metadata and artifact repository.
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">provinstall &lt;InstallableUnit&gt; &lt;version&gt; &lt;profileid&gt;</code></td><td style="border-bottom: 1.0pt solid ; ">
Install an IU to the profileid. If no profileid is given, installs into default profile.
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">provremove &lt;InstallableUnit&gt; &lt;version&gt; &lt;profileid&gt;</code></td><td style="border-bottom: 1.0pt solid ; ">
Uninstall an IU from the profileid. If no profileid is given, uninstalls form default profile.
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">provlg [&lt;repository URI&gt; &lt;iu id | *&gt; &lt;version range | *&gt;]</code></td><td style="border-bottom: 1.0pt solid ; ">
Lists all IUs with group capabilities in the given repo or in all repos if URI is omitted.
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">provliu [&lt;repository URI | *&gt; &lt;iu id | *&gt; &lt;version range | *&gt;]</code></td><td style="border-bottom: 1.0pt solid ; ">
Lists the IUs that match the pattern in the given repo. * matches all.
</td></tr><tr><td style="border-right: 1.0pt solid ; "><code class="literal">confapply</code></td><td style="">
This is a Simple Configurator command, not a p2 one. However it is relevant because it applies dynamically, at runtime, the installed p2 features.
What the command does is to apply to the running OSGi framework the current content in the bundles.info file. When using the provinstall command it takes care of updateing the bundles.info file.
</td></tr></tbody></table></div></div><br class="table-break"><p>Here's an example showing how to install the ECF remote services but with the p2 commands this time:</p><pre class="screen">osgi&gt; provaddrepo http://download.eclipse.org/rt/ecf/3.5.3/site.p2
osgi&gt; provlg
org.eclipse.ecf.core.feature.group 3.5.3.v20111109-2142
org.eclipse.ecf.core.featurepatch.feature.group 3.5.3.v20111109-2142
org.eclipse.ecf.core.featurepatch.source.feature.group 3.5.3.v20111109-2142
org.eclipse.ecf.core.source.feature.group 3.5.3.v20111109-2142
org.eclipse.ecf.datashare.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.datashare.source.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.discovery.dnssd.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.discovery.dnssd.source.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.discovery.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.discovery.jmdns.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.discovery.jmdns.source.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.discovery.slp.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.discovery.slp.source.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.discovery.source.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.discovery.zookeeper.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.discovery.zookeeper.source.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.eventadmin.examples.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.eventadmin.examples.source.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.eventadmin.feature.feature.group 2.0.0.v20111109-2142
org.eclipse.ecf.eventadmin.source.feature.feature.group 2.0.0.v20111109-2142
org.eclipse.ecf.osgi.services.feature.feature.group 2.0.1.v20111109-2142
org.eclipse.ecf.osgi.services.source.feature.feature.group 2.0.1.v20111109-2142
org.eclipse.ecf.remoteservice.examples.feature.feature.group 1.1.0.v20111109-2142
org.eclipse.ecf.remoteservice.examples.source.feature.feature.group 1.1.0.v20111109-2142
org.eclipse.ecf.remoteservice.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.remoteservice.rest.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.remoteservice.rest.source.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.remoteservice.rosgi.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.remoteservice.rosgi.source.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.remoteservice.sdk.feature.feature.group 3.5.3.v20111109-2142
org.eclipse.ecf.remoteservice.sdk.source.feature.feature.group 3.5.3.v20111109-2142
org.eclipse.ecf.remoteservice.soap.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.remoteservice.soap.source.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.remoteservice.source.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.server.generic.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.server.generic.source.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.xmpp.feature.feature.group 1.0.0.v20111109-2142
org.eclipse.ecf.xmpp.source.feature.feature.group 1.0.0.v20111109-2142
osgi&gt; provinstall org.eclipse.ecf.remoteservice.feature.feature.group 1.0.0.v20111109-2142
Installation complete for org.eclipse.ecf.remoteservice.feature.feature.group 1.0.0.v20111109-2142
osgi&gt; confapply
osgi&gt; ss
"Framework is launched."
id State Bundle
0 ACTIVE org.eclipse.osgi_3.7.1.R37x_v20110808-1106
....
92 RESOLVED org.springframework.osgi.io_1.2.1
93 RESOLVED org.eclipse.ecf.console_1.0.0.v20111109-2142
94 RESOLVED org.eclipse.ecf.discovery_4.0.0.v20111109-2142
95 RESOLVED org.eclipse.ecf.provider_4.2.100.v20111109-2142
96 RESOLVED org.eclipse.ecf.provider.discovery_2.1.200.v20111109-2142
97 RESOLVED org.eclipse.ecf.provider.remoteservice_4.0.0.v20111109-2142
98 RESOLVED org.eclipse.ecf.remoteservice_6.0.200.v20111109-2142
99 RESOLVED org.eclipse.ecf.sharedobject_2.2.100.v20111109-2142
100 RESOLVED org.eclipse.equinox.concurrent_1.0.200.v20110502</pre><p>You can see that after applying the changes with <span class="emphasis"><em>confapply</em></span> the remote services bundles and their dependencies are installed in VN.</p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="admin-console"></a>9.&nbsp;The Web Admin Console</h2></div></div></div><p>The Web Server Admin Console is a Web application for managing a single instance of Virgo Server for Apache Tomcat or Virgo Jetty Server
(referred to, generically, as "Web Server" below). Using the Admin Console, you can:</p><div class="itemizedlist"><ul type="disc"><li><p><a class="link" href="#admin-console-login" title="9.1&nbsp;Invoking the Admin Console">View an overview of the Web Server properties</a>.</p></li><li><p><a class="link" href="#admin-console-manage-artifacts" title="Viewing and Managing the Lifecycle of Deployed Artifacts">View and manage the lifecycle</a> of artifacts already deployed to the Web Server instance. Artifacts include bundles, configuration files, PARs, and plans. Lifecycle management tasks include starting, stopping, refreshing, and uninstalling the artifacts.</p></li><li><p><a class="link" href="#admin-console-install-artifacts" title="Installing a New Artifact">Install new artifacts to Web Server</a>.</p></li><li><p><a class="link" href="#admin-console-view-properties" title="Viewing Properties of Deployed Configuration Artifacts">View the properties of the configuration artifacts</a> deployed to Web Server.</p></li><li><p><a class="link" href="#admin-console-view-dumps" title="Viewing the Details of Dump Files">View details of dump files</a> that Web Server might have generated after encountering a problem. This feature is particularly valuable if Web Server fails to install a new artifact due to resolution failures; the OSGi state inspector can help you discover the exact artifact causing the resolution failure.</p></li><li><p><a class="link" href="#admin-console-view-osgi-state" title="Viewing Overview and Details of the OSGi State">View an overview and details of the OSGi State</a> of Web Server, or in other words, a list of all bundles currently installed in Web Server and their state. You can then drill down into the details of each bundle, such as its symbolic name, packages it imports and exports, services it provides and consumes, and so on. You can also view the bundles that were deployed when an exception that generated a dump occurred.</p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">
This section is not applicable to Virgo Nano.
</td></tr></table></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="admin-console-login"></a>9.1&nbsp;Invoking the Admin Console</h2></div></div></div><p>
To use the Admin Console, start the
Virgo Server for Apache Tomcat and then enter the following URL in your
browser of choice.
</p><pre class="screen">http://localhost:8080/admin</pre><p>
Replace <code class="literal">localhost</code> with the hostname of the computer on which the Virgo Server for Apache Tomcat is running if it is not the same as the computer on which you are running your browser. </p><p>The Admin Console uses basic authentication, therefore you will need to enter the default administration ID and password.
</p><pre class="screen">ID: admin
Password: springsource</pre><p>The following graphic shows the main page of the Admin Console.
</p><div class="mediaobject" align="right"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0"><tr><td align="right" valign="bottom"><img src="images/console-main-page.png" align="right"></td></tr></table></div><p>
</p><p>Use the links at the top of the console to perform various tasks, such as viewing and managing artifacts (<span class="bold"><strong>Artifacts</strong></span>), viewing the properties of deployed configuration artifacts (<span class="bold"><strong>Configuration</strong></span>), viewing details of dumps (<span class="bold"><strong>Dump Inspector</strong></span>), and viewing the OSGi state of the Web Server instance (<span class="bold"><strong>OSGi State</strong></span>).</p><p>You can always return to the main Admin Console page by clicking <span class="bold"><strong>Information</strong></span> in the top right-hand corner.</p><p>The <code class="literal">Server Properties</code> section provides information about Web Server itself, such as details about the Java Virtual Machine (JVM), the operating system on which Web Server is installed, the time zone configured for the computer, and the complete version of Web Server.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="admin-console-auth"></a>Changing the Admin User</h3></div></div></div><p>
To change the ID and password for the Admin Console, update the <code class="literal">SERVER_HOME/configuration/org.eclipse.virgo.kernel.users.properties</code> file. First specify the administration username by changing the value of the <code class="literal">role.admin</code> property. Then set the password of this new user by adding a new property called <code class="literal">user.<span class="emphasis"><em>username</em></span></code>, where <code class="literal"><span class="emphasis"><em>username</em></span></code> refers to the actual name of the user. Finally, restart Web Server for the changes to take effect.</p><p>For example, if you want change the administration username to <code class="literal">juliet</code> with password <code class="literal">capulet</code>, change the file as follows:
</p><pre class="programlisting">##################
# User definitions
##################
user.juliet=capulet
##################
# Role definitions
##################
role.admin=juliet</pre><p>
The Admin Console always runs against the <code class="literal">admin</code> role.
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="admin-console-tasks"></a>9.2&nbsp;Typical Admin Console Use Cases</h2></div></div></div><p>The following use cases describe the typical tasks that you can perform with the Admin Console:</p><div class="itemizedlist"><ul type="disc"><li><a class="link" href="#admin-console-manage-artifacts" title="Viewing and Managing the Lifecycle of Deployed Artifacts">View and Manage the Lifecycle of Deployed Artifacts</a></li><li><a class="link" href="#admin-console-install-artifacts" title="Installing a New Artifact">Install a New Artifact</a></li><li><a class="link" href="#admin-console-view-properties" title="Viewing Properties of Deployed Configuration Artifacts">View the Properties of Deployed Configuration Artifacts</a></li><li><a class="link" href="#admin-console-view-dumps" title="Viewing the Details of Dump Files">View Details of Dump Files</a></li><li><a class="link" href="#admin-console-view-osgi-state" title="Viewing Overview and Details of the OSGi State">View Overview and Details of the OSGi State</a></li></ul></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="admin-console-manage-artifacts"></a>Viewing and Managing the Lifecycle of Deployed Artifacts</h3></div></div></div><p>The following procedure describes how to view the list of artifacts that are currently deployed in the user region of Web Server. It then describes how to stop, start, refresh, and uninstall the deployed artifacts.</p><div class="orderedlist"><ol type="1"><li><p>From the main Admin Console page, click the <span class="bold"><strong>Artifacts</strong></span> link at the top.</p><p>In the lower part of the page, the console displays a tree structure that displays the four kinds of artifacts that you can deploy to the user region of Web Server: bundles, configuration files, PARs, and plans. When you first install Web Server, there will already be a number of artifacts deployed related to the Admin console itself, the main splash screen, the repository, and so on. </p><p>The following graphic shows an expanded tree that displays a few of the deployed artifacts:</p><p><img src="images/console-artifacts.png"></p></li><li><p>To view details of a particular artifact, click the "+" to the left of the artifact to expand the tree. The following graphic shows an expanded <code class="literal">org.eclipse.virgo.apps.admin.web</code> bundle:</p><p><img src="images/console-bundle-details.png"></p><p>The particular details that the Admin Console displays depends on the artifact. For example, for all artifacts you can view their state and how it was installed (such as by a user using the Admin Console or programmatically). The two most common states are Active (running and ready to be used) and Resolved (all dependencies resolved but you must start it before you can use it). An artifact can also be in one of the transition states, such as Starting and Stopping. </p><p>As shown in the preceding graphic, the Admin Console provides a link for Web modules that you can click on to actually invoke the application (<code class="literal">org.eclipse.virgo.web.contextPath:/admin</code> in the example above).</p><p>For PARs and plans, the Admin Console also displays whether the artifact is:</p><div class="itemizedlist"><ul type="disc"><li><span class="bold"><strong>Scoped</strong></span>. Scoping specifies whether Web Server should deploy the members of the PAR/plan in their own scope; when scoping is disabled, Web Server deploys the artifacts into the global scope and they are accessible by all other artifacts.</li><li><span class="bold"><strong>Atomic</strong></span>. When a PAR/plan is atomic, Web Server manages the lifecycle of all its member artifacts as a single entity, which means if one artifact member is started, then Web Server starts all the PAR/plan artifacts. If one artifact fails to start, then Web Server stops all other artifacts in the PAR/plan.</li></ul></div><p>The following graphic shows details of a PAR, in particular that it is both scoped and atomic:</p><p><img src="images/console-par-details.png"></p><p>Finally, for bundles, PARs, and plans, you can see the list of bundles that they depend on; this typically means the bundles that export the packages that they import.</p></li><li><p>To manage the lifecycle of an artifact, click on its name in the expanded tree to enable the lifecycle buttons. Then, depending on the current state of the artifact, you can: </p><div class="itemizedlist"><ul type="disc"><li>Start the artifact. All dependencies of the artifact must have been resolved for you to start it. After successfully starting the artifact, it is in the Active state and you can use the application associated with the artifact.</li><li>Stop the artifact. This moves the artifact from an Active to Resolved state, and you cannot use the application associated with the artifact. </li><li>Refresh the artifact. This action updates the physical contents of the artifact; use this button when you have changed the artifact in some way and you want your changes to take effect.</li><li>Uninstall the artifact. This action removes the artifact from Web Server and it does not show up in the Admin Console any more. To use the application associated with this artifact, you must re-install the artifact.</li></ul></div></li></ol></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="admin-console-install-artifacts"></a>Installing a New Artifact</h3></div></div></div><p>The following procedure describes how to install a new artifact (bundle, PAR, plan, or configuration file.) The procedure is similar for all types of artifacts; the procedure uses a WAR file as an example.</p><div class="orderedlist"><ol type="1"><li><p>From the main Admin Console page, click the <span class="bold"><strong>Artifacts</strong></span> link at the top.</p></li><li><p>Click the <span class="bold"><strong>Browse</strong></span> button to invoke the file loader application for your platform. Note that the Browse button searches the computer that is running the browser in which you invoked the Admin Console and <span class="emphasis"><em>not</em></span> the computer on which Web Server is running, in the case where they are different.</p><p>Use the file loader to find the artifact. This can be a WAR or JAR file bundle, a configuration artifact that contains properties, an XML file that corresponds to a plan, or a PAR file.</p></li><li><p>Click <span class="bold"><strong>Upload</strong></span> to actually upload the artifact to Web Server. </p><p>Web Server automatically attempts to resolve all dependencies, and then puts the artifact in an Active state if possible. If all is successful, the message <code class="literal">Artifact Deployed</code> appears next to the <span class="bold"><strong>Artifact Console</strong></span> header. If there is an error, a message to that effect is displayed; to get more details about the error, see the terminal window from which you started Web Server.</p></li><li><p>Expand the artifact tree to view your newly deployed artifact. If Web Server installed it without errors, it should show up in the appropriate section and be in an Active state.</p></li></ol></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="admin-console-view-properties"></a>Viewing Properties of Deployed Configuration Artifacts</h3></div></div></div><p>The following procedure describes how you can view the list of configuration artifacts that are currently deployed to Web Server, and then view the specific properties that are defined for a particular configuration artifact. </p><div class="orderedlist"><ol type="1"><li><p>From the main Admin Console page, click the <span class="bold"><strong>Configuration</strong></span> link at the top.</p><p>The Admin Console displays all the configuration artifacts that are currently deployed, as shown in the following graphic:</p><p><img src="images/console-configuration-details.png"></p></li><li><p>To view the properties defined for a particular configuration artifact click the arrow to the left of its name. </p></li></ol></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="admin-console-view-dumps"></a>Viewing the Details of Dump Files</h3></div></div></div><p>The following procedure describes how to view the details of any service dumps that have occurred in Web Server. Each time a dump is triggered for Web Server, the server creates a directory in <code class="literal">$SERVER_HOME/serviceability/dump</code> with a name corresponding to the time the dump occurred, and then the server populates the directory with detailed information. Using the Admin Console, you can easily view this information.</p><p> A service dump is triggered when there is either a failure in the Web Server code or Web Server detects a thread deadlock in either its own code or a user application. The service dump contains a snapshot of all the important state from the running Web Server instance. <span class="bold"><strong>NOTE:</strong></span> This snapshot is not intended for end user consumption but is useful for service personnel.</p><div class="orderedlist"><ol type="1"><li><p>From the main Admin Console page, click the <span class="bold"><strong>Dump Inspector</strong></span> link at the top.</p></li><li><p>In the drop-down box on the left, select the dump you want to inspect based on its timestamp.</p></li><li><p>Click <span class="bold"><strong>Select Dump</strong></span>.</p></li><li><p>In the right drop-down box, select the type of dump information you want to view.</p><p>For example, <code class="literal">summary.txt</code> provides a short summary of why the dump might have occurred. The <code class="literal">thread.txt</code> option provides information about the state of the Web Server threads at the time of the dump, including any that were deadlocked. The <code class="literal">repository</code> options provide information about what was in the external and user repositories at the time of the dump. The <code class="literal">configurationAdmin.properties</code> option provides a snapshot of the complete configuration of Web Server, including the kernel and repositories.</p></li><li><p>Click <span class="bold"><strong>Select Entry</strong></span>.</p><p>The Admin Console displays the information in the Dump Entry Viewer, as shown in the following graphic:</p><p><img src="images/console-dump-details.png"></p></li></ol></div><p>
Note that the dump entry <code class="literal">osgi.zip</code> is a binary OSGi state dump which should be viewed as described in
<a class="link" href="#admin-console-view-osgi-state" title="Viewing Overview and Details of the OSGi State">Viewing Overview and Details of the OSGi State</a>.
Dumps may contain other binary entries which are not intended for viewing via the dump inspector.
For example, <code class="literal">heap.out</code> contains a dump of the Java heap and <code class="literal">region.digraph</code>
contains a dump of the sharing policy between kernel and use region (this is used by the OSGi state dump inspector).
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="admin-console-view-osgi-state"></a>Viewing Overview and Details of the OSGi State</h3></div></div></div><p>
The following procedure describes how you can view the OSGi state of the Web Server, either currently or at the time that a particular service dump
occurred.
</p><p>
The OSGi state is a list of bundles that are currently installed. When viewing the current state, additional information is available
such as whether each bundle is Spring powered and a list of services in the OSGi service registry. This additional information is not available
when viewing a state dump.
</p><div class="orderedlist"><ol type="1"><li><p>From the main Admin Console page, click the <span class="bold"><strong>OSGi State</strong></span> link at the top.</p><p>By default, the Admin Console displays the complete list of bundles that are currently installed in Web Server.</p><p>For each bundle, the console displays its internal ID, its symbolic name, its version, and its current state (usually either Active or Resolved.)</p></li><li><p>To view the bundles that were installed at the time of a service dump, select the service dump based on its timestamp from the drop-down box on the
right and click <span class="bold"><strong>Go</strong></span>. </p></li><li><p>To view details about a particular bundle, click on its bundle ID. A full description of the bundle is displayed, as shown in the following graphic:</p><p><img src="images/console-osgi-state.png"></p><p>The console displays again the symbolic name, version, and internal ID of the bundle. It then displays whether the bundle is Spring powered and the exact physical location of the bundle JAR file on the computer that hosts Web Server.</p><p>The console then displays the full list of packages that the bundle imports, as well as the bundles that in turn export these imported packages. The console also displays the packages that the current bundle exports, and then in turn the list of other installed bundles that are currently importing these exported packages. For each package, you can drill down and view details of the corresponding bundle.</p><p>Similarly, the console displays the consumed and provided OSGi services. </p><p>Finally, the console also displays information about the Spring context, if the bundle is Spring powered. </p></li><li><p>To view the full list of OSGi services, click the <code class="literal">Services Overview</code> link from the main OSGi state page</p></li><li><p>Typically, the list of bundles and services can be very long, making it difficult to find a particular bundle. Use the <span class="bold"><strong>Search</strong></span> box at the top right corner to narrow down the list of displayed bundles.</p><p>
Enter a package name with wildcards '<code class="literal">*</code>' representing part of a package name (excluding periods) and
'<code class="literal">**</code>' representing one or more components of a package name separated by periods.
For example, '<code class="literal">**.virgo.**</code>' displays Virgo packages.
</p></li></ol></div></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="repository"></a>10.&nbsp;The Provisioning Repository</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="repository-introduction"></a>10.1&nbsp;Overview of the Provisioning Repository</h2></div></div></div><p>
This section describes the provisioning repository feature of Virgo, the reasons for using it, and how to configure it.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">
This section is not applicable to Virgo Nano. The provisioning mechanism used there is p2.
</td></tr></table></div><p>
</p><p>
In most use cases, your application has a dependency on one or more separate artifacts; these artifacts might include OSGi bundles, configuration artifacts, third-party libraries, PARs or plans. A typical example is a Spring application that depends on a third-party library such as Spring Framework or Hibernate.
</p><p>
The way you express this dependency depends on the artifact. For example, a plan is by definition a list of dependent bundles.
</p><p>
Libraries are another example. Some third-party dependencies consist of multiple bundles but are logically one unit. To support this, Virgo has a concept of a library. A library is a collection of related bundles that can be referenced as a whole. You typically express the dependencies between your application and third-party libraries using the <code class="literal">Import-Package</code>, <code class="literal">Import-Bundle</code>, or <code class="literal">Import-Library</code> manifest header in the <code class="literal">MANIFEST.MF</code> file of your application. The <code class="literal">Import-Package</code> header is standard to OSGi; <code class="literal">Import-Bundle</code> and <code class="literal">Import-Library</code>, however, are specific to Virgo.
</p><p>
For additional details about the creation and usage of libraries, as well as general information about dependencies, see <a class="ulink" href="../../virgo-programmer-guide/html/index.html" target="_top">Programmer&#8217;s Guide</a>.
</p><p>
In Virgo, you store all third-party dependencies required by your applications, such as Spring Framework and Hibernate, as artifacts in the provisioning repository. As mentioned above, you can store the following types of artifacts in the repository:
</p><div class="itemizedlist"><ul type="disc"><li>OSGi bundles</li><li>Libraries</li><li>PARs</li><li>Plans</li><li>Configuration Artifacts</li></ul></div><p>
When you deploy your application, Virgo installs the bundle(s) comprising the application to the Virgo runtime; part of this internal installation procedure is to satisfy all the application&#8217;s dependencies. If your application has a dependency that cannot be satisfied from the bundles that you have already deployed (and Virgo has thus installed), then Virgo searches the provisioning repository for an artifact that can satisfy that dependency.
</p><p>
The provisioning repository for a particular instance of Virgo can include artifacts in the following general locations:
</p><div class="itemizedlist"><ul type="disc"><li>Local: This means that artifacts have been physically installed in the provisioning repository directory structure of the local Virgo instance. The artifacts in a local repository include installed third-party libraries, bundles supplied by Virgo, bundles supplied by an end user, and internal bundles used only by Virgo. You can further categorize this location into <code class="literal">external</code> directories that adhere to a specified search pattern and are scanned by Virgo just on a clean startup, or <code class="literal">watched</code> directories that point to a single directory location and which Virgo scans on a regular basis. </li><li>Remote: This means that a local instance of Virgo gets the artifact from a remotely-hosted repository that is physically located on a remote Virgo Server for Apache Tomcat instance. </li></ul></div><p>
You configure the provisioning repository using the <code class="literal">$SERVER_HOME/configuration/org.eclipse.virgo.repository.properties</code> file.
</p><p> As previously described, a particular instance of Virgo Server for Apache Tomcat can itself also act as a repository host for remote server instances to use when satisfying the dependencies of the applications deployed to it. In this case, you configure a hosted repository using the <code class="literal">$SERVER_HOME/configuration/org.eclipse.virgo.apps.repository.properties</code> file. Typically, only remote clients use hosted repositories and their contents; the Virgo Server for Apache Tomcat instance that actually hosts the repository does not typically use the artifacts in it. Rather, it uses artifacts in its local repository.
</p><p>
Making a third-party dependency available to your application is simply a matter of adding its artifact to the appropriate location in the provisioning repository. This could be either in the local directories or the remote ones if you are getting artifacts from a remotely-hosted repository.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="repository-structure"></a>Local Repository Structure</h3></div></div></div><p>
When you first install Virgo, the local provisioning repository is located at <code class="literal">$SERVER_HOME/repository</code> by default and consists of two main directories: <code class="literal">ext</code> and <code class="literal">usr</code>. The <code class="literal">ext</code> directory contains artifacts supplied with the Virgo and <code class="literal">usr</code> contains artifacts supplied by the user and is initially empty.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="repository-installing-bundles"></a>Installing Artifacts to a Repository</h3></div></div></div><p>
To install an artifact into the default repository, simply copy it into the <code class="literal">$SERVER_HOME/repository/usr</code> directory.
</p><p>If you have configured additional watched or external repositories (additional, that is, to the default ones already configured in a freshly-installed Virgo instance), you install the artifacts in the same way: simply copy the files to the configured directories. You configure additional watched or external repositories in the same file as the default repositories: <code class="literal">$SERVER_HOME/configuration/org.eclipse.virgo.repository.properties</code>.
</p><p>When you install a plan or a library into the repository, you must ensure that all referenced artifacts within the plan or library have been installed as well.
</p><p>Artifacts must have unique names so it is considered best practice to include the version number in the file name,
allowing for multiple versions of the artifact to be installed at the same time. For example, a bundle file name might be <code class="literal">my-exciting-bundle.2.1.0.jar</code>.
</p><p>
For watched repositories, such as <code class="literal">$SERVER_HOME/repository/usr</code>, Virgo automatically detects changes
at runtime, thereby avoiding the need to restart Virgo.
</p><p>
Of specific relevance during development is picking up changes to an application&#8217;s direct dependencies during deployment of the application. For example, if you deploy an application and receive a message that a dependency is missing, you can simply add the dependency to the repository and then redeploy the application. The redeploy will cause the new dependency to be picked up, allowing progress to be made without restarting Virgo. For other changes such as addition of optional dependencies, Virgo must be restarted to pick up any changes to the provisioning repository.
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="repository-brits"></a>10.2&nbsp;Downloading Bundles from the SpringSource Enterprise Bundle Repository</h2></div></div></div><p>
The SpringSource Enterprise Bundle Repository is a public collection of open source libraries commonly used for developing enterprise Java applications with the Spring Framework and Virgo. It contains hundreds of the most popular enterprise Java libraries made available for general use in an OSGi-ready format. You can browse the collection and then download the bundles that you need into your own local repository.
</p><p>
The SpringSource Enterprise Bundle Repository is located <a class="ulink" href="http://www.springsource.com/repository" target="_top">here</a>.
</p><p>
<img src="images/bundle-repository.png">
</p><p>
You can find bundles in the repository using a number of options. You use the &#8216;Search&#8217; facility by typing in a keyword. The matching criteria returned can be explored by name, symbolic name, class, package or resource.
</p><p>
There is also the option of clicking on &#8216;Browse by Bundle&#8217;. This gives an alphabetical list of bundles. You can select the desired bundle to see details and find the download link. Finally, you can also choose to &#8216;Browse by Library&#8217;, which allows you to browse the alphabetical list of libraries in the repository.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="repository-configuration"></a>10.3&nbsp;Configuring the Repository</h2></div></div></div><p>Details of how to configure a Virgo installation&#8217;s provisioning repository can be found in <a class="link" href="#configuring-provisioning-repository" title="13.4&nbsp;Configuring the Local Provisioning Repository">Configuring the Provisioning Repository</a>. See <a class="link" href="#configuring-hosted-repo" title="13.5&nbsp;Configuring a Hosted Repository">Configuring a Hosted Repository</a> for details of how to configure a repository that remote clients can access, also called a hosted repository.
</p><p>
The two configuration sections describe the format of the repository properties files of Virgo, how to add new directories to the local repository, how to configure the repository to get artifacts from a remote repository hosted on a remote VTS instance, and how to configure the local VTS instance to host a repository that other remote servers access.
</p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="serviceability"></a>11.&nbsp;Serviceability and Diagnostics</h2></div></div></div><p>
Virgo supports two kinds of logging: <span class="emphasis"><em>Event Logging</em></span> and <span class="emphasis"><em>Trace logging</em></span> which is usually referred
to simply as <span class="emphasis"><em>Logging</em></span>. The difference between Event Logging and Logging is explained below, but both are configured in the
<code class="literal">serviceability.xml</code> file in the <code class="literal">configuration</code> directory. This file takes the form of a Logback configuration, Virgo
uses a Logback implementation behind the SLF4J logging interface.
</p><p>
For a description of the syntax and facilities provided by <code class="literal">serviceability.xml</code>
see the <span class="emphasis"><em>Logback</em></span> documentation (referenced in <a class="xref" href="#furtherreading" title="Appendix&nbsp;C.&nbsp; Further Reading">Appendix&nbsp;C, <i>
Further Reading
</i></a>).
</p><p>
</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="serviceability-info-log"></a>11.1&nbsp;Event Logging</h2></div></div></div><p>
Event logging records important events in Virgo. Each event is logged to
an event log file and is accompanied by a code enclosed in angle brackets.
An example is shown below:
</p><pre class="screen">
[2010-10-25 16:20:45.897] system-artifacts &lt;TC0010I&gt; Creating HTTP/1.1 connector with scheme http on port 8080.
</pre><p>
(For a description of the log code syntax, see <a class="xref" href="#log-codes" title="Appendix&nbsp;A.&nbsp;Event log codes">Appendix&nbsp;A, <i>Event log codes</i></a>.)
The format of event log messages is fully configurable.
</p><p>
By default, event log messages are stored in <code class="literal">$SERVER_HOME/serviceability/eventlogs/eventlog.log</code>.
</p><p>
The default behaviour is that, once <code class="literal">eventlog.log</code> reaches a 10Mb limit, it rolls into a series of files named
<code class="literal">eventlog_</code><span class="emphasis"><em>i</em></span><code class="literal">.log</code> where <span class="emphasis"><em>i</em></span> ranges from 1 to 4, and event logging continues in
a new <code class="literal">eventlog.log</code> file.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="serviceability-info-trace"></a>11.2&nbsp;(Trace) Logging</h2></div></div></div><p>
The Virgo&#8217;s (trace) logging support serves two main purposes:
</p><div class="itemizedlist"><ul type="disc"><li>
It provides global trace files that capture high-volume information regarding the Virgo&#8217;s internal events.
The files are intended for use by support personnel to diagnose runtime problems.
</li><li>
It provides application trace files that contain application-generated output. This includes output generated using popular logging and
tracing APIs including the OSGi LogService, as well as output generated by calls to <code class="literal">System.out</code> and <code class="literal">System.err</code>.
These files are intended for use by application developers and system administrators. An application is defined as a scope so a single bundle will
not get its own log file unless it is a Web application Bundle or is included in a scoped plan or a par file.
</li></ul></div><p>
</p><p>
By default, the Virgo trace file is called <code class="literal">$SERVER_HOME/serviceability/logs/log.log</code>,
and, again by default, the application trace files are called <code class="literal">$SERVER_HOME/serviceability/logs/</code><span class="emphasis"><em>application_name</em></span>
<code class="literal">/log.log</code>, where <span class="emphasis"><em>application_name</em></span> is automatically set by Virgo for each application artifact
installed and run (it is a combination of the artifact name and the version).
</p><p>
The default behaviour of these trace files is that, once <code class="literal">log.log</code> reaches a 10Mb limit, it rolls into a series of files named
<code class="literal">log_</code><span class="emphasis"><em>i</em></span><code class="literal">.log</code> where <span class="emphasis"><em>i</em></span> ranges from 1 to 4, and logging continues in
a new <code class="literal">log.log</code> file.
</p><p>
Entries in trace files are by default of the form &lt;timestamp&gt; &lt;thread-name&gt; &lt;source&gt; &lt;level&gt; &lt;entry-text&gt;. For example:
</p><pre class="screen">
[2008-05-15 09:09:46.940] server-dm-2 org.apache.coyote.http11.Http11Protocol I Initializing Coyote HTTP/1.1 on http-48080
</pre><p>
although this format is completely determined by the Logback configuration file <code class="literal">serviceability.xml</code>.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="serviceability-info-trace-app"></a>Application Output</h3></div></div></div><p>
Virgo provides advanced support for capturing and tracing application-generated output by automatically separating trace output on a
per-application basis and will also capture any <code class="literal">System.out</code> and <code class="literal">System.err</code> output.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="per-application-trace"></a>Per-application trace</h4></div></div></div><p>
Virgo uses SLF4J interfaces to Logback, and the root logger (by default) captures all logging output
and appends it to the application-specific trace files as described above.
To modify this, define application-specific loggers in the <code class="literal">serviceability.xml</code> file in the normal way.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sysout-and-syserr"></a>System.out and System.err</h4></div></div></div><p>
<code class="literal">System.out</code> and <code class="literal">System.err</code> output from applications is, by default, captured in the
application&#8217;s trace file.
This happens because the output streams are intercepted and written to the loggers named
<code class="literal">System.out</code> and <code class="literal">System.err</code> respectively.
Since there are no explicit loggers defined with these names in the <code class="literal">serviceability.xml</code> file,
this output is logged by the root logger (which captures <code class="literal">INFO</code> level and above).
</p><p>
The capture of <code class="literal">System.out</code> and <code class="literal">System.err</code> output is configured in the
<code class="literal">configuration/org.eclipse.virgo.medic.properties</code> file by the <code class="literal">log.wrapSysOut</code> and
<code class="literal">log.wrapSysErr</code> properties. By default the properties have a value of <code class="literal">true</code>
and capture is enabled. Capture can be disabled by configuring the properties with a value of <code class="literal">false</code>.
The third and last accepted value is <code class="literal">tee</code> which captures the System streams output in the logs
while at the same time allows printing output to the System streams. Thus this output will appear both in the logs
and in the System stream output - an example could be the Equinox console, launched with <code class="literal">-console</code> startup argument.
</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.gif"></td><th align="left">Important</th></tr><tr><td align="left" valign="top">
If you provide value different than 'true | tee | false' then the server will default to 'tee' and print out a warning.
</td></tr></table></div><p>
The trace entries for <code class="literal">System.out</code> and <code class="literal">System.err</code>
output are of the form:
</p><pre class="screen">
[2008-05-16 09:28:45.874] server-tomcat-thread-1 System.out Hello world!
[2008-05-16 09:28:45.874] server-tomcat-thread-1 System.err Hello world!
</pre><p>
The third column indicates where the output came from (<code class="literal">System.out</code> or <code class="literal">System.err</code>).
</p><p>
To over-ride this behaviour, simply define explicit loggers named <code class="literal">System.out</code>
and/or <code class="literal">System.err</code> in the configuration file to send this output to an appender of your choice.
Be aware that all applications&#8217; output streams will be caught by these loggers, and that a sifting appender might be useful to separate them.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="janino"></a>Janino</h4></div></div></div><p>
Janino can be used to define trace filters as Java expressions. This adds a significant overhead to tracing, so should be used with care.
</p><p>
For example, the addition of the following filter element to the sifting appender in <code class="literal">serviceability.xml</code>
suppresses per-application trace output that is not associated with a particular application and is normally written to
<code class="literal">serviceability/logs/virgo-kernel/log.log</code>.
</p><pre class="programlisting">&lt;<span class="hl-tag">appender</span> <span class="hl-attribute">name</span>=<span class="hl-value">"SIFTED_LOG_FILE"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"ch.qos.logback.classic.sift.SiftingAppender"</span>&gt;
&lt;<span class="hl-tag">discriminator</span>&gt;
&lt;<span class="hl-tag">Key</span>&gt;applicationName&lt;<span class="hl-tag">/Key</span>&gt;
&lt;<span class="hl-tag">DefaultValue</span>&gt;virgo-kernel&lt;<span class="hl-tag">/DefaultValue</span>&gt;
&lt;<span class="hl-tag">/discriminator</span>&gt;
&lt;<span class="hl-tag">sift</span>&gt;
&lt;<span class="hl-tag">appender</span> <span class="hl-attribute">name</span>=<span class="hl-value">"${applicationName}_LOG_FILE"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"ch.qos.logback.core.rolling.RollingFileAppender"</span>&gt;
&lt;<span class="hl-tag">filter</span> <span class="hl-attribute">class</span>=<span class="hl-value">"ch.qos.logback.core.filter.EvaluatorFilter"</span>&gt;
&lt;<span class="hl-tag">evaluator</span> <span class="hl-attribute">class</span>=<span class="hl-value">"ch.qos.logback.classic.boolex.JaninoEventEvaluator"</span>&gt;
&lt;<span class="hl-tag">expression</span>&gt;
(mdc == null) || (mdc.get("applicationName") == null)
&lt;<span class="hl-tag">/expression</span>&gt;
&lt;<span class="hl-tag">/evaluator</span>&gt;
&lt;<span class="hl-tag">OnMismatch</span>&gt;NEUTRAL&lt;<span class="hl-tag">/OnMismatch</span>&gt;
&lt;<span class="hl-tag">OnMatch</span>&gt;DENY&lt;<span class="hl-tag">/OnMatch</span>&gt;
&lt;<span class="hl-tag">/filter</span>&gt;
&lt;<span class="hl-tag">file</span>&gt;serviceability/logs/${applicationName}/log.log&lt;<span class="hl-tag">/file</span>&gt;
...
&lt;<span class="hl-tag">/appender</span>&gt;
&lt;<span class="hl-tag">/sift</span>&gt;
&lt;<span class="hl-tag">/appender</span>&gt;</pre><p>
</p><p>
To enable Janino in Virgo, place the Janino and commons compiler JARs, converted to OSGi bundles, in <code class="literal">plugins</code>.
For example these bundles are available at v2.6.1 from the SpringSource Enterprise Bundle Repository.
Then add the following lines to
<code class="literal">configuration/org.eclipse.equinox.simpleconfigurator/bundles.info</code>
(as described in <a class="link" href="#configuring-framework-bundles" title="Configuring OSGi Framework Bundles">Configuring OSGi Framework Bundles</a>):
</p><pre class="programlisting">com.springsource.org.codehaus.janino,2.6.1,plugins/com.springsource.org.codehaus.janino-2.6.1.jar,4,false
com.springsource.org.codehaus.commons.compiler,2.6.1,plugins/com.springsource.org.codehaus.commons.compiler-2.6.1.jar,4,false</pre><p>
</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.gif"></td><th align="left">Important</th></tr><tr><td align="left" valign="top">
Current versions of Logback, including 0.9.28 to 1.0, do not set Janino's "parent" class loader correctly.
This bug is covered by the Logback issue <a class="ulink" href="http://jira.qos.ch/browse/LBCORE-244" target="_top">LBCORE-244</a>.
With such versions, it is necessary to attach a fragment bundle to Janino. Place the fragment bundle in <code class="literal">plugins</code> and list it in
<code class="literal">configuration/org.eclipse.equinox.simpleconfigurator/bundles.info</code>.
The fragment's contents are described in <a class="ulink" href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=333920#c15" target="_top">bug 333920</a>.
</td></tr></table></div></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="serviceability-info-dump"></a>11.3&nbsp;Service Dumps</h2></div></div></div><p>
A service dump is triggered when one of the following events
occurs:
</p><div class="orderedlist"><ol type="1"><li><p>
A failure is detected in the Virgo code, or
</p></li><li><p>
a thread deadlock is detected.
</p></li></ol></div><p>
A service dump contains a snapshot of all the important state from
the running Virgo instance. This snapshot is not intended
for end user consumption but is useful for service personnel.
</p><p>
By default, service dumps are created in
<code class="literal">$SERVER_HOME/serviceability/dump</code>.
</p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="deployment"></a>12.&nbsp;Working with Applications</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="deployment-deploying"></a>12.1&nbsp;Deploying Artifacts</h2></div></div></div><p>
In the context of Virgo Server for Apache Tomcat, <span class="emphasis"><em>deploying</em></span> refers to installing an artifact to the server and then starting it to make it available to users. Typically, when you install an artifact, VTS automatically starts it as long as the server is able to successfully resolve all its dependencies. For this reason, the terms <span class="emphasis"><em>deploying</em></span> and <span class="emphasis"><em>installing</em></span> are often used interchangeably.
</p><p>You deploy artifacts to Virgo Server for Apache Tomcat using either the hot-deploy directory on the file system or by using the Admin Console. The artifacts that you can deploy to VTS are:
</p><div class="itemizedlist"><ul type="disc"><li>Bundles, including Web Application Bundles</li><li>WARs</li><li>PARs</li><li>Plans</li><li>Configuration Files</li></ul></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="deployment-deploying-nested-contexts"></a>Deploying WARs with nested Web-ContextPaths</h3></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">
This section currently is ONLY relevant for Virgo Nano.
</td></tr></table></div><p>
Virgo Nano Web supports deployment of WAR files which are transformed into Web Application Bundles. This process involves automatic creation of an OSGi manifest with all relevant OSGi header plus the very important Web-ContextPath header. Its value defines how the deployed WAR file can be requested. There is a limitation about this process that the automatic generation only creates a flat context path which equals the name of your WAR file. Virgo Nano Web supports generation of a nested one.
</p><p>In order to benefit from this flexibility all you need to do is just to add hashes '#' to your WAR file name in the places where you want to have slashes in your web context path. Here is an example:
</p><pre class="screen">myWarFile.war would result into "/myWarFile" web context path</pre><p>
</p><pre class="screen">my#War#File.war would result into "/my/War/File" web context path</pre><p>
The symbolic name of the resulting WAB file is the same as the WAR file name but the hashes '#' are replaced with dots '.'.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="initial-deployment-deploying-bulk"></a>Initial Bulk Hot Deploy</h3></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">
This section currently is ONLY relevant for Virgo Nano.
</td></tr></table></div><p>
To hot deploy an artifact initially in bulk mode, copy it into the pickup directory (by default <code class="literal">$SERVER_HOME/pickup</code>) and start up the server. Upon this startup all the artifacts in the <code class="literal">pickup</code> directory will get first installed and resolved and only then they will be started.
</p><p>
This solves the problem where artifacts depend on each other and when not in bulk mode the install order is not guaranteed therefore errors could occur.
</p><p>
This is only available as part of the initial scan of the <code class="literal">pickup</code> directory. Subsequently it goes back to the known mode of single file handled at a time.
</p><pre class="programlisting">prompt$ cd /home/applications
prompt$ cp BundleA.jar $SERVER_HOME/pickup
prompt$ cp BundleWithDependencyOnA.jar $SERVER_HOME/pickup
prompt$ cd $SERVER_HOME/bin
prompt$ ./startup.sh</pre><p>
When the server is started, artifacts are hot deployed and messages similar to the following appear in the log file:
</p><pre class="screen">[2009-12-10 06:41:01.021] fs-watcher &lt;HD0001I&gt; Hot deployer processing 'INITIAL' event for file 'BundleA.jar; BundleWithDependencyOnA.jar; '.
[2009-12-10 06:41:01.087] fs-watcher &lt;DE0000I&gt; Installing bundle 'BundleA' version '0.0.0'.
[2009-12-10 06:41:01.274] fs-watcher &lt;DE0001I&gt; Installed bundle 'BundleA' version '0.0.0'.
[2009-12-10 06:41:01.087] fs-watcher &lt;DE0000I&gt; Installing bundle 'BundleWithDependencyOnA' version '0.0.0'.
[2009-12-10 06:41:01.274] fs-watcher &lt;DE0001I&gt; Installed bundle 'BundleWithDependencyOnA' version '0.0.0'.
[2009-12-10 06:41:01.397] fs-watcher &lt;DE0004I&gt; Starting bundle 'BundleA' version '0.0.0'.
[2009-12-10 06:41:01.550] start-signalling-1 &lt;DE0005I&gt; Started bundle 'BundleA' version '0.0.0'.
[2009-12-10 06:41:01.397] fs-watcher &lt;DE0004I&gt; Starting bundle 'BundleWithDependencyOnA' version '0.0.0'.
[2009-12-10 06:41:01.550] start-signalling-1 &lt;DE0005I&gt; Started bundle 'BundleWithDependencyOnA' version '0.0.0'.</pre><p>
If there is a problem with the deployment, such as the server being unable to resolve all dependencies, the console and log both show an error message to help you with troubleshooting.
</p><p>If there are no problems, Virgo Nano automatically starts the artifacts so that they are immediately available to users.
</p><p>Bulk deployment can be disabled and reverted back to the old one-file-at-a-time processing by removing this line from <code class="literal">$SERVER_HOME/configuration/config.ini</code>:
</p><pre class="programlisting">org.eclipse.virgo.fschecker.initialEventMode=bulk</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="deployment-deploying-hot"></a>Hot Deploy</h3></div></div></div><p>
To hot deploy an artifact, copy it into the pickup directory (by default <code class="literal">$SERVER_HOME/pickup</code>):
</p><pre class="programlisting">prompt$ cd /home/applications
prompt$ cp helloWorld.war $SERVER_HOME/pickup</pre><p>
When the artifact is hot deployed, messages similar to the following appear in the log file:
</p><pre class="screen">[2009-12-10 06:41:01.021] fs-watcher &lt;HD0001I&gt; Hot deployer processing 'CREATED' event for file 'helloWorld.war'.
[2009-12-10 06:41:01.087] fs-watcher &lt;DE0000I&gt; Installing bundle 'helloWorld' version '0.0.0'.
[2009-12-10 06:41:01.274] fs-watcher &lt;DE0001I&gt; Installed bundle 'helloWorld' version '0.0.0'.
[2009-12-10 06:41:01.397] fs-watcher &lt;DE0004I&gt; Starting bundle 'helloWorld' version '0.0.0'.
[2009-12-10 06:41:01.414] Thread-3 &lt;WE0000I&gt; Starting web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
[2009-12-10 06:41:01.537] Thread-3 &lt;WE0001I&gt; Started web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
[2009-12-10 06:41:01.550] start-signalling-1 &lt;DE0005I&gt; Started bundle 'helloWorld' version '0.0.0'.</pre><p>
If there is a problem with the deployment, such as the server being unable to resolve all dependencies, the console and log both show an error message to help you with troubleshooting.
</p><p>If there are no problems, VTS automatically starts the artifact so that it is immediately available to users.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="deployment-redeploy-hot"></a>Hot Redeploy</h3></div></div></div><p>
To hot redeploy an artifact which is already hot deployed, copy the updated artifact into the pickup directory (by default <code class="literal">$SERVER_HOME/pickup</code>),
just as for hot deploy. When the artifact is redeployed, messages similar to the following appear in the log file:
</p><pre class="screen">[2013-01-09 14:08:12.422] fs-watcher &lt;HD0001I&gt; Hot deployer processing 'MODIFIED' event for file 'helloWorld.war'.
[2013-01-09 14:08:12.422] fs-watcher &lt;DE0007I&gt; Refreshing bundle 'helloWorld' version '0.0.0'.
[2013-01-09 14:08:12.469] fs-watcher &lt;WE0002I&gt; Stopping web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
[2013-01-09 14:08:13.094] fs-watcher &lt;WE0003I&gt; Stopped web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
[2013-01-09 14:08:13.094] fs-watcher &lt;DE0010I&gt; Stopping bundle 'helloWorld' version '0.0.0'.
[2013-01-09 14:08:13.110] fs-watcher &lt;DE0011I&gt; Stopped bundle 'helloWorld' version '0.0.0'.
[2013-01-09 14:08:13.250] fs-watcher &lt;DE0004I&gt; Starting bundle 'helloWorld' version '0.0.0'.
[2013-01-09 14:08:13.250] start-signalling-2 &lt;WE0000I&gt; Starting web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
[2013-01-09 14:08:13.860] start-signalling-2 &lt;WE0001I&gt; Started web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
[2013-01-09 14:08:13.860] start-signalling-2 &lt;DE0005I&gt; Started bundle 'helloWorld' version '0.0.0'.
[2013-01-09 14:08:13.860] fs-watcher &lt;DE0008I&gt; Refreshed bundle 'helloWorld' version '0.0.0'.</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">
The following paragraph is ONLY relevant for Virgo Nano.
</td></tr></table></div><p>
The redeploy waits for any previous operations on the artifact being redeployed to finish. The wait timeout could be configured through the following property in <code class="literal">$SERVER_HOME/configuration/config.ini</code>:
</p><pre class="programlisting">org.eclipse.virgo.update.timeout</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="deployment-deploying-manual"></a>Deploying Using the Admin Console</h3></div></div></div><p>
The Admin Console allows you to upload a file, which will be deployed automatically, from your local file system to the Virgo Server for Apache Tomcat. As soon as Virgo Server for Apache Tomcat deploys the artifact, it appears in the list of artifacts in the Admin Console. Note that the GUI for uploading varies according to the browser and operating system you use.
</p><p>See <a class="link" href="#admin-console-install-artifacts" title="Installing a New Artifact">Installing a New Artifact</a> for details about using the Admin Console to install (deploy) an artifact. See <a class="link" href="#admin-console" title="9.&nbsp;The Web Admin Console">The Web Admin Console</a> for general information about the Admin Console.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="deployment-deploying-happens"></a>What Happens When You Deploy</h3></div></div></div><p>
When you deploy an artifact, either using hot-deployment or the Admin Console, Web Server copies the file to its work directory (<code class="literal">SERVER_HOME/work</code>) and registers it in its internal registry.
The server then checks any dependencies the artifact might have to see if
deployment can go ahead, and if all dependencies are resolved, Virgo Server for Apache Tomcat starts the artifact.
Because of all these additional internal activities, you should NOT simply copy the artifact into the <code class="literal">work</code> directory and assume it will be deployed, because Virgo Server for Apache Tomcat will not do so.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="deployment-deploying-ordering"></a>Deployment Ordering</h3></div></div></div><p>
When deploying bundles that have dependencies, it is important
that you deploy them in the correct order. Virgo Server for Apache Tomcat
honors this ordering when it redeploys the artifacts on startup.
</p><p>
If you use hot deployment to deploy your artifacts, be sure to copy the corresponding files into the pickup
directory one-by-one. Copying the files in one group, for example by using a single <code class="literal">cp</code> command, provides no guarantee of ordering.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="deployment-deploying-shared"></a>Deploying Shared Artifacts</h3></div></div></div><p>
Artifacts may be shared by plans.
Sharing occurs when a plan is deployed which references an artifact that was previously deployed or is a child artifact
of a plan that was previously deployed.
Sharing also occurs when an artifact is deployed which is already a child of a deployed plan, but in this case the shared
artifact may <span class="emphasis"><em>not</em></span> appear as a top-level artifact, for example, in the Admin Console, in the shell,
and in JMX.
</p><p>
Sharing is taken into account when artifacts are stopped.
A shared artifact is stopped only when all the artifacts referencing the shared artifact have been stopped
and, if the shared artifact was deployed in its own right, the artifact itself has been stopped.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="deployment-deploying-restrictions"></a>Restrictions</h3></div></div></div><p>
Virgo Server for Apache Tomcat does not support deploying fragment bundles. Typically, fragment bundles should be placed in <code class="literal">$SERVER_HOME/repository/ext</code>
or <code class="literal">$SERVER_HOME/repository/usr</code> so that they will be installed automatically with their host bundles.
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="deployment-undeploy"></a>12.2&nbsp;Undeploying Artifacts</h2></div></div></div><p>
You undeploy artifacts from Virgo Server for Apache Tomcat by using either the hot-deploy directory on the file system, or the Admin Console.
</p><p><span class="bold"><strong>Note:</strong></span> As with deploying, in this guide the terms <span class="emphasis"><em>undeploying</em></span> and <span class="emphasis"><em>uninstalling</em></span> are used interchangeably.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="deployment-undeploy-hot"></a>Hot Undeploy</h3></div></div></div><p>
To hot-undeploy an artifact, remove the corresponding file from the pickup directory (by default <code class="literal">$SERVER_HOME/pickup</code>):
</p><pre class="programlisting">prompt$ cd $SERVER_HOME/pickup
prompt$ rm helloWorld.war</pre><p>
When Virgo Server for Apache Tomcat completes the undeployment of the artifact, messages similar to the following appear in the log:
</p><pre class="screen">[2009-12-10 06:46:33.254] fs-watcher &lt;HD0001I&gt; Hot deployer processing 'DELETED' event for file 'helloWorld.war'.
[2009-12-10 06:46:33.259] Thread-3 &lt;WE0002I&gt; Stopping web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
[2009-12-10 06:46:33.285] Thread-3 &lt;WE0003I&gt; Stopped web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
[2009-12-10 06:46:33.290] fs-watcher &lt;DE0010I&gt; Stopping bundle 'helloWorld' version '0.0.0'.
[2009-12-10 06:46:33.295] fs-watcher &lt;DE0011I&gt; Stopped bundle 'helloWorld' version '0.0.0'.
[2009-12-10 06:46:33.302] fs-watcher &lt;DE0013I&gt; Uninstalling bundle 'helloWorld' version '0.0.0'.
[2009-12-10 06:46:33.319] fs-watcher &lt;DE0014I&gt; Uninstalled bundle 'helloWorld' version '0.0.0'.</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="deployment-undeploy-manual"></a>Undeploying Using the Admin Console</h3></div></div></div><p>
You can undeploy only whole artifacts from the Admin Console, or in other words, you cannot undeploy the separate modules or bundles that make up an artifact.</p><p>
The only artifact that you cannot undeploy from the Admin Console is the Admin Console itself. If you need to undeploy this application, you must remove it from the pickup directory (by default <code class="literal">SERVER_HOME/pickup</code>); the name of the artifact is
<code class="literal">org.eclipse.virgo.server.admin-2.1.0.RELEASE.plan</code>.
</p><p>See <a class="link" href="#admin-console-manage-artifacts" title="Viewing and Managing the Lifecycle of Deployed Artifacts">Viewing and Managing the Lifecycle of Deployed Artifacts</a> for details about uninstalling (undeploying) an artifact using the Admin Console. The high-level steps are to highlight the artifact in the artifact tree then click <code class="literal">Uninstall</code>. </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="deployment-undeploying-shared"></a>Undeploying Shared Artifacts</h3></div></div></div><p>
Sharing is taken into account when artifacts are undeployed.
A shared artifact is undeployed only when all the artifacts referencing the shared artifact have been undeployed
and, if the shared artifact was deployed in its own right, the artifact itself has been undeployed.
</p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="configuring"></a>13.&nbsp;Configuration</h2></div></div></div><p>You use configuration files in the <code class="literal">$SERVER_HOME/configuration</code> directory to configure Virgo. You can also configure the OSGi framework using files the same <code class="literal">$SERVER_HOME/configuration</code> directory. This section divides the configuration of the server into the following high-level tasks:</p><div class="itemizedlist"><ul type="disc"><li><p><a class="link" href="#configuring-osgi-framework" title="13.1&nbsp;Configuring the OSGi Framework">Configuring the OSGi framework</a></p></li><li><p><a class="link" href="#configuring-framework-extensions" title="13.2&nbsp;Configuring Framework Extensions and Fragments on the System Bundle">Configuring framework extensions and fragments on the system bundle</a></p></li><li><p><a class="link" href="#configuring-serviceability" title="13.3&nbsp;Configuring Serviceability and Diagnostics">Configuring serviceability</a></p></li><li><p><a class="link" href="#configuring-provisioning-repository" title="13.4&nbsp;Configuring the Local Provisioning Repository">Configuring the local provisioning repository</a></p></li><li><p><a class="link" href="#configuring-hosted-repo" title="13.5&nbsp;Configuring a Hosted Repository">Configuring the hosted repository</a></p></li><li><p><a class="link" href="#configuring-kernel" title="13.6&nbsp;Configuring the Kernel and User Region">Configuring the kernel and User Region</a></p></li><li><p><a class="link" href="#configuring-tomcat" title="13.7&nbsp;Configuring the Embedded Tomcat Servlet Container">Configuring the embedded Tomcat servlet container</a></p></li><li><p><a class="link" href="#configuring-web" title="13.8&nbsp;Configuring the Web Integration Layer">Configuring the web integration layer</a></p></li><li><p><a class="link" href="#configuring-jetty" title="13.9&nbsp;Configuring the Embedded Jetty Servlet Container">Configuring the embedded Jetty servlet container</a></p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note: Why is there both a config and a configuration directory?"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Why is there both a config and a configuration directory?</th></tr><tr><td align="left" valign="top"><p>The <span class="emphasis"><em>config</em></span> directory has always contained Virgo configuration files. When Virgo Nano and its support for p2 provisioning was introduced in Virgo 3.5.0, a <span class="emphasis"><em>configuration</em></span> directory replaced the old <span class="emphasis"><em>config</em></span> one. Now all Virgo configurations are assembled in that directory providing a single point of configuration. The directory name <span class="emphasis"><em>configuration</em></span> in the installation's root is used by default in p2 to configure the OSGi framework during provisioning.</p><p>This chapter makes it clear which configuration goes in each directory.</p></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">Sections 4-6 and 8-9 does not apply for Virgo Nano.</td></tr></table></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-osgi-framework"></a>13.1&nbsp;Configuring the OSGi Framework</h2></div></div></div><p>
This section provides information about configuring the OSGi framework by updating the following files in the <code class="literal">$SERVER_HOME/configuration</code> directory:
</p><div class="table"><a name="configuring-osgi-framework-table"></a><p class="title"><b>Table&nbsp;13.1.&nbsp;OSGi Framework Configuration Files </b></p><div class="table-contents"><table summary="OSGi Framework Configuration Files " style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Property File</th><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Description</th><th style="border-bottom: 1.0pt solid ; ">Location</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">config.ini</code></td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Configures <a class="link" href="#configuring-framework-properties" title="Configuring OSGi Framework Properties">OSGi framework properties</a>.</td><td style="border-bottom: 1.0pt solid ; ">$SERVER_HOME/configuration</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">bundles.info</code></td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Configures <a class="link" href="#configuring-framework-bundles" title="Configuring OSGi Framework Bundles">OSGi framework bundles</a>.</td><td style="border-bottom: 1.0pt solid ; ">$SERVER_HOME/configuration/org.eclipse.equinox.simpleconfigurator</td></tr><tr><td style="border-right: 1.0pt solid ; "><code class="literal">java6-server.profile</code></td><td style="border-right: 1.0pt solid ; ">Configures the <a class="link" href="#configuring-framework-profile" title="Configuring OSGi Framework Profile">OSGi framework profile</a>.</td><td style="">$SERVER_HOME/configuration</td></tr></tbody></table></div></div><br class="table-break"><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-framework-properties"></a>Configuring OSGi Framework Properties</h3></div></div></div><p>
You specify the framework properties in the <code class="literal">$SERVER_HOME/configuration/config.ini</code> file. The
properties most relevant to users are described in the following table.
</p><p>
<span class="bold"><strong>WARNING:</strong></span> We strongly recommend that you update only the
properties below; updating other properties could cause Virgo
to fail.
</p><div class="table"><a name="configuring-framework-properties-table"></a><p class="title"><b>Table&nbsp;13.2.&nbsp;Framework Properties</b></p><div class="table-contents"><table summary="Framework Properties" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Property</th><th style="border-bottom: 1.0pt solid ; ">Description</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">org.eclipse.virgo.kernel.startup.wait.limit</code></td><td style="border-bottom: 1.0pt solid ; ">
Specifies the amount of time, in seconds, after which various operations time out out while trying to start the kernel.
The default value is 180.
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">org.eclipse.virgo.suppress.heap.dumps</code></td><td style="border-bottom: 1.0pt solid ; ">
Set to 'false' by default this property will prevent heap dumps being contributed to dumps taken during a
First Failure Data Capture (FFDC) event. When the heap dumps are produced they will be located along with
the other dump artifacts in the <code class="literal">$SERVER_HOME/serviceability/dump/</code> folder.
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">osgi.java.profile</code></td><td style="border-bottom: 1.0pt solid ; ">
Specifies the profile to use using a <code class="literal">file:</code> URI with default value
<code class="literal">file:configuration/java6-server.profile</code>.
</td></tr><tr><td style="border-right: 1.0pt solid ; "><code class="literal">osgi.bundlefile.limit</code></td><td style="">
Specifies a limit on the number of jar files the framework will keep open.
The minimum value allowed is 10. Any value less than 10 will disable the bundle file limit, making the the number of jar files the framework keeps open unlimited.
By default the value is 100.
Increase the default value if you have many jar files in the bundle class path, expect a lot of file system operations etc.
</td></tr></tbody></table></div></div><br class="table-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-framework-bundles"></a>Configuring OSGi Framework Bundles</h3></div></div></div><p>
You specify the framework bundles in the <code class="literal">$SERVER_HOME/configuration/org.eclipse.equinox.simpleconfigurator/bundles.info</code> file. The syntax
that is accepted for listing bundles there is:
</p><pre class="screen">&lt;bsn&gt;,&lt;version&gt;,&lt;jar-location&gt;,&lt;start-level&gt;,&lt;toStart?&gt;
bsn - the bundle's symbolic name string
version - the bundle's version string
jar-location - relative or absolute path to the jar file
start-level - a digit indicating the bundle's start level
toStart? - true or false value indicating whether a bundle should be started or not</pre><p>
</p><p>Here's an example:</p><p>
</p><pre class="screen">org.eclipse.virgo.util.osgi,3.1.0.BUILD-20111031165127,plugins/org.eclipse.virgo.util.osgi_3.1.0.BUILD-20111031165127.jar,4,true</pre><p>
</p><p>
<span class="bold"><strong>WARNING:</strong></span> We strongly recommend that you don't remove bundles already present in your bundles.info file as that may break your server. Add bundles here only if absolutely necessary.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-framework-profile"></a>Configuring OSGi Framework Profile</h3></div></div></div><p>
You specify the framework profile in the <code class="literal">$SERVER_HOME/configuration/java6-server.profile</code> file. The
properties most relevant to users are described in the following table.
</p><p>
<span class="bold"><strong>WARNING:</strong></span> We advise you not to change the framework profile unless you are sure you know exactly what
you are doing; updating the profile could cause Virgo to fail.
</p><div class="table"><a name="configuring-framework-profile-table"></a><p class="title"><b>Table&nbsp;13.3.&nbsp;Framework Profile Properties</b></p><div class="table-contents"><table summary="Framework Profile Properties" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Property</th><th style="border-bottom: 1.0pt solid ; ">Description</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">org.osgi.framework.bootdelegation</code></td><td style="border-bottom: 1.0pt solid ; ">
<p>
This property specifies the packages which are loaded by delegation to the application class loader.
Bundles can load classes belonging to these packages without importing the packages.
The <code class="literal">.*</code> wildcard matches any package suffix. <code class="literal">java.*</code> is always
boot delegated and must not be specified in this property.
</p>
<p>
A common reason for adding packages to this property is to run Virgo under a performance profiler.
</p>
</td></tr><tr><td style="border-right: 1.0pt solid ; "><code class="literal">org.osgi.framework.system.packages</code></td><td style="">
<p>
This property specifies the packages which are exported by the system bundle.
</p>
<p>
Although the system bundle is typically imported into the User Region, any additional packages will not be
visible in the User Region unless you also import them using the <code class="literal">packagedImports</code> property.
See <a class="link" href="#configuring-user-region" title="Configuring the User Region">Configuring the User Region</a> for instructions.
</p>
<p>
It is very occasionally necessary to extend the set, for example when configuring email logging appenders since the
implementation of <code class="literal">javax.mail</code> is intimately related to the implementation of
<code class="literal">javax.activation</code>.
</p>
<p>
To make the corresponding classes available for loading, the relevant JAR file(s) should be placed in
<code class="literal">$SERVER_HOME/lib</code> so that they will be added to the application class path.
</p>
</td></tr></tbody></table></div></div><br class="table-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-framework-extensions"></a>13.2&nbsp;Configuring Framework Extensions and Fragments on the System Bundle</h2></div></div></div><p>
This section provides information about configuring framework extensions and fragments on the system bundle. Deployment of such bundles is not allowed in
Virgo. This is because by refreshing or uninstalling them the system.bundle is also refreshed, which causes Virgo to crash.
</p><p>
<span class="bold"><strong>NOTE:</strong></span> This only applies for fragments on the system bundle. All other fragment bundles have no deployment restrictions.
</p><p>
Generally it's best to avoid usage of such fragment bundles as they are a common OSGi framework issue and often require restarting the framework.
However sometimes there are no other options and one has to use framework extensions or fragments on the system bundle.
</p><p>
You can configure framework extensions and system bundle fragments as follows:
</p><p>
<span class="bold"><strong>1.</strong></span> Place your fragment bundle in the <code class="literal">/plugins</code> directory of your Virgo installation.
</p><p>
Lets say we have bundle with
</p><p>
</p><pre class="programlisting">
symbolic name: <span class="emphasis"><em>testFragment</em></span>, version: <span class="emphasis"><em>1.0.0</em></span> and filename: <span class="emphasis"><em>testFragmentBinary_1.0.0.jar</em></span>
</pre><p>
</p><p>
<span class="bold"><strong>2.</strong></span> Configure the <code class="literal">bundles.info</code> file in <code class="literal">/configuration/org.eclipse.equinox.simpleconfigurator</code> to include the
just copied fragment or framework extension bundle.
</p><p>
Add a line at the end of the <code class="literal">bundles.info</code> file similar to this one:
</p><p>
</p><pre class="programlisting">
<span class="emphasis"><em>testFragment,1.0.0,plugins/testFragmentBinary_1.0.0.jar,4,false</em></span>
</pre><p>
</p><p>
<span class="bold"><strong>3.</strong></span> Configure the <code class="literal">org.eclipse.virgo.kernel.userregion.properties</code> file in <code class="literal">/configuration</code> folder to import the fragment bundle or framework extension in the User Region.
</p><p>
Add to the <code class="literal">bundleImports</code> property a new line describing the fragment bundle using its symbolic name and version.
</p><p>
</p><pre class="programlisting">
bundleImports = org.eclipse.osgi;bundle-version="0",<span class="bold"><strong>testFragment;bundle-version="0"</strong></span>
</pre><p>
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-serviceability"></a>13.3&nbsp;Configuring Serviceability and Diagnostics</h2></div></div></div><p>The serviceability features of Virgo allow you to gather and view data and information that you can then use to diagnose problems and failures. Serviceability data includes:</p><div class="itemizedlist"><ul type="disc"><li><p>
Service dumps: Contain a snapshot of all the important state from the running Virgo instance when an internal failure or thread deadlock is detected.
</p><p>You configure service dumps for Virgo using the <a class="link" href="#configuring-serviceability-medic" title="The org.eclipse.virgo.medic.properties File">org.eclipse.virgo.medic.properties</a> file in the <code class="literal">$SERVER_HOME/configuration</code> directory. This file also includes some additional logging configuration.</p></li><li><p>
Event logs and server/application (trace) logging: Logging support in Virgo is based on <a class="ulink" href="http://logback.qos.ch/" target="_top">Logback</a>. This means that you have complete control over the format of log output and have the complete range of Logback's appenders available for your use.
</p><p>You configure logging for Virgo using the <a class="link" href="#configuring-serviceability-logback" title="The serviceability.xml File">serviceability.xml</a> file in the <code class="literal">$SERVER_HOME/configuration</code> directory. This file is essentially the Logback <code class="literal">logback.xml</code> (or <code class="literal">logback-test.xml</code>) configuration file but renamed for Virgo. </p></li></ul></div><p>For additional conceptual information about the serviceability subsystem, see <a class="xref" href="#serviceability" title="11.&nbsp;Serviceability and Diagnostics">Chapter&nbsp;11, <i>Serviceability and Diagnostics</i></a>. </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-serviceability-medic"></a>The org.eclipse.virgo.medic.properties File</h3></div></div></div><p>The <code class="literal">$SERVER_HOME/configuration/org.eclipse.virgo.medic.properties</code> file configures Virgo service dumps and whether you want to capture <code class="literal">System.out</code> and <code class="literal">System.err</code> output to your application's trace file. </p><p>The following table describes the properties you can include in the <code class="literal">$SERVER_HOME/configuration/org.eclipse.virgo.medic.properties</code> file. This file configures serviceability properties that Virgo includes in addition to those supplied by the Logback, configured in the <code class="literal">serviceability.xml</code> file.</p><div class="table"><a name="medic-properties-table"></a><p class="title"><b>Table&nbsp;13.4.&nbsp;Serviceability Properties</b></p><div class="table-contents"><table summary="Serviceability Properties" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Property</th><th style="border-bottom: 1.0pt solid ; ">Description</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">dump.root.directory</code></td><td style="border-bottom: 1.0pt solid ; ">Specifies the directory to which Virgo writes the service dumps. The directory name is relative to <code class="literal">$SERVER_HOME</code>. </td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">log.wrapSysOut</code></td><td style="border-bottom: 1.0pt solid ; ">Specifies whether you want to capture <code class="literal">System.out</code> output from your applications to the application trace file. The output is logged by Virgo's root logger, which captures <code class="literal">INFO</code> level and above.
<p>Valid values for this property are <code class="literal">true</code> to capture <code class="literal">System.out</code> output, or <code class="literal">false</code> to disable the capture.</p>
<p>For more information, see <a class="link" href="#sysout-and-syserr" title="System.out and System.err">System.out and System.err</a>.</p>
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">log.wrapSysErr</code></td><td style="border-bottom: 1.0pt solid ; ">Specifies whether you want to capture <code class="literal">System.err</code> output from your applications to the application trace file. The output is logged by Virgo's root logger, which captures <code class="literal">INFO</code> level and above.
<p>Valid values for this property are <code class="literal">true</code> to capture <code class="literal">System.err</code> output, or <code class="literal">false</code> to disable the capture.</p>
<p>For more information, see <a class="link" href="#sysout-and-syserr" title="System.out and System.err">System.out and System.err</a>.</p>
</td></tr><tr><td style="border-right: 1.0pt solid ; "><code class="literal">log.jul.consoleHandler</code></td><td style="">Specifies whether you want to use the <code class="literal">ConsoleHandler</code> of Java Util Logging. The default JVM configuration uses the handler to write logs to <code class="literal">System.err</code>.
<p>Valid values for this property are <code class="literal">true</code> to enable <code class="literal">ConsoleHandler</code> output, or <code class="literal">false</code> to disable it. The default value is <code class="literal">false</code>.</p>
<p>For more information, see <a class="ulink" href="http://download.oracle.com/javase/6/docs/technotes/guides/logging/overview.html" target="_top">Java Logging Overview</a>.</p>
</td></tr></tbody></table></div></div><br class="table-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-serviceability-logback"></a>The serviceability.xml File</h3></div></div></div><p>Logging support in Virgo is based on <a class="ulink" href="http://logback.qos.ch/" target="_top">Logback</a>, which is a successor of the log4j project. The Logback logging framework is faster, more reliable, and easier to use than log4j and certain other logging systems.</p><p>You configure logging for Virgo using the <code class="literal">$SERVER_HOME/configuration/serviceability.xml</code> file. This file is the standard Logback <code class="literal">logback.xml</code> or <code class="literal">logback-test.xml</code> configuration file, but renamed for Virgo. </p><p>The following listing shows the default <code class="literal">serviceability.xml</code> file in a freshly-installed Virgo; see the text after the listing for a brief overview of the file:</p><pre class="programlisting">&lt;<span class="hl-tag">configuration</span>&gt;
&lt;<span class="hl-tag">jmxConfigurator</span> /&gt;
&lt;<span class="hl-tag">contextListener</span> <span class="hl-attribute">class</span>=<span class="hl-value">"ch.qos.logback.classic.jul.LevelChangePropagator"</span>/&gt;
&lt;<span class="hl-tag">appender</span> <span class="hl-attribute">name</span>=<span class="hl-value">"SIFTED_LOG_FILE"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"ch.qos.logback.classic.sift.SiftingAppender"</span>&gt;
&lt;<span class="hl-tag">discriminator</span>&gt;
&lt;<span class="hl-tag">Key</span>&gt;applicationName&lt;<span class="hl-tag">/Key</span>&gt;
&lt;<span class="hl-tag">DefaultValue</span>&gt;virgo-server&lt;<span class="hl-tag">/DefaultValue</span>&gt;
&lt;<span class="hl-tag">/discriminator</span>&gt;
&lt;<span class="hl-tag">sift</span>&gt;
&lt;<span class="hl-tag">appender</span> <span class="hl-attribute">name</span>=<span class="hl-value">"${applicationName}_LOG_FILE"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"ch.qos.logback.core.rolling.RollingFileAppender"</span>&gt;
&lt;<span class="hl-tag">file</span>&gt;serviceability/logs/${applicationName}/log.log&lt;<span class="hl-tag">/file</span>&gt;
&lt;<span class="hl-tag">rollingPolicy</span> <span class="hl-attribute">class</span>=<span class="hl-value">"ch.qos.logback.core.rolling.FixedWindowRollingPolicy"</span>&gt;
&lt;<span class="hl-tag">FileNamePattern</span>&gt;serviceability/logs/${applicationName}/log_%i.log&lt;<span class="hl-tag">/FileNamePattern</span>&gt;
&lt;<span class="hl-tag">MinIndex</span>&gt;1&lt;<span class="hl-tag">/MinIndex</span>&gt;
&lt;<span class="hl-tag">MaxIndex</span>&gt;4&lt;<span class="hl-tag">/MaxIndex</span>&gt;
&lt;<span class="hl-tag">/rollingPolicy</span>&gt;
&lt;<span class="hl-tag">triggeringPolicy</span> <span class="hl-attribute">class</span>=<span class="hl-value">"ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy"</span>&gt;
&lt;<span class="hl-tag">MaxFileSize</span>&gt;10MB&lt;<span class="hl-tag">/MaxFileSize</span>&gt;
&lt;<span class="hl-tag">/triggeringPolicy</span>&gt;
&lt;<span class="hl-tag">encoder</span> <span class="hl-attribute">class</span>=<span class="hl-value">"ch.qos.logback.classic.encoder.PatternLayoutEncoder"</span>&gt;
&lt;<span class="hl-tag">Pattern</span>&gt;[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-5level %-28.28thread %-64.64logger{64} %X{medic.eventCode} %msg %ex%n&lt;<span class="hl-tag">/Pattern</span>&gt;
&lt;<span class="hl-tag">/encoder</span>&gt;
&lt;<span class="hl-tag">/appender</span>&gt;
&lt;<span class="hl-tag">/sift</span>&gt;
&lt;<span class="hl-tag">/appender</span>&gt;
&lt;<span class="hl-tag">appender</span> <span class="hl-attribute">name</span>=<span class="hl-value">"LOG_FILE"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"ch.qos.logback.core.rolling.RollingFileAppender"</span>&gt;
&lt;<span class="hl-tag">file</span>&gt;serviceability/logs/log.log&lt;<span class="hl-tag">/file</span>&gt;
&lt;<span class="hl-tag">rollingPolicy</span> <span class="hl-attribute">class</span>=<span class="hl-value">"ch.qos.logback.core.rolling.FixedWindowRollingPolicy"</span>&gt;
&lt;<span class="hl-tag">FileNamePattern</span>&gt;serviceability/logs/log_%i.log&lt;<span class="hl-tag">/FileNamePattern</span>&gt;
&lt;<span class="hl-tag">MinIndex</span>&gt;1&lt;<span class="hl-tag">/MinIndex</span>&gt;
&lt;<span class="hl-tag">MaxIndex</span>&gt;4&lt;<span class="hl-tag">/MaxIndex</span>&gt;
&lt;<span class="hl-tag">/rollingPolicy</span>&gt;
&lt;<span class="hl-tag">triggeringPolicy</span> <span class="hl-attribute">class</span>=<span class="hl-value">"ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy"</span>&gt;
&lt;<span class="hl-tag">MaxFileSize</span>&gt;10MB&lt;<span class="hl-tag">/MaxFileSize</span>&gt;
&lt;<span class="hl-tag">/triggeringPolicy</span>&gt;
&lt;<span class="hl-tag">encoder</span> <span class="hl-attribute">class</span>=<span class="hl-value">"ch.qos.logback.classic.encoder.PatternLayoutEncoder"</span>&gt;
&lt;<span class="hl-tag">Pattern</span>&gt;[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-5level %-28.28thread %-64.64logger{64} %X{medic.eventCode} %msg %ex%n&lt;<span class="hl-tag">/Pattern</span>&gt;
&lt;<span class="hl-tag">/encoder</span>&gt;
&lt;<span class="hl-tag">/appender</span>&gt;
&lt;<span class="hl-tag">appender</span> <span class="hl-attribute">name</span>=<span class="hl-value">"EVENT_LOG_STDOUT"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.eclipse.virgo.medic.log.logback.ReroutingAwareConsoleAppender"</span>&gt;
&lt;<span class="hl-tag">encoder</span> <span class="hl-attribute">class</span>=<span class="hl-value">"ch.qos.logback.classic.encoder.PatternLayoutEncoder"</span>&gt;
&lt;<span class="hl-tag">Pattern</span>&gt;[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-28.28thread &amp;lt;%X{medic.eventCode}&amp;gt; %msg %ex%n&lt;<span class="hl-tag">/Pattern</span>&gt;
&lt;<span class="hl-tag">/encoder</span>&gt;
&lt;<span class="hl-tag">/appender</span>&gt;
&lt;<span class="hl-tag">appender</span> <span class="hl-attribute">name</span>=<span class="hl-value">"EVENT_LOG_FILE"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"ch.qos.logback.core.rolling.RollingFileAppender"</span>&gt;
&lt;<span class="hl-tag">file</span>&gt;serviceability/eventlogs/eventlog.log&lt;<span class="hl-tag">/file</span>&gt;
&lt;<span class="hl-tag">rollingPolicy</span> <span class="hl-attribute">class</span>=<span class="hl-value">"ch.qos.logback.core.rolling.FixedWindowRollingPolicy"</span>&gt;
&lt;<span class="hl-tag">FileNamePattern</span>&gt;serviceability/eventlogs/eventlog_%i.log&lt;<span class="hl-tag">/FileNamePattern</span>&gt;
&lt;<span class="hl-tag">MinIndex</span>&gt;1&lt;<span class="hl-tag">/MinIndex</span>&gt;
&lt;<span class="hl-tag">MaxIndex</span>&gt;4&lt;<span class="hl-tag">/MaxIndex</span>&gt;
&lt;<span class="hl-tag">/rollingPolicy</span>&gt;
&lt;<span class="hl-tag">triggeringPolicy</span> <span class="hl-attribute">class</span>=<span class="hl-value">"ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy"</span>&gt;
&lt;<span class="hl-tag">MaxFileSize</span>&gt;10MB&lt;<span class="hl-tag">/MaxFileSize</span>&gt;
&lt;<span class="hl-tag">/triggeringPolicy</span>&gt;
&lt;<span class="hl-tag">encoder</span> <span class="hl-attribute">class</span>=<span class="hl-value">"ch.qos.logback.classic.encoder.PatternLayoutEncoder"</span>&gt;
&lt;<span class="hl-tag">Pattern</span>&gt;[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-28.28thread &amp;lt;%X{medic.eventCode}&amp;gt; %msg %ex%n&lt;<span class="hl-tag">/Pattern</span>&gt;
&lt;<span class="hl-tag">/encoder</span>&gt;
&lt;<span class="hl-tag">/appender</span>&gt;
&lt;<span class="hl-tag">logger</span> <span class="hl-attribute">level</span>=<span class="hl-value">"INFO"</span> <span class="hl-attribute">additivity</span>=<span class="hl-value">"false"</span> <span class="hl-attribute">name</span>=<span class="hl-value">"org.eclipse.virgo.medic.eventlog.localized"</span>&gt;
&lt;<span class="hl-tag">appender-ref</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"EVENT_LOG_STDOUT"</span> /&gt;
&lt;<span class="hl-tag">appender-ref</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"EVENT_LOG_FILE"</span> /&gt;
&lt;<span class="hl-tag">/logger</span>&gt;
&lt;<span class="hl-tag">logger</span> <span class="hl-attribute">level</span>=<span class="hl-value">"INFO"</span> <span class="hl-attribute">additivity</span>=<span class="hl-value">"false"</span> <span class="hl-attribute">name</span>=<span class="hl-value">"org.eclipse.virgo.medic.eventlog.default"</span>&gt;
&lt;<span class="hl-tag">appender-ref</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"SIFTED_LOG_FILE"</span> /&gt;
&lt;<span class="hl-tag">appender-ref</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"LOG_FILE"</span> /&gt;
&lt;<span class="hl-tag">/logger</span>&gt;
&lt;<span class="hl-tag">root</span> <span class="hl-attribute">level</span>=<span class="hl-value">"INFO"</span>&gt;
&lt;<span class="hl-tag">appender-ref</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"SIFTED_LOG_FILE"</span> /&gt;
&lt;<span class="hl-tag">appender-ref</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"LOG_FILE"</span> /&gt;
&lt;<span class="hl-tag">/root</span>&gt;
&lt;<span class="hl-tag">/configuration</span>&gt;</pre><p>Logback allows Virgo to use logger, appender, and encoder (layout) objects to log messages according to message type and level and to format these messages and define where they are written. The default <code class="literal">serviceability.xml</code> file shown above includes four appenders and three loggers (two user and one root.)</p><p>The main information to get from this file is that Virgo writes log messages to four different locations that map to the four appenders:</p><div class="itemizedlist"><ul type="disc"><li><p>The <code class="literal">jmxConfigurator</code> provides a possibility to configure logback via JMX. For more information see <a class="ulink" href="http://logback.qos.ch/manual/jmxConfig.html" target="_top">JMX Configurator</a> documentation.</p></li><li><p>The <code class="literal">contextListener</code> propagates the changes made to the levels of logback loggers to Java Util Logging (JUL). For more information see <a class="ulink" href="http://logback.qos.ch/manual/configuration.html#LevelChangePropagator" target="_top">LevelChangePropagator</a> documentation.</p></li><li><p>The <code class="literal">SIFTED_LOG_FILE</code> appender logs both global and application-specific messages to the <code class="literal">$SERVER_HOME/serviceability/logs/</code><span class="emphasis"><em><code class="literal">applicationName</code></em></span><code class="literal">/log.log</code> file, where <span class="emphasis"><em><code class="literal">applicationName</code></em></span> refers to the name of the application. The log messages for Virgo itself are logged to the <code class="literal">$SERVER_HOME/serviceability/logs/virgo-server/log.log</code> file. Because this appender creates different log files for each application, it is called a <span class="emphasis"><em>sifting appender</em></span>. </p><p>
The default behaviour of these trace files is that, once <code class="literal">log.log</code> reaches a 10Mb limit, it rolls into a series of files named
<code class="literal">log_</code><span class="emphasis"><em>i</em></span><code class="literal">.log</code> where <span class="emphasis"><em>i</em></span> ranges from 1 to 4, and logging continues in
a new <code class="literal">log.log</code> file. This is called its <span class="emphasis"><em>rolling policy</em></span>.
</p><p>The <code class="literal">&lt;Pattern&gt;</code> element defines the format of each log message; messages include the timestamp, the thread that generated the log message, the context-specific event code, and a stack trace of the exception, if any. For example:</p><p><code class="literal">[2008-05-15 09:09:46.940] server-dm-2 org.apache.coyote.http11.Http11Protocol I Initializing Coyote HTTP/1.1 on http-48080</code></p></li><li><p>The <code class="literal">LOG_FILE</code> appender is very similar to the first one, but it logs <span class="emphasis"><em>all</em></span> log messages to the <code class="literal">$SERVER_HOME/serviceability/log/log.log</code> file rather than sifting application-specific messages to their own log file. The rolling policy and message format for this appender is similar to that of the <code class="literal">SIFTED_LOG_FILE</code> appender.</p></li><li><p>The <code class="literal">EVENT_LOG_STDOUT</code> appender does not log messages to a file, but rather to the console window from which you started Virgo. For example:</p><p><code class="literal">[2010-10-25 16:20:49.367] Thread-3 &lt;WE0000I&gt; Starting web bundle 'org.eclipse.virgo.apps.admin.web' version '2.1.0.RELEASE' with context path '/admin'.</code></p></li><li><p>The <code class="literal">EVENT_LOG_FILE</code> appender logs only important events to the <code class="literal">$SERVER_HOME/serviceability/eventlogs/eventlog.log</code> file, and thus the volume of information is much lower than with the first two appenders. The rolling policy for the event log is the same as with the first two appenders, but the format of the messages is similar to that of the <code class="literal">EVENT_LOG_STDOUT</code> appender. </p></li></ul></div><p>The loggers and root logger specify the level of log that is written for each of the referenced appenders.</p><p>Typically, the default logging configuration as specified by the <code class="literal">serviceability.xml</code> file is adequate for all Virgo environments. However, if you want to customize logging further, you can edit this file as well as the <code class="literal">org.eclipse.virgo.medic.properties</code>. See the <a class="ulink" href="http://logback.qos.ch/manual/index.html" target="_top">logback documentation</a> for detailed information about the architecture and the configuration of Logback.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-provisioning-repository"></a>13.4&nbsp;Configuring the Local Provisioning Repository</h2></div></div></div><p>
You configure the locations that Virgo includes in its provisioning repository
by editing the <code class="literal">org.eclipse.virgo.repository.properties</code> file in the <code class="literal">$SERVER_HOME/configuration</code> directory.
</p><p>When you specify a property in the file, use the format <code class="literal">repository-name.property=value</code>, where:
</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">repository-name</code> refers to the name of the local repository.</p></li><li><p><code class="literal">property</code> refers to the name of a particular property.</p></li><li><p><code class="literal">value</code> refers to the value of the property.</p></li></ul></div><p>
</p><p>For example, <code class="literal">ext.type=external</code> specifies that the <code class="literal">type</code> property of the repository
with name <code class="literal">ext</code> is <code class="literal">external</code>.
</p><p>
The <code class="literal">chain</code> property specifies the order in which Virgo searches the individual repositories
when it looks for dependencies.
The <code class="literal">chain</code> property uses the names of the individual repositories as specified in the individual repository properties;
for example, in the property <code class="literal">ext.type=external</code>, the name of the repository is <code class="literal">ext</code>.
</p><p>
The default repository configuration for a newly installed Virgo instance is as follows:
</p><pre class="programlisting">ext.type=external
ext.searchPattern=repository/ext/{artifact}
usr.type=watched
usr.watchDirectory=repository/usr
chain=ext,usr</pre><p>
</p><p>
The default configuration shown above has two searchpaths corresponding to the two default sub-directories of the <code class="literal">$SERVER_HOME/repository</code> directory created when you first install Virgo: <code class="literal">ext</code> and <code class="literal">usr</code>. Virgo searches each of these individual repositories when locating entries for inclusion in the repository. </p><p>
The <code class="literal">chain</code> property shows the order in which Virgo searches the individual repositories: first <code class="literal">ext</code> and then <code class="literal">usr</code>.
</p><p>
The following table lists all the available properties that you can use to configure an individual repository.
Individual repositories as well as the repository search chain are configured in the file
<code class="literal">$SERVER_HOME/configuration/org.eclipse.virgo.repository.properties</code>.
</p><div class="table"><a name="repository-options-table"></a><p class="title"><b>Table&nbsp;13.5.&nbsp;Repository Properties</b></p><div class="table-contents"><table summary="Repository Properties" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
Property
</th><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
Description
</th><th style="border-bottom: 1.0pt solid ; ">
Default Value
</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
<span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.type</code>
</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
<p>
Specifies the type of path. You can set this property to one of the following three valid values:
</p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">external</code>: Specifies that this path points to a number of directories that satisfy a given search pattern
and are local to the current Virgo instance.
Use the <code class="literal">searchPattern</code> property to specify the directory search pattern.
</p></li><li><p>
<code class="literal">watched</code>: Specifies that this path points to a single directory, local to the current Virgo instance.
Virgo regularly scans watched repositories so it automatically picks up any changes to the artifacts in the directory at runtime.
Virgo also scans its local watched repositories when deploying any artifact.
Use the <code class="literal">watchDirectory</code> property to specify the watched directory
and the <code class="literal">watchInterval</code> property to specify how often Virgo checks the directory.
</p></li><li><p>
<code class="literal">remote</code>: Specifies that the path points to a remotely-hosted repository,
hosted by a remote instance of Virgo Server for Apache Tomcat.
Use the <code class="literal">uri</code> property to specify the full URI of the remote repository.
You can also specify the optional <code class="literal">indexRefreshInterval</code> property.
</p></li></ul></div><p>
</p>
<p>
See <a class="link" href="#configuring-repository-watched-versus-external" title="Should I Configure a Watched or External Repository?">Watched or External Repository?</a>
for additional information about when to configure watched or external repositories for your particular environment.
</p>
</td><td style="border-bottom: 1.0pt solid ; ">
<span class="emphasis"><em>no default</em></span>
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
<span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.searchPattern</code>
</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
<p>
Specifies the pattern that an external repository uses when deciding which local directories it should search
when identifying artifacts. Use this property together with <span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.type=external</code>.
See <a class="link" href="#configuring-provisioning-repository-search-paths" title="Search Paths: Additional Information">Search Paths: Additional Information</a>
for detailed information about specifying a search pattern.
</p>
</td><td style="border-bottom: 1.0pt solid ; ">
<span class="emphasis"><em>no default</em></span>
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
<span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.watchDirectory</code>
</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
<p>
Specifies the single directory of a watched repository.
You can specify either an absolute or relative pathname for the directory.
If you specify a relative pathname, it is relative to the root of the Virgo installation (<code class="literal">$SERVER_HOME</code>).
Use this property together with <span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.type=watched</code>.
</p>
</td><td style="border-bottom: 1.0pt solid ; ">
<span class="emphasis"><em>no default</em></span>
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
<span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.watchInterval</code>
</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
<p>
Specifies the interval in seconds between checks of a watched directory by a watched repository.
Use this property together with <span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.type=watched</code>.
</p>
</td><td style="border-bottom: 1.0pt solid ; ">
<code class="literal">5</code>
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
<span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.uri</code>
</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
<p>
Specifies the URI of the hosted repository to which a remote repository connects.
The value of this property takes the following format:
</p>
<p> <code class="literal">http://</code><span class="emphasis"><em><code class="literal">host</code></em></span><code class="literal">:</code><span class="emphasis"><em><code class="literal">port</code></em></span><code class="literal">/org.eclipse.virgo.apps.repository/</code><span class="emphasis"><em><code class="literal">remote-repository-name</code></em></span>
</p>
<p>
where:
</p><div class="itemizedlist"><ul type="disc"><li><p>
<span class="emphasis"><em><code class="literal">host</code></em></span> refers to the computer on which the remote VTS
instance hosts the remote repository.
</p></li><li><p>
<span class="emphasis"><em><code class="literal">port</code></em></span> refers to a Tomcat listener port of the remote VTS
instance which hosts the remote repository.
</p></li><li><p>
<span class="emphasis"><em><code class="literal">remote-repository-name</code></em></span> refers to the name of the remote repository,
as specified in the <code class="literal">org.eclipse.virgo.apps.repository.properties</code> file of the remote VTS instance.
</p></li></ul></div><p>
</p>
<p>
Use this property together with <span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.type=remote</code>.
</p>
</td><td style="border-bottom: 1.0pt solid ; ">
<span class="emphasis"><em>no default</em></span>
</td></tr><tr><td style="border-right: 1.0pt solid ; ">
<span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.indexRefreshInterval</code>
</td><td style="border-right: 1.0pt solid ; ">
<p>
Specifies the interval in seconds between checks by a remote repository that
its local copy of the hosted repository index is up-to-date
(a remote repository acts as a proxy for a hosted repository and thus it holds a local copy of the hosted repository&#8217;s index).
</p>
<p>
Use this property together with <span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.type=remote</code>.
</p>
</td><td style="">
<code class="literal">5</code>
</td></tr></tbody></table></div></div><p><br class="table-break">
</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-repository-watched-versus-external"></a>Should I Configure a Watched or External Repository?</h3></div></div></div><p>The main difference between a watched and an external repository is that Virgo regularly scans watched directories
and automatically picks up any changed artifacts,
while Virgo scans external directories only at startup, and then only if there is no cached index available.
This means that Virgo always performs a scan of an external repository when you start the server
with the <code class="literal">-clean</code> (as this deletes the index) and only scans during a normal startup if the index isn&#8217;t there because,
for example, this is the first time you start the server.
</p><p>There is a performance cost associated with using a watched repository due to Virgo using resources
to scan the directory at the configured interval.
The cost is small if the watched repository contains just a few artifacts; however,
the performance cost increases as the number of artifacts increases.
Note that Virgo re-scans its local watched repositories when deploying any artifact, so the scanning interval
can be configured to be relatively long.
</p><p> For this reason, we recommend that you put most of your dependencies in external repositories,
even when in development mode.
If you make any changes to the artifacts in the external repositories,
remember to restart Virgo with the <code class="literal">-clean</code> option so that the server picks up any changes.
Use watched directories for artifacts that you are prototyping, actively updating, or when adding new dependencies
so that Virgo quickly and easily picks them up.
To increase performance even during development, however, you can use an external repository for most of your dependencies,
in particular the ones that are fairly static.
</p><p>In production environments, where dependencies should not change,
we recommend that you use <span class="emphasis"><em>only</em></span> external repositories.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-provisioning-repository-search-paths"></a>Search Paths: Additional Information</h3></div></div></div><p>
The <span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.searchPattern</code> and
<span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.watchDirectory</code> properties specify search paths
for external and watched repositories, respectively,
that define a physical location that Virgo searches when looking for a library or bundle dependency.
If a search path is relative, its location is relative to the root of the installation,
in other words, the <code class="literal">$SERVER_HOME</code> directory.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="configuring-provisioning-repository-search-paths-wildcards"></a>Using Wildcards</h4></div></div></div><p>
Search paths specified with the <span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.searchPattern</code> property
provide support for wildcards.
In the entries above, the path segments surrounded by curly braces,
for example <code class="literal">{bundle}</code> and <code class="literal">{library}</code>,
are wildcards entries for a directory with any name.
Allowing wildcards to be named in this way is intended to improve the readability of search path configuration.
</p><p>
In addition to supporting the above-described form of wildcards, Virgo also supports Ant-style paths,
that is <code class="literal">*</code> and <code class="literal">**</code> can be used to represent any directory and
any series of directories, respectively.
For example, <code class="literal">repository/usr/{bundle}</code> and <code class="literal">repository/usr/*</code>
are equivalent.
</p><p>
A common usage of the <code class="literal">**</code> wildcard is to allow dependencies stored in a directory structure of varying depth,
such as a local Maven repository, to be provisioned by the Virgo.
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-provisioning-repository-using-system-properties"></a>Using System Properties</h3></div></div></div><p>
You can use system properties when specifying the values of the <span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.searchPattern</code>,
<span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.watchDirectory</code>,
<span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.watchInterval</code>,
<span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.uri</code>,
and <span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.indexRefreshInterval</code>
properties.
You reference system properties as <code class="literal">${system.property.name}</code>;
for example, a search path of <code class="literal">${user.home}/repository/bundles</code> references the
<code class="literal">repository/bundles</code> directory in the user&#8217;s home directory.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-provisioning-repository-examples"></a>Example Repository Configurations</h3></div></div></div><p>
The following examples provide sample configuration that could be used for some common use cases.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="configuring-provisioning-repository-examples-ivy"></a>Add an Ivy cache repository</h4></div></div></div><p>The following example shows how to add an external repository whose location is actually an Ivy cache.</p><p><span class="emphasis"><em>Note that Ivy repositories can contain bundles which will conflict with the normal operation of Virgo, so care should
be exercised when adding such an external repository.</em></span></p><pre class="programlisting">ext.type=external
ext.searchPattern=repository/ext/{artifact}
usr.type=watched
usr.watchDirectory=repository/usr
ivy-repo.type=external
ivy-repo.searchPattern=${user.home}/.ivy2/cache/{org}/{name}/{version}/{bundle}.jar
chain=ext,usr,ivy-repo</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="configuring-provisioning-repository-examples-maven"></a>Add a Maven local repository</h4></div></div></div><p>The following example shows how to add an external repository whose location is actually a Maven repository.</p><p><span class="emphasis"><em>Note that Maven repositories can contain bundles which will conflict with the normal operation of Virgo, so care should
be exercised when adding such an external repository.</em></span></p><pre class="programlisting">ext.type=external
ext.searchPattern=repository/ext/{artifact}
usr.type=watched
usr.watchDirectory=repository/usr
maven-repo.type=external
maven-repo.searchPattern=${user.home}/.m2/repository/**/{bundle}.jar
chain=ext,usr,maven-repo</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="configuring-repository-examples-remote-watched"></a>Add remote and watched repositories</h4></div></div></div><p>The following example shows the default <code class="literal">org.eclipse.virgo.repository.properties</code> file
from a freshly-installed Virgo instance, but then updated to include new remote and watched repositories.
Both of these repositories are part of the repository chain.
</p><p>The remote repository is called <code class="literal">remote-repo</code>.
The URI of the hosted repository from which <code class="literal">remote-repo</code> gets its artifacts is
<code class="literal">http://my-host:8080/org.eclipse.virgo.apps.repository/my-hosted-repo</code>;
this means that there is a VTS instance running on host <code class="literal">my-host</code>
whose Tomcat server listens at the default port, <code class="literal">8080</code>,
and this server instance hosts a repository called <code class="literal">my-hosted-repo</code>,
configured in the <code class="literal">org.eclipse.virgo.apps.repository.properties</code> file of the remote server instance.
The remote repository checks for changes in the hosted repository every 30 seconds.
</p><p>The watched repository is called <code class="literal">watched-repo</code> and the directory that holds the artifacts
is <code class="literal">repository/watched</code>,
relative to the installation directory of the VTS instance.
The server checks for changes in this watched repository every 5 seconds.
</p><pre class="programlisting">ext.type=external
ext.searchPattern=repository/ext/{artifact}
usr.type=watched
usr.watchDirectory=repository/usr
remote-repo.type=remote
remote-repo.uri=http://my-host:8080/org.eclipse.virgo.apps.repository/my-hosted-repo
remote-repo.indexRefreshInterval=30
watched-repo.type=watched
watched-repo.watchedDirectory=repository/watched
watched-repo.watchedInterval=5
chain=ext,usr,remote-repo,watched-repo</pre></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-hosted-repo"></a>13.5&nbsp;Configuring a Hosted Repository</h2></div></div></div><p>You configure a VTS instance to host a repository
by editing the <code class="literal">$SERVER_HOME/configuration/org.eclipse.virgo.apps.repository.properties</code> file;
remote clients can then access the artifacts in this hosted repository and use them locally.
</p><p>When you specify a property in the file, use the format <code class="literal">repository-name.property=value</code>, where:
</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">repository-name</code> refers to the name of the hosted repository.</p></li><li><p><code class="literal">property</code> refers to the name of a particular property.</p></li><li><p><code class="literal">value</code> refers to the value of the property.</p></li></ul></div><p>
</p><p>For example, <code class="literal">my-hosted-repo.type=external</code> specifies that the <code class="literal">type</code> property
of the <code class="literal">my-hosted-repo</code> repository is <code class="literal">external</code>.
</p><p>The following table lists the properties that you can include in the <code class="literal">org.eclipse.virgo.apps.repository.properties</code> file.
</p><div class="table"><a name="hosted-repository-properties-table"></a><p class="title"><b>Table&nbsp;13.6.&nbsp;Hosted Repository Properties</b></p><div class="table-contents"><table summary="Hosted Repository Properties" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Property</th><th style="border-bottom: 1.0pt solid ; ">Description</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.type</code></td><td style="border-bottom: 1.0pt solid ; ">Specifies the type of path of the hosted repository.
All paths are local to the current VTS instance.
You can set this property to one of the following valid values:
<div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">external</code>: Specifies that this path points to a number of directories that satisfy a given search pattern.
Use the <code class="literal">searchPattern</code> property to specify the directory search pattern.
</p></li><li><p>
<code class="literal">watched</code>: Specifies that this path points to a single directory.
Virgo regularly scans watched repositories so it automatically picks up any changes to the artifacts in the directory at runtime.
Use the <code class="literal">watchDirectory</code> property to specify the actual watched directory and the <code class="literal">watchInterval</code> property
to specify how often VTS checks the directory.
</p></li></ul></div>
<p>See <a class="link" href="#configuring-repository-watched-versus-external" title="Should I Configure a Watched or External Repository?">Watched or External Repository?</a>
for additional information about when to configure watched or external repositories for your particular environment.
</p>
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.searchPattern</code></td><td style="border-bottom: 1.0pt solid ; "> <p>Specifies the pattern that an external hosted repository uses when deciding which
local directories it should search when identifying artifacts.
Use this property when <code class="literal">repository-name.type=external</code>.
See <a class="link" href="#configuring-provisioning-repository-search-paths" title="Search Paths: Additional Information">Search Paths: Additional Information</a>
for detailed information about specifying a search pattern.
</p> </td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.watchDirectory</code></td><td style="border-bottom: 1.0pt solid ; "> <p>Specifies the single directory of a watched hosted repository.
You can specify either an absolute or relative pathname for the directory.
If you specify a relative pathname, it is relative to the root of the VTS installation (<code class="literal">$SERVER_HOME</code>).
Use this property when <code class="literal">repository-name.type=watched</code>.
</p></td></tr><tr><td style="border-right: 1.0pt solid ; "><span class="emphasis"><em><code class="literal">repository-name</code></em></span><code class="literal">.watchInterval</code></td><td style=""> <p>Specifies the interval in seconds between checks of a watched directory by a watched hosted repository.
This property is optional. Use this property when <code class="literal">repository-name.type=watched</code>.
</p> </td></tr></tbody></table></div></div><br class="table-break"><p>The following sample shows a <code class="literal">org.eclipse.virgo.apps.repository.properties</code> file with a single external repository
called <code class="literal">my-hosted-repo</code> with search pattern <code class="literal">$SERVER_HOME/repository/hosted/*</code>.
</p><pre class="programlisting">my-hosted-repo.type=external
my-hosted-repo.searchPattern=repository/hosted/*</pre><p>
</p><p>See <a class="link" href="#configuring-repository-examples-remote-watched" title="Add remote and watched repositories">Example of watched and remote repositories</a>
for details on how a local repository can remotely access the artifacts in this hosted repository.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-kernel"></a>13.6&nbsp;Configuring the Kernel and User Region</h2></div></div></div><p>This section provides information about configuring the Virgo kernel and the User Region.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-kernel-properties"></a>Configuring the Kernel</h3></div></div></div><p>To change any of the kernel properties, provide the new value to the startup script. The following table describes all properties.</p><div class="table"><a name="configuring-kernel-table"></a><p class="title"><b>Table&nbsp;13.7.&nbsp;Kernel Configuration Properties</b></p><div class="table-contents"><table summary="Kernel Configuration Properties" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
Property (prefixed by <code class="literal">org.eclipse.virgo</code>)
</th><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
Description
</th><th style="border-bottom: 1.0pt solid ; ">
Default Value
</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
<code class="literal">.kernel.home</code>
</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
Specifies the location of the Virgo Kernel.
</td><td style="border-bottom: 1.0pt solid ; ">
<code class="literal">$SERVER_HOME</code>
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
<code class="literal">.kernel.config</code>
</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
Specifies the location of the Virgo Kernel and User Region <a class="link" href="#configuring-kernel-files" title="Configuration Files">configuration files</a>.
The location of the configuration files can also be specified using
<a class="link" href="#starting-stopping-configuration-directory" title="7.5&nbsp;Starting with a Custom Configuration Directory"><code class="literal">-configDir</code> startup parameter</a>.
</td><td style="border-bottom: 1.0pt solid ; ">
<code class="literal">$SERVER_HOME/configuration</code>
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
<code class="literal">.kernel.domain</code>
</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
Specifies the <a class="ulink" href="http://download.oracle.com/javase/6/docs/api/javax/management/ObjectName.html" target="_top">JMX domain</a> that should be
used by the Virgo Kernel.
</td><td style="border-bottom: 1.0pt solid ; ">
<code class="literal">org.eclipse.virgo.kernel</code>
</td></tr><tr><td style="border-right: 1.0pt solid ; ">
<code class="literal">.kernel.startup.wait.limit</code>
</td><td style="border-right: 1.0pt solid ; ">
Specifies the amount of time, in seconds, after which various operations time out out while trying to start the kernel.
See <a class="link" href="#configuring-framework-properties" title="Configuring OSGi Framework Properties">Configuring OSGi Framework Properties</a> for the recommended way
to configure this parameter.
</td><td style=""><code class="literal">180</code>
</td></tr></tbody></table></div></div><br class="table-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-kernel-files"></a>Configuration Files</h3></div></div></div><p>The configuration of the Virgo Kernel and User Region by default is located in the <code class="literal">$SERVER_HOME/configuration</code> directory:</p><div class="table"><a name="configuring-kernel-files-table"></a><p class="title"><b>Table&nbsp;13.8.&nbsp;Kernel Configuration Files </b></p><div class="table-contents"><table summary="Kernel Configuration Files " style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Property File</th><th style="border-bottom: 1.0pt solid ; ">Description</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">org.eclipse.virgo.kernel.properties</code></td><td style="border-bottom: 1.0pt solid ; ">Configures <a class="link" href="#configuring-deployment" title="Configuring Deployment">deployment</a>. </td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">org.eclipse.virgo.kernel.userregion.properties</code></td><td style="border-bottom: 1.0pt solid ; ">Configures the <a class="link" href="#configuring-user-region" title="Configuring the User Region">User Region</a> of Virgo.</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">org.eclipse.virgo.kernel.users.properties</code></td><td style="border-bottom: 1.0pt solid ; ">Configures the <a class="link" href="#configuring-authentication" title="Configuring Authentication">users that are allowed to access</a> the Admin Console, and roles to which they map. </td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">org.eclipse.virgo.kernel.jmxremote.access.properties</code></td><td style="border-bottom: 1.0pt solid ; ">Configures the <a class="link" href="#configuring-authentication" title="Configuring Authentication">permissions for users</a> that are allowed to access the Admin Console. </td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">org.eclipse.virgo.kernel.authentication.config</code></td><td style="border-bottom: 1.0pt solid ; ">Configures the <a class="link" href="#configuring-authentication" title="Configuring Authentication">Java Authentication and Authorization Service (JAAS)</a> for the Tomcat server users.</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">osgi.console.ssh.properties</code></td><td style="border-bottom: 1.0pt solid ; ">Configures the kernel SSH console. See <a class="xref" href="#admin-shell-enable" title="8.1&nbsp;Enabling the Equinox Console">Section&nbsp;8.1, &#8220;Enabling the Equinox Console&#8221;</a>.</td></tr><tr><td style="border-right: 1.0pt solid ; "><code class="literal">osgi.console.telnet.properties</code></td><td style="">Configures the kernel telnet console. See <a class="xref" href="#admin-shell-enable" title="8.1&nbsp;Enabling the Equinox Console">Section&nbsp;8.1, &#8220;Enabling the Equinox Console&#8221;</a>.</td></tr></tbody></table></div></div><br class="table-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-deployment"></a>Configuring Deployment</h3></div></div></div><p>
You can configure various properties of deployment: the pickup directory into which you copy applications for hot-deployment, the deployment timeout,
and whether or not bundles are unpacked during deployment.
</p><p>To change any of these properties, edit the <code class="literal">deployer.XXX</code> properties of the <code class="literal">$SERVER_HOME/configuration/org.eclipse.virgo.kernel.properties</code> file. The following table describes these properties. </p><div class="table"><a name="configuring-deployment-table"></a><p class="title"><b>Table&nbsp;13.9.&nbsp;Deployment Configuration Properties</b></p><div class="table-contents"><table summary="Deployment Configuration Properties" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
Property
</th><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
Description
</th><th style="border-bottom: 1.0pt solid ; ">
Default Value
</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
<code class="literal">deployer.pickupDirectory</code>
</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
Specifies the absolute or relative path to the pickup directory to which you copy applications for hot-deployment.
Relative paths are relative to <code class="literal">$SERVER_HOME</code>.
</td><td style="border-bottom: 1.0pt solid ; ">
<code class="literal">./pickup</code>
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
<code class="literal">deployer.timeout</code>
</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
Specifies the amount of time, in seconds, after which Virgo times out while trying to deploy an artifact.
If you want to disable deployment timeout, specify <code class="literal">0</code>.
</td><td style="border-bottom: 1.0pt solid ; ">
<code class="literal">300</code>
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
<code class="literal">deployer.unpackBundles</code>
</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
Determines whether or not bundles (with file extension <code class="literal">.jar</code> or <code class="literal">.war</code>) are unpacked
during deployment. The value must be either <code class="literal">true</code> or <code class="literal">false</code>.
<p>
If you want to deploy bundles packed, specify <code class="literal">false</code>.
This option can help alleviate a known issue with <a class="link" href="#long-work-paths" title="B.6&nbsp;Long Work Directory Paths under Windows">long work directory paths under Windows</a>.
</p>
<p>
Note that web applications may behave differently depending on whether they are deployed packed or unpacked.
Certain servlet API methods return <code class="literal">null</code> when a web application is deployed packed.
</p>
</td><td style="border-bottom: 1.0pt solid ; ">
<code class="literal">true</code>
</td></tr><tr><td style="border-right: 1.0pt solid ; ">
<code class="literal">WABHeaders</code>
</td><td style="border-right: 1.0pt solid ; ">
<p>
This kernel property is only relevant for Virgo Nano Web. For the corresponding property in Virgo Server for Apache Tomcat, see <a class="link" href="#configuring-web" title="13.8&nbsp;Configuring the Web Integration Layer">Configuring the Web Integration Layer</a>.
</p>
<p>
Specifies how Web Application Bundle manifest headers are processed.
See "Web Application Manifest Processing" in the
<a class="ulink" href="../../virgo-programmer-guide/html/index.html" target="_top">Programmer Guide</a> for details.
</p>
<p>
A value of <code class="literal">strict</code> causes Virgo Nano Web to interpret certain headers in strict compliance with
the OSGi Web Applications specification if they are not specified.
</p>
<p>
A value of <code class="literal">defaulted</code> causes Virgo Nano Web to set certain headers to default values if they are not specified.
<span class="emphasis"><em>This value is provided as a migration aid and may not be supported in future releases.</em></span>
</p>
</td><td style="">
<code class="literal">strict</code>
</td></tr></tbody></table></div></div><br class="table-break"><p>The following listing displays the default configuration distributed with Virgo; only relevant sections of the <code class="literal">org.eclipse.virgo.kernel.properties</code> file are shown. </p><pre class="programlisting">deployer.timeout=300
deployer.pickupDirectory=pickup</pre><p>So the default deployment timeout is 300 seconds and the default pickup directory is <code class="literal">$SERVER_HOME/pickup</code>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-user-region"></a>Configuring the User Region</h3></div></div></div><p>
The User Region is the subsystem of Virgo that
supports deployed applications, both your own user applications and
those of the server itself, such as the Admin Console. The User Region
is deliberately isolated from the kernel, which protects the kernel from interference by applications.
</p><p>
You configure the User Region by updating properties in the
<code class="literal">$SERVER_HOME/configuration/org.eclipse.virgo.kernel.userregion.properties</code>
file; these properties are described in the following table.
</p><p>
<span class="bold"><strong>WARNING:</strong></span>
We strongly recommend that you update only the
<code class="literal">initialArtifacts</code>
property; updating other properties could cause
Virgo to fail. These properties are documented for your
information.
</p><div class="table"><a name="configuring-user-region-table"></a><p class="title"><b>Table&nbsp;13.10.&nbsp;User Region Configuration Properties</b></p><div class="table-contents"><table summary="User Region Configuration Properties" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Property</th><th style="border-bottom: 1.0pt solid ; ">Description</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">baseBundles</code></td><td style="border-bottom: 1.0pt solid ; ">Specifies the hard-coded list of bundles that Virgo installs directly into the User Region.
Virgo does not perform any automatic dependency satisfaction for these bundles; in other words, you only get the bundles
in the list and nothing more. </td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">bundleImports</code></td><td style="border-bottom: 1.0pt solid ; ">
<p>
Specifies the bundles in the kernel that Virgo imports into the User Region so that they are visible to bundles in the User Region.
This property supports an optional <code class="literal">bundle-version</code> attribute which specifies a version range.
By default only the system bundle is imported.
</p>
<p>
Note that packages exported by these bundles are <span class="emphasis"><em>not</em></span> automatically made available in the User Region: these must be specified using the
<code class="literal">packageImports</code> property.
</p>
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">packageImports</code></td><td style="border-bottom: 1.0pt solid ; ">
<p>
Specifies the packages in the kernel that Virgo imports into the User Region so that they are in turn available to be
imported by bundles in the User Region.
This property supports a <code class="literal">.*</code> wildcard which is expanded based on the packages available in the kernel
when the User Region is created.
For example, <code class="literal">org.eclipse.virgo.util.*</code> will import all packages that start with
<code class="literal">org.eclipse.virgo.util.</code> (but <span class="emphasis"><em>not</em></span> the package <code class="literal">org.eclipse.virgo.util</code>
which would need to be specified separately to be imported).
</p>
<p>
The property also supports matching attributes such as <code class="literal">version</code>, <code class="literal">bundle-symbolic-name</code>,
<code class="literal">bundle-version</code>, and user-defined attributes. This can be used to import all the packages of a bundle imported using the
<code class="literal">bundleImports</code> property.
For example the following imports all the packages of the system bundle:
</p><pre class="programlisting">packageImports=*;bundle-symbolic-name="org.eclipse.osgi",\
...</pre><p>
Note that if a package is specified more than once in <code class="literal">packageImports</code>, the last occurrence is used and the earlier
occurrences are ignored.
For this reason, it is recommended that imports specifying matching attributes are placed earlier in the list than other imports so that
if an import is specified with and without matching attributes, the form without the matching attributes is used.
</p>
</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">serviceImports</code></td><td style="border-bottom: 1.0pt solid ; ">Specifies the services in the kernel that are imported into the User Region so they are available to bundles in the User Region. </td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">serviceExports</code></td><td style="border-bottom: 1.0pt solid ; ">Specifies the services in the User Region that are exported to the kernel so they are available to bundles in the kernel. </td></tr><tr><td style="border-right: 1.0pt solid ; "><code class="literal">initialArtifacts</code></td><td style="">
<p>
Specifies the artifacts that Virgo deploys into the User Region when the server starts.
Virgo performs dependency satisfaction when it deploys these artifacts.
This means that you only need to list the top-level artifacts that you care about; Virgo automatically installs,
from the repository, any other artifacts upon which they depend.
</p>
<p>
The artifacts are specified as a comma separated list of URI strings of the form:
</p><pre class="programlisting">repository:type/name[/version]</pre><p>
where <code class="literal">type</code> is the artifact type (e.g. "plan", "par", "bundle",
"configuration"), <code class="literal">name</code> is the (symbolic) name of the artifact, and, optionally,
<code class="literal">version</code> is the version of the artifact.
If <code class="literal">version</code> is omitted and there is at least one artifact in the repository with the given type and name, then the
artifact with the highest version is selected.
So, for example, the following entries are valid:
</p><pre class="programlisting">initialArtifacts=...,\
repository:plan/APlan,\
repository:bundle/ABundle/1.0</pre><p>
</p>
</td></tr></tbody></table></div></div><br class="table-break"><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="configuring-user-region-consoles"></a>Configurating User Region Consoles</h4></div></div></div><p>The configuration of the User Region consoles is located by default in the <code class="literal">$SERVER_HOME/repository/ext</code> directory:</p><div class="table"><a name="configuring-user-region-consoles-table"></a><p class="title"><b>Table&nbsp;13.11.&nbsp;User Region Console Configuration Files </b></p><div class="table-contents"><table summary="User Region Console Configuration Files " style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Property File</th><th style="border-bottom: 1.0pt solid ; ">Description</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">osgi.console.ssh.properties</code></td><td style="border-bottom: 1.0pt solid ; ">Configures the User Region SSH console. See <a class="xref" href="#admin-shell-enable" title="8.1&nbsp;Enabling the Equinox Console">Section&nbsp;8.1, &#8220;Enabling the Equinox Console&#8221;</a>.</td></tr><tr><td style="border-right: 1.0pt solid ; "><code class="literal">osgi.console.telnet.properties</code></td><td style="">Configures the User Region telnet console. See <a class="xref" href="#admin-shell-enable" title="8.1&nbsp;Enabling the Equinox Console">Section&nbsp;8.1, &#8220;Enabling the Equinox Console&#8221;</a>.</td></tr></tbody></table></div></div><br class="table-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-authentication"></a>Configuring Authentication</h3></div></div></div><p>
Virgo uses the
<a class="ulink" href="http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html" target="_top">Java Authentication and Authorization Service (JAAS)</a>
framework to authenticate the administration user that connects to Web
Servers using the Admin Console. This section describes
how the authentication mechanism is configured by default, and the
files that you need to update if you want to change the administration
user, change their password, and so on.
</p><p>The <code class="literal">$SERVER_HOME/configuration/org.eclipse.virgo.kernel.authentication.config</code> file configures the underlying authentication technology for Virgo. The short file consists of the following entries:</p><pre class="programlisting">virgo-kernel {
org.eclipse.virgo.kernel.authentication.KernelLoginModule REQUIRED;
};
equinox_console {
org.eclipse.virgo.kernel.authentication.KernelLoginModule REQUIRED;
};</pre><p>The entry named <code class="literal">virgo-kernel</code> corresponds to the <code class="literal">&lt;Realm&gt;</code> element in the <code class="literal">$SERVER_HOME/configuration/tomcat-server.xml</code> file that configures the JAAS authentication mechanism for the <code class="literal">Catalina</code> service of the <a class="link" href="#configuring-tomcat" title="13.7&nbsp;Configuring the Embedded Tomcat Servlet Container">Tomcat servlet container</a>. The <code class="literal">virgo-kernel</code> entry specifies that the JAAS LoginModule that Virgo uses to authenticate users is <code class="literal">org.eclipse.virgo.kernel.authentication.KernelLoginModule</code> and that this <code class="literal">KernelLoginModule</code> is required to "succeed" in order for authentication to be considered successful. The <code class="literal">KernelLoginModule</code> succeeds only if the name and password supplied by the user are the ones it expects. The default administration username/password pair for VTS is <code class="literal">admin/springsource</code>. </p><p>
The entry named <code class="literal">equinox_console</code> controls ssh authentication for the Virgo shell. It also uses the <code class="literal">KernelLoginModule</code>.
</p><p>You configure the administration user in the <code class="literal">org.eclipse.virgo.kernel.users.properties</code> file. The default file for a freshly installed Virgo is as follows:</p><pre class="programlisting">##################
# User definitions
##################
user.admin=springsource
##################
# Role definitions
##################
role.admin=admin</pre><p>
The administration user that connect to the Admin Console must have the
<code class="literal">admin</code>
role. The preceding file shows how, by default, the
<code class="literal">admin</code>
role is assigned the
<code class="literal">admin</code>
user with password
<code class="literal">springsource</code>.
</p><p>If you want to change the administration user, update the <code class="literal">org.eclipse.virgo.kernel.users.properties</code> file. For example, if you want the <code class="literal">juliet</code> user, with password <code class="literal">supersecret</code>, to be the new adminstration user, update the file as shown:</p><pre class="programlisting">##################
# User definitions
##################
user.juliet=supersecret
##################
# Role definitions
##################
role.admin=juliet</pre><p>Be sure to restart Virgo after you make this change for it to take effect.</p><p>The final file involved in Virgo authentication is <code class="literal">$SERVER_HOME/configuration/org.eclipse.virgo.kernel.jmxremote.access.properties</code>. This file specifies the JMX access privileges that the administration user has; by default they are read and write, as shown in the following listing:</p><pre class="programlisting">admin=readwrite</pre><p>
The only other value you can enter is
<code class="literal">readonly</code>, which means that the adminstration user would only be able to <span class="emphasis"><em>view</em></span>
information using the Admin Console.
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-tomcat"></a>13.7&nbsp;Configuring the Embedded Tomcat Servlet Container</h2></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">Virgo Nano uses the default Gemini Web configuration. The details described below may still apply.</td></tr></table></div><p>
Virgo
embeds an OSGi-enhanced version of the <a class="ulink" href="http://tomcat.apache.org/" target="_top">Tomcat Servlet Container</a>
in order to provide support for deploying Java EE WARs and OSGi <span class="emphasis"><em>Web Application Bundles</em></span>.
You configure the embedded Servlet container using the standard Apache Tomcat configuration. The main difference is that the configuration file is called <code class="filename">tomcat-server.xml</code> rather than <code class="literal">server.xml</code>. As with the other Virgo configuration files, the <code class="literal">tomcat-server.xml</code> file is located in the <code class="literal">$SERVER_HOME/configuration</code> directory.
Another difference is that not all standard Apache Tomcat configuration is supported in Virgo Server for Apache Tomcat: the restrictions are described in the
remainder of this section.
</p><p>Here's an extract of the default configuration distributed with the VTS.
</p><pre class="programlisting">&lt;<span class="hl-tag">?xml version='1.0' encoding='utf-8'?</span>&gt;
&lt;<span class="hl-tag">Server</span> <span class="hl-attribute">port</span>=<span class="hl-value">"8005"</span> <span class="hl-attribute">shutdown</span>=<span class="hl-value">"SHUTDOWN"</span>&gt;
&lt;<span class="hl-tag">Listener</span> <span class="hl-attribute">className</span>=<span class="hl-value">"org.apache.catalina.core.AprLifecycleListener"</span> <span class="hl-attribute">SSLEngine</span>=<span class="hl-value">"on"</span> /&gt;
&lt;<span class="hl-tag">Listener</span> <span class="hl-attribute">className</span>=<span class="hl-value">"org.apache.catalina.core.JasperListener"</span> /&gt;
&lt;<span class="hl-tag">Listener</span> <span class="hl-attribute">className</span>=<span class="hl-value">"org.apache.catalina.mbeans.GlobalResourcesLifecycleListener"</span> /&gt;
&lt;<span class="hl-tag">Listener</span> <span class="hl-attribute">className</span>=<span class="hl-value">"org.eclipse.virgo.web.tomcat.ServerLifecycleLoggingListener"</span>/&gt;
&lt;<span class="hl-tag">Service</span> <span class="hl-attribute">name</span>=<span class="hl-value">"Catalina"</span>&gt;
&lt;<span class="hl-tag">Connector</span> <span class="hl-attribute">port</span>=<span class="hl-value">"8080"</span> <span class="hl-attribute">protocol</span>=<span class="hl-value">"HTTP/1.1"</span>
<span class="hl-attribute">connectionTimeout</span>=<span class="hl-value">"20000"</span>
<span class="hl-attribute">redirectPort</span>=<span class="hl-value">"8443"</span> /&gt;
&lt;<span class="hl-tag">Connector</span> <span class="hl-attribute">port</span>=<span class="hl-value">"8443"</span> <span class="hl-attribute">protocol</span>=<span class="hl-value">"HTTP/1.1"</span> <span class="hl-attribute">SSLEnabled</span>=<span class="hl-value">"true"</span>
<span class="hl-attribute">maxThreads</span>=<span class="hl-value">"150"</span> <span class="hl-attribute">scheme</span>=<span class="hl-value">"https"</span> <span class="hl-attribute">secure</span>=<span class="hl-value">"true"</span>
<span class="hl-attribute">clientAuth</span>=<span class="hl-value">"false"</span> <span class="hl-attribute">sslProtocol</span>=<span class="hl-value">"TLS"</span>
<span class="hl-attribute">keystoreFile</span>=<span class="hl-value">"configuration/keystore"</span>
<span class="hl-attribute">keystorePass</span>=<span class="hl-value">"changeit"</span>/&gt;
&lt;<span class="hl-tag">Connector</span> <span class="hl-attribute">port</span>=<span class="hl-value">"8009"</span> <span class="hl-attribute">protocol</span>=<span class="hl-value">"AJP/1.3"</span> <span class="hl-attribute">redirectPort</span>=<span class="hl-value">"8443"</span> /&gt;
&lt;<span class="hl-tag">Engine</span> <span class="hl-attribute">name</span>=<span class="hl-value">"Catalina"</span> <span class="hl-attribute">defaultHost</span>=<span class="hl-value">"localhost"</span>&gt;
&lt;<span class="hl-tag">Realm</span> <span class="hl-attribute">className</span>=<span class="hl-value">"org.apache.catalina.realm.JAASRealm"</span> <span class="hl-attribute">appName</span>=<span class="hl-value">"virgo-kernel"</span>
<span class="hl-attribute">userClassNames</span>=<span class="hl-value">"org.eclipse.virgo.kernel.authentication.User"</span>
<span class="hl-attribute">roleClassNames</span>=<span class="hl-value">"org.eclipse.virgo.kernel.authentication.Role"</span>/&gt;
&lt;<span class="hl-tag">Host</span> <span class="hl-attribute">name</span>=<span class="hl-value">"localhost"</span> <span class="hl-attribute">appBase</span>=<span class="hl-value">"webapps"</span>
<span class="hl-attribute">unpackWARs</span>=<span class="hl-value">"false"</span> <span class="hl-attribute">autoDeploy</span>=<span class="hl-value">"false"</span>
<span class="hl-attribute">deployOnStartup</span>=<span class="hl-value">"false"</span> <span class="hl-attribute">createDirs</span>=<span class="hl-value">"false"</span>&gt;
&lt;<span class="hl-tag">Valve</span> <span class="hl-attribute">className</span>=<span class="hl-value">"org.apache.catalina.valves.AccessLogValve"</span> <span class="hl-attribute">directory</span>=<span class="hl-value">"serviceability/logs/access"</span>
<span class="hl-attribute">prefix</span>=<span class="hl-value">"localhost_access_log."</span> <span class="hl-attribute">suffix</span>=<span class="hl-value">".txt"</span> <span class="hl-attribute">pattern</span>=<span class="hl-value">"common"</span> <span class="hl-attribute">resolveHosts</span>=<span class="hl-value">"false"</span>/&gt;
&lt;<span class="hl-tag">Valve</span> <span class="hl-attribute">className</span>=<span class="hl-value">"org.eclipse.virgo.web.tomcat.ApplicationNameTrackingValve"</span>/&gt;
&lt;<span class="hl-tag">/Host</span>&gt;
&lt;<span class="hl-tag">/Engine</span>&gt;
&lt;<span class="hl-tag">/Service</span>&gt;
&lt;<span class="hl-tag">/Server</span>&gt;</pre><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="overview-tomcat-servlet-container"></a>Description of the Default Apache Tomcat Configuration</h3></div></div></div><p>
The following bullets describe the main elements and attributes in the default <code class="literal">tomcat-server.xml</code> file; for details about updating this file to further configure the embedded Apache Tomcat server, see the <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/config/index.html" target="_top">Apache Tomcat Configuration Reference</a>.
</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip: Relative paths"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.gif"></td><th align="left">Relative paths</th></tr><tr><td align="left" valign="top"><p>If the configured path to a directory or file does not represent an absolute path, Virgo typically interprets it as a path relative to the <code class="filename">$SERVER_HOME</code> directory.</p></td></tr></table></div><div class="itemizedlist"><ul type="disc"><li><p>The root element of the <code class="literal">tomcat-server.xml</code> file is <code class="literal">&lt;Server&gt;</code>. The attributes of this element represent the characteristics of the entire embedded Tomcat servlet container. The <code class="literal">shutdown</code> attribute specifies the command string that the shutdown port number receives via a TCP/IP connection in order to shut down the servlet container. The <code class="literal">port</code> attribute specifies the TCP/IP port number that listens for a shutdown message.</p></li><li><p>The <code class="literal">&lt;Listener&gt;</code> XML elements specify the list of lifecycle listeners that monitor and manage the embedded Tomcat servlet container. Each listener class is a Java Management Extensions (JMX) MBean that listens to a specific component of the servlet container and has been programmed to do something at certain lifecycle events of the component, such as before starting up, after stopping, and so on.</p><p> The first four <code class="literal">&lt;Listener&gt;</code> elements configure standard Tomcat lifecycle listeners. The listener implemented by the <code class="literal">org.eclipse.virgo.web.tomcat.ServerLifecycleLoggingListener</code> class is specific to Virgo Server for Apache Tomcat and manages server lifecycle logging.
</p></li><li><p>The <code class="literal">&lt;Service&gt;</code> XML element groups together one or more connectors and a single engine. Connectors define a transport mechanism, such as HTTP, that clients use to to send and receive messages to and from the associated service. There are many transports that a client can use, which is why a <code class="literal">&lt;Service&gt;</code> element can have many <code class="literal">&lt;Connector&gt;</code> elements. The engine then defines how these requests and responses that the connector receives and sends are in turn handled by the servlet container; you can define only a single <code class="literal">&lt;Engine&gt;</code> element for any given <code class="literal">&lt;Service&gt;</code> element.</p><p> The sample <code class="literal">tomcat-server.xml</code> file above includes three <code class="literal">&lt;Connector&gt;</code> elements: one for the HTTP transport, one for the HTTPS transport, and one for the AJP transport. The file also includes a single <code class="literal">&lt;Engine&gt;</code> element, as required.
</p></li><li><p>The first connector listens for HTTP requests at the <code class="literal">8080</code> TCP/IP port. The connector, after accepting a connection from a client, waits for a maximum of 20000 milliseconds for a request URI; if it does not receive one from the client by then, the connector times out. If this connector receives a request from the client that requires the SSL transport, the servlet container automatically redirects the request to port <code class="literal">8443</code>. </p></li><li><p>The second connector is for HTTPS requests. The TCP/IP port that users specify as the secure connection port is <code class="literal">8443</code>. Be sure that you set the value of the <code class="literal">redirectPort</code> attribute of your non-SSL connectors to this value to ensure that users that require a secure connection are redirected to the secure port, even if they initially start at the non-secure port. The <code class="literal">SSLEnabled</code> attribute specifies that SSL is enabled for this connector. The <code class="literal">secure</code> attribute ensures that a call to <code class="literal">request.isSecure()</code> from the connecting client always returns <code class="literal">true</code>. The <code class="literal">scheme</code> attribute ensures that a call to <code class="literal">request.getScheme()</code> from the connecting client always returns <code class="literal">https</code> when clients use this connector. </p><p>The <code class="literal">maxThreads</code> attribute specifies that the servlet container creates a maximum of 150 request processing threads,
which determines the maximum number of simultaneous requests that can be handled.
The <code class="literal">clientAuth</code> attribute specifies that the servlet container does not require a certificate chain
unless the client requests a resource protected by a security constraint that uses CLIENT-CERT authentication.
</p><p>The <code class="literal">keystoreFile</code> attribute specifies the name of the file that contains the servlet container&#8217;s
private key and public certificate used in the SSL handshake, encryption, and decryption.
You use an alias and password to access this information.
In the example, this file is <code class="literal">$SERVER_HOME/configuration/keystore</code>.
The <code class="literal">keystorePass</code> attributes specify the password used to access the keystore.
</p></li><li><p>The third AJP Connector element represents a Connector component that communicates with a web connector via the AJP protocol.
</p></li><li><p>The engine has a logical name of <code class="literal">Catalina</code>;
this is the name used in all log and error messages so you can easily identify problems.
The value of the <code class="literal">defaultHost</code> attribute refers to the name of a <code class="literal">&lt;Host&gt;</code>
child element of <code class="literal">&lt;Engine&gt;</code>;
this host processes requests directed to host names on this servlet container.
</p></li><li><p>The <code class="literal">&lt;Realm&gt;</code> child element of <code class="literal">&lt;Engine&gt;</code> represents a database of
users, passwords, and mapped roles used for authentication in this service. Virgo Web Server uses an implementation of the Tomcat 6 Realm interface that authenticates users through the Java Authentication and Authorization Service (JAAS) framework which is provided as part of the standard J2SE API.</p><p>With the JAASRealm, you can combine practically any conceivable security realm with Tomcat's container managed authentication. For details, see <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/realm-howto.html" target="_top">Realm Configuration</a>.</p></li><li><p>The <code class="literal">&lt;Host&gt;</code> child element represents a virtual host,
which is an association of a network name for a server (such as <code class="literal">www.mycompany.com</code>) with the particular
server on which Catalina is running.
The servlet container unpacks Web applications into a directory hierarchy if they are deployed as WAR files.
</p><p>
Note that multiple <code class="literal">&lt;Host&gt;</code> elements are not supported in Virgo Server for Apache Tomcat.
</p></li><li><p>Finally, the <code class="literal">org.apache.catalina.valves.AccessLogValve</code> valve creates log files
in the same format as those created by standard web servers.
The servlet container creates the log files in the <code class="literal">$SERVER_HOME/serviceability/logs/access</code> directory.
The log files are prefixed with the string <code class="literal">localhost_access_log.</code>, have a suffix of <code class="literal">.txt</code>,
use a standard format for identifying what should be logged, and do not include DNS lookups of the IP address of the remote host.
</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-tomcat-connectors"></a>Connector Configuration</h3></div></div></div><p> The Virgo Server for Apache Tomcat supports the configuration of any connector supported by Apache Tomcat.
See the default configuration above for syntax examples, and for further details of the configuration properties
supported for various <code class="literal">&lt;Connector&gt;</code> implementations,
consult the official <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/config/http.html" target="_top">Tomcat HTTP Connector</a> documentation.
</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip: Configuring SSL for Tomcat"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.gif"></td><th align="left">Configuring SSL for Tomcat</th></tr><tr><td align="left" valign="top"><p> The Virgo Server for Apache Tomcat distribution includes a preconfigured <code class="filename">$SERVER_HOME/configuration/keystore</code>
file that contains a single self-signed SSL Certificate.
The password for this <code class="filename">keystore</code> file is <code class="literal">changeit</code>.
This <code class="filename">keystore</code> file is intended for testing purposes only.
For detailed instructions on how to configure Tomcat&#8217;s SSL support,
consult the official <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html" target="_top">Tomcat SSL Configuration HOW-TO</a>.
</p></td></tr></table></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-tomcat-clustering"></a>Cluster Configuration</h3></div></div></div><p>
Virgo Server for Apache Tomcat supports standard Apache Tomcat cluster configuration.
By default, clustering of the embedded servlet container is disabled,
and the default configuration does not include any clustering information.
See <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/cluster-howto.html" target="_top">Tomcat Clustering/Session Replication HOW-TO</a>
for detailed information about enabling and configuring clustering.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-default-web-xml"></a>Default web.xml Configuration</h3></div></div></div><p>
Java Servlet specification enables web applications to provide deployment descriptor (<code class="literal">web.xml</code>) in the <code class="literal">WEB-INF</code> directory.
Apache Tomcat introduces a default <code class="literal">web.xml</code> which is similar to web application's <code class="literal">web.xml</code>, but provides configurations that are applied to all web applications.
When deploying a web application, Apache Tomcat uses the default <code class="literal">web.xml</code> file as a base configuration.
If the web application provides its own configurations via <code class="literal">web.xml</code> (the one located in the web application's <code class="literal">WEB-INF</code>) or annotations, they overwrite the default ones.
In Virgo Server for Apache Tomcat you can also provide default configurations for all web applications.
If you want to change/extend the default configurations, you can provide the default <code class="literal">web.xml</code> file located in the <code class="literal">VTS_HOME/configuration</code> directory.
</p><p>
</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.gif"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top">Be careful when changing/extending the default <code class="literal">web.xml</code> as this will affect all web applications.</td></tr></table></div><p>
</p><p>
Here's an extract of the default configuration distributed with the VTS.
</p><pre class="programlisting">&lt;<span class="hl-tag">?xml version="1.0" encoding="ISO-8859-1"?</span>&gt;
&lt;<span class="hl-tag">web-app</span> <span class="hl-attribute">xmlns</span>=<span class="hl-value">"http://java.sun.com/xml/ns/javaee"</span>
<span class="hl-attribute">xmlns:xsi</span>=<span class="hl-value">"http://www.w3.org/2001/XMLSchema-instance"</span>
<span class="hl-attribute">xsi:schemaLocation</span>=<span class="hl-value">"http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"</span>
<span class="hl-attribute">version</span>=<span class="hl-value">"3.0"</span>&gt;
&lt;<span class="hl-tag">servlet</span>&gt;
&lt;<span class="hl-tag">servlet-name</span>&gt;default&lt;<span class="hl-tag">/servlet-name</span>&gt;
&lt;<span class="hl-tag">servlet-class</span>&gt;org.apache.catalina.servlets.DefaultServlet&lt;<span class="hl-tag">/servlet-class</span>&gt;
&lt;<span class="hl-tag">init-param</span>&gt;
&lt;<span class="hl-tag">param-name</span>&gt;debug&lt;<span class="hl-tag">/param-name</span>&gt;
&lt;<span class="hl-tag">param-value</span>&gt;0&lt;<span class="hl-tag">/param-value</span>&gt;
&lt;<span class="hl-tag">/init-param</span>&gt;
&lt;<span class="hl-tag">init-param</span>&gt;
&lt;<span class="hl-tag">param-name</span>&gt;listings&lt;<span class="hl-tag">/param-name</span>&gt;
&lt;<span class="hl-tag">param-value</span>&gt;false&lt;<span class="hl-tag">/param-value</span>&gt;
&lt;<span class="hl-tag">/init-param</span>&gt;
&lt;<span class="hl-tag">load-on-startup</span>&gt;1&lt;<span class="hl-tag">/load-on-startup</span>&gt;
&lt;<span class="hl-tag">/servlet</span>&gt;
&lt;<span class="hl-tag">servlet</span>&gt;
&lt;<span class="hl-tag">servlet-name</span>&gt;jsp&lt;<span class="hl-tag">/servlet-name</span>&gt;
&lt;<span class="hl-tag">servlet-class</span>&gt;org.apache.jasper.servlet.JspServlet&lt;<span class="hl-tag">/servlet-class</span>&gt;
&lt;<span class="hl-tag">init-param</span>&gt;
&lt;<span class="hl-tag">param-name</span>&gt;fork&lt;<span class="hl-tag">/param-name</span>&gt;
&lt;<span class="hl-tag">param-value</span>&gt;false&lt;<span class="hl-tag">/param-value</span>&gt;
&lt;<span class="hl-tag">/init-param</span>&gt;
&lt;<span class="hl-tag">init-param</span>&gt;
&lt;<span class="hl-tag">param-name</span>&gt;xpoweredBy&lt;<span class="hl-tag">/param-name</span>&gt;
&lt;<span class="hl-tag">param-value</span>&gt;false&lt;<span class="hl-tag">/param-value</span>&gt;
&lt;<span class="hl-tag">/init-param</span>&gt;
&lt;<span class="hl-tag">load-on-startup</span>&gt;3&lt;<span class="hl-tag">/load-on-startup</span>&gt;
&lt;<span class="hl-tag">/servlet</span>&gt;
&lt;<span class="hl-tag">servlet-mapping</span>&gt;
&lt;<span class="hl-tag">servlet-name</span>&gt;default&lt;<span class="hl-tag">/servlet-name</span>&gt;
&lt;<span class="hl-tag">url-pattern</span>&gt;/&lt;<span class="hl-tag">/url-pattern</span>&gt;
&lt;<span class="hl-tag">/servlet-mapping</span>&gt;
&lt;<span class="hl-tag">servlet-mapping</span>&gt;
&lt;<span class="hl-tag">servlet-name</span>&gt;jsp&lt;<span class="hl-tag">/servlet-name</span>&gt;
&lt;<span class="hl-tag">url-pattern</span>&gt;*.jsp&lt;<span class="hl-tag">/url-pattern</span>&gt;
&lt;<span class="hl-tag">/servlet-mapping</span>&gt;
&lt;<span class="hl-tag">servlet-mapping</span>&gt;
&lt;<span class="hl-tag">servlet-name</span>&gt;jsp&lt;<span class="hl-tag">/servlet-name</span>&gt;
&lt;<span class="hl-tag">url-pattern</span>&gt;*.jspx&lt;<span class="hl-tag">/url-pattern</span>&gt;
&lt;<span class="hl-tag">/servlet-mapping</span>&gt;
&lt;<span class="hl-tag">session-config</span>&gt;
&lt;<span class="hl-tag">session-timeout</span>&gt;30&lt;<span class="hl-tag">/session-timeout</span>&gt;
&lt;<span class="hl-tag">/session-config</span>&gt;
&lt;<span class="hl-tag">mime-mapping</span>&gt;
&lt;<span class="hl-tag">extension</span>&gt;abs&lt;<span class="hl-tag">/extension</span>&gt;
&lt;<span class="hl-tag">mime-type</span>&gt;audio/x-mpeg&lt;<span class="hl-tag">/mime-type</span>&gt;
&lt;<span class="hl-tag">/mime-mapping</span>&gt;
......
&lt;<span class="hl-tag">mime-mapping</span>&gt;
&lt;<span class="hl-tag">extension</span>&gt;ppt&lt;<span class="hl-tag">/extension</span>&gt;
&lt;<span class="hl-tag">mime-type</span>&gt;application/vnd.ms-powerpoint&lt;<span class="hl-tag">/mime-type</span>&gt;
&lt;<span class="hl-tag">/mime-mapping</span>&gt;
&lt;<span class="hl-tag">welcome-file-list</span>&gt;
&lt;<span class="hl-tag">welcome-file</span>&gt;index.html&lt;<span class="hl-tag">/welcome-file</span>&gt;
&lt;<span class="hl-tag">welcome-file</span>&gt;index.htm&lt;<span class="hl-tag">/welcome-file</span>&gt;
&lt;<span class="hl-tag">welcome-file</span>&gt;index.jsp&lt;<span class="hl-tag">/welcome-file</span>&gt;
&lt;<span class="hl-tag">/welcome-file-list</span>&gt;
&lt;<span class="hl-tag">/web-app</span>&gt;
</pre><p>
The following bullets describe the main elements in the default <code class="literal">web.xml</code> file.
</p><div class="itemizedlist"><ul type="disc"><li><p>The <code class="literal">&lt;Servlet&gt;</code> XML element declares a given servlet and its configurations. The sample <code class="literal">web.xml</code> file above includes two &lt;Servlet&gt; elements.</p><div class="itemizedlist"><ul type="circle"><li><p>
The default servlet serves static resources and processes the requests that are not mapped to any servlet.
For details about default servlet configuration, see the <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/default-servlet.html" target="_top">Apache Tomcat Default Servlet Reference.</a>.
</p></li><li><p>
The jsp servlet serves the requests to JavaServer Pages. It is mapped to the URL pattern "*.jsp" and "*.jspx".
For details about jsp servlet configuration, see the <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/jasper-howto.html" target="_top">Apache Tomcat Jasper 2 JSP Engine.</a>.
</p></li></ul></div></li><li><p>The <code class="literal">&lt;servlet-mapping&gt;</code> XML element specifies the mapping between the servlet and URL pattern.</p></li><li><p>
The <code class="literal">&lt;session-config&gt;</code> XML element defines the session configuration for one web application.
The sample <code class="literal">web.xml</code> file above specifies that the session timeout for all web applications will be 30 minutes by default.
</p></li><li><p>
The <code class="literal">&lt;mime-mapping&gt;</code> XML element defines a mapping between a filename extension and a mime type.
When serving static resources, a "Content-Type" header will be generated based on these mappings.
</p></li><li><p>
The <code class="literal">&lt;welcome-file-list&gt;</code> XML element specifies a list of welcome files.
When a request URI refers to a directory, the default servlet looks for a "welcome file" within that directory.
If the "welcome file" exists it will be served, otherwise 404 status or directory listing will be returned, depending on the default servlet configuration.
</p></li></ul></div><p>
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-tomcat-contexts"></a>Context Configuration</h3></div></div></div><p>
Virgo Server for Apache Tomcat supports standard Apache Tomcat web application context configuration.
The <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/config/index.html" target="_top">Apache Tomcat Configuration Reference</a> has a section on
<a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/config/context.html" target="_top">The Context Container</a> which describes the mechanism that
is used in VTS for searching context configuration files and details the context configuration properties.
</p><p>
Context configuration files may be placed in the following locations,
where <code class="literal">[enginename]</code> is the name of Tomcat's engine ('Catalina' by default) and <code class="literal">[hostname]</code> names
a virtual host ('localhost' by default), both of which are configured in <code class="literal">tomcat-server.xml</code>:
</p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">$SERVER_HOME/configuration/context.xml</code> provides the default context configuration file for all web applications.
</p></li><li><p>
The <code class="literal">$SERVER_HOME/configuration/[enginename]/[hostname]</code> directory may contain:
</p><div class="itemizedlist"><ul type="circle"><li><p>
The default context configuration for all web applications of a given virtual host in the file <code class="literal">context.xml.default</code>.
</p></li><li><p>
Individual web applications' context configuration files as described in the Apache Tomcat Configuration Reference.
For example, the context for a web application with
context path <code class="literal">foo</code> may be configured in <code class="literal">foo.xml</code>.
</p></li></ul></div><p>
</p></li></ul></div><p>
</p><p>
Note that the following context configuration features are not supported in Virgo Server for Apache Tomcat:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Custom class loaders.
</p></li><li><p>
Specifying the context path. This is specified using the <code class="literal">Web-ContextPath</code> header in the web application's
<code class="literal">MANIFEST.MF</code> file.
</p></li><li><p>
Specifying the document base directory.
</p></li></ul></div><p>
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-jsp-compilation"></a>JSP Compilation</h3></div></div></div><p>
By default Apache Tomcat compiles JSP files in web applications agains Java 1.6.
In order to enable JSP compilation against Java 1.7 for your web application,
additional init parameters (<code class="literal">compilerSourceVM</code> and <code class="literal">compilerTargetVM</code>) should be added for the <code class="literal">org.apache.jasper.servlet.JspServlet</code> configuration.
For details about <code class="literal">org.apache.jasper.servlet.JspServlet</code> configuration, see the <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/jasper-howto.html" target="_top">Apache Tomcat Jasper 2 JSP Engine</a>.
<code class="literal">org.apache.jasper.servlet.JspServlet</code> configuration can be provided with the web application's web.xml.
</p><pre class="programlisting">&lt;<span class="hl-tag">?xml version="1.0" encoding="ISO-8859-1"?</span>&gt;
&lt;<span class="hl-tag">servlet</span>&gt;
&lt;<span class="hl-tag">servlet-name</span>&gt;jsp&lt;<span class="hl-tag">/servlet-name</span>&gt;
&lt;<span class="hl-tag">servlet-class</span>&gt;org.apache.jasper.servlet.JspServlet&lt;<span class="hl-tag">/servlet-class</span>&gt;
&lt;<span class="hl-tag">init-param</span>&gt;
&lt;<span class="hl-tag">param-name</span>&gt;compilerSourceVM&lt;<span class="hl-tag">/param-name</span>&gt;
&lt;<span class="hl-tag">param-value</span>&gt;1.7&lt;<span class="hl-tag">/param-value</span>&gt;
&lt;<span class="hl-tag">/init-param</span>&gt;
&lt;<span class="hl-tag">init-param</span>&gt;
&lt;<span class="hl-tag">param-name</span>&gt;compilerTargetVM&lt;<span class="hl-tag">/param-name</span>&gt;
&lt;<span class="hl-tag">param-value</span>&gt;1.7&lt;<span class="hl-tag">/param-value</span>&gt;
&lt;<span class="hl-tag">/init-param</span>&gt;
&lt;<span class="hl-tag">init-param</span>&gt;
&lt;<span class="hl-tag">param-name</span>&gt;fork&lt;<span class="hl-tag">/param-name</span>&gt;
&lt;<span class="hl-tag">param-value</span>&gt;false&lt;<span class="hl-tag">/param-value</span>&gt;
&lt;<span class="hl-tag">/init-param</span>&gt;
&lt;<span class="hl-tag">init-param</span>&gt;
&lt;<span class="hl-tag">param-name</span>&gt;xpoweredBy&lt;<span class="hl-tag">/param-name</span>&gt;
&lt;<span class="hl-tag">param-value</span>&gt;false&lt;<span class="hl-tag">/param-value</span>&gt;
&lt;<span class="hl-tag">/init-param</span>&gt;
&lt;<span class="hl-tag">load-on-startup</span>&gt;3&lt;<span class="hl-tag">/load-on-startup</span>&gt;
&lt;<span class="hl-tag">/servlet</span>&gt;
&lt;<span class="hl-tag">servlet-mapping</span>&gt;
&lt;<span class="hl-tag">servlet-name</span>&gt;jsp&lt;<span class="hl-tag">/servlet-name</span>&gt;
&lt;<span class="hl-tag">url-pattern</span>&gt;*.jsp&lt;<span class="hl-tag">/url-pattern</span>&gt;
&lt;<span class="hl-tag">url-pattern</span>&gt;*.jspx&lt;<span class="hl-tag">/url-pattern</span>&gt;
&lt;<span class="hl-tag">/servlet-mapping</span>&gt;
</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-web"></a>13.8&nbsp;Configuring the Web Integration Layer</h2></div></div></div><p>
Virgo Server for Apache Tomcat integrates an OSGi-enhanced version of the <a class="ulink" href="http://tomcat.apache.org/" target="_top">Tomcat Servlet Container</a>
in order to provide support for deploying Java EE WARs and OSGi <span class="emphasis"><em>Web Application Bundles</em></span>.
</p><p>
For Virgo Server for Apache Tomcat you
configure the behaviour of the Web Integration Layer using the properties file called <code class="literal">org.eclipse.virgo.web.properties</code>.
The <code class="literal">org.eclipse.virgo.web.properties</code> file is located in the <code class="literal">$SERVER_HOME/repository/ext</code> directory.
</p><p>The following table describes the properties. </p><div class="table"><a name="configuring-web-integration-layer"></a><p class="title"><b>Table&nbsp;13.12.&nbsp;Web Integration Layer Properties</b></p><div class="table-contents"><table summary="Web Integration Layer Properties" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
Property
</th><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">
Description
</th><th style="border-bottom: 1.0pt solid ; ">
Default Value
</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; ">
<code class="literal">WABHeaders</code>
</td><td style="border-right: 1.0pt solid ; ">
<p>
Specifies how Web Application Bundle manifest headers are processed.
See "Web Application Manifest Processing" in the
<a class="ulink" href="../../virgo-programmer-guide/html/index.html" target="_top">Programmer Guide</a> for details.
</p>
<p>
A value of <code class="literal">strict</code> causes VTS to interpret certain headers in strict compliance with
the OSGi Web Applications specification if they are not specified.
</p>
<p>
A value of <code class="literal">defaulted</code> causes VTS to set certain headers to default values if they are not specified.
This was how VTS behaved prior to version 3.
<span class="emphasis"><em>This value is provided as a migration aid and may not be supported in future releases.</em></span>
A warning event log message (WE0006W) is generated if this value is specified.
</p>
<p>
The Virgo Jetty Server will always operate in <code class="literal">strict</code> mode.
</p>
<p>
Virgo Nano Web does not have a Web Integration Layer, but has a corresponding kernel property.
See <a class="link" href="#configuring-deployment" title="Configuring Deployment">Configuring Deployment</a>.
</p>
</td><td style="">
<code class="literal">strict</code>
</td></tr></tbody></table></div></div><br class="table-break"><p>
There is no Web Integration Layer in Virgo Jetty Server. The relevant configuration is described in
<a class="link" href="#configuring-jetty" title="13.9&nbsp;Configuring the Embedded Jetty Servlet Container">Configuring the Embedded Jetty Servlet Container</a>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-jetty"></a>13.9&nbsp;Configuring the Embedded Jetty Servlet Container</h2></div></div></div><p>
Virgo Jetty Server supports <span class="emphasis"><em>Web Application Bundles</em></span>, but does not provide support for Java EE WARs.
</p><p>
The Virgo Jetty Server contains a standard Jetty configuration file at <code class="literal">SERVER_HOME/jetty/etc/jetty.xml</code>.
This has been tailored to the Virgo Runtime Environment. To make modifications please refer to the
<a class="ulink" href="http://wiki.eclipse.org/Jetty/Howto/Configure_Jetty#Using_Jetty_XML" target="_top">Jetty documentation</a>.
</p></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="log-codes"></a>Appendix&nbsp;A.&nbsp;Event log codes</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="event-log-codes-format"></a>A.1&nbsp;Format of the event log codes</h2></div></div></div><p>
Event log codes issued by Virgo have the general syntax
<code class="literal">&lt;XXnnnnL&gt;</code> where:
</p><div class="informaltable"><table style="border: none;"><colgroup><col><col></colgroup><tbody><tr><td style=""><code class="literal">XX</code></td><td style="">
is a two-letter code (upper-case) identifying the area of the Virgo code which issued the log message;
</td></tr><tr><td style=""><code class="literal">nnnn</code></td><td style="">
is a four-digit message number; and
</td></tr><tr><td style=""><code class="literal">L</code></td><td style="">
is a single-letter (upper-case) code identifying the level of the message.
</td></tr></tbody></table></div><p>
</p><p>
The two-letter codes are (this list is not complete):
</p><div class="informaltable"><table style="border: none;"><colgroup><col><col></colgroup><tbody><tr><td style=""><code class="literal">AG</code></td><td style=""><code class="literal">org.eclipse.virgo.kernel.agent.dm</code></td></tr><tr><td style=""><code class="literal">DE</code></td><td style=""><code class="literal">org.eclipse.virgo.kernel.deployer.core</code></td></tr><tr><td style=""><code class="literal">HD</code></td><td style=""><code class="literal">org.eclipse.virgo.kernel.deployer.hot</code></td></tr><tr><td style=""><code class="literal">HR</code></td><td style=""><code class="literal">org.eclipse.virgo.apps.repository.core</code></td></tr><tr><td style=""><code class="literal">KE</code></td><td style=""><code class="literal">org.eclipse.virgo.kernel.core</code></td></tr><tr><td style=""><code class="literal">KS</code></td><td style=""><code class="literal">org.eclipse.virgo.kernel.services</code></td></tr><tr><td style=""><code class="literal">OF</code></td><td style=""><code class="literal">org.eclipse.virgo.kernel.osgi</code></td></tr><tr><td style=""><code class="literal">RP</code></td><td style=""><code class="literal">org.eclipse.virgo.repository</code></td></tr><tr><td style=""><code class="literal">TC</code></td><td style=""><code class="literal">org.eclipse.virgo.web.tomcat</code></td></tr><tr><td style=""><code class="literal">UR</code></td><td style=""><code class="literal">org.eclipse.virgo.kernel.userregion</code></td></tr><tr><td style=""><code class="literal">WE</code></td><td style=""><code class="literal">org.eclipse.virgo.web.core</code></td></tr></tbody></table></div><p>
</p><p>
The four-digit numbers identify the message text (with placeholders for inserted values). These are not listed here, but can be discovered by examining the files called
<code class="literal">EventLogMessages.properties</code>, found in the relevant packages.
</p><p>
The single-digit level code is one of:
</p><div class="informaltable"><table style="border: none;"><colgroup><col><col></colgroup><tbody><tr><td style=""><code class="literal">E</code></td><td style="">Error level: enabled if level is <code class="literal">ERROR</code>.</td></tr><tr><td style=""><code class="literal">W</code></td><td style="">Warning level: enabled if level is <code class="literal">WARNING</code> or above.</td></tr><tr><td style=""><code class="literal">I</code></td><td style="">Info level: enabled if level is <code class="literal">INFO</code> or above.</td></tr><tr><td style=""><code class="literal">D</code></td><td style="">Debug level: enabled if level is <code class="literal">DEBUG</code> or above.</td></tr><tr><td style=""><code class="literal">T</code></td><td style="">Trace level: always enabled.</td></tr></tbody></table></div><p>
There are never two messages with the same prefix and number, but with different levels.
</p></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="known-issues"></a>Appendix&nbsp;B.&nbsp;Known Issues</h2></div></div></div><p>This section describes known issues that you might run into, along with corresponding workarounds. </p><p>For the full list of known issues, see <a class="ulink" href="https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;order=Importance;classification=RT;product=Virgo" target="_top">Virgo bugs in Eclipse Bugzilla</a>. The bugs are organised by component as well as by release. You can also use bugzilla to enter a new issue if you cannot find an existing issue that describes the problem you are running into, but it's probably worth asking on the <a class="ulink" href="http://www.eclipse.org/forums/index.php?t=thread&amp;frm_id=159" target="_top">Virgo community forum</a> first.</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="known-issues-firewall-timeout"></a>B.1&nbsp;Timeout During Startup Due to Firewall Settings</h2></div></div></div><p>
Virgo will fail to start correctly if it is prevented from
connecting to needed ports by the firewall. Typically this manifests
as error <code class="literal">SPPM0003E</code> . Configuring the firewall to
allow Virgo process to bind to the necessary ports will prevent
this error from occurring.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="known-issues-startup-timeout"></a>B.2&nbsp;Timeout During Startup Due to Insufficient Resources</h2></div></div></div><p>
Virgo will fail to start correctly if it is running on slow hardware or
on a system with insufficient resources. Typically this manifests as error <code class="literal">KE0004E</code> .
Configuring the <a class="link" href="#configuring-kernel-properties" title="Configuring the Kernel">startup wait limit</a> will provide
Virgo with more time for initialisation.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="known-issues-perm-gen-sun-vm"></a>B.3&nbsp;OutOfMemoryError: PermGen Space Running on Sun JVM</h2></div></div></div><p>
As a result of Sun Java bug
<a class="ulink" href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4957990" target="_top">4957990</a>,
the Virgo may consume more PermGen space than expected when running with the
server HotSpot compiler. This problem may be resolved by configuring the
<code class="literal">JAVA_OPTS</code> environment variable to specify an increased
<code class="literal">MaxPermSize</code>, for example <code class="literal">-XX:MaxPermSize=128M</code>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="alternate-serviceability-work"></a>B.4&nbsp;Alternate <code class="literal">serviceability</code> and <code class="literal">work</code> Directories</h2></div></div></div><p>
Although an alternate <code class="literal">configuration</code> directory may be specified on startup, there is no way to specify
alternate <code class="literal">serviceability</code> or <code class="literal">work</code> directories. This is covered by
<a class="ulink" href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=307737" target="_top">bug 307737</a> which also describes a workaround.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="windows-deletion"></a>B.5&nbsp;Problem Deleting Installation Directory under Windows</h2></div></div></div><p>
Sometimes Microsoft Windows won't let you delete the Virgo Server installation directory, typically because of long paths
inside the <code class="literal">work</code> directory.
</p><p>
You can return the Virgo instance to a clean state by stopping Virgo if necessary and then running the startup script with the options
<code class="literal">-clean -noStart</code>, after which you should be able to delete the installation directory.
See <a class="link" href="#cleaning-without-starting" title="7.7&nbsp;Cleaning Virgo Server for Apache Tomcat without Starting it">Cleaning Virgo Server for Apache Tomcat without Starting it</a> for more information.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="long-work-paths"></a>B.6&nbsp;Long Work Directory Paths under Windows</h2></div></div></div><p>
Problems can arise under Windows when long paths are created in the <code class="literal">work</code> directory as artefacts are deployed.
</p><p>
You can shorten some of these paths by preventing bundles from being unpacked during deployment.
See <a class="link" href="#configuring-deployment" title="Configuring Deployment">Configuring Deployment</a> for more information.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="known-issues-jetty-restrictions"></a>B.7&nbsp;Virgo Jetty Server Restrictions</h2></div></div></div><p>
When using the Virgo Jetty Server the Hosted Repository application and the Snaps modular web technology are not supported.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="known-issues-shutdown-logs-shell"></a>B.8&nbsp;Shutdown Log Messages in Telnet Shell</h2></div></div></div><p>
When you use the <code class="literal">shutdown</code> shell command to stop Virgo Tomcat Server, the shutdown log messages appear in the shell terminal instead of in the terminal in which Virgo runs.
See <a class="link" href="#admin-shell-enable" title="8.1&nbsp;Enabling the Equinox Console">Enabling Equinox Console</a> for more information. This is covered also by <a class="ulink" href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=351533" target="_top">bug 351533</a>.
</p></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="furtherreading"></a>Appendix&nbsp;C.&nbsp;
Further Reading
</h2></div></div></div><p>
<a class="ulink" href="../../virgo-programmer-guide/html/index.html" target="_top">
Virgo Server for Apache Tomcat Programmer Guide
</a>
</p><p>
<a class="ulink" href="http://static.springframework.org/spring/docs/2.5.x/reference/index.html" target="_top">
Spring Framework Reference Guide
</a>
</p><p>
<a class="ulink" href="http://static.springframework.org/osgi/docs/current/reference/html/" target="_top">
Spring Dynamic Modules Reference Guide
</a>
</p><p>
<a class="ulink" href="http://www.osgi.org/Specifications/HomePage" target="_top">
Blueprint Container Specification
</a>
(in the OSGi 4.2 and 5.0 Enterprise Specifications)
</p><p>
<a class="ulink" href="http://logback.qos.ch/manual" target="_top">
The Logback Manual
</a>
</p></div></div><!--Begin LoopFuse code--><script src="http://loopfuse.net/webrecorder/js/listen.js" type="text/javascript"></script><script type="text/javascript">
_lf_cid = "LF_48be82fa";
_lf_remora();
</script><!--End LoopFuse code--></body></html>