| <html><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Configuring the Embedded Tomcat Servlet Container</title><meta content="DocBook XSL Stylesheets V1.76.0" name="generator"><link rel="home" href="index.html" title="Virgo User Guide"><link rel="up" href="ch13.html" title="Chapter 13. Configuration"><link rel="prev" href="ch13s06.html" title="Configuring the Kernel and User Region"><link rel="next" href="ch13s08.html" title="Configuring the Web Integration Layer"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><td align="left" width="20%"><a accesskey="p" href="ch13s06.html">Prev</a> </td><th align="center" width="60%"> </th><td align="right" width="20%"> <a accesskey="n" href="ch13s08.html">Next</a></td></tr></table><hr></div><div class="section" title="Configuring the Embedded Tomcat Servlet Container"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-tomcat"></a>Configuring the Embedded Tomcat Servlet Container</h2></div></div></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Virgo Nano uses the default Gemini Web configuration. The details described below may still apply.</div><p> |
| Virgo |
| embeds an OSGi-enhanced version of the <a class="ulink" href="http://tomcat.apache.org/" target="_top">Tomcat Servlet Container</a> |
| in order to provide support for deploying Java EE WARs and OSGi <span class="emphasis"><em>Web Application Bundles</em></span>. |
| You configure the embedded Servlet container using the standard Apache Tomcat configuration. The main difference is that the configuration file is called <code class="filename">tomcat-server.xml</code> rather than <code class="literal">server.xml</code>. As with the other Virgo configuration files, the <code class="literal">tomcat-server.xml</code> file is located in the <code class="literal">$SERVER_HOME/configuration</code> directory. |
| Another difference is that not all standard Apache Tomcat configuration is supported in Virgo Server for Apache Tomcat: the restrictions are described in the |
| remainder of this section. |
| </p><p>Here's an extract of the default configuration distributed with the VTS. |
| </p><pre class="programlisting"><?xml version='1.0' encoding='utf-8'?> |
| <Server port="8005" shutdown="SHUTDOWN"> |
| |
| <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" /> |
| <Listener className="org.apache.catalina.core.JasperListener" /> |
| <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" /> |
| |
| <Listener className="org.eclipse.virgo.web.tomcat.ServerLifecycleLoggingListener"/> |
| |
| <Service name="Catalina"> |
| <Connector port="8080" protocol="HTTP/1.1" |
| connectionTimeout="20000" |
| redirectPort="8443" /> |
| |
| <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" |
| maxThreads="150" scheme="https" secure="true" |
| clientAuth="false" sslProtocol="TLS" |
| keystoreFile="configuration/keystore" |
| keystorePass="changeit"/> |
| |
| <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" /> |
| |
| <Engine name="Catalina" defaultHost="localhost"> |
| <Realm className="org.apache.catalina.realm.JAASRealm" appName="virgo-kernel" |
| userClassNames="org.eclipse.virgo.kernel.authentication.User" |
| roleClassNames="org.eclipse.virgo.kernel.authentication.Role"/> |
| |
| <Host name="localhost" appBase="webapps" |
| unpackWARs="false" autoDeploy="false" |
| deployOnStartup="false" createDirs="false"> |
| |
| <Valve className="org.apache.catalina.valves.AccessLogValve" directory="serviceability/logs/access" |
| prefix="localhost_access_log." suffix=".txt" pattern="common" resolveHosts="false"/> |
| |
| <Valve className="org.eclipse.virgo.web.tomcat.ApplicationNameTrackingValve"/> |
| </Host> |
| </Engine> |
| </Service> |
| </Server></pre><div class="section" title="Description of the Default Apache Tomcat Configuration"><div class="titlepage"><div><div><h3 class="title"><a name="overview-tomcat-servlet-container"></a>Description of the Default Apache Tomcat Configuration</h3></div></div></div><p> |
| The following bullets describe the main elements and attributes in the default <code class="literal">tomcat-server.xml</code> file; for details about updating this file to further configure the embedded Apache Tomcat server, see the <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/config/index.html" target="_top">Apache Tomcat Configuration Reference</a>. |
| </p><div class="tip" title="Relative paths" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Relative paths</h3><p>If the configured path to a directory or file does not represent an absolute path, Virgo typically interprets it as a path relative to the <code class="filename">$SERVER_HOME</code> directory.</p></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><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 class="listitem"><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 Server for Apache Tomcat and manages server lifecycle logging. |
| </p></li><li class="listitem"><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 class="listitem"><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 class="listitem"><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/configuration/keystore</code>. |
| The <code class="literal">keystorePass</code> attributes specify the password used to access the keystore. |
| </p></li><li class="listitem"><p>The third AJP Connector element represents a Connector component that communicates with a web connector via the AJP protocol. |
| </p></li><li class="listitem"><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 class="listitem"><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-7.0-doc/realm-howto.html" target="_top">Realm Configuration</a>.</p></li><li class="listitem"><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. |
| </p><p> |
| Note that multiple <code class="literal"><Host></code> elements are not supported in Virgo Server for Apache Tomcat. |
| </p></li><li class="listitem"><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" title="Connector Configuration"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-tomcat-connectors"></a>Connector Configuration</h3></div></div></div><p> The Virgo Server for Apache Tomcat supports the configuration of any connector supported by Apache Tomcat. |
| See the default configuration above for syntax examples, and for further details of the configuration properties |
| supported for various <code class="literal"><Connector></code> implementations, |
| consult the official <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/config/http.html" target="_top">Tomcat HTTP Connector</a> documentation. |
| </p><div class="tip" title="Configuring SSL for Tomcat" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Configuring SSL for Tomcat</h3><p> The Virgo Server for Apache Tomcat distribution includes a preconfigured <code class="filename">$SERVER_HOME/configuration/keystore</code> |
| file that contains a single self-signed SSL Certificate. |
| The password for this <code class="filename">keystore</code> file is <code class="literal">changeit</code>. |
| This <code class="filename">keystore</code> file is intended for testing purposes only. |
| For detailed instructions on how to configure Tomcat’s SSL support, |
| consult the official <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html" target="_top">Tomcat SSL Configuration HOW-TO</a>. |
| </p></div></div><div class="section" title="Cluster Configuration"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-tomcat-clustering"></a>Cluster Configuration</h3></div></div></div><p> |
| Virgo Server for Apache Tomcat supports standard Apache Tomcat cluster configuration. |
| By default, clustering of the embedded servlet container is disabled, |
| and the default configuration does not include any clustering information. |
| See <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/cluster-howto.html" target="_top">Tomcat Clustering/Session Replication HOW-TO</a> |
| for detailed information about enabling and configuring clustering. |
| </p></div><div class="section" title="Context Configuration"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-tomcat-contexts"></a>Context Configuration</h3></div></div></div><p> |
| Virgo Server for Apache Tomcat supports standard Apache Tomcat web application context configuration. |
| The <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/config/index.html" target="_top">Apache Tomcat Configuration Reference</a> has a section on |
| <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/config/context.html" target="_top">The Context Container</a> which describes the mechanism that |
| is used in VTS for searching context configuration files and details the context configuration properties. |
| </p><p> |
| Context configuration files may be placed in the following locations, |
| where <code class="literal">[enginename]</code> is the name of Tomcat's engine ('Catalina' by default) and <code class="literal">[hostname]</code> names |
| a virtual host ('localhost' by default), both of which are configured in <code class="literal">tomcat-server.xml</code>: |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> |
| <code class="literal">$SERVER_HOME/configuration/context.xml</code> provides the default context configuration file for all web applications. |
| </p></li><li class="listitem"><p> |
| The <code class="literal">$SERVER_HOME/configuration/[enginename]/[hostname]</code> directory may contain: |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><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 class="listitem"><p> |
| Individual web applications' context configuration files as described in the Apache Tomcat Configuration Reference. |
| For example, the context for a web application with |
| context path <code class="literal">foo</code> may be configured in <code class="literal">foo.xml</code>. |
| </p></li></ul></div><p> |
| </p></li></ul></div><p> |
| </p><p> |
| Note that the following context configuration features are not supported in Virgo Server for Apache Tomcat: |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> |
| Custom class loaders. |
| </p></li><li class="listitem"><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 class="listitem"><p> |
| Specifying the document base directory. |
| </p></li></ul></div><p> |
| </p></div></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ch13s06.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="ch13.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="ch13s08.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%"> </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%"> </td></tr></table></div></body></html> |
