| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>11.3 Configuring the Embedded Tomcat Servlet Container</title><link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"><link rel="home" href="index.html" title="Virgo User Guide"><link rel="up" href="ch11.html" title="11. Configuration"><link rel="prev" href="ch11s02.html" title="11.2 Configuring Serviceability"><link rel="next" href="ch11s04.html" title="11.4 Configuring the Local Provisioning Repository"><!--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="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">11.3 Configuring the Embedded Tomcat Servlet Container</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch11s02.html">Prev</a> </td><th width="60%" align="center">11. Configuration</th><td width="20%" align="right"> <a accesskey="n" href="ch11s04.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-tomcat"></a>11.3 Configuring the Embedded Tomcat Servlet Container</h2></div></div></div><p> |
| Virgo Web Server |
| 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 VWS configuration files, the <code class="literal">tomcat-server.xml</code> file is located in the <code class="literal">$SERVER_HOME/config</code> directory. |
| </p><p>Here's an extract of the default configuration distributed with the VWS. |
| </p><pre class="programlisting"><<span class="hl-tag">?xml version='1.0' encoding='utf-8'?</span>> |
| <<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>> |
| |
| <<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> /> |
| <<span class="hl-tag">Listener</span> <span class="hl-attribute">className</span>=<span class="hl-value">"org.apache.catalina.core.JasperListener"</span> /> |
| <<span class="hl-tag">Listener</span> <span class="hl-attribute">className</span>=<span class="hl-value">"org.apache.catalina.mbeans.ServerLifecycleListener"</span> /> |
| <<span class="hl-tag">Listener</span> <span class="hl-attribute">className</span>=<span class="hl-value">"org.apache.catalina.mbeans.GlobalResourcesLifecycleListener"</span> /> |
| |
| <<span class="hl-tag">Listener</span> <span class="hl-attribute">className</span>=<span class="hl-value">"org.eclipse.virgo.web.tomcat.ServerLifecycleLoggingListener"</span>/> |
| |
| <<span class="hl-tag">Service</span> <span class="hl-attribute">name</span>=<span class="hl-value">"Catalina"</span>> |
| <<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> /> |
| |
| <<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">"config/keystore"</span> |
| <span class="hl-attribute">keystorePass</span>=<span class="hl-value">"changeit"</span>/> |
| |
| <<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> /> |
| |
| <<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>> |
| <<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>/> |
| |
| <<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">"true"</span> <span class="hl-attribute">autoDeploy</span>=<span class="hl-value">"true"</span> |
| <span class="hl-attribute">xmlValidation</span>=<span class="hl-value">"false"</span> <span class="hl-attribute">xmlNamespaceAware</span>=<span class="hl-value">"false"</span>> |
| |
| <<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>/> |
| |
| <<span class="hl-tag">Valve</span> <span class="hl-attribute">className</span>=<span class="hl-value">"org.eclipse.virgo.web.tomcat.ApplicationNameTrackingValve"</span>/> |
| <<span class="hl-tag">/Host</span>> |
| <<span class="hl-tag">/Engine</span>> |
| <<span class="hl-tag">/Service</span>> |
| <<span class="hl-tag">/Server</span>></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-6.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, VWS 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"><Server></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"><Listener></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"><Listener></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 Web Server and manages server lifecycle logging. |
| </p></li><li><p>The <code class="literal"><Service></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"><Service></code> element can have many <code class="literal"><Connector></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"><Engine></code> element for any given <code class="literal"><Service></code> element.</p><p> The sample <code class="literal">tomcat-server.xml</code> file above includes three <code class="literal"><Connector></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"><Engine></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’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/config/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"><Host></code> |
| child element of <code class="literal"><Engine></code>; |
| this host processes requests directed to host names on this servlet container. |
| </p></li><li><p>The <code class="literal"><Realm></code> child element of <code class="literal"><Engine></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-6.0-doc/realm-howto.html" target="_top">Realm Configuration</a>.</p></li><li><p>The <code class="literal"><Host></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. |
| The <code class="literal">xmlValidation</code> attribute specifies that the servlet container does not validate XML files when parsing them, |
| or in other words, it accepts invalid XML. |
| The <code class="literal">xmlNamespaceAware</code> attribute specifies that the servlet container does not take namespaces into account |
| when reading XML files. |
| </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 Web Server 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"><Connector></code> implementations, |
| consult the official <a class="ulink" href="http://tomcat.apache.org/tomcat-6.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 Web Server distribution includes a preconfigured <code class="filename">$SERVER_HOME/config/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’s SSL support, |
| consult the official <a class="ulink" href="http://tomcat.apache.org/tomcat-6.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 Web Server 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-6.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-tomcat-contexts"></a>Context Configuration</h3></div></div></div><p> |
| Virgo Web Server supports standard Apache Tomcat web application context configuration. |
| The <a class="ulink" href="http://tomcat.apache.org/tomcat-6.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-6.0-doc/config/context.html" target="_top">The Context Container</a> which describes the mechanism that |
| is used in VWS 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/config/context.xml</code> provides the default context configuration file for all web applications. |
| </p></li><li><p> |
| The <code class="literal">$SERVER_HOME/config/[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 Web Server: |
| </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><p> |
| See <a class="link" href="apbs04.html" title="B.4 Web Application Context Configuration File Copying">Web Application Context Configuration File Copying</a> for a known issue related to |
| providing a context configuration file inside a web application archive. |
| </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--><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch11s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch11.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch11s04.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">11.2 Configuring Serviceability </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 11.4 Configuring the Local Provisioning Repository</td></tr></table></div></body></html> |