user-guide/src/starting-stopping.xml - virgo/org.eclipse.virgo.documentation - Git at Google

 <?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">
 <chapter id="starting-stopping" xreflabel="Starting and Stopping @tomcat.product.name@">
 	  <title>Starting and Stopping @tomcat.product.name@</title>
         <titleabbrev>Starting and Stopping @tomcat.product.name.short@</titleabbrev>
 	  <section>
 	    <title>Starting @tomcat.product.name@</title>
 	    <para>
 	      To start @tomcat.product.name@ run the <literal>startup.sh</literal> (Linux) or <literal>startup.bat</literal> (Windows) script.
 	      For both platforms, the script is located in the <literal>SERVER_HOME/bin</literal> directory.
 	    </para>
 	    <note>
 	      This chapter applies to @nano.product.name@ too. Note that since @nano.product.name.short@
 	      has a single region you can ignore the console output from the user region and focus on the instructions.
 	      A successful startup of @nano.product.name.short@ is as simple as that:
 	      <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.
 	      </screen>
 	    </note>
 	    <section>
 	      <title>Linux</title>
 	      <para>
 	        To start @tomcat.product.name@, open a terminal window and run <literal>startup.sh</literal>:
 	      </para>
 	      <screen>prompt$ cd $SERVER_HOME
 prompt$ bin/startup.sh</screen>
 	      <para>
 	        Once @tomcat.product.name@ has started, the console will display a log message
 	        similar to the one shown below, along with other status messages:
 	      </para>

 	      <screen>[2009-11-30 12:12:12.111] Thread-2   &lt;UR0001I&gt; User region ready.</screen>
 	      <para>The preceding message indicates that you can start using @tomcat.product.name.short@.</para>
 	    </section>
 	    <section>
 	      <title>Microsoft Windows</title>
 	      <para>
 	        To start @tomcat.product.name@, open a command-window and run <literal>startup.bat</literal>:
 	      </para>
 	      <screen>prompt> cd %SERVER_HOME%
 prompt> bin\startup.bat</screen>
 	      <para>
 	        Once @tomcat.product.name@ has started, the console will display a log message
 	        similar to the one shown below, along with other status messages:
 	      <screen>[2009-11-30 12:12:12.111] Thread-2   &lt;UR0001I&gt; User region ready.</screen>
 	      <para>The preceding message indicates that you can start using @tomcat.product.name.short@.</para>
 	      </para>
 	    </section>
 	  </section>
 	  <section>
 	    <title>Starting in Clean Mode</title>
 	    <para>
 			When you start @tomcat.product.name@ in clean mode, the startup script removes the <literal>SERVER_HOME/work</literal> directory (and hence all
 			running applications) as well as all trace, log and dump files.  It leaves the
 			<literal>SERVER_HOME/repository</literal> and <literal>SERVER_HOME/pickup</literal> directories untouched,
 			which means that any applications previously hot deployed will be automatically reinstalled.
 	    </para>
 	    <section>
 	      <title>Linux</title>
 	      <para>
 	        To start @tomcat.product.name@ in clean mode, open a terminal window and run <literal>startup.sh -clean</literal>:
 	      </para>
 	      <screen>prompt$ cd $SERVER_HOME
 prompt$ bin/startup.sh -clean </screen>
 	    </section>
 	    <section>
 	      <title>Microsoft Windows</title>
 	      <para>
 	        To start @tomcat.product.name@ in clean mode, open a command window and run <literal>startup.bat -clean</literal>:
 	      </para>
 	      <screen>prompt> cd %SERVER_HOME%
 prompt> bin\startup.bat -clean</screen>
 	    </section>
 	  </section>
 	  <section>
 	    <title>Starting in Debug Mode</title>
 	    <section>
 	      <title>Linux</title>
 	      <para>
 	        To start @tomcat.product.name@ in debug mode, run
 	        <literal>startup.sh</literal> passing in the
 	        <literal>-debug</literal> argument:
 	      </para>
 	      <screen>prompt$ cd $SERVER_HOME
 prompt$ bin/startup.sh -debug</screen>
 	      <para>
 	        This will start the debug agent listening on port
 	        <literal>8000</literal> 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 <literal>-debug</literal> argument:
 	      </para>
 	      <screen>prompt$ cd $SERVER_HOME
 prompt$ bin/startup.sh -debug 8001</screen>
 	      <para>
 	        This will start the debug agent listening on port
 	        <literal>8001</literal>. To start in debug mode and suspend the VM
 	        until a debugger attaches, pass in the <literal>-suspend</literal>
 	        argument along with the <literal>-debug</literal> argument:
 	      </para>
 	      <screen>prompt$ cd $SERVER_HOME
 prompt$ bin/startup.sh -debug -suspend</screen>
 	      <para>
 	        This starts the debug agent, but prevents @tomcat.product.name@ from actually
 	        starting until a debugger attaches to the agent. This can be useful
 	        when trying to diagnose problems that occur during startup.
 	      </para>
 	    </section>
 	    <section>
 	      <title>Microsoft Windows</title>
 	      <para>
 	        To start @tomcat.product.name@ in debug mode, run
 	        <literal>startup.bat</literal> passing in the
 	        <literal>-debug</literal> argument:
 	      </para>
 	      <screen>prompt> cd %SERVER_HOME%
 prompt> bin\startup.bat -debug</screen>
 	      <para>
 	        This will start the debug agent listening on port
 	        <literal>8000</literal> 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 <literal>-debug</literal> argument:
 	      </para>
 	      <screen>prompt> cd %SERVER_HOME%
 prompt> bin\startup.bat -debug 8001</screen>
 	      <para>
 	        This will start the debug agent listening on port
 	        <literal>8001</literal>. To start in debug mode and suspend the VM
 	        until a debugger attaches, pass in the <literal>-suspend</literal>
 	        argument along with the <literal>-debug</literal> argument:
 	      </para>
 	      <screen>prompt> cd %SERVER_HOME%
 prompt> bin\startup.bat -debug -suspend</screen>
 	      <para>
 	        This starts the debug agent, but prevents @tomcat.product.name@ from actually
 	        starting until a debugger attaches to the agent. This can be useful
 	        when trying to diagnose problems that occur during startup.
 	      </para>
 	    </section>
 	  </section>
 		  <section>
 		    <title>Starting with JMX Access Modifications</title>
 			The @tomcat.product.name@ 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 <literal>9875</literal>
 			and the default username and password are <literal>admin</literal> and <literal>springsource</literal>.
 			<section>
 				<title>Linux</title>
 				<para>
 					To start @tomcat.product.name@ with default JMX access enabled, run <literal>startup.sh</literal> passing
 					in no arguments:
 				</para>
 				<screen>prompt$ cd $SERVER_HOME
 prompt$ bin/startup.sh </screen>
 				<para>
 					To start JConsole, run the <literal>jconsole.sh</literal> script, located in the <literal>bin</literal> directory, as shown:
 				</para>
 				<screen>prompt$ cd $SERVER_HOME
 prompt$ bin/jconsole.sh </screen>
 				<para>
 					The following image shows how to specify a local connection using JConsole.
 				</para>
 				<para>
 					<imagedata fileref="images/jmx-local-attach.png"/>
 				</para>
 				<para>
 					The following image shows how to specify a remote connection in JConsole that uses SSL with the default
 					username/password (<literal>admin/springsource</literal> and default secure port of <literal>9875</literal>).
 				</para>
 				<para>
 					<imagedata fileref="images/jmx-remote-attach-default.png"/>
 				</para>
 				<para>
 					To start with the JMX remote access on a specific port number other than the default <literal>9875</literal>,
 					pass this port number in as the value
 					of the <literal>-jmxport</literal> argument:
 				</para>
 				<screen>prompt$ cd $SERVER_HOME
 prompt$ bin/startup.sh -jmxport 9090</screen>
 				<para>
 					This will start the @tomcat.product.name@ with JMX enabled for remote connections on port <literal>9090</literal>.
 				</para>
 				<para>
 					<imagedata fileref="images/jmx-remote-attach-jmxport.png"/>
 				</para>

 		                <para>To start the JMX remote access with a custom username and password, update the <literal>$SERVER_HOME/configuration/org.eclipse.virgo.kernel.users.properties</literal> file.  First specify the custom username by changing the value of the <literal>role.admin</literal> property.  Then set the password of this new user by adding a new property called <literal>user.<emphasis>username</emphasis></literal>, where <literal><emphasis>username</emphasis></literal> refers to the actual name of the user.  Finally, restart @tomcat.product.name.short@ for the changes to take effect.</para>
 	 <para>For example, if you want change the JMX remote access username to <literal>zebedee</literal> with password <literal>florence</literal>, change the file as follows:
 		</para>
        		<programlisting>##################
 # User definitions
 ##################
 user.zebedee=florence


 ##################
 # Role definitions
 ##################
 role.admin=zebedee</programlisting>
 			 	<para>Specify the custom username in JConsole as shown.  </para>
 				<para>
 					<imagedata fileref="images/jmx-remote-attach-jmxusers.png"/>
 				</para>
 				<para>
 					To start the JMX remote access using a custom SSL certificate, edit the file located at
 					<literal>$SERVER_HOME/configuration/keystore</literal>. If you wish to use a different keystore,
 					pass this filename in as the value for the <literal>-keystore</literal> argument and the keystore
 					password in as the value for the <literal>-keystorePassword</literal> argument:
 				</para>
 				<screen>prompt$ cd $SERVER_HOME
 prompt$ bin/startup.sh -keystore customKeystore -keystorePassword customKeystorePassword</screen>
 				<para>
 					This will start the @tomcat.product.name@ with JMX enabled for remote connections using an SSL certificate from
 					<literal>customKeystore</literal> with a password of <literal>customKeystorePassword</literal>.
 				</para>
 			</section>
 		    <section>
 		      <title>Microsoft Windows</title>
 				<para>
 					To start @tomcat.product.name@ with default JMX access enabled, run <literal>startup.bat</literal> passing
 					in no arguments:
 				</para>
 				<screen>prompt> cd %SERVER_HOME%
 prompt> bin\startup.bat</screen>
 				<para>
 					To start JConsole, run the <literal>jconsole.bat</literal> script, located in the <literal>bin</literal> directory, as shown:
 				</para>
 				<screen>prompt> cd %SERVER_HOME%
 prompt> bin\jconsole.bat </screen>
 				<para>
 					The following image shows how to specify a local connection using JConsole.
 				</para>
 				<para>
 					<imagedata fileref="images/jmx-local-attach.png"/>
 				</para>
 				<para>
 					The following image shows how to specify a remote connection in JConsole that uses SSL with the default
 					username/password (<literal>admin/springsource</literal> and default secure port of <literal>9875</literal>).
 				</para>
 				<para>
 					<imagedata fileref="images/jmx-remote-attach-default.png"/>
 				</para>
 				<para>
 					To start with the JMX remote access on a specific port number other than the default <literal>9875</literal>,
 					pass this port number in as the value of the <literal>-jmxport</literal> argument:
 				</para>
 				<screen>prompt> cd %SERVER_HOME%
 prompt> bin\startup.bat -jmxport 9090</screen>
 				<para>
 					This will start the @tomcat.product.name@ with JMX enabled for remote connections on port
 					<literal>9090</literal>.
 				</para>
 				<para>
 					<imagedata fileref="images/jmx-remote-attach-jmxport.png"/>
 				</para>
 		                <para>To start the JMX remote access with a custom username and password, update the <literal>%SERVER_HOME%\configuration\org.eclipse.virgo.kernel.users.properties</literal> file.  First specify the custom username by changing the value of the <literal>role.admin</literal> property.  Then set the password of this new user by adding a new property called <literal>user.<emphasis>username</emphasis></literal>, where <literal><emphasis>username</emphasis></literal> refers to the actual name of the user.  Finally, restart @tomcat.product.name.short@ for the changes to take effect.</para>
 	 <para>For example, if you want change the JMX remote access username to <literal>zebedee</literal> with password <literal>florence</literal>, change the file as follows:
 		</para>
        		<programlisting>##################
 # User definitions
 ##################
 user.zebedee=florence


 ##################
 # Role definitions
 ##################
 role.admin=zebedee</programlisting>
 			 	<para>Specify the custom username in JConsole as shown.  </para>
 				<para>
 					<imagedata fileref="images/jmx-remote-attach-jmxusers.png"/>
 				</para>
 				<para>
 					To start the JMX remote access using a custom SSL certificate, edit the file located at
 					<literal>%SERVER_HOME%\configuration\keystore</literal>. If you wish to use a different
 					keystore, pass this filename in as the value for the <literal>-keystore</literal> argument and the
 					keystore password in as the value for the <literal>-keystorePassword</literal> argument:
 				</para>
 				<screen>prompt> cd %SERVER_HOME%
 prompt> bin\startup.bat -keystore customKeystore -keystorePassword customKeystorePassword</screen>
 				<para>
 					This will start the @tomcat.product.name@ with JMX enabled for remote attach using an SSL certificate from
 					<literal>customKeystore</literal> with a password of <literal>customKeystorePassword</literal>.
 				</para>
 		</section>
 	</section>
 	<section id="starting-stopping-configuration-directory">
 		<title>Starting with a Custom Configuration Directory</title>
 		<para>
 			Use the <literal>-configDir</literal> option to specify an alternate <literal>configuration</literal> directory, different from the
 			default <literal>SERVER_HOME/configuration</literal> directory. This option allows you to use the same @tomcat.product.name@
 			installation to run multiple instances of @tomcat.product.name.short@. 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 @tomcat.product.name.short@.
 		</para>
 		<para>
 			If you specify a relative path for the <literal>-configDir</literal> parameter,
 			the startup script interprets the path as relative to the root of the @tomcat.product.name@ installation,
 			and not relative to the directory from which you execute the <literal>startup</literal> script.
 		</para>
 		<para>
 			See <link linkend="alternate-serviceability-work">Alternate <literal>serviceability</literal> and <literal>work</literal>
 			Directories</link> for a known issue related to specifying an alternate <literal>configuration</literal> directory.
 		</para>
 		<section>
 			<title>Linux</title>
 			To start @tomcat.product.name@ using a configuration directory of <literal>/configuration/node1</literal>:
 			<screen>prompt$ cd $SERVER_HOME
 prompt$ bin/startup.sh -configDir /configuration/node1</screen>
 		</section>
 		<section>
 			<title>Windows</title>
 			To start @tomcat.product.name@ using a configuration directory of <literal>c:\configuration\node1</literal>:
 			<screen>prompt> cd %SERVER_HOME%
 prompt> bin\startup.bat -configDir c:\configuration\node1</screen>
 		</section>
 	</section>
 	  <section>
 	    <title>Stopping @tomcat.product.name@</title>
 	    <section>
 	      <title>Linux</title>
 	      <para>
 	        To stop a running instance of @tomcat.product.name@, start a new terminal window and run the <literal>shutdown.sh</literal> script:
 	      </para>
 	      <screen>prompt$ cd $SERVER_HOME
 prompt$ bin/shutdown.sh</screen>
 	      <para>
 	        To stop a running instance of @tomcat.product.name@ immediately, bypassing normal shutdown
 		processing, run <literal>shutdown.sh</literal> with the <literal>-immediate</literal> option:
 	      </para>
 	      <screen>prompt$ cd $SERVER_HOME
 prompt$ bin/shutdown.sh -immediate</screen>
 	      <para>
 	        If, when you started the Web Server instance, you used the <literal>-jmxport</literal> option to specify a non-default JMX port number,
 	        then you must pass this port number to the <literal>-jmxport</literal> of the <literal>shutdown.sh</literal> script
 	        to gracefully shut it down.
 	        For example, if you specified <literal>9090</literal> as the JMX port, use the following to shut down the Web Server instance:
 	      </para>
 	      <screen>prompt$ cd $SERVER_HOME
 prompt$ bin/shutdown.sh -jmxport 9090</screen>
 	    </section>
 	    <section>
 	      <title>Microsoft Windows</title>
 	      <para>
 	        To stop a running instance of @tomcat.product.name@, start a new console window and run the <literal>shutdown.bat</literal> script:
 	      </para>
 	      <screen>prompt> cd %SERVER_HOME%
 prompt> bin\shutdown.bat</screen>
 	      <para>
 	        To stop a running instance of @tomcat.product.name@ immediately, bypassing normal shutdown
 			processing, run <literal>shutdown.bat</literal> with the <literal>-immediate</literal> option:
 	      </para>
 	      <screen>prompt> cd %SERVER_HOME%
 prompt> bin\shutdown.bat -immediate</screen>
 	      <para>
 	        If, when you started the Web Server instance, you used the <literal>-jmxport</literal> option to specify a non-default JMX port number,
 	        then you must pass this port number to the <literal>-jmxport</literal> of the <literal>shutdown.bat</literal> script to gracefully shut it down.
 	        For example, if you specified <literal>9090</literal> as the JMX port, use the following to shut down the Web Server instance:
 	      </para>
 	      <screen>prompt> cd %SERVER_HOME%
 prompt> bin\shutdown.bat -jmxport 9090</screen>
 	    </section>
 	  </section>
 		  <section id="cleaning-without-starting">
 		    <title>Cleaning  @tomcat.product.name@ without Starting it</title>
 		    <para>
 				When you clean @tomcat.product.name@, the startup script removes the <literal>SERVER_HOME/work</literal> directory (and hence all
 				running applications) as well as all trace, log and dump files.  It leaves the
 				<literal>SERVER_HOME/repository</literal> and <literal>SERVER_HOME/pickup</literal> directories untouched,
 				which means that any applications previously hot deployed will be automatically reinstalled next time the Web Server is started.
 		    </para>
 		    <para>
 				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.
 			</para>
 			<para>
 				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 <link linkend="windows-deletion">Problem Deleting Installation Directory under Windows</link> for more details.
 			</para>
 		    <section>
 		      <title>Linux</title>
 		      <para>
 		        To clean @tomcat.product.name@, open a terminal window and run <literal>startup.sh -clean -noStart</literal>:
 		      </para>
 		      <screen>prompt$ cd $SERVER_HOME
 prompt$ bin/startup.sh -clean -noStart</screen>
 		    </section>
 		    <section>
 		      <title>Microsoft Windows</title>
 		      <para>
 		        To clean @tomcat.product.name@, open a command window and run <literal>startup.bat -clean -noStart</literal>:
 		      </para>
 		      <screen>prompt> cd %SERVER_HOME%
 prompt> bin\startup.bat -clean -noStart</screen>
 		    </section>
 		  </section>
 		<section id="equinox-launcher">
 		    <title>Using Equinox Launcher</title>
 		    <para>
 				Since version 3.5 @project.name@ 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.
 				<important>The Equinox Launcher arguments must be placed at the end of the startup call. Here's an example
 				<screen>./startup.sh "virgo-args" "equinox-launcher-args"
 ./startup.sh -clean -console 2222</screen>
 				</important>
 		    </para>
 		    <para>
 				A full list of the accepted Equinox Launcher arguments is available at <ulink url="http://help.eclipse.org/indigo/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fmisc%2Fruntime-options.html">help.eclipse.org</ulink>.
 			</para>
 		</section>

 </chapter>
	<?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">
	<chapter id="starting-stopping" xreflabel="Starting and Stopping @tomcat.product.name@">
	<title>Starting and Stopping @tomcat.product.name@</title>
	<titleabbrev>Starting and Stopping @tomcat.product.name.short@</titleabbrev>
	<section>
	<title>Starting @tomcat.product.name@</title>
	<para>
	To start @tomcat.product.name@ run the <literal>startup.sh</literal> (Linux) or <literal>startup.bat</literal> (Windows) script.
	For both platforms, the script is located in the <literal>SERVER_HOME/bin</literal> directory.
	</para>
	<note>
	This chapter applies to @nano.product.name@ too. Note that since @nano.product.name.short@
	has a single region you can ignore the console output from the user region and focus on the instructions.
	A successful startup of @nano.product.name.short@ is as simple as that:
	<screen>[2011-12-28 11:41:31.528] startup-tracker <KE0001I> Kernel starting.
	[2011-12-28 11:41:31.602] startup-tracker <KE0002I> Kernel started.
	</screen>
	</note>
	<section>
	<title>Linux</title>
	<para>
	To start @tomcat.product.name@, open a terminal window and run <literal>startup.sh</literal>:
	</para>
	<screen>prompt$ cd $SERVER_HOME
	prompt$ bin/startup.sh</screen>
	<para>
	Once @tomcat.product.name@ has started, the console will display a log message
	similar to the one shown below, along with other status messages:
	</para>

	<screen>[2009-11-30 12:12:12.111] Thread-2 <UR0001I> User region ready.</screen>
	<para>The preceding message indicates that you can start using @tomcat.product.name.short@.</para>
	</section>
	<section>
	<title>Microsoft Windows</title>
	<para>
	To start @tomcat.product.name@, open a command-window and run <literal>startup.bat</literal>:
	</para>
	<screen>prompt> cd %SERVER_HOME%
	prompt> bin\startup.bat</screen>
	<para>
	Once @tomcat.product.name@ has started, the console will display a log message
	similar to the one shown below, along with other status messages:
	<screen>[2009-11-30 12:12:12.111] Thread-2 <UR0001I> User region ready.</screen>
	<para>The preceding message indicates that you can start using @tomcat.product.name.short@.</para>
	</para>
	</section>
	</section>
	<section>
	<title>Starting in Clean Mode</title>
	<para>
	When you start @tomcat.product.name@ in clean mode, the startup script removes the <literal>SERVER_HOME/work</literal> directory (and hence all
	running applications) as well as all trace, log and dump files. It leaves the
	<literal>SERVER_HOME/repository</literal> and <literal>SERVER_HOME/pickup</literal> directories untouched,
	which means that any applications previously hot deployed will be automatically reinstalled.
	</para>
	<section>
	<title>Linux</title>
	<para>
	To start @tomcat.product.name@ in clean mode, open a terminal window and run <literal>startup.sh -clean</literal>:
	</para>
	<screen>prompt$ cd $SERVER_HOME
	prompt$ bin/startup.sh -clean </screen>
	</section>
	<section>
	<title>Microsoft Windows</title>
	<para>
	To start @tomcat.product.name@ in clean mode, open a command window and run <literal>startup.bat -clean</literal>:
	</para>
	<screen>prompt> cd %SERVER_HOME%
	prompt> bin\startup.bat -clean</screen>
	</section>
	</section>
	<section>
	<title>Starting in Debug Mode</title>
	<section>
	<title>Linux</title>
	<para>
	To start @tomcat.product.name@ in debug mode, run
	<literal>startup.sh</literal> passing in the
	<literal>-debug</literal> argument:
	</para>
	<screen>prompt$ cd $SERVER_HOME
	prompt$ bin/startup.sh -debug</screen>
	<para>
	This will start the debug agent listening on port
	<literal>8000</literal> 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 <literal>-debug</literal> argument:
	</para>
	<screen>prompt$ cd $SERVER_HOME
	prompt$ bin/startup.sh -debug 8001</screen>
	<para>
	This will start the debug agent listening on port
	<literal>8001</literal>. To start in debug mode and suspend the VM
	until a debugger attaches, pass in the <literal>-suspend</literal>
	argument along with the <literal>-debug</literal> argument:
	</para>
	<screen>prompt$ cd $SERVER_HOME
	prompt$ bin/startup.sh -debug -suspend</screen>
	<para>
	This starts the debug agent, but prevents @tomcat.product.name@ from actually
	starting until a debugger attaches to the agent. This can be useful
	when trying to diagnose problems that occur during startup.
	</para>
	</section>
	<section>
	<title>Microsoft Windows</title>
	<para>
	To start @tomcat.product.name@ in debug mode, run
	<literal>startup.bat</literal> passing in the
	<literal>-debug</literal> argument:
	</para>
	<screen>prompt> cd %SERVER_HOME%
	prompt> bin\startup.bat -debug</screen>
	<para>
	This will start the debug agent listening on port
	<literal>8000</literal> 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 <literal>-debug</literal> argument:
	</para>
	<screen>prompt> cd %SERVER_HOME%
	prompt> bin\startup.bat -debug 8001</screen>
	<para>
	This will start the debug agent listening on port
	<literal>8001</literal>. To start in debug mode and suspend the VM
	until a debugger attaches, pass in the <literal>-suspend</literal>
	argument along with the <literal>-debug</literal> argument:
	</para>
	<screen>prompt> cd %SERVER_HOME%
	prompt> bin\startup.bat -debug -suspend</screen>
	<para>
	This starts the debug agent, but prevents @tomcat.product.name@ from actually
	starting until a debugger attaches to the agent. This can be useful
	when trying to diagnose problems that occur during startup.
	</para>
	</section>
	</section>
	<section>
	<title>Starting with JMX Access Modifications</title>
	The @tomcat.product.name@ 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 <literal>9875</literal>
	and the default username and password are <literal>admin</literal> and <literal>springsource</literal>.
	<section>
	<title>Linux</title>
	<para>
	To start @tomcat.product.name@ with default JMX access enabled, run <literal>startup.sh</literal> passing
	in no arguments:
	</para>
	<screen>prompt$ cd $SERVER_HOME
	prompt$ bin/startup.sh </screen>
	<para>
	To start JConsole, run the <literal>jconsole.sh</literal> script, located in the <literal>bin</literal> directory, as shown:
	</para>
	<screen>prompt$ cd $SERVER_HOME
	prompt$ bin/jconsole.sh </screen>
	<para>
	The following image shows how to specify a local connection using JConsole.
	</para>
	<para>
	<imagedata fileref="images/jmx-local-attach.png"/>
	</para>
	<para>
	The following image shows how to specify a remote connection in JConsole that uses SSL with the default
	username/password (<literal>admin/springsource</literal> and default secure port of <literal>9875</literal>).
	</para>
	<para>
	<imagedata fileref="images/jmx-remote-attach-default.png"/>
	</para>
	<para>
	To start with the JMX remote access on a specific port number other than the default <literal>9875</literal>,
	pass this port number in as the value
	of the <literal>-jmxport</literal> argument:
	</para>
	<screen>prompt$ cd $SERVER_HOME
	prompt$ bin/startup.sh -jmxport 9090</screen>
	<para>
	This will start the @tomcat.product.name@ with JMX enabled for remote connections on port <literal>9090</literal>.
	</para>
	<para>
	<imagedata fileref="images/jmx-remote-attach-jmxport.png"/>
	</para>

	<para>To start the JMX remote access with a custom username and password, update the <literal>$SERVER_HOME/configuration/org.eclipse.virgo.kernel.users.properties</literal> file. First specify the custom username by changing the value of the <literal>role.admin</literal> property. Then set the password of this new user by adding a new property called <literal>user.<emphasis>username</emphasis></literal>, where <literal><emphasis>username</emphasis></literal> refers to the actual name of the user. Finally, restart @tomcat.product.name.short@ for the changes to take effect.</para>
	<para>For example, if you want change the JMX remote access username to <literal>zebedee</literal> with password <literal>florence</literal>, change the file as follows:
	</para>
	<programlisting>##################
	# User definitions
	##################
	user.zebedee=florence


	##################
	# Role definitions
	##################
	role.admin=zebedee</programlisting>
	<para>Specify the custom username in JConsole as shown. </para>
	<para>
	<imagedata fileref="images/jmx-remote-attach-jmxusers.png"/>
	</para>
	<para>
	To start the JMX remote access using a custom SSL certificate, edit the file located at
	<literal>$SERVER_HOME/configuration/keystore</literal>. If you wish to use a different keystore,
	pass this filename in as the value for the <literal>-keystore</literal> argument and the keystore
	password in as the value for the <literal>-keystorePassword</literal> argument:
	</para>
	<screen>prompt$ cd $SERVER_HOME
	prompt$ bin/startup.sh -keystore customKeystore -keystorePassword customKeystorePassword</screen>
	<para>
	This will start the @tomcat.product.name@ with JMX enabled for remote connections using an SSL certificate from
	<literal>customKeystore</literal> with a password of <literal>customKeystorePassword</literal>.
	</para>
	</section>
	<section>
	<title>Microsoft Windows</title>
	<para>
	To start @tomcat.product.name@ with default JMX access enabled, run <literal>startup.bat</literal> passing
	in no arguments:
	</para>
	<screen>prompt> cd %SERVER_HOME%
	prompt> bin\startup.bat</screen>
	<para>
	To start JConsole, run the <literal>jconsole.bat</literal> script, located in the <literal>bin</literal> directory, as shown:
	</para>
	<screen>prompt> cd %SERVER_HOME%
	prompt> bin\jconsole.bat </screen>
	<para>
	The following image shows how to specify a local connection using JConsole.
	</para>
	<para>
	<imagedata fileref="images/jmx-local-attach.png"/>
	</para>
	<para>
	The following image shows how to specify a remote connection in JConsole that uses SSL with the default
	username/password (<literal>admin/springsource</literal> and default secure port of <literal>9875</literal>).
	</para>
	<para>
	<imagedata fileref="images/jmx-remote-attach-default.png"/>
	</para>
	<para>
	To start with the JMX remote access on a specific port number other than the default <literal>9875</literal>,
	pass this port number in as the value of the <literal>-jmxport</literal> argument:
	</para>
	<screen>prompt> cd %SERVER_HOME%
	prompt> bin\startup.bat -jmxport 9090</screen>
	<para>
	This will start the @tomcat.product.name@ with JMX enabled for remote connections on port
	<literal>9090</literal>.
	</para>
	<para>
	<imagedata fileref="images/jmx-remote-attach-jmxport.png"/>
	</para>
	<para>To start the JMX remote access with a custom username and password, update the <literal>%SERVER_HOME%\configuration\org.eclipse.virgo.kernel.users.properties</literal> file. First specify the custom username by changing the value of the <literal>role.admin</literal> property. Then set the password of this new user by adding a new property called <literal>user.<emphasis>username</emphasis></literal>, where <literal><emphasis>username</emphasis></literal> refers to the actual name of the user. Finally, restart @tomcat.product.name.short@ for the changes to take effect.</para>
	<para>For example, if you want change the JMX remote access username to <literal>zebedee</literal> with password <literal>florence</literal>, change the file as follows:
	</para>
	<programlisting>##################
	# User definitions
	##################
	user.zebedee=florence


	##################
	# Role definitions
	##################
	role.admin=zebedee</programlisting>
	<para>Specify the custom username in JConsole as shown. </para>
	<para>
	<imagedata fileref="images/jmx-remote-attach-jmxusers.png"/>
	</para>
	<para>
	To start the JMX remote access using a custom SSL certificate, edit the file located at
	<literal>%SERVER_HOME%\configuration\keystore</literal>. If you wish to use a different
	keystore, pass this filename in as the value for the <literal>-keystore</literal> argument and the
	keystore password in as the value for the <literal>-keystorePassword</literal> argument:
	</para>
	<screen>prompt> cd %SERVER_HOME%
	prompt> bin\startup.bat -keystore customKeystore -keystorePassword customKeystorePassword</screen>
	<para>
	This will start the @tomcat.product.name@ with JMX enabled for remote attach using an SSL certificate from
	<literal>customKeystore</literal> with a password of <literal>customKeystorePassword</literal>.
	</para>
	</section>
	</section>
	<section id="starting-stopping-configuration-directory">
	<title>Starting with a Custom Configuration Directory</title>
	<para>
	Use the <literal>-configDir</literal> option to specify an alternate <literal>configuration</literal> directory, different from the
	default <literal>SERVER_HOME/configuration</literal> directory. This option allows you to use the same @tomcat.product.name@
	installation to run multiple instances of @tomcat.product.name.short@. 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 @tomcat.product.name.short@.
	</para>
	<para>
	If you specify a relative path for the <literal>-configDir</literal> parameter,
	the startup script interprets the path as relative to the root of the @tomcat.product.name@ installation,
	and not relative to the directory from which you execute the <literal>startup</literal> script.
	</para>
	<para>
	See <link linkend="alternate-serviceability-work">Alternate <literal>serviceability</literal> and <literal>work</literal>
	Directories</link> for a known issue related to specifying an alternate <literal>configuration</literal> directory.
	</para>
	<section>
	<title>Linux</title>
	To start @tomcat.product.name@ using a configuration directory of <literal>/configuration/node1</literal>:
	<screen>prompt$ cd $SERVER_HOME
	prompt$ bin/startup.sh -configDir /configuration/node1</screen>
	</section>
	<section>
	<title>Windows</title>
	To start @tomcat.product.name@ using a configuration directory of <literal>c:\configuration\node1</literal>:
	<screen>prompt> cd %SERVER_HOME%
	prompt> bin\startup.bat -configDir c:\configuration\node1</screen>
	</section>
	</section>
	<section>
	<title>Stopping @tomcat.product.name@</title>
	<section>
	<title>Linux</title>
	<para>
	To stop a running instance of @tomcat.product.name@, start a new terminal window and run the <literal>shutdown.sh</literal> script:
	</para>
	<screen>prompt$ cd $SERVER_HOME
	prompt$ bin/shutdown.sh</screen>
	<para>
	To stop a running instance of @tomcat.product.name@ immediately, bypassing normal shutdown
	processing, run <literal>shutdown.sh</literal> with the <literal>-immediate</literal> option:
	</para>
	<screen>prompt$ cd $SERVER_HOME
	prompt$ bin/shutdown.sh -immediate</screen>
	<para>
	If, when you started the Web Server instance, you used the <literal>-jmxport</literal> option to specify a non-default JMX port number,
	then you must pass this port number to the <literal>-jmxport</literal> of the <literal>shutdown.sh</literal> script
	to gracefully shut it down.
	For example, if you specified <literal>9090</literal> as the JMX port, use the following to shut down the Web Server instance:
	</para>
	<screen>prompt$ cd $SERVER_HOME
	prompt$ bin/shutdown.sh -jmxport 9090</screen>
	</section>
	<section>
	<title>Microsoft Windows</title>
	<para>
	To stop a running instance of @tomcat.product.name@, start a new console window and run the <literal>shutdown.bat</literal> script:
	</para>
	<screen>prompt> cd %SERVER_HOME%
	prompt> bin\shutdown.bat</screen>
	<para>
	To stop a running instance of @tomcat.product.name@ immediately, bypassing normal shutdown
	processing, run <literal>shutdown.bat</literal> with the <literal>-immediate</literal> option:
	</para>
	<screen>prompt> cd %SERVER_HOME%
	prompt> bin\shutdown.bat -immediate</screen>
	<para>
	If, when you started the Web Server instance, you used the <literal>-jmxport</literal> option to specify a non-default JMX port number,
	then you must pass this port number to the <literal>-jmxport</literal> of the <literal>shutdown.bat</literal> script to gracefully shut it down.
	For example, if you specified <literal>9090</literal> as the JMX port, use the following to shut down the Web Server instance:
	</para>
	<screen>prompt> cd %SERVER_HOME%
	prompt> bin\shutdown.bat -jmxport 9090</screen>
	</section>
	</section>
	<section id="cleaning-without-starting">
	<title>Cleaning @tomcat.product.name@ without Starting it</title>
	<para>
	When you clean @tomcat.product.name@, the startup script removes the <literal>SERVER_HOME/work</literal> directory (and hence all
	running applications) as well as all trace, log and dump files. It leaves the
	<literal>SERVER_HOME/repository</literal> and <literal>SERVER_HOME/pickup</literal> directories untouched,
	which means that any applications previously hot deployed will be automatically reinstalled next time the Web Server is started.
	</para>
	<para>
	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.
	</para>
	<para>
	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 <link linkend="windows-deletion">Problem Deleting Installation Directory under Windows</link> for more details.
	</para>
	<section>
	<title>Linux</title>
	<para>
	To clean @tomcat.product.name@, open a terminal window and run <literal>startup.sh -clean -noStart</literal>:
	</para>
	<screen>prompt$ cd $SERVER_HOME
	prompt$ bin/startup.sh -clean -noStart</screen>
	</section>
	<section>
	<title>Microsoft Windows</title>
	<para>
	To clean @tomcat.product.name@, open a command window and run <literal>startup.bat -clean -noStart</literal>:
	</para>
	<screen>prompt> cd %SERVER_HOME%
	prompt> bin\startup.bat -clean -noStart</screen>
	</section>
	</section>
	<section id="equinox-launcher">
	<title>Using Equinox Launcher</title>
	<para>
	Since version 3.5 @project.name@ 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.
	<important>The Equinox Launcher arguments must be placed at the end of the startup call. Here's an example
	<screen>./startup.sh "virgo-args" "equinox-launcher-args"
	./startup.sh -clean -console 2222</screen>
	</important>
	</para>
	<para>
	A full list of the accepted Equinox Launcher arguments is available at <ulink url="http://help.eclipse.org/indigo/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fmisc%2Fruntime-options.html">help.eclipse.org</ulink>.
	</para>
	</section>

	</chapter>