[jboss-cvs] jboss-docs/jbossas/web/en ...
Norman Richards
norman.richards at jboss.com
Mon Oct 2 22:57:27 EDT 2006
User: nrichards
Date: 06/10/02 22:57:27
Modified: jbossas/web/en master.xml
Log:
convert sections to chapters
Revision Changes Path
1.2 +520 -545 jboss-docs/jbossas/web/en/master.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: master.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-docs/jbossas/web/en/master.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- master.xml 18 Sep 2006 16:48:22 -0000 1.1
+++ master.xml 3 Oct 2006 02:57:27 -0000 1.2
@@ -17,73 +17,63 @@
</bookinfo>
<toc/>
- <chapter id="ch9.chapt">
- <title>Web Applications</title>
- <subtitle>Using Tomcat 5</subtitle>
-
- <para>This chapter discusses the configuration of web applications in JBoss. It looks at general issues specific
- to the use of Tomcat 5 in JBoss.</para>
-
- <section>
+ <chapter>
<title>The Tomcat Service</title>
- <para> Tomcat 5.5, the latest release of the Apache Java servlet container, supports the Servlet 2.4 and JSP
- 2.0 specifications. Tomcat is distributed as a deployable service in
- <literal>jbossweb-tomcat-55.sar</literal> in the deploy directory. It is shipped in exploded directory
- form, so it's easy to inspect and update the configuration of the embedded Tomcat instance. </para>
+ <para> Tomcat 5.5, the latest release of the Apache Java servlet container, supports the Servlet 2.4 and JSP 2.0
+ specifications. Tomcat is distributed as a deployable service in <literal>jbossweb-tomcat-55.sar</literal>
+ in the deploy directory. It is shipped in exploded directory form, so it's easy to inspect and update the
+ configuration of the embedded Tomcat instance. </para>
<para> The main service file is <literal>META-INF/jboss-service.xml</literal>. It configures the
<literal>org.jboss.web.tomcat.tc5.Tomcat5</literal> MBean which controls Tomcat. Its configurable
attributes include:</para>
<itemizedlist>
<listitem>
<para>
- <emphasis role="bold">DefaultSecurityDomain</emphasis>: This specifies the JAAS security domain
- to use in the absence of an explicit <literal>security-domain</literal> specification in the
+ <emphasis role="bold">DefaultSecurityDomain</emphasis>: This specifies the JAAS security domain to
+ use in the absence of an explicit <literal>security-domain</literal> specification in the
<literal>jboss-web.xml</literal> of a WAR file. </para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">Java2ClassLoadingCompliance</emphasis>: This enables the standard Java2
- parent delegation class loading model rather than the servlet model which loads from the WAR
- first. It is true by default, otherwise loading from WARs that include client JARs with classes
- used by EJBs causes class loading conflicts. If you enable the servlet class loading model by
- setting this flag to false, you need to organize yodeployment package to avoid having duplicate
- classes in the deployment.</para>
+ <emphasis role="bold">Java2ClassLoadingCompliance</emphasis>: This enables the standard Java2 parent
+ delegation class loading model rather than the servlet model which loads from the WAR first. It is
+ true by default, otherwise loading from WARs that include client JARs with classes used by EJBs
+ causes class loading conflicts. If you enable the servlet class loading model by setting this flag
+ to false, you need to organize yodeployment package to avoid having duplicate classes in the
+ deployment.</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">UseJBossWebLoader</emphasis>: This flag indicates that Tomcat should use a
JBoss unified class loader as the web application class loader. The default is true, which means
- that the classes inside of the <literal>WEB-INF/classes</literal> and
- <literal>WEB-INF/lib</literal> directories of the WAR file are incorporated into the default
- shared class loader repository. This allows classes and resources to be shared between web
- applications. If this is not what you want, you can disable this behaviour by setting this
- attribute to false.</para>
+ that the classes inside of the <literal>WEB-INF/classes</literal> and <literal>WEB-INF/lib</literal>
+ directories of the WAR file are incorporated into the default shared class loader repository. This
+ allows classes and resources to be shared between web applications. If this is not what you want,
+ you can disable this behaviour by setting this attribute to false.</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">LenientEjbLink</emphasis>: This flag indicates that
<literal>ejb-link</literal> errors should be ignored in favor of trying the
- <literal>jndi-name</literal> in the <literal>jboss-web.xml</literal>. The default is
- true.</para>
+ <literal>jndi-name</literal> in the <literal>jboss-web.xml</literal>. The default is true.</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">ManagerClass</emphasis>: This is the class to use as the session manager
- for replicating the state of web applications marked as distributable. The only provided
- implementation session manager is
- <literal>org.jboss.web.tomcat.tc5.session.JBossCacheManager</literal>, which uses JBossCache to
- track the distributed state. </para>
+ <emphasis role="bold">ManagerClass</emphasis>: This is the class to use as the session manager for
+ replicating the state of web applications marked as distributable. The only provided implementation
+ session manager is <literal>org.jboss.web.tomcat.tc5.session.JBossCacheManager</literal>, which uses
+ JBossCache to track the distributed state. </para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">SubjectAttributeName</emphasis>: If set, this represents the request
- attribute name under which the JAAS subject will be stored. There is no default value, meaning
- that the subject is not set in the request.</para>
+ <emphasis role="bold">SubjectAttributeName</emphasis>: If set, this represents the request attribute
+ name under which the JAAS subject will be stored. There is no default value, meaning that the
+ subject is not set in the request.</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">SessionIdAlphabet</emphasis>: This is the set of characters used to create
- a session IDs. It must be made up of exactly 65 unique characters. </para>
+ <emphasis role="bold">SessionIdAlphabet</emphasis>: This is the set of characters used to create a
+ session IDs. It must be made up of exactly 65 unique characters. </para>
</listitem>
<listitem>
<para>
@@ -95,17 +85,17 @@
</listitem>
<listitem>
<para>
- <emphasis role="bold">SnapshotInterval</emphasis>: This sets the snapshot interval in
- milliseconds for the interval snapshot mode. The default is 1000ms, which is 1 second.</para>
+ <emphasis role="bold">SnapshotInterval</emphasis>: This sets the snapshot interval in milliseconds
+ for the interval snapshot mode. The default is 1000ms, which is 1 second.</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">UseLocalCache</emphasis>: This is a flag that indicates whether the local
- HTTP session value should be used if it exists. When it is true, the existing local HTTP session
- values are used and updates are replicated, but updates to the same session on other nodes do
- not update the local session value. This mode is only useful for failover. When it is false, the
- session value is obtained from the distributed cache. This mode can be used with load balancing.
- The default is true. </para>
+ <emphasis role="bold">UseLocalCache</emphasis>: This is a flag that indicates whether the local HTTP
+ session value should be used if it exists. When it is true, the existing local HTTP session values
+ are used and updates are replicated, but updates to the same session on other nodes do not update
+ the local session value. This mode is only useful for failover. When it is false, the session value
+ is obtained from the distributed cache. This mode can be used with load balancing. The default is
+ true. </para>
</listitem>
<listitem>
<para>
@@ -128,17 +118,16 @@
<literal>jboss.security:service=JaasSecurityManager</literal>. </para>
</listitem>
</itemizedlist>
- </section>
- <section>
+ </chapter>
+ <chapter>
<title>The server.xml file</title>
- <para>While the <literal>jboss-service.xml</literal> file controls the Tomcat integration service, Tomcat
- itself has its own configuration file which guides its operation. This is the
- <literal>server.xml</literal> descriptor that you will find in the
- <literal>jbossweb-tomcat55.sar</literal> directory. </para>
+ <para>While the <literal>jboss-service.xml</literal> file controls the Tomcat integration service, Tomcat itself
+ has its own configuration file which guides its operation. This is the <literal>server.xml</literal>
+ descriptor that you will find in the <literal>jbossweb-tomcat55.sar</literal> directory. </para>
<para> The <literal>server.xml</literal> file doesn't have a formal DTD or schema definition, so we'll just
cover the major configurable elements available. The top-level element is the <literal>Server</literal>
- element. It should contain a <literal>Service</literal> element representing the entire web subsystem.
- The supported attributes are:</para>
+ element. It should contain a <literal>Service</literal> element representing the entire web subsystem. The
+ supported attributes are:</para>
<itemizedlist>
<listitem>
<para>
@@ -162,9 +151,9 @@
<para>
<emphasis role="bold">className</emphasis>: the fully qualified name of the class of the
connector implementation. The class must implement the
- <literal>org.apache.catalina.Connector</literal> interface. The embedded service
- defaults to the <literal>org.apache.catalina.connector.http.HttpConnector</literal>, which
- is the HTTP connector implementation.</para>
+ <literal>org.apache.catalina.Connector</literal> interface. The embedded service defaults to the
+ <literal>org.apache.catalina.connector.http.HttpConnector</literal>, which is the HTTP
+ connector implementation.</para>
</listitem>
<listitem>
<para>
@@ -175,61 +164,60 @@
<listitem>
<para>
<emphasis role="bold">address</emphasis>. 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.</para>
+ 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.</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">bufferSize</emphasis>: This is 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.</para>
+ provided for input streams created by this connector. By default, buffers of 2048 bytes will be
+ provided.</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">connectionTimeout</emphasis>: This is the number of milliseconds this
- connector will wait, after accepting a connection, for the request URI line to be presented.
- The default value is 60000 (i.e. 60 seconds).</para>
+ connector will wait, after accepting a connection, for the request URI line to be presented. The
+ default value is 60000 (i.e. 60 seconds).</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">debug</emphasis>: This is the debugging detail level of log messages
generated by this component, with higher numbers creating more detailed output. If not
- specified, this attribute is set to zero (0). Whether or not this shows up in the log
- further depends on the log4j category <literal>org.jboss.web.tomcat.tc5.Tomcat5</literal>
+ specified, this attribute is set to zero (0). Whether or not this shows up in the log further
+ depends on the log4j category <literal>org.jboss.web.tomcat.tc5.Tomcat5</literal>
threshold.</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">enableLookups</emphasis>: This is a flag that enables DNS resolution
- of the client hostname, as accessed via the <literal>ServletRequest.getRemoteHost</literal>
- method. This flag defaults to false.</para>
+ <emphasis role="bold">enableLookups</emphasis>: This is a flag that enables DNS resolution of
+ the client hostname, as accessed via the <literal>ServletRequest.getRemoteHost</literal> method.
+ This flag defaults to false.</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">maxThreads</emphasis>: This is the maximum number of request
- processing threads to be created by this connector, which therefore determines the maximum
- number of simultaneous requests that can be handled. If not specified, this attribute is set
- to 200.</para>
+ <emphasis role="bold">maxThreads</emphasis>: This is the maximum number of request processing
+ threads to be created by this connector, which therefore determines the maximum number of
+ simultaneous requests that can be handled. If not specified, this attribute is set to
+ 200.</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">maxSpareThreads</emphasis>: This is the maximum number of unused
- request processing threads that will be allowed to exist until the thread pool starts
- stopping the unnecessary threads. The default value is 50.</para>
+ <emphasis role="bold">maxSpareThreads</emphasis>: This is the maximum number of unused request
+ processing threads that will be allowed to exist until the thread pool starts stopping the
+ unnecessary threads. The default value is 50.</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">minSpareThreads</emphasis>: This is the number of request processing
- threads that will be created when this connector is first started. The connector will also
- make sure it has the specified number of idle processing threads available. This attribute
- should be set to a value smaller than that set for maxThreads. The default value is 4.
- </para>
+ threads that will be created when this connector is first started. The connector will also make
+ sure it has the specified number of idle processing threads available. This attribute should be
+ set to a value smaller than that set for maxThreads. The default value is 4. </para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">port</emphasis>: This is the TCP port number on which this connector
- will create a server socket and await incoming connections. Only one server application can
- listen to a particular port number on a particular IP address at a time.</para>
+ <emphasis role="bold">port</emphasis>: This is the TCP port number on which this connector will
+ create a server socket and await incoming connections. Only one server application can listen to
+ a particular port number on a particular IP address at a time.</para>
</listitem>
<listitem>
<para>
@@ -245,9 +233,9 @@
</listitem>
<listitem>
<para>
- <emphasis role="bold">redirectPort</emphasis>: This is the port that non-SSL requests will
- be redirected to when a request for content secured under a transport confidentiality or
- integrity constraint is received. This defaults to the standard HTTPS port of 443.</para>
+ <emphasis role="bold">redirectPort</emphasis>: This is the port that non-SSL requests will be
+ redirected to when a request for content secured under a transport confidentiality or integrity
+ constraint is received. This defaults to the standard HTTPS port of 443.</para>
</listitem>
<listitem>
<para>
@@ -273,23 +261,22 @@
</section>
<section>
<title>The Engine element</title>
- <para>Each <literal>Service</literal> must have a single <literal>Engine</literal> configuration. An
- engine handles the requests submitted to a service via the configured connectors. The child elements
- supported by the embedded service include <literal>Host</literal>, <literal>Logger</literal>,
+ <para>Each <literal>Service</literal> must have a single <literal>Engine</literal> configuration. An engine
+ handles the requests submitted to a service via the configured connectors. The child elements supported
+ by the embedded service include <literal>Host</literal>, <literal>Logger</literal>,
<literal>Valve</literal> and <literal>Listener</literal>. The supported attributes include:</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">className</emphasis>: This is the fully qualified class name of the
<literal>org.apache.catalina.Engine</literal> interface implementation to use. If not
- specifies this defaults to
- <literal>org.apache.catalina.core.StandardEngine</literal>.</para>
+ specifies this defaults to <literal>org.apache.catalina.core.StandardEngine</literal>.</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">defaultHost</emphasis>: This is he name of a <literal>Host</literal>
- configured under the <literal>Engine</literal> that will handle requests with host names
- that do not match a <literal>Host</literal> configuration.</para>
+ configured under the <literal>Engine</literal> that will handle requests with host names that do
+ not match a <literal>Host</literal> configuration.</para>
</listitem>
<listitem>
<para>
@@ -304,10 +291,10 @@
</section>
<section>
<title>The Host element</title>
- <para>A <literal>Host</literal> element represents a virtual host configuration. It is a container for
- web applications with a specified DNS hostname. The child elements supported by the embedded service
- include <literal>Alias</literal>, <literal>Valve</literal> and <literal>Listener</literal>. The
- supported attributes include:</para>
+ <para>A <literal>Host</literal> element represents a virtual host configuration. It is a container for web
+ applications with a specified DNS hostname. The child elements supported by the embedded service include
+ <literal>Alias</literal>, <literal>Valve</literal> and <literal>Listener</literal>. The supported
+ attributes include:</para>
<itemizedlist>
<listitem>
<para>
@@ -317,23 +304,22 @@
</listitem>
<listitem>
<para>
- <emphasis role="bold">name</emphasis>: This is the DNS name of the virtual host. At least
- one <literal>Host</literal> element must be configured with a name that corresponds to the
+ <emphasis role="bold">name</emphasis>: This is the DNS name of the virtual host. At least one
+ <literal>Host</literal> element must be configured with a name that corresponds to the
<literal>defaultHost</literal> value of the containing <literal>Engine</literal>.</para>
</listitem>
</itemizedlist>
<para>The <literal>Alias</literal> element is an optional child element of the <literal>Host</literal>
element. Each <literal>Alias</literal> specifies an alternate DNS name for the enclosing
<literal>Host</literal>.</para>
- <para>You can find additional information on the <literal>Host</literal> element in the Tomcat
- documentation at <ulink url="http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/host.html"
- />.</para>
+ <para>You can find additional information on the <literal>Host</literal> element in the Tomcat documentation
+ at <ulink url="http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/host.html"/>.</para>
</section>
<section>
<title>The Valve element</title>
- <para>A <literal>Valve</literal> element configures a hook into the request processing pipeline for the
- web container. Valves must implement the <literal>org.apache.catalina.Valve</literal> interface.
- There is only one required configuration attribute: </para>
+ <para>A <literal>Valve</literal> element configures a hook into the request processing pipeline for the web
+ container. Valves must implement the <literal>org.apache.catalina.Valve</literal> interface. There is
+ only one required configuration attribute: </para>
<itemizedlist>
<listitem>
<para>
@@ -341,20 +327,20 @@
<literal>org.apache.catalina.Valve</literal> interface implementation.</para>
</listitem>
</itemizedlist>
- <para> The most commonly used valve is the <literal>AccessLogValve</literal>, which keeps a standard
- HTTP access log of incoming requests. The <literal>className</literal> for the access log value is
+ <para> The most commonly used valve is the <literal>AccessLogValve</literal>, which keeps a standard HTTP
+ access log of incoming requests. The <literal>className</literal> for the access log value is
<literal>org.jboss.web.catalina.valves.AccessLogValue</literal>. The additional attributes its
supports include:</para>
<itemizedlist>
<listitem>
<para>
- <emphasis role="bold">directory</emphasis>: This is the directory path into which the access
- log files will be created.</para>
+ <emphasis role="bold">directory</emphasis>: This is the directory path into which the access log
+ files will be created.</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">pattern</emphasis>: This is a pattern specifier that defines the
- format of the log messages. It defaults to <literal>common</literal>.</para>
+ <emphasis role="bold">pattern</emphasis>: This is a pattern specifier that defines the format of
+ the log messages. It defaults to <literal>common</literal>.</para>
</listitem>
<listitem>
<para>
@@ -367,15 +353,15 @@
defaults to an empty string, meaning that no suffix will be added.</para>
</listitem>
</itemizedlist>
- <para>You can find additional information on the <literal>Valve</literal> element and the available
- valve implementations in the Tomcat documentation at <ulink
+ <para>You can find additional information on the <literal>Valve</literal> element and the available valve
+ implementations in the Tomcat documentation at <ulink
url="http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/valve.html"/>.</para>
</section>
- </section>
- <section>
+ </chapter>
+ <chapter>
<title>The context.xml file</title>
- <para>The <literal>context.xml</literal> file contains the default Context element used for all web
- applications in the system. The supported attributes include:</para>
+ <para>The <literal>context.xml</literal> file contains the default Context element used for all web applications
+ in the system. The supported attributes include:</para>
<itemizedlist>
<listitem>
<para>
@@ -389,19 +375,17 @@
other web applications deployed in the calling web application's virtual host.</para>
</listitem>
</itemizedlist>
- <para>You can find additional information on the <literal>Context</literal> element in the Tomcat
- documentation at <ulink url="http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/context.html"/>.
- </para>
- </section>
- <section id="ch9.https.sect">
+ <para>You can find additional information on the <literal>Context</literal> element in the Tomcat documentation
+ at <ulink url="http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/context.html"/>. </para>
+ </chapter>
+ <chapter id="ch9.https.sect">
<title>Using HTTPS</title>
- <para>There are a few ways you can configure HTTP over SSL for the embedded Tomcat servlet container
- depending on whether or not you use the JBoss specific connector socket factory, which allows you to
- obtain the JSSE server certificate information from a JBossSX <literal>SecurityDomain</literal>. This
- requires establishing a <literal>SecurityDomain</literal> using the
- <literal>org.jboss.security.plugins.JaasSecurityDomain</literal> MBean. A
- <literal>server.xml</literal> configuration file that illustrates the setup of only an SSL connector via
- this approach is given below. </para>
+ <para>There are a few ways you can configure HTTP over SSL for the embedded Tomcat servlet container depending
+ on whether or not you use the JBoss specific connector socket factory, which allows you to obtain the JSSE
+ server certificate information from a JBossSX <literal>SecurityDomain</literal>. This requires establishing
+ a <literal>SecurityDomain</literal> using the
+ <literal>org.jboss.security.plugins.JaasSecurityDomain</literal> MBean. A <literal>server.xml</literal>
+ configuration file that illustrates the setup of only an SSL connector via this approach is given below. </para>
<programlisting><Server>
<Service name="jboss.web" className="org.jboss.web.tomcat.tc5.StandardService">
@@ -428,42 +412,40 @@
</Engine>
</Service>
</Server></programlisting>
- <para>This configuration includes a <literal>JaasSecurityDomain</literal>, but since the descriptor is not
- being deployed as part of a SAR that includes the <literal>chap8.keystore</literal>, you need to copy
- the <literal>chap8.keystore</literal> to the <literal>server/default/conf </literal>directory. You can
- test this configuration by accessing the JMX console web application over HTTPS using this URL: <ulink
+ <para>This configuration includes a <literal>JaasSecurityDomain</literal>, but since the descriptor is not being
+ deployed as part of a SAR that includes the <literal>chap8.keystore</literal>, you need to copy the
+ <literal>chap8.keystore</literal> to the <literal>server/default/conf </literal>directory. You can test
+ this configuration by accessing the JMX console web application over HTTPS using this URL: <ulink
url="https://localhost/jmx-console"/>.</para>
- <para>Note: if you are running on a system that requires special permissions to open ports below 1024, it
- might be easier need to change the port number to one above 1024. Port 8443 is commonly used because of
- this.</para>
+ <para>Note: if you are running on a system that requires special permissions to open ports below 1024, it might
+ be easier need to change the port number to one above 1024. Port 8443 is commonly used because of this.</para>
<para>The configurable attributes are as follows:</para>
<itemizedlist>
<listitem>
<para>
- <emphasis role="bold">algorithm</emphasis>: This is the certificate encoding algorithm to be
- used. If not specified, the default value is SunX509.</para>
+ <emphasis role="bold">algorithm</emphasis>: This is the certificate encoding algorithm to be used.
+ If not specified, the default value is SunX509.</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">className</emphasis>: This is the fully qualified class name of the SSL
- server socket factory implementation class. You must specify
- org.apache.coyote.tomcat4.CoyoteServerSocketFactory here. Using any other socket factory will
- not cause an error, but the server socket will not be using SSL.</para>
+ <emphasis role="bold">className</emphasis>: This is the fully qualified class name of the SSL server
+ socket factory implementation class. You must specify
+ org.apache.coyote.tomcat4.CoyoteServerSocketFactory here. Using any other socket factory will not
+ cause an error, but the server socket will not be using SSL.</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">clientAuth</emphasis>: This attribute should be set to true if you want
- the SSL stack to require a valid certificate chain from the client before accepting a
- connection. A false value, which is the default, will not require a certificate chain unless the
- client requests a resource protected by a security constraint that uses CLIENT-CERT
- authentication.</para>
+ <emphasis role="bold">clientAuth</emphasis>: This attribute should be set to true if you want the
+ SSL stack to require a valid certificate chain from the client before accepting a connection. A
+ false value, which is the default, will not require a certificate chain unless the client requests a
+ resource protected by a security constraint that uses CLIENT-CERT authentication.</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">keystoreFile</emphasis>: This is the pathname of the keystore file where
- you have stored the server certificate to be loaded. By default, the pathname is the file
- <literal>.keystore</literal> in the operating system home directory of the user that is
- running Tomcat.</para>
+ <emphasis role="bold">keystoreFile</emphasis>: This is the pathname of the keystore file where you
+ have stored the server certificate to be loaded. By default, the pathname is the file
+ <literal>.keystore</literal> in the operating system home directory of the user that is running
+ Tomcat.</para>
</listitem>
<listitem>
<para>
@@ -473,24 +455,23 @@
</listitem>
<listitem>
<para>
- <emphasis role="bold">keystoreType</emphasis>: The type of keystore file to be used for the
- server certificate. If not specified, the default value is <literal>JKS</literal>.</para>
+ <emphasis role="bold">keystoreType</emphasis>: The type of keystore file to be used for the server
+ certificate. If not specified, the default value is <literal>JKS</literal>.</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">protocol</emphasis>: The version of the SSL protocol to use. If not
- specified, the default is <literal>TLS</literal>.</para>
+ <emphasis role="bold">protocol</emphasis>: The version of the SSL protocol to use. If not specified,
+ the default is <literal>TLS</literal>.</para>
</listitem>
</itemizedlist>
- <para>Note that if you try to test this configuration using the self-signed certificate
- and attempt to access content over an HTTPS connection, your browser
- should display a warning dialog indicating that it does not trust the certificate authority that signed
- the certificate of the server you are connecting to. For example, when we tested the first configuration
- example, IE 5.5 showed the initial security alert dialog listed in <xref linkend="ch9.ie5alert.fig"/>.
- <xref linkend="ch9.ie5cert.fig"/> shows the server certificate details. This warning is important
- because anyone can generate a self-signed certificate with any information desired. Your only way to
- verify that the system on the other side really represents the party it claim to is by verifying that it
- is signed by a trusted third party. </para>
+ <para>Note that if you try to test this configuration using the self-signed certificate and attempt to access
+ content over an HTTPS connection, your browser should display a warning dialog indicating that it does not
+ trust the certificate authority that signed the certificate of the server you are connecting to. For
+ example, when we tested the first configuration example, IE 5.5 showed the initial security alert dialog
+ listed in <xref linkend="ch9.ie5alert.fig"/>. <xref linkend="ch9.ie5cert.fig"/> shows the server certificate
+ details. This warning is important because anyone can generate a self-signed certificate with any
+ information desired. Your only way to verify that the system on the other side really represents the party
+ it claim to is by verifying that it is signed by a trusted third party. </para>
<figure id="ch9.ie5alert.fig">
<title>The Internet Explorer 5.5 security alert dialog.</title>
<mediaobject>
@@ -507,29 +488,29 @@
</imageobject>
</mediaobject>
</figure>
- </section>
- <section>
+ </chapter>
+ <chapter>
<title>Using DIGEST Authentication</title>
- <para>When using BASIC and FORM web authentications, the users password is sent in the clear as part of the
- HTTP requests. As we saw in the last section, it is possible to encrypt the entire session using HTTPS,
- keeping the password private over the wire. However, this still requires the password to exist on in
- plain text form on the server, at least temporarily in memory if not in password store. </para>
- <para>Digest authentication employs a challenge-response mechanism, whereby the server sends a unique
- challenge to the client. The client responds with a hashed value that the server compares against it's
- own hashed value. At no point does the client ever send the the actual password text to the server. </para>
+ <para>When using BASIC and FORM web authentications, the users password is sent in the clear as part of the HTTP
+ requests. As we saw in the last section, it is possible to encrypt the entire session using HTTPS, keeping
+ the password private over the wire. However, this still requires the password to exist on in plain text form
+ on the server, at least temporarily in memory if not in password store. </para>
+ <para>Digest authentication employs a challenge-response mechanism, whereby the server sends a unique challenge
+ to the client. The client responds with a hashed value that the server compares against it's own hashed
+ value. At no point does the client ever send the the actual password text to the server. </para>
<para>Web applications request digest authentication by setting the <literal>auth-method</literal> to
- <literal>DIGEST</literal> in the <literal>web.xml</literal> deployment descriptor. The following
- example shows what this would look like, omitting the application-specific
- <literal>security-constraint</literal> and <literal>security-role</literal> declarations. </para>
+ <literal>DIGEST</literal> in the <literal>web.xml</literal> deployment descriptor. The following example
+ shows what this would look like, omitting the application-specific <literal>security-constraint</literal>
+ and <literal>security-role</literal> declarations. </para>
<programlisting><login-config>
<auth-method>DIGEST</auth-method>
<realm-name>My Aplication</realm-name>
</login-config></programlisting>
- <para>To complete the configuration, we'll create a special digest-friendly security domain and link it to
- the application. For this example, we'll create a security domain under the name
+ <para>To complete the configuration, we'll create a special digest-friendly security domain and link it to the
+ application. For this example, we'll create a security domain under the name
<literal>java:/jaas/digest</literal>. The application would link to it in the
<literal>jboss-web.xml</literal> file.</para>
<programlisting><jboss-web>
@@ -559,17 +540,17 @@
</application-policy></programlisting>
- <para>The first two module options configure the locations of the user and roles properties file. The
- remaining six complete the configuration for digest authentication. To enable digest authentication in
- your application, copy these last 6 options into your login module configuration.</para>
-
- <para>At this point, all the is required is to create the password hashes to be stored in your user store,
- which is the <literal>digest-users.properties</literal> file in this example. Digest hashes hash the
- username, the password, and the realm name together. The realm name comes from the realm name in
+ <para>The first two module options configure the locations of the user and roles properties file. The remaining
+ six complete the configuration for digest authentication. To enable digest authentication in your
+ application, copy these last 6 options into your login module configuration.</para>
+
+ <para>At this point, all the is required is to create the password hashes to be stored in your user store, which
+ is the <literal>digest-users.properties</literal> file in this example. Digest hashes hash the username, the
+ password, and the realm name together. The realm name comes from the realm name in
<literal>web.xml</literal> file. In this example it is <literal>My Application</literal>. </para>
- <para>JBoss provides a helper class to create digest hashes. It can be invoked from the bin directory as
- shown here:</para>
+ <para>JBoss provides a helper class to create digest hashes. It can be invoked from the bin directory as shown
+ here:</para>
<programlisting>[bin]$ java -cp ../server/default/lib/jbosssx.jar \
org.jboss.security.auth.spi.RFC2617Digest username "My Application" password
@@ -581,26 +562,25 @@
<programlisting>user=9b47ec6f03603dd49863e7d58c4c49ea</programlisting>
- <para>You would still need to define the application roles and configure them in the login module to
- complete the security configuration. However, none of this differs with digest authentication.</para>
+ <para>You would still need to define the application roles and configure them in the login module to complete
+ the security configuration. However, none of this differs with digest authentication.</para>
- </section>
- <section>
+ </chapter>
+ <chapter>
<title>Setting the context root of a web application</title>
- <para> The context root of a web application determines which URLs Tomcat will delegate to your web
- application. If your application's context root is <literal>myapp</literal> then any request for
- <literal>/myapp</literal> or <literal>/myapp/*</literal> will be handled by your application unless
- a more specific context root exists. If a second web application were assigned the context root
- <literal>myapp/help</literal>, a request for <literal>/myapp/help/help.jsp</literal> would be
- handled by the second web application, not the first.</para>
- <para>This relationship also holds when the context root is set to <literal>/</literal>, which is known as
- the root context. When an application is assigned to the root context, it will respond to all requests
- no handled by a more specific context root. </para>
+ <para> The context root of a web application determines which URLs Tomcat will delegate to your web application.
+ If your application's context root is <literal>myapp</literal> then any request for
+ <literal>/myapp</literal> or <literal>/myapp/*</literal> will be handled by your application unless a more
+ specific context root exists. If a second web application were assigned the context root
+ <literal>myapp/help</literal>, a request for <literal>/myapp/help/help.jsp</literal> would be handled by the
+ second web application, not the first.</para>
+ <para>This relationship also holds when the context root is set to <literal>/</literal>, which is known as the
+ root context. When an application is assigned to the root context, it will respond to all requests no
+ handled by a more specific context root. </para>
<para> The context root for an application is determined by how it is deployed. When a web application is
- deployed inside an EAR file, the context root is specified in the <literal>application.xml</literal>
- file of the EAR, using a <literal>context-root</literal> element inside of a web module. In the
- following example, the context root of the <literal>web-client.war</literal> application is set to
- <literal>bank</literal>. </para>
+ deployed inside an EAR file, the context root is specified in the <literal>application.xml</literal> file of
+ the EAR, using a <literal>context-root</literal> element inside of a web module. In the following example,
+ the context root of the <literal>web-client.war</literal> application is set to <literal>bank</literal>. </para>
<programlisting><application xmlns="http://java.sun.com/xml/ns/j2ee" version="1.4"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com /xml/ns/j2ee
@@ -620,29 +600,28 @@
</application></programlisting>
<para> For web applications that are deployed outside an EAR file, the context root can be specified in two
ways. First, the context root can be specified in the <literal>WEB-INF/jboss-web.xml</literal> file. The
- following example shows what the <literal>jboss-web.xml</literal> file would look like if it weren't
- bundled inside of an EAR file. </para>
+ following example shows what the <literal>jboss-web.xml</literal> file would look like if it weren't bundled
+ inside of an EAR file. </para>
<programlisting><jboss-web>
<emphasis role="bold"><context-root>bank</context-root></emphasis>
</jboss-web></programlisting>
- <para> Finally, if no context root specification exists, the context root will be the base name of the WAR
- file. For <literal>web-client.war</literal>, the context root would default to
- <literal>web-client</literal>. The only special case to this naming special name
- <literal>ROOT</literal>. To deploy an application under the root context, you simply name it
- <literal>ROOT.war</literal>. JBoss already contains a <literal>ROOT.war</literal> web application in
- the <literal>jbossweb-tomcat55.sar</literal> directory. You will need to remove or rename that one to
- create your own root application.</para>
- <para> Naming your WAR file after the context root they are intended to handle is a very good practice. Not
- only does it reduce the number of configuration settings to manage, but it improves the maintainability
- of the application by making the intended function of the web application clear.</para>
- </section>
- <section>
+ <para> Finally, if no context root specification exists, the context root will be the base name of the WAR file.
+ For <literal>web-client.war</literal>, the context root would default to <literal>web-client</literal>. The
+ only special case to this naming special name <literal>ROOT</literal>. To deploy an application under the
+ root context, you simply name it <literal>ROOT.war</literal>. JBoss already contains a
+ <literal>ROOT.war</literal> web application in the <literal>jbossweb-tomcat55.sar</literal> directory. You
+ will need to remove or rename that one to create your own root application.</para>
+ <para> Naming your WAR file after the context root they are intended to handle is a very good practice. Not only
+ does it reduce the number of configuration settings to manage, but it improves the maintainability of the
+ application by making the intended function of the web application clear.</para>
+ </chapter>
+ <chapter>
<title>Setting up Virtual Hosts</title>
- <para>Virtual hosts allow you to group web applications according to the various DNS names by which the
- machine running JBoss is known. As an example, consider the <literal>server.xml</literal> configuration
- file given in <xref linkend="ch9.virtualhost.ex"/>. This configuration defines a default host named
- <literal>vhost1.mydot.com</literal> and a second host named <literal>vhost2.mydot.com</literal>,
- which also has the alias <literal>www.mydot.com</literal> associated with it.</para>
+ <para>Virtual hosts allow you to group web applications according to the various DNS names by which the machine
+ running JBoss is known. As an example, consider the <literal>server.xml</literal> configuration file given
+ in <xref linkend="ch9.virtualhost.ex"/>. This configuration defines a default host named
+ <literal>vhost1.mydot.com</literal> and a second host named <literal>vhost2.mydot.com</literal>, which
+ also has the alias <literal>www.mydot.com</literal> associated with it.</para>
<example id="ch9.virtualhost.ex">
<title>A virtual host configuration.</title>
<programlisting><Server>
@@ -689,34 +668,32 @@
</Server></programlisting>
</example>
<para>When a WAR file is deployed, it is associated by default with the virtual host whose name matches the
- <literal>defaultHost</literal> attribute of the containing <literal>Engine</literal>. To deploy a
- WAR to a specific virtual host you need to specify an appropriate <literal>virtual-host</literal>
- definition in your <literal>jboss-web.xml</literal> descriptor. The following
- <literal>jboss-web.xml</literal> descriptor demonstrates how to deploy a WAR to the virtual host
- <literal>www.mydot.com</literal>. Note that you can use either the virtual host name in the config
- file or the actual host name.</para>
+ <literal>defaultHost</literal> attribute of the containing <literal>Engine</literal>. To deploy a WAR to
+ a specific virtual host you need to specify an appropriate <literal>virtual-host</literal> definition in
+ your <literal>jboss-web.xml</literal> descriptor. The following <literal>jboss-web.xml</literal> descriptor
+ demonstrates how to deploy a WAR to the virtual host <literal>www.mydot.com</literal>. Note that you can use
+ either the virtual host name in the config file or the actual host name.</para>
<programlisting><jboss-web>
<context-root>/</context-root>
<virtual-host>www.mydot.com</virtual-host>
</jboss-web></programlisting>
- </section>
- <section>
+ </chapter>
+ <chapter>
<title>Serving Static Content</title>
<para>JBoss provides a default application that serves content for the <emphasis>root</emphasis> application
context. This default context is the <literal>ROOT.war</literal> application in the
- <literal>jbossweb-tomcat55.sar</literal> directory. You can serve static files not associated with
- any other application by adding that content to the <literal>ROOT.war</literal> directory. For example,
- if you want to have a shared image directory you could create an <literal>image</literal> subdirectory
- in <literal>ROOT.war</literal> and place the images there. You could then access an image named
+ <literal>jbossweb-tomcat55.sar</literal> directory. You can serve static files not associated with any
+ other application by adding that content to the <literal>ROOT.war</literal> directory. For example, if you
+ want to have a shared image directory you could create an <literal>image</literal> subdirectory in
+ <literal>ROOT.war</literal> and place the images there. You could then access an image named
<literal>myimage.jpg</literal> at <ulink url="http://localhost:8080/images/myimage.jpg"/>. </para>
- </section>
- <section>
+ </chapter>
+ <chapter>
<title>Using Apache with Tomcat</title>
- <para>In some architectures, it is useful to put an Apache web server in front of the JBoss server. External
- web clients talk to an Apache instance, which in turn speaks to the Tomcat instance on behalf of the
- clients. Apache needs to be configured to use the mod_jk module which speaks the AJP protocol to an AJP
- connector running in Tomcat. The provided <literal>server.xml</literal> file comes with this AJP
- connector enabled. </para>
+ <para>In some architectures, it is useful to put an Apache web server in front of the JBoss server. External web
+ clients talk to an Apache instance, which in turn speaks to the Tomcat instance on behalf of the clients.
+ Apache needs to be configured to use the mod_jk module which speaks the AJP protocol to an AJP connector
+ running in Tomcat. The provided <literal>server.xml</literal> file comes with this AJP connector enabled. </para>
<programlisting><Connector port="8009" address="${jboss.bind.address}"
enableLookups="false" redirectPort="8443" debug="0"
protocol="AJP/1.3" /></programlisting>
@@ -733,17 +710,17 @@
JkLogLevel debug
JkMount /jbosstest/* ajp13
</IfModule></programlisting>
- <para> The <literal>workers.properties</literal> file contains the details of how to contact the JBoss
- instance. For more details on how to front Apache for JBoss, especially for a cluster of JBoss servers,
- please refer to JBoss 4 Clustering Guide.</para>
- </section>
+ <para> The <literal>workers.properties</literal> file contains the details of how to contact the JBoss instance.
+ For more details on how to front Apache for JBoss, especially for a cluster of JBoss servers, please refer
+ to JBoss 4 Clustering Guide.</para>
+ </chapter>
- <section>
+ <chapter>
<title>Using JavaServer Faces</title>
- <para> Starting with version 4.0.3, the JBoss Application Server features built-in JavaServer Faces support.
- The implementation used is Apache MyFaces; however, the MyFaces extensions are not included with the
- JBoss distribution at this time. JBoss allows you to install your JSF application without putting lots
- of extra JSF implementation JAR files in your <literal>WEB-INF/lib</literal> directory.</para>
+ <para> Starting with version 4.0.3, the JBoss Application Server features built-in JavaServer Faces support. The
+ implementation used is Apache MyFaces; however, the MyFaces extensions are not included with the JBoss
+ distribution at this time. JBoss allows you to install your JSF application without putting lots of extra
+ JSF implementation JAR files in your <literal>WEB-INF/lib</literal> directory.</para>
<para>To make use of JSF, you need to declare the Faces Servlet and the servlet mapping in the
<literal>web.xml</literal> file:</para>
<programlisting><servlet>
@@ -840,12 +817,10 @@
Default: "false"
</description>
</context-param></programlisting>
- <para>To use another JSF implementation, such as the reference implementation, instead of the bundled
- MyFaces implementation, simply delete the <programlisting>jbossweb-tomcat55.sar/jsf-lib</programlisting>
- directory. You will need to include the the implementation JAR files in your own
- <programlisting>WEB-INF/lib</programlisting> directory for each web application making use of
- JSF.</para>
- </section>
+ <para>To use another JSF implementation, such as the reference implementation, instead of the bundled MyFaces
+ implementation, simply delete the <programlisting>jbossweb-tomcat55.sar/jsf-lib</programlisting> directory.
+ You will need to include the the implementation JAR files in your own
+ <programlisting>WEB-INF/lib</programlisting> directory for each web application making use of JSF.</para>
</chapter>
</book>
More information about the jboss-cvs-commits
mailing list