embeds an OSGi-enhanced version of the Tomcat Servlet Container
in order to provide support for deploying Java EE WARs and OSGi Web Application Bundles.
You configure the embedded Servlet container using the standard Apache Tomcat configuration. The main difference is that the configuration file is called
tomcat-server.xml rather than
server.xml. As with the other Virgo configuration files, the
tomcat-server.xml file is located in the
Here's an extract of the default configuration distributed with the VTS.
<?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="config/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>
The following bullets describe the main elements and attributes in the default
tomcat-server.xml file; for details about updating this file to further configure the embedded Apache Tomcat server, see the Apache Tomcat Configuration Reference.
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
The root element of the
tomcat-server.xml file is
<Server>. The attributes of this element represent the characteristics of the entire embedded Tomcat servlet container. The
shutdown 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
port attribute specifies the TCP/IP port number that listens for a shutdown message.
<Listener> 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.
The first four
<Listener> elements configure standard Tomcat lifecycle listeners. The listener implemented by the
org.eclipse.virgo.web.tomcat.ServerLifecycleLoggingListener class is specific to Virgo Tomcat Server and manages server lifecycle logging.
<Service> 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
<Service> element can have many
<Connector> 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
<Engine> element for any given
tomcat-server.xml file above includes three
<Connector> elements: one for the HTTP transport, one for the HTTPS transport, and one for the AJP transport. The file also includes a single
<Engine> element, as required.
The first connector listens for HTTP requests at the
8080 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
The second connector is for HTTPS requests. The TCP/IP port that users specify as the secure connection port is
8443. Be sure that you set the value of the
redirectPort 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
SSLEnabled attribute specifies that SSL is enabled for this connector. The
secure attribute ensures that a call to
request.isSecure() from the connecting client always returns
scheme attribute ensures that a call to
request.getScheme() from the connecting client always returns
https when clients use this connector.
maxThreads 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.
clientAuth 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.
keystoreFile 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
keystorePass attributes specify the password used to access the keystore.
The third AJP Connector element represents a Connector component that communicates with a web connector via the AJP protocol.
The engine has a logical name of
this is the name used in all log and error messages so you can easily identify problems.
The value of the
defaultHost attribute refers to the name of a
child element of
this host processes requests directed to host names on this servlet container.
<Realm> child element of
<Engine> 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.
With the JAASRealm, you can combine practically any conceivable security realm with Tomcat's container managed authentication. For details, see Realm Configuration.
<Host> child element represents a virtual host,
which is an association of a network name for a server (such as
www.mycompany.com) 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.
org.apache.catalina.valves.AccessLogValve valve creates log files
in the same format as those created by standard web servers.
The servlet container creates the log files in the
The log files are prefixed with the string
localhost_access_log., have a suffix of
use a standard format for identifying what should be logged, and do not include DNS lookups of the IP address of the remote host.
The Virgo Tomcat 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
consult the official Tomcat HTTP Connector documentation.
|Configuring SSL for Tomcat|
The Virgo Tomcat Server distribution includes a preconfigured
Virgo Tomcat 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 Tomcat Clustering/Session Replication HOW-TO for detailed information about enabling and configuring clustering.
Virgo Tomcat Server supports standard Apache Tomcat web application context configuration. The Apache Tomcat Configuration Reference has a section on The Context Container which describes the mechanism that is used in VTS for searching context configuration files and details the context configuration properties.
Context configuration files may be placed in the following locations,
[enginename] is the name of Tomcat's engine ('Catalina' by default) and
a virtual host ('localhost' by default), both of which are configured in
$SERVER_HOME/config/context.xml provides the default context configuration file for all web applications.
$SERVER_HOME/config/[enginename]/[hostname] directory may contain:
The default context configuration for all web applications of a given virtual host in the file
Individual web applications' context configuration files as described in the Apache Tomcat Configuration Reference.
For example, the context for a web application with
foo may be configured in
Note that the following context configuration features are not supported in Virgo Tomcat Server:
Custom class loaders.
Specifying the context path. This is specified using the
Web-ContextPath header in the web application's
Specifying the document base directory.