[jbossweb-commits] JBossWeb SVN: r1751 - trunk/webapps/docs/config.

Author: jfrederic.clere(a)jboss.com Date: 2011-06-30 07:10:02 -0400 (Thu, 30 Jun 2011) New Revision: 1751 Modified: trunk/webapps/docs/config/host.xml Log: Arrange the virtual-server element description. Modified: trunk/webapps/docs/config/host.xml =================================================================== --- trunk/webapps/docs/config/host.xml 2011-06-29 16:43:28 UTC (rev 1750) +++ trunk/webapps/docs/config/host.xml 2011-06-30 11:10:02 UTC (rev 1751) @@ -73,11 +73,6 @@ 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> @@ -85,59 +80,8 @@ <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> + <p>virtual-server doesn't support more attributes that the ones 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> @@ -146,344 +90,93 @@ <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> + <subsection name="access-log"> - <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> + <p><code>access-log</code>describes how the access log information should be logged. + It adds the <code>AccessLogValve</code> to the Virtual Host defined by <code>virtual-server</code> + See the <a href="../api/org/apache/catalina/valves/AccessLogValve.html">AccessLogValve api documentation</a> for more information. + </p> -</section> + <attributes> + <attribute name="relative-to" required="false"> + <p>directory location based on the global path configuration in the domain model. + If not specified, it defaults to the JBoss Application data directory (jboss.server.data.dir).</p> + </attribute> + <attribute name="path" required="false"> + <p>directory location based on the referenced path.</p> + </attribute> -<section name="Special Features"> + <attribute name="pattern" required="false"> + <p>Patern used by the AccessLogValve. The paterns are described in the <a href="../api/org/apache/catalina/valves/AccessLogValve.html"> + AccessLogValve api documentation.</a> + If not specified, a default of <code>common</code> is used.</p> + </attribute> + <attribute name="resolve-hosts" required="false"> + <p>Tell the Valve to resolve or not the host names. + If not specified, a default of <code>false</code> is used.</p> + </attribute> - <subsection name="Logging"> + <attribute name="extended" required="false"> + <p>Used the <code>ExtendedAccessLogValve</code> instead the <code>AccessLogValve</code> + If not specified, a default of <code>false</code> is used.</p> + </attribute> - <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> + <attribute name="prefix" required="false"> + <p>Define the prefix to use to name the log file. + If not specified, a default of <code>access_log.</code> is used.</p> + </attribute> - </subsection> + <attribute name="rotate" required="false"> + <p>Tell the valve if it should rotate the ouput or not. + If not specified, a default of <code>true</code> is used.</p> + </attribute> + </attributes> - - <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> -&lt;Host name="localhost" ...&gt; - ... - &lt;Valve className="org.apache.catalina.valves.AccessLogValve" - prefix="localhost_access_log." suffix=".txt" - pattern="common"/&gt; - ... -&lt;/Host&gt; -</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>&lt;Context&gt;</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> + <subsection name="rewrite"> + <p><code>rewrite</code>describes how requests should be rewritten before processing. + It adds the <code>RewriteValve</code> to the Virtual Host defined by <code>virtual-server</code> + See <a href="../rewrite.html">URL Rewriting</a> for more information. </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> + <attributes> + <attribute name="condition" required="true"> + <p>list of <code>condition</code>Elements. See condition below.</p> + </attribute> - <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> + <attribute name="pattern" required="true"> + <p>Pattern is a perl compatible regular expression, which is applied to the URL of the request.</p> + </attribute> - </subsection> + <attribute name="substitution" required="true"> + <p>The substitution of a rewrite rule is the string which is substituted for (or replaces) the original URL which Pattern matched</p> + </attribute> - - <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> -&lt;Host name="www.mycompany.com" ...&gt; - ... - &lt;Alias&gt;mycompany.com&lt;/Alias&gt; - ... -&lt;/Host&gt; -</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> - + <attribute name="flags" required="true"> + <p>Substitution options (See <a href="../rewrite.html">URL Rewriting</a> for all the available options</p> + </attribute> + </attributes> </subsection> + <subsection name="condition"> + <attributes> + <p><code>condition</code>describes a condition of the conditions list to apply the pattern substitution</p> + <attribute name="test" required="true"> + <p>a test string is first evaluated, before being matched against the specified pattern</p> + </attribute> - <subsection name="Lifecycle Listeners"> + <attribute name="pattern" required="true"> + <p>CondPattern is the condition pattern, a regular expression which is applied to the current instance of the test string</p> + </attribute> - <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> -&lt;Host name="localhost" ...&gt; - ... - &lt;Listener className="com.mycompany.mypackage.MyListener" ... &gt; - ... -&lt;/Host&gt; -</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> - + <attribute name="flags" required="true"> + <p>Matching options AND/OR and NC</p> + </attribute> + </attributes> </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> -&lt;Host name="localhost" ...&gt; - ... - &lt;Valve className="org.apache.catalina.valves.RemoteHostValve" - allow="*.mycompany.com,www.yourcompany.com"/&gt; - &lt;Valve className="org.apache.catalina.valves.RemoteAddrValve" - deny="192.168.1.*"/&gt; - ... -&lt;/Host&gt; -</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> -&lt;Host name="localhost" ...&gt; - ... - &lt;Valve className="org.apache.catalina.authenticator.SingleSignOn" - debug="0"/&gt; - ... -&lt;/Host&gt; -</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> -&lt;Host name="localhost" ...&gt; - ... - &lt;Listener className="org.apache.catalina.startup.UserConfig" - directoryName="public_html" - userClass="org.apache.catalina.startup.PasswdUserDatabase"/&gt; - ... -&lt;/Host&gt; -</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> -&lt;Host name="localhost" ...&gt; - ... - &lt;Listener className="org.apache.catalina.startup.UserConfig" - directoryName="public_html" - homeBase=c:\Homes" - userClass="org.apache.catalina.startup.HomesUserDatabase"/&gt; - ... -&lt;/Host&gt; -</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>