user-guide/src/known-issues.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
		"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<appendix id="known-issues">
	<title>Known Issues</title>

	<para>This section describes known issues that you might run into, along with corresponding workarounds.  </para>

	<para>For the full list of known issues, see <ulink url="https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;order=Importance;classification=RT;product=Virgo">Virgo bugs in Eclipse Bugzilla</ulink>.  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 <ulink url="http://www.eclipse.org/forums/index.php?t=thread&amp;frm_id=159">Virgo community forum</ulink> first.</para>

	<section id="known-issues-firewall-timeout">
		<title>Timeout During Startup Due to Firewall Settings</title>
		<para>
			@project.name@ will fail to start correctly if it is prevented from 
			connecting to needed ports by the firewall. Typically this manifests 
			as error <literal>SPPM0003E</literal> . Configuring the firewall to
			allow @project.name@ process to bind to the necessary ports will prevent
			this error from occurring.
		</para>
	</section>
    <section id="known-issues-startup-timeout">
        <title>Timeout During Startup Due to Insufficient Resources</title>
        <para>
            @project.name@ will fail to start correctly if it is running on slow hardware or
            on a system with insufficient resources. Typically this manifests as error <literal>KE0004E</literal> .
            Configuring the <link linkend="configuring-kernel-properties">startup wait limit</link> will provide
            @project.name@ with more time for initialisation.
        </para>
    </section>
	<section id="known-issues-perm-gen-sun-vm">
		<title>OutOfMemoryError: PermGen Space Running on Sun JVM</title>
		<para>
			As a result of Sun Java bug
			<ulink url="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4957990">4957990</ulink>,
			the @project.name@ may consume more PermGen space than expected when running with the
			server HotSpot compiler. This problem may be resolved by configuring the
			<literal>JAVA_OPTS</literal> environment variable to specify an increased
			<literal>MaxPermSize</literal>, for example <literal>-XX:MaxPermSize=128M</literal>.
		</para>
	</section>
	<section id="alternate-serviceability-work">
		<title>Alternate <literal>serviceability</literal> and <literal>work</literal> Directories</title>
		<para>
			Although an alternate <literal>configuration</literal> directory may be specified on startup, there is no way to specify
			alternate <literal>serviceability</literal> or <literal>work</literal> directories. This is covered by
			<ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=307737">bug 307737</ulink> which also describes a workaround.
		</para>
	</section>
	<section id="windows-deletion">
		<title>Problem Deleting Installation Directory under Windows</title>
		<para>
			Sometimes Microsoft Windows won't let you delete the @project.name@ Server installation directory, typically because of long paths
			inside the <literal>work</literal> directory.
	 	</para>
		<para>
			You can return the @project.name@ instance to a clean state by stopping @project.name@ if necessary and then running the startup script with the options
			<literal>-clean -noStart</literal>, after which you should be able to delete the installation directory.
			See <link linkend="cleaning-without-starting">Cleaning @tomcat.product.name@ without Starting it</link> for more information.
		</para>
	</section>
	<section id="long-work-paths">
		<title>Long Work Directory Paths under Windows</title>
		<para>
			Problems can arise under Windows when long paths are created in the <literal>work</literal> directory as artefacts are deployed.
	 	</para>
		<para>
			You can shorten some of these paths by preventing bundles from being unpacked during deployment.
			See <link linkend="configuring-deployment">Configuring Deployment</link> for more information.
		</para>
	</section>	
	<section id="known-issues-jetty-restrictions">
		<title>@jetty.product.name@ Restrictions</title>
		<para>
			When using the @jetty.product.name@ the Hosted Repository application and the Snaps modular web technology are not supported.
		</para>
	</section>
	<section id="known-issues-shutdown-logs-shell">
	  <title>Shutdown Log Messages in Telnet Shell</title>
	  <para>
	    When you use the <literal>shutdown</literal> shell command to stop Virgo Server for Apache Tomcat, the shutdown log messages appear in the shell terminal instead of in the terminal in which Virgo runs. 
      See <link linkend="admin-shell-enable">Enabling Equinox Console</link> for more information. This is covered also by <ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=351533">bug 351533</ulink>.
	  </para>
	</section>
</appendix>