You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2013/08/30 09:38:50 UTC
svn commit: r1518900 [2/2] - /tomcat/trunk/webapps/docs/
Modified: tomcat/trunk/webapps/docs/ssl-howto.xml
URL: http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/ssl-howto.xml?rev=1518900&r1=1518899&r2=1518900&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/ssl-howto.xml (original)
+++ tomcat/trunk/webapps/docs/ssl-howto.xml Fri Aug 30 07:38:49 2013
@@ -36,33 +36,29 @@
<section name="Quick Start">
- <blockquote><em>
- <p>The description below uses the variable name $CATALINA_BASE to refer the
+
+ <p><em>The description below uses the variable name $CATALINA_BASE to refer the
base directory against which most relative paths are resolved. If you have
not configured Tomcat for multiple instances by setting a CATALINA_BASE
directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
- the directory into which you have installed Tomcat.</p>
- </em></blockquote>
+ the directory into which you have installed Tomcat.</em></p>
+
<p>To install and configure SSL support on Tomcat, you need to follow
these simple steps. For more information, read the rest of this HOW-TO.</p>
<ol>
-<li>Create a keystore file to store the server's private key and
-self-signed certificate by executing the following command:
+<li><p>Create a keystore file to store the server's private key and
+self-signed certificate by executing the following command:</p>
<p>Windows:</p>
-<source>
-%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
-</source>
+<source>%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA</source>
<p>Unix:</p>
-<source>
-$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
-</source>
-<p></p>
- and specify a password value of "changeit".</li><br/><br/>
-<li>Uncomment the "SSL HTTP/1.1 Connector" entry in
+<source>$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA</source>
+
+<p>and specify a password value of "changeit".</p></li>
+<li><p>Uncomment the "SSL HTTP/1.1 Connector" entry in
<code>$CATALINA_BASE/conf/server.xml</code> and modify as described in
- the <a href="#Configuration">Configuration section</a> below.</li>
- <br/><br/>
+ the <a href="#Configuration">Configuration section</a> below.</p></li>
+
</ol>
@@ -213,24 +209,19 @@ Note that OpenSSL often adds readable co
they exist before importing the key using <code>keytool</code>.
</p>
<p>To import an existing certificate signed by your own CA into a PKCS12
-keystore using OpenSSL you would execute a command like:
+keystore using OpenSSL you would execute a command like:</p>
<source>openssl pkcs12 -export -in mycert.crt -inkey mykey.key \
-out mycert.p12 -name tomcat -CAfile myCA.crt \
- -caname root -chain
-</source>
-For more advanced cases, consult the <a href="http://www.openssl.org/">OpenSSL
+ -caname root -chain</source>
+<p>For more advanced cases, consult the <a href="http://www.openssl.org/">OpenSSL
documentation</a>.
</p>
<p>To create a new keystore from scratch, containing a single self-signed
Certificate, execute the following from a terminal command line:</p>
<p>Windows:</p>
-<source>
-%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
-</source>
+<source>%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA</source>
<p>Unix:</p>
-<source>
-$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
-</source>
+<source>$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA</source>
<p>(The RSA algorithm should be preferred as a secure algorithm, and this
also ensures general compatibility with other servers and components.)</p>
@@ -243,15 +234,11 @@ to the <code>keytool</code> command show
reflect this new location in the <code>server.xml</code> configuration file,
as described later. For example:</p>
<p>Windows:</p>
-<source>
-%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA \
- -keystore \path\to\my\keystore
-</source>
+<source>%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA \
+ -keystore \path\to\my\keystore</source>
<p>Unix:</p>
-<source>
-$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA \
- -keystore /path/to/my/keystore
-</source>
+<source>$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA \
+ -keystore /path/to/my/keystore</source>
<p>After executing this command, you will first be prompted for the keystore
password. The default password used by Tomcat is "<code>changeit</code>"
@@ -281,10 +268,12 @@ Certificate that can be used by your ser
<subsection name="Edit the Tomcat Configuration File">
<p>
Tomcat can use two different implementations of SSL:
+</p>
<ul>
<li>the JSSE implementation provided as part of the Java runtime (since 1.4)</li>
<li>the APR implementation, which uses the OpenSSL engine by default.</li>
</ul>
+<p>
The exact configuration details depend on which implementation is being used.
The implementation used by Tomcat is chosen automatically unless it is overriden as described below.
If the installation uses <a href="apr.html">APR</a>
@@ -296,46 +285,38 @@ then it will use the APR SSL implementat
To avoid auto configuration you can define which implementation to use by specifying a classname
in the <b>protocol</b> attribute of the Connector.<br/>
To define a Java (JSSE) connector, regardless of whether the APR library is loaded or not do:
-<source>
-<!-- Define a blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 -->
-<Connector protocol="org.apache.coyote.http11.Http11Protocol"
- port="8443" .../>
-
-<!-- Define a non-blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 -->
-<Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
- port="8443" .../>
-</source>
-Alternatively, to specify an APR connector (the APR library must be available) use:
-<source>
-<!-- Define a APR SSL Coyote HTTP/1.1 Connector on port 8443 -->
-<Connector protocol="org.apache.coyote.http11.Http11AprProtocol"
- port="8443" .../>
-</source>
-
</p>
-
-<p>If you are using APR, you have the option of configuring an alternative engine to OpenSSL.
-<source>
-<Listener className="org.apache.catalina.core.AprLifecycleListener"
- SSLEngine="someengine" SSLRandomSeed="somedevice" />
-</source>
-The default value is
-<source>
-<Listener className="org.apache.catalina.core.AprLifecycleListener"
- SSLEngine="on" SSLRandomSeed="builtin" />
-</source>
+<source><![CDATA[<!-- Define a blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 -->
+<Connector protocol="org.apache.coyote.http11.Http11Protocol"
+ port="8443" .../>
+
+<!-- Define a non-blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 -->
+<Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
+ port="8443" .../>]]></source>
+<p>Alternatively, to specify an APR connector (the APR library must be available) use:</p>
+<source><![CDATA[<!-- Define a APR SSL Coyote HTTP/1.1 Connector on port 8443 -->
+<Connector protocol="org.apache.coyote.http11.Http11AprProtocol"
+ port="8443" .../>]]></source>
+
+
+<p>If you are using APR, you have the option of configuring an alternative engine to OpenSSL.</p>
+<source><![CDATA[<Listener className="org.apache.catalina.core.AprLifecycleListener"
+ SSLEngine="someengine" SSLRandomSeed="somedevice" />]]></source>
+<p>The default value is</p>
+<source><![CDATA[<Listener className="org.apache.catalina.core.AprLifecycleListener"
+ SSLEngine="on" SSLRandomSeed="builtin" />]]></source>
+<p>
So to use SSL under APR, make sure the SSLEngine attribute is set to something other than <code>off</code>.
The default value is <code>on</code> and if you specify another value, it has to be a valid engine name.
<br/>
If you haven't compiled in SSL support into your Tomcat Native library, then you can turn this initialization off
-<source>
-<Listener className="org.apache.catalina.core.AprLifecycleListener"
- SSLEngine="off" />
-</source>
+</p>
+<source><![CDATA[<Listener className="org.apache.catalina.core.AprLifecycleListener"
+ SSLEngine="off" />]]></source>
+<p>
SSLRandomSeed allows to specify a source of entropy. Productive system needs a reliable source of entropy
but entropy may need a lot of time to be collected therefore test systems could use no blocking entropy
sources like "/dev/urandom" that will allow quicker starts of Tomcat.
-
</p>
<p>The final step is to configure the Connector in the
@@ -346,31 +327,27 @@ for an SSL connector is included in the
file installed with Tomcat. To configure an SSL connector that uses JSSE, you
will need to remove the comments and edit it so it looks something like
this:</p>
-<source>
-<!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
-<Connector
+<source><![CDATA[<!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
+<Connector
protocol="HTTP/1.1"
port="8443" maxThreads="200"
scheme="https" secure="true" SSLEnabled="true"
keystoreFile="${user.home}/.keystore" keystorePass="changeit"
- clientAuth="false" sslProtocol="TLS"/>
-</source>
+ clientAuth="false" sslProtocol="TLS"/>]]></source>
<p>
The example above will throw an error if you have the APR and the Tomcat
Native libraries in your path, as Tomcat will try to use the APR connector.
The APR connector uses different attributes for many SSL settings,
- particularly keys and certificates. An example of an APR configuration is:
-<source>
-<!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
-<Connector
+ particularly keys and certificates. An example of an APR configuration is:</p>
+<source><![CDATA[<!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
+<Connector
protocol="HTTP/1.1"
port="8443" maxThreads="200"
scheme="https" secure="true" SSLEnabled="true"
SSLCertificateFile="/usr/local/ssl/server.crt"
SSLCertificateKeyFile="/usr/local/ssl/server.pem"
- SSLVerifyClient="optional" SSLProtocol="TLSv1"/>
-</source>
-</p>
+ SSLVerifyClient="optional" SSLProtocol="TLSv1"/>]]></source>
+
<p>You will note that the example SSL connector elements are commented out by
default. You can either remove the comment tags from around the the example SSL
@@ -378,7 +355,7 @@ connector you wish to use or add a new C
case, you will need to configure the SSL Connector for your requirements
and environment. The configuration options and information on which attributes
are mandatory, are documented in the SSL Support section of the
-<a href="config/http.html#SSL Support">HTTP connector</a> configuration
+<a href="config/http.html#SSL_Support">HTTP connector</a> configuration
reference. Make sure that you use the correct attributes for the connector you
are using. The BIO and NIO connectors use JSSE whereas the APR/native connector
uses APR.</p>
@@ -390,20 +367,18 @@ change this to any port number you wish
(outside the scope of this document) is necessary to run Tomcat on port
numbers lower than 1024 on many operating systems.</p>
- <blockquote><em>
- <p>If you change the port number here, you should also change the
+
+ <p><em>If you change the port number here, you should also change the
value specified for the <code>redirectPort</code> attribute on the
non-SSL connector. This allows Tomcat to automatically redirect
users who attempt to access a page with a security constraint specifying
- that SSL is required, as required by the Servlet Specification.</p>
- </em></blockquote>
+ that SSL is required, as required by the Servlet Specification.</em></p>
+
<p>After completing these configuration changes, you must restart Tomcat as
you normally do, and you should be in business. You should be able to access
any web application supported by Tomcat via SSL. For example, try:</p>
-<source>
-https://localhost:8443
-</source>
+<source>https://localhost:8443</source>
<p>and you should see the usual Tomcat splash page (unless you have modified
the ROOT web application). If this does not work, the following section
contains some troubleshooting tips.</p>
@@ -474,45 +449,45 @@ SSL communications, and what to do about
<li>When Tomcat starts up, I get an exception like
"java.io.FileNotFoundException: {some-directory}/{some-file} not found".
- <blockquote>
+
<p>A likely explanation is that Tomcat cannot find the keystore file
where it is looking. By default, Tomcat expects the keystore file to
be named <code>.keystore</code> in the user home directory under which
Tomcat is running (which may or may not be the same as yours :-). If
the keystore file is anywhere else, you will need to add a
<code>keystoreFile</code> attribute to the <code><Factory></code>
- element in the <a href="#Edit the Tomcat Configuration File">Tomcat
+ element in the <a href="#Edit_the_Tomcat_Configuration_File">Tomcat
configuration file</a>.</p>
- </blockquote></li>
+ </li>
<li>When Tomcat starts up, I get an exception like
"java.io.FileNotFoundException: Keystore was tampered with, or
password was incorrect".
- <blockquote>
+
<p>Assuming that someone has not <em>actually</em> tampered with
your keystore file, the most likely cause is that Tomcat is using
a different password than the one you used when you created the
keystore file. To fix this, you can either go back and
- <a href="#Prepare the Certificate Keystore">recreate the keystore
+ <a href="#Prepare_the_Certificate_Keystore">recreate the keystore
file</a>, or you can add or update the <code>keystorePass</code>
attribute on the <code><Connector></code> element in the
- <a href="#Edit the Tomcat Configuration File">Tomcat configuration
+ <a href="#Edit_the_Tomcat_Configuration_File">Tomcat configuration
file</a>. <strong>REMINDER</strong> - Passwords are case sensitive!</p>
- </blockquote></li>
+ </li>
<li>When Tomcat starts up, I get an exception like
"java.net.SocketException: SSL handshake errorjavax.net.ssl.SSLException: No
available certificate or key corresponds to the SSL cipher suites which are
enabled."
- <blockquote>
+
<p>A likely explanation is that Tomcat cannot find the alias for the server
key within the specified keystore. Check that the correct
<code>keystoreFile</code> and <code>keyAlias</code> are specified in the
<code><Connector></code> element in the
- <a href="#Edit the Tomcat Configuration File">Tomcat configuration file</a>.
+ <a href="#Edit_the_Tomcat_Configuration_File">Tomcat configuration file</a>.
<strong>REMINDER</strong> - <code>keyAlias</code> values may be case
sensitive!</p>
- </blockquote></li>
+ </li>
</ul>
@@ -527,7 +502,7 @@ information, at
<section name="Using the SSL for session tracking in your application">
<p>This is a new feature in the Servlet 3.0 specification. Because it uses the
SSL session ID associated with the physical client-server connection there
- are some limitations. They are:
+ are some limitations. They are:</p>
<ul>
<li>Tomcat must have a connector with the attribute
<strong>isSecure</strong> set to <code>true</code>.</li>
@@ -538,14 +513,12 @@ information, at
session replication as the SSL session IDs will be different on each
node.</li>
</ul>
- </p>
<p>
To enable SSL session tracking you need to use a context listener to set the
tracking mode for the context to be just SSL (if any other tracking mode is
- enabled, it will be used in preference). It might look something like:
- <source>
-package org.apache.tomcat.example;
+ enabled, it will be used in preference). It might look something like:</p>
+ <source><![CDATA[package org.apache.tomcat.example;
import java.util.EnumSet;
@@ -564,15 +537,14 @@ public class SessionTrackingModeListener
@Override
public void contextInitialized(ServletContextEvent event) {
ServletContext context = event.getServletContext();
- EnumSet<SessionTrackingMode> modes =
+ EnumSet<SessionTrackingMode> modes =
EnumSet.of(SessionTrackingMode.SSL);
context.setSessionTrackingModes(modes);
}
-}
- </source>
- </p>
+}]]></source>
+
<p>Note: SSL session tracking is implemented for the BIO and NIO connectors.
It is not yet implemented for the APR connector.</p>
@@ -580,19 +552,16 @@ public class SessionTrackingModeListener
<section name="Miscellaneous Tips and Bits">
-<p>To access the SSL session ID from the request, use:<br />
+<p>To access the SSL session ID from the request, use:</p>
- <code>
- String sslID = (String)request.getAttribute("javax.servlet.request.ssl_session_id");
- </code>
-<br />
+ <source><![CDATA[String sslID = (String)request.getAttribute("javax.servlet.request.ssl_session_id");]]></source>
+<p>
For additional discussion on this area, please see
<a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=22679">Bugzilla</a>.
</p>
- <p>To terminate an SSL session, use:
- <source>
-// Standard HTTP session invalidation
+ <p>To terminate an SSL session, use:</p>
+ <source><![CDATA[// Standard HTTP session invalidation
session.invalidate();
// Invalidate the SSL Session
@@ -603,8 +572,8 @@ mgr.invalidateSession();
// Close the connection since the SSL session will be active until the connection
// is closed
-response.setHeader("Connection", "close");
- </source>
+response.setHeader("Connection", "close");]]></source>
+ <p>
Note that this code is Tomcat specific due to the use of the
SSLSessionManager class. This is currently only available for the BIO and
NIO connectors, not the APR/native connector.
Modified: tomcat/trunk/webapps/docs/virtual-hosting-howto.xml
URL: http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/virtual-hosting-howto.xml?rev=1518900&r1=1518899&r2=1518900&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/virtual-hosting-howto.xml (original)
+++ tomcat/trunk/webapps/docs/virtual-hosting-howto.xml Fri Aug 30 07:38:49 2013
@@ -50,12 +50,10 @@
At the simplest, edit the <a href="config/engine.html">Engine</a> portion
of your <code>server.xml</code> file to look like this:
</p>
- <source>
-<Engine name="Catalina" defaultHost="ren">
- <Host name="ren" appBase="renapps"/>
- <Host name="stimpy" appBase="stimpyapps"/>
-</Engine>
- </source>
+ <source><![CDATA[<Engine name="Catalina" defaultHost="ren">
+ <Host name="ren" appBase="renapps"/>
+ <Host name="stimpy" appBase="stimpyapps"/>
+</Engine>]]></source>
<p>
Note that the directory structures under the appBase for each host should
not overlap each other.
@@ -71,10 +69,8 @@
<p>
Create directories for each of the virtual hosts:
</p>
- <source>
-mkdir $CATALINA_HOME/renapps
-mkdir $CATALINA_HOME/stimpyapps
- </source>
+ <source>mkdir $CATALINA_HOME/renapps
+mkdir $CATALINA_HOME/stimpyapps</source>
</section>
<section name="Configuring Your Contexts">
@@ -106,10 +102,8 @@ mkdir $CATALINA_HOME/stimpyapps
Create a structure under <code>$CATALINA_HOME/conf/Catalina</code>
corresponding to your virtual hosts, e.g.:
</p>
- <source>
-mkdir $CATALINA_HOME/conf/Catalina/ren
-mkdir $CATALINA_HOME/conf/Catalina/stimpy
- </source>
+ <source>mkdir $CATALINA_HOME/conf/Catalina/ren
+mkdir $CATALINA_HOME/conf/Catalina/stimpy</source>
<p>
Note that the ending directory name "Catalina" represents the
<code>name</code> attribute of the
@@ -118,19 +112,15 @@ mkdir $CATALINA_HOME/conf/Catalina/stimp
<p>
Now, for your default webapps, add:
</p>
- <source>
-$CATALINA_HOME/conf/Catalina/ren/ROOT.xml
-$CATALINA_HOME/conf/Catalina/stimpy/ROOT.xml
- </source>
+ <source>$CATALINA_HOME/conf/Catalina/ren/ROOT.xml
+$CATALINA_HOME/conf/Catalina/stimpy/ROOT.xml</source>
<p>
If you want to use the Tomcat manager webapp for each host, you'll also
need to add it here:
</p>
- <source>
-cd $CATALINA_HOME/conf/Catalina
+ <source>cd $CATALINA_HOME/conf/Catalina
cp localhost/manager.xml ren/
-cp localhost/manager.xml stimpy/
- </source>
+cp localhost/manager.xml stimpy/</source>
</subsection>
<subsection name="Further Information">
<p>
Modified: tomcat/trunk/webapps/docs/windows-auth-howto.xml
URL: http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/windows-auth-howto.xml?rev=1518900&r1=1518899&r2=1518900&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/windows-auth-howto.xml (original)
+++ tomcat/trunk/webapps/docs/windows-auth-howto.xml Fri Aug 30 07:38:49 2013
@@ -39,14 +39,14 @@ the user being authenticated are part of
authenticated automatically, the client machine used by the user must also be
part of the domain.</p>
<p>There are several options for implementing integrated Windows authentication
-with Apache Tomcat. They are:
+with Apache Tomcat. They are:</p>
<ul>
<li>Built-in Tomcat support.</li>
<li>Use a third party library such as Waffle.</li>
<li>Use a reverse proxy that supports Windows authentication to perform the
authentication step such as IIS or httpd.</li>
</ul>
-The configuration of each of these options is discussed in the following
+<p>The configuration of each of these options is discussed in the following
sections.</p>
</section>
Modified: tomcat/trunk/webapps/docs/windows-service-howto.xml
URL: http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/windows-service-howto.xml?rev=1518900&r1=1518899&r2=1518900&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/windows-service-howto.xml (original)
+++ tomcat/trunk/webapps/docs/windows-service-howto.xml Fri Aug 30 07:38:49 2013
@@ -44,55 +44,55 @@
services.
</p>
<p>The available command line options are:</p>
-<p>
- <table>
- <tr><th>//ES//</th>
+
+ <table class="defaultTable">
+ <tr><td><b>//ES//</b></td>
<td>Edit service configuration</td>
<td>This is the default operation. It is called if the no option is
provided but the executable is renamed to <b>servicenameW.exe</b></td>
</tr>
- <tr><th>//MS//</th>
+ <tr><td><b>//MS//</b></td>
<td>Monitor service</td>
<td>Put the icon in the system tray</td>
</tr>
</table>
-</p>
+
</section>
<section name="Command line arguments">
<p>
Each command line directive is in the form of <b>//XX//ServiceName</b>
</p>
<p>The available command line options are:</p>
-<p>
- <table>
- <tr><th>//TS//</th>
+
+ <table class="defaultTable">
+ <tr><td><b>//TS//</b></td>
<td>Run the service as console application</td>
<td>This is the default operation. It is called if the no option is
provided. The ServiceName is the name of the executable without
exe suffix, meaning Tomcat7</td>
</tr>
- <tr><th>//RS//</th>
+ <tr><td><b>//RS//</b></td>
<td>Run the service</td>
<td>Called only from ServiceManager</td>
</tr>
- <tr><th>//SS//</th>
+ <tr><td><b>//SS//</b></td>
<td>Stop the service</td>
<td></td>
</tr>
- <tr><th>//US//</th>
+ <tr><td><b>//US//</b></td>
<td>Update service parameters</td>
<td></td>
</tr>
- <tr><th>//IS//</th>
+ <tr><td><b>//IS//</b></td>
<td>Install service</td>
<td></td>
</tr>
- <tr><th>//DS//</th>
+ <tr><td><b>//DS//</b></td>
<td>Delete service</td>
<td>Stops the service if running</td>
</tr>
</table>
-</p>
+
</section>
<section name="Command line parameters">
<p>
@@ -101,15 +101,14 @@
be appended to the existing option.
If the environment variable with the same name as command line parameter but
prefixed with <code>PR_</code> exists it will take precedence.
- For example:
+ For example:</p>
<source>set PR_CLASSPATH=xx.jar</source>
-</p>
-<p>is equivalent to providing
+
+<p>is equivalent to providing</p>
<source>--Classpath=xx.jar</source>
-</p>
<p> as command line parameter.</p>
-<p>
- <table>
+
+ <table class="defaultTable">
<tr>
<th>ParameterName</th>
<th>Default</th>
@@ -202,7 +201,6 @@
<td>Thread stack size in KB</td>
</tr>
<tr>
- <tr>
<td>--StartImage</td>
<td></td>
<td>Executable that will be run.</td>
@@ -234,6 +232,7 @@
<td>executable</td>
<td>Can one of <b>jvm</b> <b>java</b> or <b>exe</b></td>
</tr>
+ <tr>
<td>--StopImage</td>
<td></td>
<td>Executable that will be run on Stop service signal.</td>
@@ -298,7 +297,7 @@
<td>Redirected stderr filename</td>
</tr>
</table>
-</p>
+
</section>
<section name="Installing services">
<p>
@@ -309,77 +308,70 @@ a user to use for the installation of th
</p>
<p>
<strong>NOTE:</strong> On Windows Vista or any other operating system with User
-Account Control (UAC) you must either disable UAC or right-click on cmd.exe and
-select "Run as administrator" in order to run this script. If UAC is enabled
-neither being logged on with an Administrator account, nor using the
+Account Control (UAC) enabled you must
+<!-- either disable UAC or [NOTE: Disabling UAC is mostly not a good idea,
+except on Windows Server OSes] -->
+right-click on cmd.exe and
+select "Run as administrator" in order to run this script. On Windows 8 (or later) or
+Windows Server 2012 (or later), you can open an elevated command prompt
+for the current directory from the explorer
+by clicking on the "File" menu bar.<br/>
+If UAC is enabled,
+neither being logged on with an Administrator account nor using the
<code>/user</code> switch is sufficient.
</p>
-<p>
-<source>
-Install the service named 'Tomcat7'
-C:\> service.bat install
-</source>
-</p>
+
+<source>Install the service named 'Tomcat7'
+C:\> service.bat install</source>
+
<p>There is a 2nd optional parameter that lets you specify the name of the
service, as displayed in Windows services.</p>
-<p>
-<source>
-Install the service named 'MyService'
-C:\> service.bat install MyService
-</source>
-</p>
+
+<source>Install the service named 'MyService'
+C:\> service.bat install MyService</source>
+
<p>
If using tomcat7.exe, you need to use the <b>//IS//</b> parameter.</p>
-<p>
-<source>
-Install the service named 'Tomcat7'
+
+<source>Install the service named 'Tomcat7'
C:\> tomcat7 //IS//Tomcat7 --DisplayName="Apache Tomcat 7" \
C:\> --Install="C:\Program Files\Tomcat\bin\tomcat7.exe" --Jvm=auto \
C:\> --StartMode=jvm --StopMode=jvm \
C:\> --StartClass=org.apache.catalina.startup.Bootstrap --StartParams=start \
-C:\> --StopClass=org.apache.catalina.startup.Bootstrap --StopParams=stop
-</source>
-</p>
+C:\> --StopClass=org.apache.catalina.startup.Bootstrap --StopParams=stop</source>
+
</section>
<section name="Updating services">
<p>
To update the service parameters, you need to use the <b>//US//</b> parameter.
</p>
-<p>
-<source>
-Update the service named 'Tomcat7'
+
+<source>Update the service named 'Tomcat7'
C:\> tomcat7 //US//Tomcat7 --Description="Apache Tomcat Server - http://tomcat.apache.org/ " \
-C:\> --Startup=auto --Classpath=%JAVA_HOME%\lib\tools.jar;%CATALINA_HOME%\bin\bootstrap.jar
-</source>
-</p>
+C:\> --Startup=auto --Classpath=%JAVA_HOME%\lib\tools.jar;%CATALINA_HOME%\bin\bootstrap.jar</source>
+
<p>If you gave the service an optional name, you need to specify it like this:
</p>
-<p>
-<source>
-Update the service named 'MyService'
+
+<source>Update the service named 'MyService'
C:\> tomcat7 //US//MyService --Description="Apache Tomcat Server - http://tomcat.apache.org/ " \
-C:\> --Startup=auto --Classpath=%JAVA_HOME%\lib\tools.jar;%CATALINA_HOME%\bin\bootstrap.jar
-</source>
-</p>
+C:\> --Startup=auto --Classpath=%JAVA_HOME%\lib\tools.jar;%CATALINA_HOME%\bin\bootstrap.jar</source>
+
</section>
<section name="Removing services">
<p>
To remove the service, you need to use the <b>//DS//</b> parameter.<br/>
If the service is running it will be stopped and then deleted.</p>
-<p>
-<source>
-Remove the service named 'Tomcat7'
-C:\> tomcat7 //DS//Tomcat7
-</source>
-</p>
+
+<source>Remove the service named 'Tomcat7'
+C:\> tomcat7 //DS//Tomcat7</source>
+
<p>If you gave the service an optional name, you need to specify it like this:
</p>
-<p>
-<source>
-Remove the service named 'MyService'
-C:\> tomcat7 //DS//MyService
-</source>
-</p>
+
+<source>Remove the service named 'MyService'
+C:\> tomcat7 //DS//MyService</source>
+
</section>
<section name="Debugging services">
<p>
@@ -388,14 +380,12 @@ The service shutdown can be initiated by
<b>CTRL+BREAK</b>.
If you rename the tomcat7.exe to testservice.exe then you can just execute the
testservice.exe and this command mode will be executed by default.</p>
-<p>
-<source>
-Run the service named 'Tomcat7' in console mode
+
+<source>Run the service named 'Tomcat7' in console mode
C:\> tomcat7 //TS//Tomcat7 [additional arguments]
Or simply execute:
-C:\> tomcat7
-</source>
-</p>
+C:\> tomcat7</source>
+
</section>
<section name="Multiple Instances">
<p>
@@ -425,32 +415,28 @@ from CATALINA_HOME\conf.</p>
<p>
You must edit CATALINA_BASE\conf\server.xml to specify a unique IP/port for the
instance to listen on. Find the line that contains
-<pre><Connector port="8080" ...</pre> and add an address attribute and/or
+<code><Connector port="8080" ...</code> and add an address attribute and/or
update the port number so as to specify a unique IP/port combination.</p>
<p>
To install an instance, first set the CATALINA_HOME environment variable to the
name of the Tomcat installation directory. Then create a second environment
variable CATALINA_BASE and point this to the instance folder. Then run "service
install" command specifying a service name.</p>
-<p>
-<source>
-set CATALINA_HOME=c:\tomcat_7
+
+<source>set CATALINA_HOME=c:\tomcat_7
set CATALINA_BASE=c:\tomcat_7\instances\instance1
-service install instance1
-</source>
-</p>
+service install instance1</source>
+
<p>
To modify the service settings, you can run <b>tomcat7w //ES//instance1</b>.
</p>
<p>
For additional instances, create additional instance folder, update the
CATALINA_BASE environment variable, and run the service install again.</p>
-<p>
-<source>
-set CATALINA_BASE=c:\tomcat_7\instances\instance2
-service install instance2
-</source>
-</p>
+
+<source>set CATALINA_BASE=c:\tomcat_7\instances\instance2
+service install instance2</source>
+
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org