11:43 a.m.
Author: jfrederic.clere(a)jboss.com
Date: 2011-06-29 12:43:28 -0400 (Wed, 29 Jun 2011)
New Revision: 1750
Added:
trunk/webapps/docs/config/ssl.xml
trunk/webapps/docs/config/static.xml
Modified:
trunk/java/org/apache/catalina/connector/CoyoteAdapter.java
trunk/webapps/docs/config/host.xml
trunk/webapps/docs/config/http.xml
trunk/webapps/docs/config/index.xml
trunk/webapps/docs/config/project.xml
trunk/webapps/docs/index.xml
trunk/webapps/docs/introduction.xml
trunk/webapps/docs/tomcat-docs.xsl
Log:
Add AS7 docs.
Modified: trunk/java/org/apache/catalina/connector/CoyoteAdapter.java
===================================================================
--- trunk/java/org/apache/catalina/connector/CoyoteAdapter.java 2011-06-28 20:44:24 UTC
(rev 1749)
+++ trunk/java/org/apache/catalina/connector/CoyoteAdapter.java 2011-06-29 16:43:28 UTC
(rev 1750)
@@ -523,6 +523,7 @@
}
connector.getService().getMapper().map(serverName, decodedURI,
request.getMappingData());
+ log.error("Merde: " + request.getMappingData().context + " :
" + request.getMappingData().host + " : " + request.getMappingData());
request.setContext((Context) request.getMappingData().context);
request.setWrapper((Wrapper) request.getMappingData().wrapper);
Modified: trunk/webapps/docs/config/host.xml
===================================================================
--- trunk/webapps/docs/config/host.xml 2011-06-28 20:44:24 UTC (rev 1749)
+++ trunk/webapps/docs/config/host.xml 2011-06-29 16:43:28 UTC (rev 1750)
@@ -10,7 +10,8 @@
<author email="craigmcc(a)apache.org">Craig R.
McClanahan</author>
<author email="remm(a)apache.org">Remy Maucherat</author>
<author email="yoavs(a)apache.org">Yoav Shapira</author>
- <title>The Host Container</title>
+ <author email="jfclere(a)gmail.com">Jean-Frederic Clere</author>
+ <title>The virtual-server element</title>
</properties>
<body>
@@ -18,7 +19,7 @@
<section name="Introduction">
- <p>The <strong>Host</strong> element represents a <em>virtual
host</em>,
+ <p>The <strong>virtual-server</strong> element represents a
<em>virtual host</em>,
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. In order to be effective, this name must be registered in the
@@ -32,23 +33,9 @@
This can be accomplished using the <a href="#Host Name Aliases">Host
Name Aliases</a> feature discussed below.</p>
- <p>One or more <strong>Host</strong> elements are nested inside an
- <a href="engine.html">Engine</a> element. Inside the Host
element, you
- can nest <a href="context.html">Context</a> elements for the web
- applications associated with this virtual host. Exactly one of the Hosts
- associated with each Engine MUST have a name matching the
- <code>defaultHost</code> attribute of that Engine.</p>
+ <p>One or more <strong>virtual-server</strong> elements are nested
inside an
+ <a href="subsystem.html">subsystem=web</a> element.</p>
- <blockquote><em>
- <p>The description below uses the variable name $CATALINA_HOME
- to refer to the directory into which you have installed JBoss Web,
- and is the base directory against which most relative paths are
- resolved. However, if you have configured JBoss Web for multiple
- instances by setting a CATALINA_BASE directory, you should use
- $CATALINA_BASE instead of $CATALINA_HOME for each of these
- references.</p>
- </em></blockquote>
-
</section>
@@ -56,70 +43,41 @@
<subsection name="Common Attributes">
- <p>All implementations of <strong>Host</strong>
- support the following attributes:</p>
+ <p>The <strong>virtual-server</strong>
+ supports the following attributes:</p>
<attributes>
- <attribute name="appBase" required="true">
- <p>The <em>Application Base</em> directory for this virtual
host.
- This is the pathname of a directory that may contain web applications
- to be deployed on this virtual host. You may specify an
- absolute pathname for this directory, or a pathname that is relative
- to the <code>$CATALINA_BASE</code> directory. See
- <a href="#Automatic Application Deployment">Automatic
Application
- Deployment</a> for more information on automatic recognition and
- deployment of web applications to be deployed automatically.</p>
+ <attribute name="name" required="true">
+ <p>Name of the Virtual Host</p>
</attribute>
- <attribute name="autoDeploy" required="false">
- <p>This flag value indicates if new web applications, dropped in to
- the <code>appBase</code> directory while JBoss Web is running,
should
- be automatically deployed. The flag's value defaults to true. See
- <a href="#Automatic Application Deployment">Automatic
Application
- Deployment</a> for more information.</p>
+ <attribute name="alias" required="false">
+ <p>List of alias supported by the Virtual Host</p>
</attribute>
- <attribute name="backgroundProcessorDelay"
required="false">
- <p>This value represents the delay in seconds between the
- invocation of the backgroundProcess method on this host and
- its child containers, including all contexts.
- Child containers will not be invoked if their delay value is not
- negative (which would mean they are using their own processing
- thread). Setting this to a positive value will cause
- a thread to be spawn. After waiting the specified amount of time,
- the thread will invoke the backgroundProcess method on this host
- and all its child containers. A host will use background processing to
- perform live web application deployment related tasks. If not
- specified, the default value for this attribute is -1, which means
- the host will rely on the background processing thread of its parent
- engine.</p>
+ <attribute name="access-log" required="false">
+ <p>Element describing how the access log information should be
logged.</p>
</attribute>
- <attribute name="className" required="false">
- <p>Java class name of the implementation to use. This class must
- implement the <code>org.apache.catalina.Host</code> interface.
- If not specified, the standard value (defined below) will be used.</p>
+ <attribute name="rewrite" required="false">
+ <p>Element describing what the rewrite valve should do with requests
corresponding to the Virtual Host.</p>
</attribute>
- <attribute name="deployOnStartup" required="false">
- <p>This flag value indicates if web applications from this host should
- be automatically deployed by the host configurator.
- The flag's value defaults to true. See
- <a href="#Automatic Application Deployment">Automatic
Application
- Deployment</a> for more information.</p>
+ <attribute name="enable-welcome-root" required="false">
+ <p>Whether or not the bundled welcome directory is used as the root web
context.</p>
</attribute>
- <attribute name="name" required="true">
- <p>Network name of this virtual host, as registered in your
- <em>Domain Name Service</em> server. One of the Hosts nested within
- an <a href="engine.html">Engine</a> MUST have a name that
matches the
- <code>defaultHost</code> setting for that Engine. See
- <a href="#Host Name Aliases">Host Name Aliases</a> for
information
- on how to assign more than one network name to the same
- virtual host.</p>
+ <attribute name="default-web-module" required="false">
+ <p>Webapp to use as default applicationWhether or not the bundled welcome
directory is used as the root web context.
+ If not specified, a default of <code>ROOT.war</code> is
used.</p>
</attribute>
+ <attribute name="missing stuff" required="false">
+ <p>TODO</p>
+ </attribute>
+
+
</attributes>
</subsection>
Modified: trunk/webapps/docs/config/http.xml
===================================================================
--- trunk/webapps/docs/config/http.xml 2011-06-28 20:44:24 UTC (rev 1749)
+++ trunk/webapps/docs/config/http.xml 2011-06-29 16:43:28 UTC (rev 1750)
@@ -9,6 +9,7 @@
<properties>
<author email="craigmcc(a)apache.org">Craig R.
McClanahan</author>
<author email="yoavs(a)apache.org">Yoav Shapira</author>
+ <author email="jfclere(a)apache.org">Jean-Frederic
Clere</author>
<title>The HTTP Connector</title>
</properties>
@@ -23,9 +24,8 @@
to its ability to execute servlets and JSP pages. A particular instance
of this component listens for connections on a specific TCP port number
on the server. One or more such <strong>Connectors</strong> can be
- configured as part of a single <a
href="service.html">Service</a>, each
- forwarding to the associated <a href="engine.html">Engine</a> to
perform
- request processing and create the response.</p>
+ configured as part of the <a href="subsystem.html">Web
subSystem</a>
+ to perform request processing and create the response.</p>
<p>If you wish to configure the <strong>Connector</strong> that is
used
for connections to web servers using the AJP protocol (such as the
@@ -36,12 +36,8 @@
a thread for the duration of that request. If more simultaneous requests
are received than can be handled by the currently available request
processing threads, additional threads will be created up to the
- configured maximum (the value of the <code>maxThreads</code> attribute).
- If still more simultaneous requests are received, they are stacked up
- inside the server socket created by the <strong>Connector</strong>, up to
- the configured maximum (the value of the <code>acceptCount</code>
- attribute. Any further simultaneous requests will receive "connection
- refused" errors, until resources are available to process them.</p>
+ configured maximum (the value of the <code>max-connections</code>
attribute).
+ Additional connections will be rejected.</p>
</section>
@@ -55,12 +51,11 @@
<attributes>
- <attribute name="allowTrace" required="false">
- <p>A boolean value which can be used to enable or disable the TRACE
- HTTP method. If not specified, this attribute is set to false.</p>
+ <attribute name="name" required="true">
+ <p>Name of the connector</p>
</attribute>
- <attribute name="enableLookups" required="false">
+ <attribute name="enable-lookups" required="false">
<p>Set to <code>true</code> if you want calls to
<code>request.getRemoteHost()</code> to perform DNS lookups in
order to return the actual host name of the remote client. Set
@@ -69,14 +64,14 @@
By default, DNS lookups are enabled.</p>
</attribute>
- <attribute name="maxPostSize" required="false">
+ <attribute name="max-post-size" required="false">
<p>The maximum size in bytes of the POST which will be handled by
the container FORM URL parameter parsing. The limit can be disabled by
setting this attribute to a value less than or equal to 0.
If not specified, this attribute is set to 2097152 (2 megabytes).</p>
</attribute>
- <attribute name="maxSavePostSize" required="false">
+ <attribute name="max-save-post-size" required="false">
<p>The maximum size in bytes of the POST which will be saved/buffered by
the container during FORM or CLIENT-CERT authentication. For both types
of authentication, the POST will be saved/buffered before the user is
@@ -112,7 +107,7 @@
</p>
</attribute>
- <attribute name="proxyName" required="false">
+ <attribute name="proxy-name" required="false">
<p>If this <strong>Connector</strong> is being used in a proxy
configuration, configure this attribute to specify the server name
to be returned for calls to <code>request.getServerName()</code>.
@@ -120,7 +115,7 @@
information.</p>
</attribute>
- <attribute name="proxyPort" required="false">
+ <attribute name="proxy-port" required="false">
<p>If this <strong>Connector</strong> is being used in a proxy
configuration, configure this attribute to specify the server port
to be returned for calls to <code>request.getServerPort()</code>.
@@ -128,7 +123,7 @@
information.</p>
</attribute>
- <attribute name="redirectPort" required="false">
+ <attribute name="redirect-port" required="false">
<p>If this <strong>Connector</strong> is supporting non-SSL
requests, and a request is received for which a matching
<code><security-constraint></code> requires SSL
transport,
@@ -136,13 +131,11 @@
number specified here.</p>
</attribute>
- <attribute name="SSLEnabled" required="false">
+ <attribute name="ssl" required="false">
<p>
- Use this attribute to enable SSL traffic on a connector.
- To turn on SSL handshake/encryption/decryption on a connector
- set this value to <code>true</code>.
- The default value is <code>false</code>.
- When turning this value <code>true</code> you will want to set the
+ Use this element to enable SSL traffic on a connector.
+ To turn on SSL handshake/encryption/decryption on a connector.
+ When present you will want to set the
<code>scheme</code> and the <code>secure</code> attributes
as well
to pass the correct <code>request.getScheme()</code> and
<code>request.isSecure()</code> values to the servlets
@@ -167,37 +160,17 @@
The default value is <code>false</code>.</p>
</attribute>
- <attribute name="URIEncoding" required="false">
- <p>This specifies the character encoding used to decode the URI bytes,
- after %xx decoding the URL. If not specified, ISO-8859-1 will be used.
- </p>
+ <attribute name="enabled" required="false">
+ <p>Set this attribute to <code>false</code> if you don't wan
the
+ Connector to be used.
+ The default value is <code>true</code>.</p>
</attribute>
- <attribute name="useBodyEncodingForURI" required="false">
- <p>This specifies if the encoding specified in contentType should be used
- for URI query parameters, instead of using the URIEncoding. This
- setting is present for compatibility with Tomcat 4.1.x, where the
- encoding specified in the contentType, or explicitely set using
- Request.setCharacterEncoding method was also used for the parameters from
- the URL. The default value is <code>false</code>.
- </p>
+ <attribute name="executor" required="false">
+ <p>A reference to the name in an <a
href="executor.html">Executor</a> element.
+ If this attribute is enabled, and the named executor exists, the connector will
+ use the executor, and all the other thread attributes will be
ignored.</p>
</attribute>
-
- <attribute name="useIPVHosts" required="false">
- <p>Set this attribute to <code>true</code> to cause JBoss Web to
use
- the IP address that the request was recieved on to determine the Host
- to send the request to. The default value is
<code>false</code>.</p>
- </attribute>
-
- <attribute name="xpoweredBy" required="false">
- <p>Set this attribute to <code>true</code> to cause JBoss Web to
advertise
- support for the Servlet specification using the header recommended in the
- specification. The default value is <code>false</code>.</p>
- </attribute>
-
-
-
-
</attributes>
</subsection>
@@ -205,157 +178,8 @@
<subsection name="Standard Implementation">
<p>
- HTTP supports the following additional attributes (in addition to the
- common attributes listed above):</p>
+ HTTP doesn't support more attributes that the ones listed above.</p>
- <attributes>
-
- <attribute name="acceptCount" required="false">
- <p>The maximum queue length for incoming connection requests when
- all possible request processing threads are in use. Any requests
- received when the queue is full will be refused. The default
- value is 10.</p>
- </attribute>
-
- <attribute name="address" required="false">
- <p>For servers with more than one IP address, this attribute
- specifies which address will be used for listening on the specified
- port. By default, this port will be used on all IP addresses
- associated with the server.</p>
- </attribute>
-
- <attribute name="bufferSize" required="false">
- <p>The size (in bytes) of the buffer to be provided for input
- streams created by this connector. By default, buffers of
- 2048 bytes will be provided.</p>
- </attribute>
-
- <attribute name="compressableMimeType" required="false">
- <p>The value is a comma separated list of MIME types for which HTTP
- compression may be used.
- The default value is
<code>text/html,text/xml,text/plain</code>.</p>
- </attribute>
-
- <attribute name="compression" required="false">
- <p>The <strong>Connector</strong> may use HTTP/1.1 GZIP
compression in
- an attempt to save server bandwidth. The acceptable values for the
- parameter is "off" (disable compression), "on" (allow
compression, which
- causes text data to be compressed), "force" (forces compression in all
- cases), or a numerical integer value (which is equivalent to "on", but
- specifies the minimum amount of data before the output is compressed). If
- the content-length is not known and compression is set to "on" or more
- aggressive, the output will also be compressed. If not specified, this
- attribute is set to "off".</p>
- </attribute>
-
- <attribute name="connectionLinger" required="false">
- <p>The number of milliseconds during which the sockets used by this
- <strong>Connector</strong> will linger when they are closed.
- The default value is -1 (socket linger is disabled).</p>
- </attribute>
-
- <attribute name="connectionTimeout" required="false">
- <p>The number of milliseconds this <strong>Connector</strong>
will wait,
- after accepting a connection, for the request URI line to be
- presented. The default value is 60000 (i.e. 60 seconds).</p>
- </attribute>
-
- <attribute name="executor" required="false">
- <p>A reference to the name in an <a
href="executor.html">Executor</a> element.
- If this attribute is enabled, and the named executor exists, the connector will
- use the executor, and all the other thread attributes will be
ignored.</p>
- </attribute>
-
- <attribute name="keepAliveTimeout" required="false">
- <p>The number of milliseconds this <strong>Connector</strong>
will wait for
- another HTTP request before closing the connection.
- The default value is to use the value that has been set for the
- connectionTimeout attribute.</p>
- </attribute>
-
- <attribute name="disableUploadTimeout" required="false">
- <p>This flag allows the servlet container to use a different, longer
- connection timeout while a servlet is being executed, which in the end
- allows either the servlet a longer amount of time to complete its
- execution, or a longer timeout during data upload. If not specified,
- this attribute is set to "true".</p>
- </attribute>
-
- <attribute name="maxHttpHeaderSize" required="false">
- <p>The maximum size of the request and response HTTP header, specified
- in bytes.
- If not specified, this attribute is set to 8192 (8 KB).</p>
- </attribute>
-
- <attribute name="maxKeepAliveRequests" required="false">
- <p>The maximum number of HTTP requests which can be pipelined until
- the connection is closed by the server. Setting this attribute to 1 will
- disable HTTP/1.0 keep-alive, as well as HTTP/1.1 keep-alive and
- pipelining. Setting this to -1 will allow an unlimited amount of
- pipelined or keep-alive HTTP requests.
- If not specified, this attribute is set to 100.</p>
- </attribute>
-
- <attribute name="maxThreads" required="false">
- <p>The maximum number of request processing threads to be created
- by this <strong>Connector</strong>, which therefore determines the
- maximum number of simultaneous requests that can be handled. If
- not specified, this attribute is set to 200. If an executor is associated
- with this connector, this attribute is ignored as the connector will
- execute tasks using the executor rather than an internal thread pool.</p>
- </attribute>
-
- <attribute name="noCompressionUserAgents"
required="false">
- <p>The value is a comma separated list of regular expressions matching
- user-agents of HTTP clients for which compression should not be used,
- because these clients, although they do advertise support for the
- feature, have a broken implementation.
- The default value is an empty String (regexp matching disabled).</p>
- </attribute>
-
- <attribute name="port" required="true">
- <p>The TCP port number on which this <strong>Connector</strong>
- will create a server socket and await incoming connections. Your
- operating system will allow only one server application to listen
- to a particular port number on a particular IP address.</p>
- </attribute>
-
- <attribute name="restrictedUserAgents" required="false">
- <p>The value is a comma separated list of regular expressions matching
- user-agents of HTTP clients for which HTTP/1.1 or HTTP/1.0 keep alive
- should not be used, even if the clients advertise support for these
- features.
- The default value is an empty String (regexp matching disabled).</p>
- </attribute>
-
- <attribute name="server" required="false">
- <p>The Server header for the http response.
- Unless your paranoid, you won't need this feature.
- </p>
- </attribute>
-
- <attribute name="socketBuffer" required="false">
- <p>The size (in bytes) of the buffer to be provided for socket
- output buffering. -1 can be specified to disable the use of a buffer.
- By default, a buffers of 9000 bytes will be used.</p>
- </attribute>
-
- <attribute name="tcpNoDelay" required="false">
- <p>If set to <code>true</code>, the TCP_NO_DELAY option will be
- set on the server socket, which improves performance under most
- circumstances. This is set to <code>true</code> by default.</p>
- </attribute>
-
- <attribute name="threadPriority" required="false">
- <p>The priority of the request processing threads within the JVM.
- The default value is <code>java.lang.Thread#NORM_PRIORITY</code>.
- See the JavaDoc for the java.lang.Thread class for more details on
- what this priority means.
- </p>
- </attribute>
-
- </attributes>
-
</subsection>
</section>
@@ -392,7 +216,7 @@
<subsection name="Proxy Support">
- <p>The <code>proxyName</code> and <code>proxyPort</code>
attributes can
+ <p>The <code>proxy-name</code> and
<code>proxy-port</code> attributes can
be used when JBoss Web is run behind a proxy server. These attributes
modify the values returned to web applications that call the
<code>request.getServerName()</code> and
<code>request.getServerPort()</code>
@@ -411,105 +235,8 @@
<subsection name="SSL Support">
- <p>You can enable SSL support for a particular instance of this
- <strong>Connector</strong> by setting the <code>secure</code>
attribute to
- <code>true</code>. In addition, you may need to configure the following
- attributes:</p>
+ <p>See <a href="ssl.html">HTTPS connector</a>.</p>
- <attributes>
-
- <attribute name="algorithm" required="false">
- <p>The certificate encoding algorithm to be used. This defaults to the Sun
- implementation (<code>SunX509</code>). For IBM JVMs you should use the
- value <code>IbmX509</code>. For other vendors, consult the JVM
- documentation for the correct value.</p>
- </attribute>
-
- <attribute name="clientAuth" required="false">
- <p>Set to <code>true</code> if you want the SSL stack to require
a
- valid certificate chain from the client before accepting a connection.
- Set to <code>want</code> if you want the SSL stack to request a client
- Certificate, but not fail if one isn't presented. A
<code>false</code>
- value (which is the default) will not require a certificate chain
- unless the client requests a resource protected by a security
- constraint that uses <code>CLIENT-CERT</code> authentication. See the
- <a href="../ssl-howto.html">SSL HowTo</a> for an
example.</p>
- </attribute>
-
- <attribute name="keystoreFile" required="false">
- <p>The pathname of the keystore file where you have stored the
- server certificate to be loaded. By default, the pathname is
- the file "<code>.keystore</code>" in the operating system
home
- directory of the user that is running JBoss Web. If your
- <code>keystoreType</code> doesn't need a file use
<code>""</code>
- (empty string) for this parameter.</p>
- </attribute>
-
- <attribute name="keystorePass" required="false">
- <p>The password used to access the server certificate from the
- specified keystore file. The default value is
"<code>changeit</code>".
- </p>
- </attribute>
-
- <attribute name="keystoreProvider" required="false">
- <p>The name of the keystore provider to be used for the server
- certificate. If not specified, the list of registered providers is
- traversed in preference order and the first provider that supports the
- <code>keystoreType</code> is used.
- </p>
- </attribute>
-
- <attribute name="keystoreType" required="false">
- <p>The type of keystore file to be used for the server certificate.
- If not specified, the default value is
"<code>JKS</code>".</p>
- </attribute>
-
- <attribute name="sslProtocol" required="false">
- <p>The version of the SSL protocol to use. If not specified,
- the default is "<code>TLS</code>".</p>
- </attribute>
-
- <attribute name="ciphers" required="false">
- <p>A comma seperated list of the encryption ciphers that may be used.
- If not specified, then any available cipher may be used.</p>
- </attribute>
-
- <attribute name="keyAlias" required="false">
- <p>The alias used to for the server certificate in the keystore. If not
- specified the first key read in the keystore will be used.</p>
- </attribute>
-
- <attribute name="truststoreFile" required="false">
- <p>The TrustStore file to use to validate client certificates.</p>
- </attribute>
-
- <attribute name="truststorePass" required="false">
- <p>The password to access the TrustStore. This defaults to the value
- of <code>keystorePass</code>.</p>
- </attribute>
-
- <attribute name="truststoreProvider" required="false">
- <p>The name of the truststore provider to be used for the server
- certificate. If not specified, the list of registered providers is
- traversed in preference order and the first provider that supports the
- <code>truststoreType</code> is used.
- </p>
- </attribute>
-
- <attribute name="truststoreType" required="false">
- <p>Add this element if your are using a different format for the
- TrustStore then you are using for the KeyStore.</p>
- </attribute>
-
- <attribute name="allowUnsafeLegacyRenegotiation"
required="false">
- <p>Is unsafe legacy TLS renegotiation allowed which is likely to expose
- users to CVE-2009-3555, a man-in-the-middle vulnerability in the TLS
- protocol that allows an attacker to inject arbitrary data into the user's
- request. If not specified, a default of <code>false</code> is
used.</p>
- </attribute>
-
- </attributes>
-
<p>For more information, see the
<a href="../ssl-howto.html">SSL Configuration
HOW-TO</a>.</p>
Modified: trunk/webapps/docs/config/index.xml
===================================================================
--- trunk/webapps/docs/config/index.xml 2011-06-28 20:44:24 UTC (rev 1749)
+++ trunk/webapps/docs/config/index.xml 2011-06-29 16:43:28 UTC (rev 1750)
@@ -8,6 +8,7 @@
<properties>
<author email="craigmcc(a)apache.org">Craig R.
McClanahan</author>
+ <author email="jfclere(a)gmail.com">Jean-Frederic Clere</author>
<title>Overview</title>
</properties>
@@ -17,7 +18,7 @@
<section name="Overview">
<p>This manual contains reference information about all of the configuration
-directives that can be included in a <code>conf/server.xml</code> file to
+directives that can be used in the Web subsystem to
configure the behavior of the JBoss Web Servlet/JSP container. It does not
attempt to describe which configuration directives should be used to perform
specific tasks - for that, see the various <em>HOW-TO</em> documents on the
@@ -26,22 +27,17 @@
<p>The configuration element descriptions are organized into the following
major categories:</p>
<ul>
-<li><strong>Top Level Elements</strong> -
<code><Server></code> is the
- root element of the entire configuration file, while
- <code><Service></code> represents a group of Connectors
that is
- associated with an Engine.</li>
-<li><strong>Connectors</strong> - Represent the interface between
external
+<li><strong>connectors</strong> - Represent the interface between
external
clients sending requests to (and receiving responses from) a particular
Service.</li>
-<li><strong>Containers</strong> - Represent components whose function
is to
- process incoming requests, and create the corresponding responses.
- An Engine handles all requests for a Service, a Host handles all requests
- for a particular virtual host, and a Context handles all requests for a
- specific web application.</li>
+<li><strong>virtual-server</strong> - Represent the virtual host
corresponding
+ to requests matching it.</li>
+<li><strong>jsp-configuration</strong> - That is the configuration of
+ the JSP container.</li>
+<li><strong>static-resources</strong> - That is the configuration of
+ Default Servlet (how the static ressources should served).</li>
<li><strong>Nested Components</strong> - Represent elements that can
be
- nested inside the element for a Container. Some elements can be nested
- inside any Container, while others can only be nested inside a
- Context.</li>
+ nested inside the above elements.</li>
</ul>
<p>For each element, the corresponding documentation follows this general
@@ -52,16 +48,11 @@
the <code>org.apache.catalina</code> pacakge) that is implemented by one
or more standard implementations.</li>
<li><strong>Attributes</strong> - The set of attributes that are legal
for
- this element. Generally, this will be subdivided into <em>Common</em>
- attributes that are supported by all implementations of the corresponding
- Java interface, and <em>Standard Implementation</em> attributes that are
- specific to a particular Java class that implements this interface.
- The names of required attributes are <strong>bolded</strong>.</li>
+ this element.</li>
<li><strong>Nested Components</strong> - Enumerates which of the
<em>Nested
Components</em> can be legally nested within this element.</li>
<li><strong>Special Features</strong> - Describes the configuration of
a large
- variety of special features (specific to each element type) that are
- supported by the standard implementation of this interface.</li>
+ variety of special features (specific to each element type).</li>
</ul>
</section>
Modified: trunk/webapps/docs/config/project.xml
===================================================================
--- trunk/webapps/docs/config/project.xml 2011-06-28 20:44:24 UTC (rev 1749)
+++ trunk/webapps/docs/config/project.xml 2011-06-29 16:43:28 UTC (rev 1750)
@@ -16,35 +16,30 @@
<item name="Config Ref. Home" href="index.html"/>
</menu>
- <menu name="Top Level Elements">
- <item name="Server"
href="server.html"/>
- <item name="Service"
href="service.html"/>
+ <menu name="Top Level Element">
+ <item name="Web SubSystem"
href="subsystem.html"/>
</menu>
- <menu name="Executors">
- <item name="Executor"
href="executor.html"/>
- </menu>
-
<menu name="Connectors">
<item name="HTTP" href="http.html"/>
<item name="AJP" href="ajp.html"/>
+ <item name="HPTTPS" href="ssl.html"/>
+ <item name="Native"
href="native.html"/>
</menu>
- <menu name="Containers">
- <item name="Context"
href="context.html"/>
- <item name="Engine"
href="engine.html"/>
- <item name="Host" href="host.html"/>
+ <menu name="Configuration elements">
+ <item name="static-resources"
href="static.html"/>
+ <item name="jsp-configuration" href="jsp.html"/>
</menu>
- <menu name="Nested Components">
- <item name="Global Resources"
href="globalresources.html"/>
- <item name="Loader"
href="loader.html"/>
- <item name="Manager"
href="manager.html"/>
- <item name="Realm" href="realm.html"/>
- <item name="Resources"
href="resources.html"/>
- <item name="Valve" href="valve.html"/>
+ <menu name="Virtual Hosts">
+ <item name="virtual-server" href="host.html"/>
</menu>
+ <menu name="Executors">
+ <item name="Executor"
href="executor.html"/>
+ </menu>
+
</body>
</project>
Added: trunk/webapps/docs/config/ssl.xml
===================================================================
--- trunk/webapps/docs/config/ssl.xml (rev 0)
+++ trunk/webapps/docs/config/ssl.xml 2011-06-29 16:43:28 UTC (rev 1750)
@@ -0,0 +1,347 @@
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document url="http.html">
+
+ &project;
+
+ <properties>
+ <author email="craigmcc(a)apache.org">Craig R.
McClanahan</author>
+ <author email="yoavs(a)apache.org">Yoav Shapira</author>
+ <author email="jfclere(a)apache.org">Jean-Frederic
Clere</author>
+ <title>The HTTP Connector</title>
+ </properties>
+
+<body>
+
+
+<section name="Introduction">
+
+ <p>The <strong>HTTP Connector</strong> element represents a
+ <strong>Connector</strong> component that supports the HTTP/1.1 protocol.
+ It enables Catalina to function as a stand-alone web server, in addition
+ to its ability to execute servlets and JSP pages. A particular instance
+ of this component listens for connections on a specific TCP port number
+ on the server. One or more such <strong>Connectors</strong> can be
+ configured as part of the <a href="subsystem.html">Web
subSystem</a>
+ to perform request processing and create the response.</p>
+
+ <p>If you wish to configure the <strong>Connector</strong> that is
used
+ for connections to web servers using the AJP protocol (such as the
+ <code>mod_jk 1.2.x</code> connector for Apache 1.3), see
+ <a href="ajp.html">here</a> instead.</p>
+
+ <p>Each incoming request requires
+ a thread for the duration of that request. If more simultaneous requests
+ are received than can be handled by the currently available request
+ processing threads, additional threads will be created up to the
+ configured maximum (the value of the <code>max-connections</code>
attribute).
+ Additional connections will be rejected.</p>
+
+</section>
+
+
+<section name="Attributes">
+
+ <subsection name="Common Attributes">
+
+ <p>All implementations of <strong>Connector</strong>
+ support the following attributes:</p>
+
+ <attributes>
+
+ <attribute name="name" required="true">
+ <p>Name of the connector</p>
+ </attribute>
+
+ <attribute name="enable-lookups" required="false">
+ <p>Set to <code>true</code> if you want calls to
+ <code>request.getRemoteHost()</code> to perform DNS lookups in
+ order to return the actual host name of the remote client. Set
+ to <code>false</code> to skip the DNS lookup and return the IP
+ address in String form instead (thereby improving performance).
+ By default, DNS lookups are enabled.</p>
+ </attribute>
+
+ <attribute name="max-post-size" required="false">
+ <p>The maximum size in bytes of the POST which will be handled by
+ the container FORM URL parameter parsing. The limit can be disabled by
+ setting this attribute to a value less than or equal to 0.
+ If not specified, this attribute is set to 2097152 (2 megabytes).</p>
+ </attribute>
+
+ <attribute name="max-save-post-size" required="false">
+ <p>The maximum size in bytes of the POST which will be saved/buffered by
+ the container during FORM or CLIENT-CERT authentication. For both types
+ of authentication, the POST will be saved/buffered before the user is
+ authenticated. For CLIENT-CERT authentication, the POST is buffered for
+ the duration of the SSL handshake and the buffer emptied when the request
+ is processed. For FORM authentication the POST is saved whilst the user
+ is re-directed to the login form and is retained until the user
+ successfully authenticates or the session associated with the
+ authentication request expires. The limit can be disabled by setting this
+ attribute to -1. Setting the attribute to zero will disable the saving of
+ POST data during authentication and the buffering during SSL handshake.
+ If not specified, this attribute is set to 4096 (4 kilobytes).</p>
+ </attribute>
+
+ <attribute name="protocol" required="false">
+ <p>
+ Sets the protocol to handle incoming traffic.
+ The default value is <code>HTTP/1.1</code> and configures the
+ <code>org.apache.coyote.http11.Http11Protocol</code>. This is the
blocking Java connector.<br/>
+ If the <code>PATH(Windows)</code> or <code>LD_LIBRARY_PATH(on
most unix system)</code>
+ environment variables contain the Tomcat native library, the APR connector
+ will automatically be configured. Please be advised that the APR connector has
different
+ settings for HTTPS than the default Java connector.<br/>
+ Other values for this attribute are, but not limited to:<br/>
+ <code>org.apache.coyote.http11.Http11Protocol</code> - same as
HTTP/1.1<br/>
+ <code>org.apache.coyote.http11.Http11NioProtocol</code> - non
blocking Java connector, not supported in JBossWeb<br/>
+ <code>org.apache.coyote.http11.Http11AprProtocol</code> - the APR
connector.<br/>
+ Take a look at our <a href="#Connector Comparison">Connector
Comparison</a> chart.
+ The configuration for both Java connectors are identical, both for http and
https. <br/>
+ For more information on the APR connector and APR specific SSL settings please
+ visit the <a href="../apr.html">APR documentation</a>
+
+ </p>
+ </attribute>
+
+ <attribute name="proxy-name" required="false">
+ <p>If this <strong>Connector</strong> is being used in a proxy
+ configuration, configure this attribute to specify the server name
+ to be returned for calls to <code>request.getServerName()</code>.
+ See <a href="#Proxy Support">Proxy Support</a> for more
+ information.</p>
+ </attribute>
+
+ <attribute name="proxy-port" required="false">
+ <p>If this <strong>Connector</strong> is being used in a proxy
+ configuration, configure this attribute to specify the server port
+ to be returned for calls to <code>request.getServerPort()</code>.
+ See <a href="#Proxy Support">Proxy Support</a> for more
+ information.</p>
+ </attribute>
+
+ <attribute name="redirect-port" required="false">
+ <p>If this <strong>Connector</strong> is supporting non-SSL
+ requests, and a request is received for which a matching
+ <code><security-constraint></code> requires SSL
transport,
+ Catalina will automatically redirect the request to the port
+ number specified here.</p>
+ </attribute>
+
+ <attribute name="ssl" required="false">
+ <p>
+ Use this element to enable SSL traffic on a connector.
+ To turn on SSL handshake/encryption/decryption on a connector.
+ When present you will want to set the
+ <code>scheme</code> and the <code>secure</code> attributes
as well
+ to pass the correct <code>request.getScheme()</code> and
+ <code>request.isSecure()</code> values to the servlets
+ See <a href="#SSL Support">SSL Support</a> for more
information.
+ </p>
+ </attribute>
+
+ <attribute name="scheme" required="false">
+ <p>Set this attribute to the name of the protocol you wish to have
+ returned by calls to <code>request.getScheme()</code>. For
+ example, you would set this attribute to
"<code>https</code>"
+ for an SSL Connector. The default value is
"<code>http</code>".
+ </p>
+ </attribute>
+
+ <attribute name="secure" required="false">
+ <p>Set this attribute to <code>true</code> if you wish to have
+ calls to <code>request.isSecure()</code> to return
<code>true</code>
+ for requests received by this Connector. You would want this on an
+ SSL Connector or a non SSL connector that is receiving data from a
+ SSL accelerator, like a crypto card, a SSL appliance or even a webserver.
+ The default value is <code>false</code>.</p>
+ </attribute>
+
+ <attribute name="enabled" required="false">
+ <p>Set this attribute to <code>false</code> if you don't wan
the
+ Connector to be used.
+ The default value is <code>true</code>.</p>
+ </attribute>
+
+ <attribute name="executor" required="false">
+ <p>A reference to the name in an <a
href="executor.html">Executor</a> element.
+ If this attribute is enabled, and the named executor exists, the connector will
+ use the executor, and all the other thread attributes will be
ignored.</p>
+ </attribute>
+ </attributes>
+
+ </subsection>
+
+ <subsection name="Standard Implementation">
+
+ <p>
+ HTTP doesn't support more attributes that the ones listed above.</p>
+
+ </subsection>
+
+</section>
+
+
+<section name="Nested Components">
+
+ <p>None at this time.</p>
+
+</section>
+
+
+<section name="Special Features">
+
+
+ <subsection name="HTTP/1.1 and HTTP/1.0 Support">
+
+ <p>This <strong>Connector</strong> supports all of the required
features
+ of the HTTP/1.1 protocol, as described in RFC 2616, including persistent
+ connections, pipelining, expectations and chunked encoding. If the client
+ (typically a browser) supports only HTTP/1.0, the
+ <strong>Connector</strong> will gracefully fall back to supporting this
+ protocol as well. No special configuration is required to enable this
+ support. The <strong>Connector</strong> also supports HTTP/1.0
+ keep-alive.</p>
+
+ <p>RFC 2616 requires that HTTP servers always begin their responses with
+ the highest HTTP version that they claim to support. Therefore, this
+ <strong>Connector</strong> will always return
<code>HTTP/1.1</code> at
+ the beginning of its responses.</p>
+
+ </subsection>
+
+
+ <subsection name="Proxy Support">
+
+ <p>The <code>proxy-name</code> and
<code>proxy-port</code> attributes can
+ be used when JBoss Web is run behind a proxy server. These attributes
+ modify the values returned to web applications that call the
+ <code>request.getServerName()</code> and
<code>request.getServerPort()</code>
+ methods, which are often used to construct absolute URLs for redirects.
+ Without configuring these attributes, the values returned would reflect
+ the server name and port on which the connection from the proxy server
+ was received, rather than the server name and port to whom the client
+ directed the original request.</p>
+
+ <p>For more information, see the
+ <a href="../proxy-howto.html">Proxy Support
HOW-TO</a>.</p>
+
+ </subsection>
+
+
+
+ <subsection name="SSL Support">
+
+ <p>You can enable SSL support for a particular instance of this
+ <strong>Connector</strong> by setting the <code>secure</code>
attribute to
+ <code>true</code>. In addition, you may need to configure the following
+ attributes:</p>
+
+ <attributes>
+
+ <attribute name="algorithm" required="false">
+ <p>The certificate encoding algorithm to be used. This defaults to the Sun
+ implementation (<code>SunX509</code>). For IBM JVMs you should use the
+ value <code>IbmX509</code>. For other vendors, consult the JVM
+ documentation for the correct value.</p>
+ </attribute>
+
+ <attribute name="clientAuth" required="false">
+ <p>Set to <code>true</code> if you want the SSL stack to require
a
+ valid certificate chain from the client before accepting a connection.
+ Set to <code>want</code> if you want the SSL stack to request a client
+ Certificate, but not fail if one isn't presented. A
<code>false</code>
+ value (which is the default) will not require a certificate chain
+ unless the client requests a resource protected by a security
+ constraint that uses <code>CLIENT-CERT</code> authentication. See the
+ <a href="../ssl-howto.html">SSL HowTo</a> for an
example.</p>
+ </attribute>
+
+ <attribute name="keystoreFile" required="false">
+ <p>The pathname of the keystore file where you have stored the
+ server certificate to be loaded. By default, the pathname is
+ the file "<code>.keystore</code>" in the operating system
home
+ directory of the user that is running JBoss Web. If your
+ <code>keystoreType</code> doesn't need a file use
<code>""</code>
+ (empty string) for this parameter.</p>
+ </attribute>
+
+ <attribute name="keystorePass" required="false">
+ <p>The password used to access the server certificate from the
+ specified keystore file. The default value is
"<code>changeit</code>".
+ </p>
+ </attribute>
+
+ <attribute name="keystoreProvider" required="false">
+ <p>The name of the keystore provider to be used for the server
+ certificate. If not specified, the list of registered providers is
+ traversed in preference order and the first provider that supports the
+ <code>keystoreType</code> is used.
+ </p>
+ </attribute>
+
+ <attribute name="keystoreType" required="false">
+ <p>The type of keystore file to be used for the server certificate.
+ If not specified, the default value is
"<code>JKS</code>".</p>
+ </attribute>
+
+ <attribute name="sslProtocol" required="false">
+ <p>The version of the SSL protocol to use. If not specified,
+ the default is "<code>TLS</code>".</p>
+ </attribute>
+
+ <attribute name="ciphers" required="false">
+ <p>A comma seperated list of the encryption ciphers that may be used.
+ If not specified, then any available cipher may be used.</p>
+ </attribute>
+
+ <attribute name="keyAlias" required="false">
+ <p>The alias used to for the server certificate in the keystore. If not
+ specified the first key read in the keystore will be used.</p>
+ </attribute>
+
+ <attribute name="truststoreFile" required="false">
+ <p>The TrustStore file to use to validate client certificates.</p>
+ </attribute>
+
+ <attribute name="truststorePass" required="false">
+ <p>The password to access the TrustStore. This defaults to the value
+ of <code>keystorePass</code>.</p>
+ </attribute>
+
+ <attribute name="truststoreProvider" required="false">
+ <p>The name of the truststore provider to be used for the server
+ certificate. If not specified, the list of registered providers is
+ traversed in preference order and the first provider that supports the
+ <code>truststoreType</code> is used.
+ </p>
+ </attribute>
+
+ <attribute name="truststoreType" required="false">
+ <p>Add this element if your are using a different format for the
+ TrustStore then you are using for the KeyStore.</p>
+ </attribute>
+
+ <attribute name="allowUnsafeLegacyRenegotiation"
required="false">
+ <p>Is unsafe legacy TLS renegotiation allowed which is likely to expose
+ users to CVE-2009-3555, a man-in-the-middle vulnerability in the TLS
+ protocol that allows an attacker to inject arbitrary data into the user's
+ request. If not specified, a default of <code>false</code> is
used.</p>
+ </attribute>
+
+ </attributes>
+
+ <p>For more information, see the
+ <a href="../ssl-howto.html">SSL Configuration
HOW-TO</a>.</p>
+
+ </subsection>
+
+</section>
+
+
+</body>
+
+</document>
Added: trunk/webapps/docs/config/static.xml
===================================================================
--- trunk/webapps/docs/config/static.xml (rev 0)
+++ trunk/webapps/docs/config/static.xml 2011-06-29 16:43:28 UTC (rev 1750)
@@ -0,0 +1,515 @@
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document url="host.html">
+
+ &project;
+
+ <properties>
+ <author email="craigmcc(a)apache.org">Craig R.
McClanahan</author>
+ <author email="remm(a)apache.org">Remy Maucherat</author>
+ <author email="yoavs(a)apache.org">Yoav Shapira</author>
+ <author email="jfclere(a)gmail.com">Jean-Frederic Clere</author>
+ <title>The virtual-server element</title>
+ </properties>
+
+<body>
+
+
+<section name="Introduction">
+
+ <p>The <strong>virtual-server</strong> element represents a
<em>virtual host</em>,
+ 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. In order to be effective, this name must be registered in the
+ <em>Domain Name Service</em> (DNS) server that manages the Internet
+ domain you belong to - contact your Network Administrator for more
+ information.</p>
+
+ <p>In many cases, System Administrators wish to associate more than
+ one network name (such as <code>www.mycompany.com</code> and
+ <code>company.com</code>) with the same virtual host and applications.
+ This can be accomplished using the <a href="#Host Name Aliases">Host
+ Name Aliases</a> feature discussed below.</p>
+
+ <p>One or more <strong>virtual-server</strong> elements are nested
inside an
+ <a href="subsystem.html">subsystem=web</a> element.</p>
+
+</section>
+
+
+<section name="Attributes">
+
+ <subsection name="Common Attributes">
+
+ <p>The <strong>virtual-server</strong>
+ supports the following attributes:</p>
+
+ <attributes>
+
+ <attribute name="name" required="true">
+ <p>Name of the Virtual Host</p>
+ </attribute>
+
+ <attribute name="autoDeploy" required="false">
+ <p>This flag value indicates if new web applications, dropped in to
+ the <code>appBase</code> directory while JBoss Web is running,
should
+ be automatically deployed. The flag's value defaults to true. See
+ <a href="#Automatic Application Deployment">Automatic
Application
+ Deployment</a> for more information.</p>
+ </attribute>
+
+ <attribute name="backgroundProcessorDelay"
required="false">
+ <p>This value represents the delay in seconds between the
+ invocation of the backgroundProcess method on this host and
+ its child containers, including all contexts.
+ Child containers will not be invoked if their delay value is not
+ negative (which would mean they are using their own processing
+ thread). Setting this to a positive value will cause
+ a thread to be spawn. After waiting the specified amount of time,
+ the thread will invoke the backgroundProcess method on this host
+ and all its child containers. A host will use background processing to
+ perform live web application deployment related tasks. If not
+ specified, the default value for this attribute is -1, which means
+ the host will rely on the background processing thread of its parent
+ engine.</p>
+ </attribute>
+
+ <attribute name="className" required="false">
+ <p>Java class name of the implementation to use. This class must
+ implement the <code>org.apache.catalina.Host</code> interface.
+ If not specified, the standard value (defined below) will be used.</p>
+ </attribute>
+
+ <attribute name="deployOnStartup" required="false">
+ <p>This flag value indicates if web applications from this host should
+ be automatically deployed by the host configurator.
+ The flag's value defaults to true. See
+ <a href="#Automatic Application Deployment">Automatic
Application
+ Deployment</a> for more information.</p>
+ </attribute>
+
+ <attribute name="name" required="true">
+ <p>Network name of this virtual host, as registered in your
+ <em>Domain Name Service</em> server. One of the Hosts nested within
+ an <a href="engine.html">Engine</a> MUST have a name that
matches the
+ <code>defaultHost</code> setting for that Engine. See
+ <a href="#Host Name Aliases">Host Name Aliases</a> for
information
+ on how to assign more than one network name to the same
+ virtual host.</p>
+ </attribute>
+
+ </attributes>
+
+ </subsection>
+
+
+ <subsection name="Standard Implementation">
+
+ <p>The standard implementation of <strong>Host</strong> is
+ <strong>org.apache.catalina.core.StandardHost</strong>.
+ It supports the following additional attributes (in addition to the
+ common attributes listed above):</p>
+
+ <attributes>
+
+ <attribute name="deployXML" required="false">
+ <p>Set to <code>false</code> if you want to disable parsing the
context.xml
+ file embedded inside the application (located at
<code>/META-INF/context.xml</code>).
+ Security consious environments should set this to <code>false</code>
to prevent
+ applications from interacting with the container's configuration. The
+ administrator will then be responsible for providing an external context
+ configuration file, and put it in
+ <code>$CATALINA_HOME/conf/[enginename]/[hostname]/</code>.
+ The flag's value defaults to <code>true</code>.</p>
+ </attribute>
+
+ <attribute name="errorReportValveClass"
required="false">
+ <p>Java class name of the error reporting valve which will be used
+ by this Host. The responsability of this valve is to output error
+ reports. Setting this property allows to customize the look of the
+ error pages which will be generated by JBoss Web. This class must
+ implement the
+ <code>org.apache.catalina.Valve</code> interface. If none is
specified,
+ the value <code>org.apache.catalina.valves.ErrorReportValve</code>
+ will be used by default.</p>
+ </attribute>
+
+ <attribute name="unpackWARs" required="false">
+ <p>Set to <code>true</code> if you want web applications that
are
+ placed in the <code>appBase</code> directory as web application
+ archive (WAR) files to be unpacked into a corresponding disk directory
+ structure, <code>false</code> to run such web applications directly
+ from a WAR file. See
+ <a href="#Automatic Application Deployment">Automatic
Application
+ Deployment</a> for more information.</p>
+ </attribute>
+
+ <attribute name="workDir" required="false">
+ <p>Pathname to a scratch directory to be used by applications for
+ this Host. Each application will have its own sub directory with
+ temporary read-write use. Configuring a Context workDir will override
+ use of the Host workDir configuration. This directory will be made
+ visible to servlets in the web application by a servlet context
+ attribute (of type <code>java.io.File</code>) named
+ <code>javax.servlet.context.tempdir</code> as described in the
+ Servlet Specification. If not specified, a suitable directory
+ underneath <code>$CATALINA_HOME/work</code> will be
provided.</p>
+ </attribute>
+
+ </attributes>
+
+ </subsection>
+
+
+</section>
+
+
+<section name="Nested Components">
+
+ <p>You can nest one or more <a
href="context.html">Context</a> elements
+ inside this <strong>Host</strong> element, each representing a different
web
+ application associated with this virtual host.</p>
+
+ <p>You can nest at most one instance of the following utility components
+ by nesting a corresponding element inside your <strong>Host</strong>
+ element:</p>
+ <ul>
+ <li><a
href="realm.html"><strong>Realm</strong></a> -
+ Configure a realm that will allow its
+ database of users, and their associated roles, to be shared across all
+ <a href="context.html">Contexts</a> nested inside this Host
(unless
+ overridden by a <a href="realm.html">Realm</a> configuration
+ at a lower level).</li>
+ </ul>
+
+</section>
+
+
+<section name="Special Features">
+
+
+ <subsection name="Logging">
+
+ <p>A host is associated with the
+
<code>org.apache.catalina.core.ContainerBase.[enginename].[hostname]</code>
+ log category. Note that the brackets are actuall part of the name,
+ don't omit them.</p>
+
+ </subsection>
+
+
+ <subsection name="Access Logs">
+
+ <p>When you run a web server, one of the output files normally generated
+ is an <em>access log</em>, which generates one line of information for
+ each request processed by the server, in a standard format. Catalina
+ includes an optional <a href="valve.html">Valve</a>
implementation that
+ can create access logs in the same standard format created by web servers,
+ or in any number of custom formats.</p>
+
+ <p>You can ask Catalina to create an access log for all requests
+ processed by an <a href="engine.html">Engine</a>,
+ <a href="host.html">Host</a>, or <a
href="context.html">Context</a>
+ by nesting a <a href="valve.html">Valve</a> element like
this:</p>
+
+<source>
+<Host name="localhost" ...>
+ ...
+ <Valve className="org.apache.catalina.valves.AccessLogValve"
+ prefix="localhost_access_log." suffix=".txt"
+ pattern="common"/>
+ ...
+</Host>
+</source>
+
+ <p>See <a href="valve.html#Access Log Valve">Access Log
Valve</a>
+ for more information on the configuration attributes that are
+ supported.</p>
+
+ </subsection>
+
+
+ <subsection name="Automatic Application Deployment">
+
+ <p>If you are using the standard <strong>Host</strong>
implementation,
+ the following actions take place automatically when Catalina is first
+ started, if the <code>deployOnStartup</code> property is set to
+ <code>true</code> (which is the default value):</p>
+ <ul>
+ <li>Any XML file in the
+ <code>$CATALINA_BASE/conf/[engine_name]/[host_name]</code> directory
is
+ assumed to contain a
+ <a href="context.html">Context</a> element (and its
associated
+ subelements) for a single web application. The <code>docBase</code>
+ attribute of this <code><Context></code> element will
typically
+ be the absolute pathname to a web application directory, or the
+ absolute pathname of a web application archive (WAR) file (which
+ will not be expanded). The path attribute will be automatically set
+ as defined in the <a href="context.html">Context</a>
documentation.</li>
+ <li>Any web application archive file within the application base (appBase)
+ directory that does not have a corresponding
+ directory of the same name (without the ".war" extension) will be
+ automatically expanded, unless the <code>unpackWARs</code> property
+ is set to <code>false</code>. If you redeploy an updated WAR file,
+ be sure to delete the expanded directory when restarting Tomcat, so
+ that the updated WAR file will be re-expanded (note that the auto
+ deployer, if enabled, will automatically expand the updated WAR file
+ once the previously expanded directory is removed). Multi-level contexts
+ may be defined by using #, eg use a WAR named
<code>foo#bar.war</code>
+ for a context path of <code>/foo/bar</code>.</li>
+ <li>Any subdirectory within the <em>application base
directory</em>
+ will receive an automatically generated <a href="context.html">
+ Context</a> element, even if this directory is not mentioned in the
+ <code>conf/server.xml</code> file. The context path for this
+ deployed Context will be a slash character ("/") followed by the
+ directory name, unless the directory name is ROOT, in which case
+ the context path will be an empty string (""). Multi-level contexts
+ may be defined by using #, eg use a directory named
<code>foo#bar</code>
+ for a context path of <code>/foo/bar</code>.</li>
+ </ul>
+
+ <p>In addition to the automatic deployment that occurs at startup time,
+ you can also request that new XML configuration files, WAR files, or
+ subdirectories that are dropped in to the <code>appBase</code> (or
+ <code>$CATALINA_HOME/conf/[engine_name]/[host_name]</code> in the case
of
+ an XML configuration file) directory while JBoss Web is running will be
+ automatically deployed, according to the rules described above. The
+ auto deployer will also track web applications for the following changes:
+ <ul>
+ <li>An update to the WEB-INF/web.xml file will trigger a reload of the
+ web application</li>
+ <li>An update to a WAR which has been expanded will trigger
+ an undeploy (<strong>with a removal of the expanded webapp</strong>),
+ followed by a deployment</li>
+ <li>An update to a XML configuration file will trigger an undeploy
+ (without the removal of any expanded directory), followed by
+ a deployment of the associated web application</li>
+ </ul>
+ </p>
+
+ <p>When using automatic deployment, the <code>docBase</code>
defined by
+ an XML <a href="context.html">Context</a> file should be
outside of the
+ <code>appBase</code> directory. If this is not the case difficulties
+ may be experienced deploying the web application or the application may
+ be deployed twice.</p>
+
+ <p>Finally, note that if you are defining contexts explicitly, you should
+ probably turn off automatic application deployment. Otherwise, your context
+ will be deployed twice each, and that may cause problems for your app.
+ </p>
+
+ </subsection>
+
+
+ <subsection name="Host Name Aliases">
+
+ <p>In many server environments, Network Administrators have configured
+ more than one network name (in the <em>Domain Name Service</em> (DNS)
+ server), that resolve to the IP address of the same server. Normally,
+ each such network name would be configured as a separate
+ <strong>Host</strong> element in
<code>conf/server.xml</code>, each
+ with its own set of web applications.</p>
+
+ <p>However, in some circumstances, it is desireable that two or more
+ network names should resolve to the <strong>same</strong> virtual host,
+ running the same set of applications. A common use case for this
+ scenario is a corporate web site, where it is desireable that users
+ be able to utilize either <code>www.mycompany.com</code> or
+ <code>company.com</code> to access exactly the same content and
+ applications.</p>
+
+ <p>This is accomplished by utilizing one or more
<strong>Alias</strong>
+ elements nested inside your <strong>Host</strong> element. For
+ example:</p>
+<source>
+<Host name="www.mycompany.com" ...>
+ ...
+ <Alias>mycompany.com</Alias>
+ ...
+</Host>
+</source>
+
+ <p>In order for this strategy to be effective, all of the network names
+ involved must be registered in your DNS server to resolve to the
+ same computer that is running this instance of Catalina.</p>
+
+ </subsection>
+
+
+ <subsection name="Lifecycle Listeners">
+
+ <p>If you have implemented a Java object that needs to know when this
+ <strong>Host</strong> is started or stopped, you can declare it by
+ nesting a <strong>Listener</strong> element inside this element. The
+ class name you specify must implement the
+ <code>org.apache.catalina.LifecycleListener</code> interface, and
+ it will be notified about the occurrence of the coresponding
+ lifecycle events. Configuration of such a listener looks like this:</p>
+
+<source>
+<Host name="localhost" ...>
+ ...
+ <Listener className="com.mycompany.mypackage.MyListener" ... >
+ ...
+</Host>
+</source>
+
+ <p>Note that a Listener can have any number of additional properties
+ that may be configured from this element. Attribute names are matched
+ to corresponding JavaBean property names using the standard property
+ method naming patterns.</p>
+
+ </subsection>
+
+
+ <subsection name="Request Filters">
+
+ <p>You can ask Catalina to check the IP address, or host name, on every
+ incoming request directed to the surrounding
+ <a href="engine.html">Engine</a>, <a
href="host.html">Host</a>, or
+ <a href="context.html">Context</a> element. The remote address
or name
+ will be checked against a configured list of "accept" and/or
"deny"
+ filters, which are defined using the Regular Expression syntax supported
+ by the <a href="http://jakarta.apache.org/regexp/">Jakarta
Regexp</a>
+ regular expression library. Requests that come from locations that are
+ not accepted will be rejected with an HTTP "Forbidden" error.
+ Example filter declarations:</p>
+
+<source>
+<Host name="localhost" ...>
+ ...
+ <Valve className="org.apache.catalina.valves.RemoteHostValve"
+ allow="*.mycompany.com,www.yourcompany.com"/>
+ <Valve className="org.apache.catalina.valves.RemoteAddrValve"
+ deny="192.168.1.*"/>
+ ...
+</Host>
+</source>
+
+ <p>See <a href="valve.html#Remote Address Filter">Remote Address
Filter</a>
+ and <a href="valve.html#Remote Host Filter">Remote Host
Filter</a> for
+ more information about the configuration options that are supported.</p>
+
+ </subsection>
+
+
+ <subsection name="Single Sign On">
+
+ <p>In many environments, but particularly in portal environments, it
+ is desireable to have a user challenged to authenticate themselves only
+ once over a set of web applications deployed on a particular virtual
+ host. This can be accomplished by nesting an element like this inside
+ the Host element for this virtual host:</p>
+
+<source>
+<Host name="localhost" ...>
+ ...
+ <Valve className="org.apache.catalina.authenticator.SingleSignOn"
+ debug="0"/>
+ ...
+</Host>
+</source>
+
+ <p>The Single Sign On facility operates according to the following rules:
+ </p>
+ <ul>
+ <li>All web applications configured for this virtual host must share the
+ same <a href="realm.html">Realm</a>. In practice, that
means you can
+ nest the Realm element inside this Host element (or the surrounding
+ <a href="engine.html">Engine</a> element), but not inside
a
+ <a href="context.html">Context</a> element for one of the
involved
+ web applications.</li>
+ <li>As long as the user accesses only unprotected resources in any of the
+ web applications on this virtual host, they will not be challenged
+ to authenticate themselves.</li>
+ <li>As soon as the user accesses a protected resource in
+ <strong>any</strong> web application associated with this virtual
+ host, the user will be challenged to authenticate himself or herself,
+ using the login method defined for the web application currently
+ being accessed.</li>
+ <li>Once authenticated, the roles associated with this user will be
+ utilized for access control decisions across <strong>all</strong>
+ of the associated web applications, without challenging the user
+ to authenticate themselves to each application individually.</li>
+ <li>As soon as the user logs out of one web application (for example,
+ by invalidating the corresponding session if form
+ based login is used), the user's sessions in
<strong>all</strong>
+ web applications will be invalidated. Any subsequent attempt to
+ access a protected resource in any application will require the
+ user to authenticate himself or herself again.</li>
+ <li>The Single Sign On feature utilizes HTTP cookies to transmit a token
+ that associates each request with the saved user identity, so it can
+ only be utilized in client environments that support cookies.</li>
+ </ul>
+
+ </subsection>
+
+
+ <subsection name="User Web Applications">
+
+ <p>Many web servers can automatically map a request URI starting with
+ a tilde character ("~") and a username to a directory (commonly named
+ <code>public_html</code>) in that user's home directory on the
server.
+ You can accomplish the same thing in Catalina by using a special
+ <strong>Listener</strong> element like this (on a Unix system that
+ uses the <code>/etc/passwd</code> file to identify valid
users):</p>
+
+<source>
+<Host name="localhost" ...>
+ ...
+ <Listener className="org.apache.catalina.startup.UserConfig"
+ directoryName="public_html"
+
userClass="org.apache.catalina.startup.PasswdUserDatabase"/>
+ ...
+</Host>
+</source>
+
+ <p>On a server where <code>/etc/passwd</code> is not in use, you
can
+ request Catalina to consider all directories found in a specified base
+ directory (such as <code>c:\Homes</code> in this example) to be
+ considered "user home" directories for the purposes of this
directive:</p>
+
+<source>
+<Host name="localhost" ...>
+ ...
+ <Listener className="org.apache.catalina.startup.UserConfig"
+ directoryName="public_html"
+ homeBase=c:\Homes"
+ userClass="org.apache.catalina.startup.HomesUserDatabase"/>
+ ...
+</Host>
+</source>
+
+ <p>If a user home directory has been set up for a user named
+ <code>craigmcc</code>, then its contents will be visible from a
+ client browser by making a request to a URL like:</p>
+
+<source>
+http://www.mycompany.com:8080/~craigmcc
+</source>
+
+ <p>Successful use of this feature requires recognition of the following
+ considerations:</p>
+ <ul>
+ <li>Each user web application will be deployed with characteristics
+ established by the global and host level default context settings.</li>
+ <li>It is legal to include more than one instance of this Listener
+ element. This would only be useful, however, in circumstances
+ where you wanted to configure more than one "homeBase"
directory.</li>
+ <li>The operating system username under which Catalina is executed
+ MUST have read access to each user's web application directory,
+ and all of its contents.</li>
+ </ul>
+
+ </subsection>
+
+
+</section>
+
+
+</body>
+
+
+</document>
Modified: trunk/webapps/docs/index.xml
===================================================================
--- trunk/webapps/docs/index.xml 2011-06-28 20:44:24 UTC (rev 1749)
+++ trunk/webapps/docs/index.xml 2011-06-29 16:43:28 UTC (rev 1750)
@@ -10,6 +10,7 @@
<author email="craigmcc(a)apache.org">Craig R.
McClanahan</author>
<author email="remm(a)apache.org">Remy Maucherat</author>
<author email="yoavs(a)apache.org">Yoav Shapira</author>
+ <author email="jfclere(a)apache.org">Jean-Frederic
Clere</author>
<title>Documentation Index</title>
</properties>
@@ -25,6 +26,8 @@
additional features that make it a useful platform for developing and deploying
web applications and web services.</p>
+<p><strong>JBoss Web 7.0.x</strong> is a subsystem of AS7, there
isn't yet standalone version of it.</p>
+
<p>Select one of the links from the navigation menu (to the left) to drill
down to the more detailed documentation that is available. Each available
manual is described in more detail below.</p>
@@ -40,8 +43,6 @@
<ol>
<li><a
href="introduction.html"><strong>Introduction</strong></a>
- A
brief, high level, overview of JBoss Web.</li>
-<li><a
href="setup.html"><strong>Setup</strong></a> - How to
install and run
- JBoss Web on a variety of platforms.</li>
<li><a href="sysprops.html"><strong>System
Properties</strong></a> - System
properties used for JBoss Web configuration.</li>
<li><a href="appdev/index.html"><strong>First web
application</strong></a>
Modified: trunk/webapps/docs/introduction.xml
===================================================================
--- trunk/webapps/docs/introduction.xml 2011-06-28 20:44:24 UTC (rev 1749)
+++ trunk/webapps/docs/introduction.xml 2011-06-29 16:43:28 UTC (rev 1750)
@@ -44,14 +44,13 @@
<section name="Directories and Files">
-<p>Throughout the docs, you'll notice there are numerous references to
-<strong>$CATALINA_HOME</strong>. This represents the root of your JBoss Web
-installation. When we say, "This information can be found in your
-$CATALINA_HOME/README.txt file" we mean to look at the README.txt file at the
-root of your JBoss Web install.</p>
+<p>Throughout the docs, you may notice references to
+<strong>$CATALINA_HOME</strong>. In <strong>JBossWeb 7.0.x
</strong> that is where the webapp are deployed
+The default location in the <strong>Stanalone Server</strong> is configured
by <code>jboss.server.temp.dir</code> normally
+<code>jboss.home.dir</code>/standalone/tmp.</p>
<p>These are some of the key JBoss Web directories, all relative
-to <strong>$CATALINA_HOME</strong>:</p>
+to <strong>$jboss.home.dir</strong>:</p>
<ul>
<li><strong>/bin</strong> - Startup, shutdown, and other scripts. The
@@ -59,11 +58,8 @@
the <code>*.bat</code> files (for Windows systems). Since the Win32
command-line lacks certain functionality, there are some additional
files in here.</li>
-<li><strong>/server/default/deploy/jbossweb.sar</strong> -
Configuration files and related DTDs. The most
- important file in here is server.xml. It is the main configuration file
- for the container.</li>
-<li><strong>/server/default/log</strong> - Log files are here by
default.</li>
-<li><strong>/server/default/deploy</strong> - This is where your
webapps go.</li>
+<li><strong>/standalone/deployments/</strong> - This is where your
webapps go.</li>
+<li><strong>/standalone/log</strong> - Log files are here by
default.</li>
</ul>
</section>
@@ -74,8 +70,8 @@
<p>This section will acquaint you with the basic information used during
the configuration of the container.</p>
-<p>All of the information in the configuration files is read at startup,
-meaning that any change to the files necessitates a restart of the container.
+<p>All of the information in the configuration file
<code>standalone/configuration/standalone.xml</code> is read at startup,
+but changes can be done used the admin console or web interface. The changes are kept
between restarts of the container.
</p>
</section>
@@ -87,7 +83,7 @@
written and easy to understand, we may have missed something. Provided
below are various web sites and mailing lists in case you get stuck.</p>
-<p>As JBoss Web 3.0 changes things over past Tomcat releases, keep in mind that
some of the
+<p>As JBoss Web 7.0 changes things over past Tomcat releases, keep in mind that
some of the
issues and solutions vary between the major versions of Tomcat (4.x, 5.x and
6.x).</p>
<ul>
@@ -95,7 +91,9 @@
to fully read the relevant documentation as it will save you much time
and effort. There's nothing like scouring the web only to find out that
the answer was right in front of you all along!</li>
-<li><a href="http://tomcat.apache.org/faq/">Tomcat FAQ</a> as
maintained by the developers.</li>
+<li><a
href="https://docs.jboss.org/author/display/AS7/Web+subsystem+config...
subsystem configuration in AS7</a></li>
+<li><a
href="http://community.jboss.org/en/jbossweb?view=discussions"&... Web User
forum</a></li>
+<li><a
href="http://community.jboss.org/en/jbossweb/dev?view=discussions&qu... Web
Developer forum</a></li>
<li><a href="http://wiki.apache.org/tomcat/">Tomcat
WIKI</a></li>
<li>Tomcat FAQ at <a
href="http://www.jguru.com/faq/home.jsp?topic=Tomcat">jGuru&...
<li>Tomcat mailing list archives - numerous sites archive the Tomcat mailing
Modified: trunk/webapps/docs/tomcat-docs.xsl
===================================================================
--- trunk/webapps/docs/tomcat-docs.xsl 2011-06-28 20:44:24 UTC (rev 1749)
+++ trunk/webapps/docs/tomcat-docs.xsl 2011-06-29 16:43:28 UTC (rev 1750)
@@ -133,7 +133,7 @@
</div>
<xsl:comment>FOOTER</xsl:comment>
- <div class="footer">© 1999-2007, Apache Software
Foundation. © 2007-2008 Red Hat Middleware, LLC. All Rights Reserved.
</div>
+ <div class="footer">© 1999-2007, Apache Software
Foundation. © 2007-2011 Red Hat Middleware, LLC. All Rights Reserved.
</div>
</div>