[jboss-cvs] jboss-docs/jbossas/web/en ...
Norman Richards
norman.richards at jboss.com
Mon Sep 18 12:48:22 EDT 2006
User: nrichards
Date: 06/09/18 12:48:22
Added: jbossas/web/en master.xml
Log:
problems checking in?
Revision Changes Path
1.1 date: 2006/09/18 16:48:22; author: nrichards; state: Exp;jboss-docs/jbossas/web/en/master.xml
Index: master.xml
===================================================================
<?xml version='1.0' encoding="iso-8859-1"?>
<book>
<bookinfo>
<title>The JBoss 4 Application Server Web Developer Reference</title>
<subtitle>JBoss AS 4.0.4</subtitle>
<releaseinfo>Release 5</releaseinfo>
<mediaobject>
<imageobject>
<imagedata fileref="images/title.jpg"/>
</imageobject>
</mediaobject>
<copyright>
<year>2006></year>
<holder>JBoss, Inc.</holder>
</copyright>
</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>
<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> 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
<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>
</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>
</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>
</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>
</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>
</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>
</listitem>
<listitem>
<para>
<emphasis role="bold">SnapshotMode</emphasis>: This sets the snapshot mode in a clustered
environment. This must be one of <literal>instant</literal> or <literal>interval</literal>. In
instant mode changes to a clustered session are instantly propagated whenever a modification is
made. In interval mode all modifications are periodically propagated according to the
<literal>SnapshotInterval</literal>.</para>
</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>
</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>
</listitem>
<listitem>
<para>
<emphasis role="bold">UseJK</emphasis>: This specifies that you are using MOD_JK(2) for load
balancing with sticky session combined with <literal>JvmRoute</literal>. If set to true, it will
insert a <literal>JvmRouteFilter</literal> to intercept every request and replace the
<literal>JvmRoute</literal> if it detects a failover. This additionally requires the
<literal>JvmRoute</literal> to be set inside the engine definition in the Tomcat
<literal>server.xml</literal> file. The default is false. </para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Domain</emphasis>: This is the JMX domain under which Tomcat will register
additional MBeans. The default domain is <literal>jboss.web</literal>.</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">SecurityMangerService</emphasis>: This is a reference to the JAAS security
manager for Tomcat to use. It defaults to
<literal>jboss.security:service=JaasSecurityManager</literal>. </para>
</listitem>
</itemizedlist>
</section>
<section>
<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> 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>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">name</emphasis>: A unique name by which the service is known.</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">className</emphasis>: The name of the class that provides the service
implementation.</para>
</listitem>
</itemizedlist>
<section>
<title>The Connector element</title>
<para>A <literal>Service</literal> element should have one or more connectors under it. A connector
configures a transport mechanism that allows clients to send requests and receive responses from the
<literal>Service</literal> it is associated with. Connectors forward requests to the engine and
return the results to the requesting client. Each connector is configured using
<literal>Connector</literal> element. Connectors support these attributes:</para>
<itemizedlist>
<listitem>
<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>
</listitem>
<listitem>
<para>
<emphasis role="bold">acceptCount</emphasis>: This is 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.</para>
</listitem>
<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>
</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>
</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>
</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>
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>
</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>
</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>
</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>
</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>
</listitem>
<listitem>
<para>
<emphasis role="bold">proxyName</emphasis>: If this connector is being used in a proxy
configuration, this attribute specifies the server name to be returned for calls to
<literal>request.getServerName()</literal>. </para>
</listitem>
<listitem>
<para>
<emphasis role="bold">proxyPort</emphasis>: If this connector is being used in a proxy
configuration, this attribute specifies the server port to be returned for calls to
<literal>request.getServerPort()</literal>. </para>
</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>
</listitem>
<listitem>
<para>
<emphasis role="bold">secure</emphasis>: This sets the
<literal>ServletRequest.isSecure</literal> method value flag to indicate whether or not the
transport channel is secure. This flag defaults to false. </para>
</listitem>
<listitem>
<para>
<emphasis role="bold">scheme</emphasis>: This sets the protocol name as accessed by the
<literal>ServletRequest.getScheme</literal> method. The scheme defaults to
<literal>http</literal>.</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">tcpNoDelay</emphasis>: If this attribute is set to true, the
<literal>TCP_NO_DELAY</literal> option will be set on the server socket, which improves
performance under most circumstances. This is set to true by default.</para>
</listitem>
</itemizedlist>
<para>You can find attribute descriptions in the Tomcat documentation at <ulink
url="http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/http.html"/>. </para>
</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>,
<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>
</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>
</listitem>
<listitem>
<para>
<emphasis role="bold">name</emphasis>: This is a logical name assigned to the
<literal>Engine</literal>. It is used in log messages produced by the
<literal>Engine</literal>.</para>
</listitem>
</itemizedlist>
<para>You can find additional information on the <literal>Engine</literal> element in the Tomcat
documentation at <ulink url="http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/engine.html"
/>.</para>
</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>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">className</emphasis>: This is the fully qualified class name of the
<literal>org.apache.catalina.Host</literal> interface implementation to use. If not
specifies this defaults to <literal>org.apache.catalina.core.StandardHost</literal>.</para>
</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
<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>
</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>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">className</emphasis>: This is the fully qualified class name of the
<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
<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>
</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>
</listitem>
<listitem>
<para>
<emphasis role="bold">prefix</emphasis>: This is the prefix to add to each log file name. It
defaults to <literal>access_log</literal>.</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">suffix</emphasis>: This is the suffix to add to each log file name. It
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
url="http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/valve.html"/>.</para>
</section>
</section>
<section>
<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>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">cookies</emphasis>: This is a flag indicating if sessions will be tracked
using cookies. The default is true.</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">crossContext</emphasis>: This is a flag indicating whether the
<literal>ServletContext.getContext(String path)</literal> method should return contexts for
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">
<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>
<programlisting><Server>
<Service name="jboss.web" className="org.jboss.web.tomcat.tc5.StandardService">
<Connector port="8080" address="${jboss.bind.address}" maxThreads="150"
minSpareThreads="25" maxSpareThreads="75" enableLookups="false"
redirectPort="443" acceptCount="100" connectionTimeout="20000"
disableUploadTimeout="true"/>
<emphasis role="bold"><Connector port="443" address="${jboss.bind.address}" maxThreads="100"
minSpareThreads="5" maxSpareThreads="15" scheme="https"
secure="true" clientAuth="false"
keystoreFile="${jboss.server.home.dir}/conf/chap8.keystore"
keystorePass="rmi+ssl" sslProtocol="TLS"/></emphasis>
<Engine name="jboss.web" defaultHost="localhost">
<Realm
className="org.jboss.web.tomcat.security.JBossSecurityMgrRealm"
certificatePrincipal="org.jboss.securia.Log4jLogger"
verbosityLevel="WARNING" category="org.jboss.web.localhost.Engine"/>
<Host name="localhost" autoDeploy="false" deployOnStartup="false"
deployXML="false">
<DefaultContext cookies="true" crossContext="true" override="true"/>
</Host>
</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
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>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>
</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>
</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>
</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>
</listitem>
<listitem>
<para>
<emphasis role="bold">keystorePass</emphasis>: This is the password used to access the server
certificate from the specified keystore file. The default value is
<literal>changeit</literal>.</para>
</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>
</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>
</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>
<figure id="ch9.ie5alert.fig">
<title>The Internet Explorer 5.5 security alert dialog.</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/Chap9-5.jpg"/>
</imageobject>
</mediaobject>
</figure>
<figure id="ch9.ie5cert.fig">
<title>The Internet Explorer 5.5 SSL certificate details dialog.</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/Chap9-6.jpg"/>
</imageobject>
</mediaobject>
</figure>
</section>
<section>
<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>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>
<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
<literal>java:/jaas/digest</literal>. The application would link to it in the
<literal>jboss-web.xml</literal> file.</para>
<programlisting><jboss-web>
<security-domain>java:/jaas/digest</security-domain>
</jboss-web> </programlisting>
<para>Now we need to create the security domain definition. We'll use the
<literal>UsersRolesLoginModule</literal> in this example, though any login module that supports password
hashing can be used. The following examples shows a complete configuration. </para>
<programlisting><application-policy name="digest">
<authentication>
<login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
flag="required">
<module-option name="usersProperties">digest-users.properties</module-option>
<module-option name="rolesProperties">digest-roles.properties</module-option>
<module-option name="hashAlgorithm">MD5</module-option>
<module-option name="hashEncoding">rfc2617</module-option>
<module-option name="hashUserPassword">false</module-option>
<module-option name="hashStorePassword">true</module-option>
<module-option name="passwordIsA1Hash">true</module-option>
<module-option name="storeDigestCallback">
org.jboss.security.auth.spi.RFC2617Digest
</module-option>
</login-module>
</authentication>
</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
<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>
<programlisting>[bin]$ java -cp ../server/default/lib/jbosssx.jar \
org.jboss.security.auth.spi.RFC2617Digest username "My Application" password
RFC2617 A1 hash: 9b47ec6f03603dd49863e7d58c4c49ea</programlisting>
<para>The three arguments are the username, the realm name and the password. The digested password should be
stored in the user management store. In the example here, it would go in the
<literal>digest-users.properties</literal> file. </para>
<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>
</section>
<section>
<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 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>
<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
http://java.sun.com/xml/ns/j2ee/application_1_4.xsd">
<display-name>JBossDukesBank</display-name>
<module>
<ejb>bank-ejb.jar</ejb>
</module>
<module>
<web>
<web-uri>web-client.war</web-uri>
<emphasis role="bold"><context-root>bank</context-root></emphasis>
</web>
</module>
</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>
<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>
<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>
<example id="ch9.virtualhost.ex">
<title>A virtual host configuration.</title>
<programlisting><Server>
<Service name="jboss.web"
className="org.jboss.web.tomcat.tc5.StandardService">
<!-- A HTTP/1.1 Connector on port 8080 -->
<Connector port="8080" address="${jboss.bind.address}"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" redirectPort="8443" acceptCount="100"
connectionTimeout="20000" disableUploadTimeout="true"/>
<Engine name="jboss.web" defaultHost="vhost1">
<Realm className="org.jboss.web.tomcat.security.JBossSecurityMgrRealm"
certificatePrincipal="org.jboss.security.auth.certs.SubjectDNMapping"
/>
<Logger className="org.jboss.web.tomcat.Log4jLogger"
verbosityLevel="WARNING"
category="org.jboss.web.localhost.Engine"/>
<Host name="vhost1" autoDeploy="false"
deployOnStartup="false" deployXML="false">
<Alias>vhost1.mydot.com</Alias>
<Valve className="org.apache.catalina.valves.AccessLogValve"
prefix="vhost1" suffix=".log" pattern="common"
directory="${jboss.server.home.dir}/log"/>
<DefaultContext cookies="true" crossContext="true" override="true"/>
</Host>
<Host name="vhost2" autoDeploy="false"
deployOnStartup="false" deployXML="false">
<Alias>vhost2.mydot.com</Alias>
<Alias>www.mydot.com</Alias>
<Valve className="org.apache.catalina.valves.AccessLogValve"
prefix="vhost2" suffix=".log" pattern="common"
directory="${jboss.server.home.dir}/log"/>
<DefaultContext cookies="true" crossContext="true" override="true"/>
</Host>
</Engine>
</Service>
</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>
<programlisting><jboss-web>
<context-root>/</context-root>
<virtual-host>www.mydot.com</virtual-host>
</jboss-web></programlisting>
</section>
<section>
<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>myimage.jpg</literal> at <ulink url="http://localhost:8080/images/myimage.jpg"/>. </para>
</section>
<section>
<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>
<programlisting><Connector port="8009" address="${jboss.bind.address}"
enableLookups="false" redirectPort="8443" debug="0"
protocol="AJP/1.3" /></programlisting>
<para>You'll need to consult the Apache and mod_jk documentation for complete installation instructions.
Assuming you have a properly configured Apache instance, the following configuration fragment shows an
example of how to connect with a WAR deployed with a context root of <literal>/jbosstest</literal>.</para>
<programlisting>...
LoadModule jk_module libexec/mod_jk.so
AddModule mod_jk.c
<IfModule mod_jk.c>
JkWorkersFile /tmp/workers.properties
JkLogFile /tmp/mod_jk.log
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>
<section>
<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>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>
<servlet-name>Faces Servlet</servlet-name>
<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>Faces Servlet</servlet-name>
<url-pattern>*.jsf</url-pattern>
</servlet-mapping></programlisting>
<para>In order to initialize the JSF environment, you also need to add the MyFaces listener to
<literal>web.xml</literal> file:</para>
<programlisting><listener>
<listener-class>org.apache.myfaces.webapp.StartupServletContextListener</listener-class>
</listener></programlisting>
<para> There are several additional context parameters that can be set to control the configuration of
JavaServer Faces for a particular application:</para>
<programlisting><context-param>
<param-name>javax.faces.CONFIG_FILES</param-name>
<param-value>
/WEB-INF/examples-config.xml
</param-value>
<description>
Comma separated list of URIs of (additional) faces config files.
(e.g. /WEB-INF/my-config.xml)
See JSF 1.0 PRD2, 10.3.2
</description>
</context-param>
<context-param>
<param-name>javax.faces.STATE_SAVING_METHOD</param-name>
<param-value>server</param-value>
<description>
State saving method: "client" or "server" (= default)
See JSF Specification 2.5.2
</description>
</context-param>
<context-param>
<param-name>org.apache.myfaces.ALLOW_JAVASCRIPT</param-name>
<param-value>true</param-value>
<description>
This parameter tells MyFaces if javascript code should be allowed in the
rendered HTML output.
If javascript is allowed, command_link anchors will have javascript code
that submits the corresponding form.
If javascript is not allowed, the state saving info and nested parameters
will be added as url parameters.
Default: "true"
</description>
</context-param>
<context-param>
<param-name>org.apache.myfaces.DETECT_JAVASCRIPT</param-name>
<param-value>false</param-value>
<description>
This parameter tells MyFaces if javascript code should be allowed in the
rendered HTML output.
If javascript is allowed, command_link anchors will have javascript code
that submits the corresponding form.
If javascript is not allowed, the state saving info and nested parameters
will be added as url parameters.
Default: "false"
Setting this param to true should be combined with STATE_SAVING_METHOD "server" for
best results.
This is an EXPERIMENTAL feature. You also have to enable the detector
filter/filter mapping below to get JavaScript detection working.
</description>
</context-param>
<context-param>
<param-name>org.apache.myfaces.PRETTY_HTML</param-name>
<param-value>true</param-value>
<description>
If true, rendered HTML code will be formatted, so that it is "human readable".
i.e. additional line separators and whitespace will be written, that do not
influence the HTML code.
Default: "true"
</description>
</context-param>
<context-param>
<param-name>org.apache.myfaces.AUTO_SCROLL</param-name>
<param-value>true</param-value>
<description>
If true, a javascript function will be rendered that is able to restore the
former vertical scroll on every request. Convenient feature if you have pages
with long lists and you do not want the browser page to always jump to the top
if you trigger a link or button action that stays on the same page.
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>
</chapter>
</book>
More information about the jboss-cvs-commits
mailing list