11:06 a.m.
Author: jfrederic.clere(a)jboss.com
Date: 2011-09-08 12:06:13 -0400 (Thu, 08 Sep 2011)
New Revision: 1832
Removed:
trunk/webapps/docs/architecture/
trunk/webapps/docs/cgi-howto.xml
trunk/webapps/docs/jasper-howto.xml
trunk/webapps/docs/manager-howto.xml
trunk/webapps/docs/mbeans-descriptor-howto.xml
trunk/webapps/docs/php.xml
trunk/webapps/docs/realm-howto.xml
trunk/webapps/docs/ssi-howto.xml
Modified:
trunk/webapps/docs/index.xml
trunk/webapps/docs/project.xml
Log:
Remove old TC docs.
Deleted: trunk/webapps/docs/cgi-howto.xml
===================================================================
--- trunk/webapps/docs/cgi-howto.xml 2011-09-08 14:43:49 UTC (rev 1831)
+++ trunk/webapps/docs/cgi-howto.xml 2011-09-08 16:06:13 UTC (rev 1832)
@@ -1,76 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE document [
- <!ENTITY project SYSTEM "project.xml">
-]>
-<document url="cgi-howto.html">
-
- &project;
-
- <properties>
- <author email="glenn(a)apache.org">Glenn L. Nielsen</author>
- <title>CGI How To</title>
- </properties>
-
-<body>
-
-<section name="Introduction">
-
-<p>The CGI (Common Gateway Interface) defines a way for a web server to
-interact with external content-generating programs, which are often
-referred to as CGI programs or CGI scripts.
-</p>
-
-<p>Within JBoss Web, CGI support can be added when you are using JBoss Web as your
-HTTP server and require CGI support. Typically this is done
-during development when you don't want to run a web server like
-Apache httpd.
-JBoss Web's CGI support is largely compatible with Apache httpd's,
-but there are some limitations (e.g., only one cgi-bin directory).
-</p>
-
-<p>CGI support is implemented using the servlet class
-<code>org.apache.catalina.servlets.CGIServlet</code>. Traditionally,
-this servlet is mapped to the URL pattern "/cgi-bin/*".</p>
-
-<p>By default CGI support is disabled in JBoss Web.</p>
-</section>
-
-<section name="Installation">
-
-<p><strong>CAUTION</strong> - CGI scripts are used to execute programs
-external to the JBoss Web JVM. If you are using the Java SecurityManager this
-will bypass your security policy configuration in
<code>catalina.policy.</code></p>
-
-<p>Remove the XML comments from around the CGI servlet and servlet-mapping
-configuration in <code>$CATALINA_BASE/conf/web.xml</code>.</p>
-</section>
-
-<p>Only Contexts which are marked as privileged may use the CGI servlet (see the
-privileged property of the Context element).</p>
-
-<section name="Configuration">
-
-<p>There are several servlet init parameters which can be used to
-configure the behaviour of the CGI servlet.
-<ul>
-<li><strong>cgiPathPrefix</strong> - The CGI search path will start at
-the web application root directory + File.separator + this prefix.
-The default cgiPathPrefix is <code>WEB-INF/cgi</code></li>
-<li><strong>debug</strong> - Debugging detail level for messages
logged
-by this servlet. Default 0.</li>
-<li><strong>executable</strong> - The of the executable to be used to
-run the script. Default is <code>perl</code>.</li>
-<li><strong>parameterEncoding</strong> - Name of the parameter
encoding
-to be used with the GCI servlet. Default is
-<code>System.getProperty("file.encoding","UTF-8")</code>.</li>
-<li><strong>passShellEnvironment</strong> - Should the shell
environment
-variables (if any) be passed to the CGI script? Default is
-<code>false</code>.</li>
-</ul>
-</p>
-
-</section>
-
-</body>
-
-</document>
Modified: trunk/webapps/docs/index.xml
===================================================================
--- trunk/webapps/docs/index.xml 2011-09-08 14:43:49 UTC (rev 1831)
+++ trunk/webapps/docs/index.xml 2011-09-08 16:06:13 UTC (rev 1832)
@@ -55,9 +55,6 @@
<li><a
href="deployer-howto.html"><strong>Deployer</strong></a> -
Operating the JBoss Web Deployer to deploy, precompile, and validate web
applications.</li>
-<li><a
href="manager-howto.html"><strong>Manager</strong></a> -
- Operating the <code>Manager</code> web app to deploy, undeploy, and
- redeploy applications while JBoss Web is running.</li>
<li><a href="realm-howto.html"><strong>Realms and Access
Control</strong></a>
- Description of how to configure <em>Realms</em> (databases of users,
passwords, and their associated roles) for use in web applications that
@@ -83,19 +80,11 @@
Installing and
configuring SSL support so that your JBoss Web will serve requests using
the <code>https</code> protocol.</li>
-<li><a href="php.html"><strong>PHP</strong></a>
-
- Using PHPs with JBoss Web.</li>
-<li><a
href="ssi-howto.html"><strong>SSI</strong></a> -
- Using Server Side Includes in JBoss Web.</li>
-<li><a
href="cgi-howto.html"><strong>CGI</strong></a> -
- Using CGIs with JBoss Web.</li>
<li><a href="rewrite.html"><strong>URL
Rewriting</strong></a> -
Using rewriting features in JBoss Web.</li>
<li><a href="proxy-howto.html"><strong>Proxy
Support</strong></a> -
Configuring JBoss Web to run behind a proxy server (or a web server
functioning as a proxy server).</li>
-<li><a href="mbeans-descriptor-howto.html"><strong>MBean
Descriptor</strong></a> -
- Configuring MBean descriptors files for custom components.</li>
<li><a href="default-servlet.html"><strong>Default
Servlet</strong></a> -
Configuring the default servlet and customizing directory listings.</li>
<li><a
href="connectors.html"><strong>Connectors</strong></a> -
Deleted: trunk/webapps/docs/jasper-howto.xml
===================================================================
--- trunk/webapps/docs/jasper-howto.xml 2011-09-08 14:43:49 UTC (rev 1831)
+++ trunk/webapps/docs/jasper-howto.xml 2011-09-08 16:06:13 UTC (rev 1832)
@@ -1,373 +0,0 @@
-<?xml version="1.0"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to You under the Apache License, Version 2.0
- (the "License"); you may not use this file except in compliance with
- the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
--->
-<!DOCTYPE document [
- <!ENTITY project SYSTEM "project.xml">
-]>
-<document url="jasper-howto.html">
-
- &project;
-
- <properties>
- <author email="glenn(a)apache.org">Glenn L. Nielsen</author>
- <author email="pero(a)apache.org">Peter Rossbach</author>
- <title>Jasper 2 JSP Engine How To</title>
- </properties>
-
-<body>
-
-<section name="Table of Contents">
-<p>
-<a href="#Introduction">Introduction</a><br />
-<a href="#Configuration">Configuration</a><br />
-<a href="#Production Configuration">Production
Configuration</a><br />
-<a href="#Web Application Compilation">Web Application
Compilation</a><br />
-<a href="#Using Jikes">Using Jikes</a><br />
-</p>
-</section>
-
-<section name="Introduction">
-
-<p>JBoss Web uses the Jasper 2 JSP Engine to implement
-the <a href="http://java.sun.com/products/jsp/">JavaServer Pages
2.0</a>
-specification.</p>
-
-<p>Jasper 2 has been redesigned to significantly improve performance over
-the orignal Jasper. In addition to general code improvements the following
-changes were made:
-<ul>
-<li><strong>JSP Custom Tag Pooling</strong> - The java objects
instantiated
-for JSP Custom Tags can now be pooled and reused. This significantly boosts
-the performance of JSP pages which use custom tags.</li>
-<li><strong>Background JSP compilation</strong> - If you make a change
to
-a JSP page which had already been compiled Jasper 2 can recompile that
-page in the background. The previously compiled JSP page will still be
-available to serve requests. Once the new page has been compiled
-successfully it will replace the old page. This helps improve availablity
-of your JSP pages on a production server.</li>
-<li><strong>Recompile JSP when included page changes</strong> - Jasper
2
-can now detect when a page included at compile time from a JSP has changed
-and then recompile the parent JSP.</li>
-<li><strong>JDT used to compile JSP pages</strong> - The
-Eclipse JDT Java compiler is now used to perform JSP java source code
-compilation. This compiler loads source dependencies from the container
-classloader. Ant and javac can still be used.</li>
-</ul>
-</p>
-
-<p>Jasper is implemented using the servlet class
-<code>org.apache.jasper.servlet.JspServlet</code>.</p>
-
-</section>
-
-<section name="Configuration">
-
-<p>By default Jasper is configured for use when doing web application
-development. See the section <a href="#Production Configuration">
-Production Configuration</a> for information on configuring Jasper
-for use on a production JBoss Web server.</p>
-
-<p>The servlet which implements Jasper is configured using init parameters
-in your global <code>$CATALINA_BASE/conf/web.xml</code>.
-
-<ul>
-<li><strong>checkInterval</strong> - If development is false and
checkInterval
-is greater than zero, background compiles are enabled. checkInterval is the time
-in seconds between checks to see if a JSP page (and its dependent files) needs
-to be recompiled. Default <code>0</code> seconds.</li>
-
-<li><strong>classdebuginfo</strong> - Should the class file be compiled
with
-debugging information? <code>true</code> or <code>false</code>,
default
-<code>true</code>.
-</li>
-
-<li><strong>classpath</strong> - Defines the class path to be used to
compile
-the generated servlets. This parameter only has an effect if the ServletContext
-attribute org.apache.jasper.Constants.SERVLET_CLASSPATH is not set. This
-attribute is always set when Jasper is used within JBoss Web. By default the
-classpath is created dynamically based on the current web application.</li>
-
-<li><strong>compiler</strong> - Which compiler Ant should use to
compile JSP
-pages. See the Ant documentation for more information. If the value is not set,
-then the default Eclipse JDT Java compiler will be used instead of using Ant.
-No default value.</li>
-
-<li><strong>compilerSourceVM</strong> - What JDK version are the source
files
-compatible with? (Default JDK 1.4)</li>
-
-<li><strong>compilerTargetVM</strong> - What JDK version are the
generated files
-compatible with? (Default JDK 1.4)</li>
-
-<li><strong>development</strong> - Is Jasper used in development mode?
If true,
-the frequency at which JSPs are checked for modification may be specified via
-the modificationTestInterval parameter.<code>true</code> or
<code>false</code>,
-default <code>true</code>.</li>
-
-<li><strong>displaySourceFragment</strong> - Should a source fragment
be
-included in exception messages? <code>true</code> or
<code>false</code>,
-default <code>true</code>.</li>
-
-<li><strong>dumpSmap</strong> - Should the SMAP info for JSR45
debugging be
-dumped to a file? <code>true</code> or <code>false</code>,
default
-<code>false</code>. <code>false</code> if suppressSmap is
true.</li>
-
-<li><strong>enablePooling</strong> - Determines whether tag handler
pooling is
-enabled. <code>true</code> or <code>false</code>, default
<code>true</code>.
-</li>
-
-<li><strong>engineOptionsClass</strong> - Allows specifying the Options
class
-used to configure Jasper. If not present, the default EmbeddedServletOptions
-will be used.
-</li>
-
-<li><strong>errorOnUseBeanInvalidClassAttribute</strong> - Should
Jasper issue
-an error when the value of the class attribute in an useBean action is not a
-valid bean class? <code>true</code> or <code>false</code>,
default
-<code>true</code>.</li>
-
-<li><strong>fork</strong> - Have Ant fork JSP page compiles so they
are
-performed in a seperate JVM from Tomcat? <code>true</code> or
-<code>false</code>, default <code>true</code>.</li>
-
-<li><strong>genStringAsCharArray</strong> - Should text strings be
generated as char
-arrays, to improve performance in some cases? Default
<code>false</code>.</li>
-
-<li><strong>ieClassId</strong> - The class-id value to be sent to
Internet
-Explorer when using <jsp:plugin> tags. Default
-<code>clsid:8AD9C840-044E-11D1-B3E9-00805F499D93</code>.</li>
-
-<li><strong>javaEncoding</strong> - Java file encoding to use for
generating
-java source files. Default <code>UTF8</code>.</li>
-
-<li><strong>keepgenerated</strong> - Should we keep the generated Java
source
-code for each page instead of deleting it? <code>true</code> or
-<code>false</code>, default <code>true</code>.</li>
-
-<li><strong>mappedfile</strong> - Should we generate static content
with one
-print statement per input line, to ease debugging?
-<code>true</code> or <code>false</code>, default
<code>true</code>.</li>
-
-<li><strong>modificationTestInterval</strong> - Causes a JSP (and its
dependent
-files) to not be checked for modification during the specified time interval
-(in seconds) from the last time the JSP was checked for modification. A value of
-0 will cause the JSP to be checked on every access. Used in development mode
-only. Default is <code>4</code> seconds.</li>
-
-<li><strong>scratchdir</strong> - What scratch directory should we use
when
-compiling JSP pages? Default is the work directory for the current web
-application.</li>
-
-<li><strong>suppressSmap</strong> - Should the generation of SMAP info
for JSR45
-debugging be suppressed? <code>true</code> or <code>false</code>,
default
-<code>false</code>.</li>
-
-<li><strong>trimSpaces</strong> - Should white spaces in template text
between
-actions or directives be trimmed ?, default <code>false</code>.</li>
-
-<li><strong>xpoweredBy</strong> - Determines whether X-Powered-By
response
-header is added by generated servlet. <code>true</code> or
<code>false</code>,
-default <code>false</code>.</li>
-</ul>
-</p>
-
-<p>The Java compiler from Eclipse JDT in included as the default compiler. It is
-an advanced Java compiler which will load all dependencies from the Tomcat class
-loader, which will help tremendously when compiling on large installations with
-tens of JARs. On fast servers, this will allow sub-second recompilation cycles
-for even large JSP pages.</p>
-
-<p>Apache Ant, which was used in previous Tomcat releases, can be used instead
-of the new compiler by simply removing the <code>lib/jasper-jdt.jar</code>
file,
-and placing the <code>ant.jar</code> file from the latest Ant distribution
in
-the <code>lib</code> folder. If you do this, you also need to use the
"javac"
-argument to catalina.sh.</p>
-
-</section>
-
-<section name="Production Configuration">
-
-<p>The main JSP optimization which can be done is precompilation of JSPs.
-However, this might not be possible (for example, when using the
-jsp-property-group feature) or practical, in which case the configuration of the
-Jasper servlet becomes critical.</p>
-
-<p>When using Jasper 2 in a production JBoss Web server you should consider
-making the following changes from the default configuration.
-<ul>
-<li><strong>development</strong> - To disable on access checks for JSP
-pages compilation set this to <code>false</code>.</li>
-<li><strong>genStringAsCharArray</strong> - To generate slightly more
efficient
-char arrays, set this to <code>true</code>.</li>
-<li><strong>modificationTestInterval</strong> - If development has to
be set to
-<code>true</code> for any reason (such as dynamic generation of JSPs),
setting
-this to a high value will improve performance a lot.</li>
-<li><strong>trimSpaces</strong> - To remove useless bytes from the
response,
-set this to <code>true</code>.</li>
-</ul>
-</p>
-
-</section>
-
-<section name="Web Application Compilation">
-
-<p>Using Ant is the preferred way to compile web applications using JSPC.
-Use the script given below (a similar script is included in the "deployer"
-download) to precompile a webapp:
-</p>
-
-<p>
-<source>
-<project name="Webapp Precompilation" default="all"
basedir=".">
-
- <import file="${tomcat.home}/bin/catalina-tasks.xml"/>
-
- <target name="jspc">
-
- <jasper
- validateXml="false"
- uriroot="${webapp.path}"
- webXmlFragment="${webapp.path}/WEB-INF/generated_web.xml"
- outputDir="${webapp.path}/WEB-INF/src" />
-
- </target>
-
- <target name="compile">
-
- <mkdir dir="${webapp.path}/WEB-INF/classes"/>
- <mkdir dir="${webapp.path}/WEB-INF/lib"/>
-
- <javac destdir="${webapp.path}/WEB-INF/classes"
- optimize="off"
- debug="on" failonerror="false"
- srcdir="${webapp.path}/WEB-INF/src"
- excludes="**/*.smap">
- <classpath>
- <pathelement location="${webapp.path}/WEB-INF/classes"/>
- <fileset dir="${webapp.path}/WEB-INF/lib">
- <include name="*.jar"/>
- </fileset>
- <pathelement location="${tomcat.home}/lib"/>
- <fileset dir="${tomcat.home}/common/lib">
- <include name="*.jar"/>
- </fileset>
- <fileset dir="${tomcat.home}/bin">
- <include name="*.jar"/>
- </fileset>
- </classpath>
- <include name="**" />
- <exclude name="tags/**" />
- </javac>
-
- </target>
-
- <target name="all" depends="jspc,compile">
- </target>
-
- <target name="cleanup">
- <delete>
- <fileset dir="${webapp.path}/WEB-INF/src"/>
- <fileset
dir="${webapp.path}/WEB-INF/classes/org/apache/jsp"/>
- </delete>
- </target>
-
-</project>
-</source>
-</p>
-
-<p>
-The following command line can be used to run the script
-(replacing the tokens with the JBoss Web base path and the path to the webapp
-which should be precompiled):<br/>
-<source>
-$ANT_HOME/bin/ant -Dtomcat.home=<$TOMCAT_HOME>
-Dwebapp.path=<$WEBAPP_PATH>
-</source>
-</p>
-
-<p>
-Then, the declarations and mappings for the servlets which were generated
-during the precompilation must be added to the web application deployment
-descriptor. Insert the <code>${webapp.path}/WEB-INF/generated_web.xml</code>
-at the right place inside the <code>${webapp.path}/WEB-INF/web.xml</code>
file.
-Restart the web application (using the manager) and test it to verify it is
-running fine with precompiled servlets. An appropriate token placed in the
-web application deployment descriptor may also be used to automatically
-insert the generated servlet declarations and mappings using Ant filtering
-capabilities.
-</p>
-
-<p>
-At the jasper2 task you can use the option <code>addWebXmlMappings</code> for
-automatic merge the <code>${webapp.path}/WEB-INF/generated_web.xml</code>
-with the current web application deployment descriptor at
-<code>${webapp.path}/WEB-INF/web.xml</code>. When you want to use Java 5
-features inside your jsp's, add the following javac compiler task attributes:
-<code>source="1.5" target="1.5"</code>.
For live
-applications you can also compile with
<code>optimize="on"</code> and
-without debug info <code>debug="off"</code>.
-</p>
-
-<p>
-When you don't want to stop the jsp generation at first jsp syntax error, use
-<code>failOnError="false"</code>and with
-<code>showSuccess="true"</code> all successfull
<i>jsp to java</i>
-generation are printed out. Sometimes it is very helpfull, when you cleanup the
-generate java source files at <code>${webapp.path}/WEB-INF/src</code>
-and the compile jsp servlet classes at
-<code>${webapp.path}/WEB-INF/classes/org/apache/jsp</code>.
-</p>
-
-<p><strong>Hints:</strong>
-<ul>
-<li> When you switch to another JBoss Web release, then regenerate and recompile
-your jsp's with the new JBoss Web version.</li>
-<li>Use java system property at server runtime to disable tag pooling
-<code>org.apache.jasper.runtime.JspFactoryImpl.USE_POOL=false</code>.
-and limit the buffering with
-<code>org.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true</code>.
Note
-that changing from the defaults may affect performance, but it will vary
-depending on the application.</li>
-</ul>
-</p>
-</section>
-
-<section name="Using Jikes">
-
-<p>If you wish to use
-<a href="http://oss.software.ibm.com/developerworks/opensource/jikes/&q...
-Jikes</a> to compile JSP pages:
-<ul>
-<li>From your <a href="ant.apache.org">Ant</a> installation,
copy ant.jar
-and (if it's available: Ant 1.5 and later) ant-launcher.jar to
-<code>$CATALINA_HOME/lib</code>.</li>
-<li>Download and install jikes. jikes must support the -encoding option.
-Execute <code>jikes -help</code> to verify that it was built with support
-for <code>-encoding</code>.</li>
-<li>Set the init parameter <code>compiler</code> to
<code>jikes</code>.</li>
-<li>Define the property <code>-Dbuild.compiler.emacs=true</code> when
starting
-Tomcat by adding it to your <code>CATALINA_OPTS</code> environment variable.
-This changes how jikes outputs error messages so that it is compatible with
-Jasper.</li>
-<li>If you get an error reporting that jikes can't use UTF8 encoding, try
-setting the init parameter <code>javaEncoding</code> to
-<code>ISO-8859-1</code>.</li>
-</ul>
-</p>
-
-</section>
-</body>
-
-</document>
Deleted: trunk/webapps/docs/manager-howto.xml
===================================================================
--- trunk/webapps/docs/manager-howto.xml 2011-09-08 14:43:49 UTC (rev 1831)
+++ trunk/webapps/docs/manager-howto.xml 2011-09-08 16:06:13 UTC (rev 1832)
@@ -1,1238 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE document [
- <!ENTITY project SYSTEM "project.xml">
-]>
-<document url="manager-howto.html">
-
- &project;
-
- <properties>
- <author email="craigmcc(a)apache.org">Craig R.
McClanahan</author>
- <title>Manager App HOW-TO</title>
- </properties>
-
-<body>
-
-<section name="Table of Contents">
-
-<p>
-<a href="#Introduction">Introduction</a><br />
-<a href="#Configuring Manager Application Access">
-Configuring Manager Application Access</a><br />
-<a href="#Supported Manager Commands">Supported Manager
Commands</a><br />
-<blockquote>
-<a href="#Deploy A New Application Remotely">Deploy A New Application
Remotely</a><br />
-<a href="#Deploy A New Application from a Local Path">Deploy A New
Application from a Local Path</a><br />
-<a href="#List Currently Deployed Applications">
-List Currently Deployed Applications</a><br />
-<a href="#Reload An Existing Application">Reload An Existing
Application</a><br />
-<a href="#List OS and JVM Properties">List OS and JVM
Properties</a><br />
-<a href="#List Available Global JNDI Resources">
-List Available Global JNDI Resources</a><br />
-<a href="#List Available Security Roles">List Available Security
Roles</a><br />
-<a href="#Session Statistics">Session Statistics</a><br />
-<a href="#Start an Existing Application">Start an Existing
Application</a><br />
-<a href="#Stop an Existing Application">Stop an Existing
Application</a><br />
-<a href="#Undeploy an Existing Application">
-Undeploy an Existing Application</a><br />
-</blockquote>
-<a href="#Executing Manager Commands With Ant">
-Executing Manager Commands With Ant</a><br />
-<a href="#Using the JMX Proxy Servlet">
-Using the JMX Proxy Servlet</a><br />
-<blockquote>
-<a href="#What is JMX Proxy Servlet">What is JMX Proxy
Servlet?</a><br />
-<a href="#JMX Query command">Query command</a><br />
-<a href="#JMX Set command">Set command</a><br />
-</blockquote>
-</p>
-
-</section>
-
-<section name="Introduction">
-
-<p>In many production environments, it is very useful to have the capability
-to deploy a new web application, or undeploy an existing one, without having
-to shut down and restart the entire container. In addition, you can request
-an existing application to reload itself, even if you have not declared it
-to be <code>reloadable</code> in the JBoss Web server
-configuration file.</p>
-
-<p>To support these capabilities, JBoss Web includes a web application
-(installed by default on context path <code>/manager</code>) that supports
-the following functions:</p>
-<ul>
-<li>Deploy a new web application from the uploaded contents of a WAR
file.</li>
-<li>Deploy a new web application, on a specified context path, from the
- server file system.</li>
-<li>List the currently deployed web applications, as well as the
- sessions that are currently active for those web apps.</li>
-<li>Reload an existing web application, to reflect changes in the
- contents of <code>/WEB-INF/classes</code> or
<code>/WEB-INF/lib</code>.
- </li>
-<li>List the OS and JVM property values.</li>
-<li>List the available global JNDI resources, for use in deployment
- tools that are preparing <code><ResourceLink></code>
elements
- nested in a <code><Context></code> deployment
description.</li>
-<li>List the available security roles defined in the user database.</li>
-<li>Start a stopped application (thus making it available again).</li>
-<li>Stop an existing application (so that it becomes unavailable), but
- do not undeploy it.</li>
-<li>Undeploy a deployed web application and delete its document base
- directory (unless it was deployed from file system).</li>
-</ul>
-
-<p>There are two ways to configure the Manager web application
-<code>Context</code>:
-<ul>
-<li>Install the <code>manager.xml</code> context configuration file
- in the <code>$CATALINA_HOME/conf/[enginename]/[hostname]</code> folder.
-</li>
-<li>Configure the Manager <code>Context</code> within the
- <code>Host</code> configuration in your JBoss Web
<code>server.xml</code>
- configuration. Here is an example:
-<pre>
-<Context path="/manager" privileged="true"
- docBase="/usr/local/jbossweb/server/webapps/manager">
-</Context>
-</pre>
-</li>
-</ul>
-</p>
-
-<p>If you have JBoss Web configured to support multiple virtual hosts
-(websites) you would need to configure a Manager for each.</p>
-
-<p>There are three ways to use the <code>Manager</code> web
application.
-<ul>
-<li>As an application with a user interface you use in your browser.
-Here is an example URL where you can replace <code>localhost</code> with
-your website host name: <code>http://localhost/manager/html/</code>
.</li>
-<li>A minimal version using HTTP requests only which is suitable for use
-by scripts setup by system administrators. Commands are given as part of the
-request URI, and responses are in the form of simple text that can be easily
-parsed and processed. See <a href="#Supported Manager Commands">
-Supported Manager Commands</a> for more information.</li>
-<li>A convenient set of task definitions for the <em>Ant</em>
-(version 1.4 or later) build tool. See
-<a href="#Executing Manager Commands With Ant">Executing Manager
Commands
-With Ant</a> for more information.</li>
-</ul>
-</p>
-
-</section>
-
-<section name="Configuring Manager Application Access">
-
- <blockquote><em>
- <p>The description below uses the variable name $CATALINA_HOME
- to refer to the directory into which you have installed JBoss Web,
- and is the base directory against which most relative paths are
- resolved. However, if you have configured JBoss Web for multiple
- instances by setting a CATALINA_BASE directory, you should use
- $CATALINA_BASE instead of $CATALINA_HOME for each of these
- references.</p>
- </em></blockquote>
-
-<p>It would be quite unsafe to ship JBoss Web with default settings that allowed
-anyone on the Internet to execute the Manager application on your server.
-Therefore, the Manager application is shipped with the requirement that anyone
-who attempts to use it must authenticate themselves, using a username and
-password that have the role <strong>manager</strong> associated with them.
-Further, there is no username in the default users file
-(<conf>$CATALINA_HOME/conf/tomcat-users.xml</conf>) that is assigned this
-role. Therefore, access to the Manager application is completely disabled
-by default.</p>
-
-<p>To enable access to the Manager web application, you must either create
-a new username/password combination and associate the role name
-<strong>manager</strong> with it, or add the
<strong>manager</strong> role
-to some existing username/password combination. Exactly where this is done
-depends on which <code>Realm</code> implementation you are using:</p>
-<ul>
-<li><em>MemoryRealm</em> - If you have not customized your
- <code>$CATALINA_HOME/conf/server.xml</code> to select a different one,
- JBoss Web defaults to an XML-format file stored at
- <code>$CATALINA_HOME/conf/tomcat-users.xml</code>, which can be
- edited with any text editor. This file contains an XML
- <code><user></code> for each individual user, which might
- look something like this:
-<source>
-<user name="craigmcc" password="secret"
roles="standard,manager" />
-</source>
- which defines the username and password used by this individual to
- log on, and the role names he or she is associated with. You can
- add the <strong>manager</strong> role to the comma-delimited
- <code>roles</code> attribute for one or more existing users, and/or
- create new users with that assigned role.</li>
-<li><em>JDBCRealm</em> - Your user and role information is stored in
- a database accessed via JDBC. Add the <strong>manager</strong> role
- to one or more existing users, and/or create one or more new users
- with this role assigned, following the standard procedures for your
- environment.</li>
-<li><em>JNDIRealm</em> - Your user and role information is stored in
- a directory server accessed via LDAP. Add the <strong>manager</strong>
- role to one or more existing users, and/or create one or more new users
- with this role assigned, following the standard procedures for your
- environment.</li>
-</ul>
-
-<p>The first time you attempt to issue one of the Manager commands
-described in the next section, you will be challenged to log on using
-BASIC authentication. The username and password you enter do not matter,
-as long as they identify a valid user in the users database who possesses
-the role <strong>manager</strong>.</p>
-
-<p>In addition to the password restrictions the manager web application
-could be restricted by the remote IP address or host by adding a
-<code>RemoteAddrValve</code> or <code>RemoteHostValve</code>.
Here is
-an example of restricting access to the localhost by IP address:
-<pre>
-<Context path="/manager" privileged="true"
- docBase="/usr/local/jbossweb/server/webapps/manager">
- <Valve className="org.apache.catalina.valves.RemoteAddrValve"
- allow="127\.0\.0\.1"/>
-</Context>
-</pre>
-</p>
-</section>
-
-
-<section name="Supported Manager Commands">
-
-<p>All commands that the Manager application knows how to process are
-specified in a single request URI like this:</p>
-<source>
-http://{host}:{port}/manager/{command}?{parameters}
-</source>
-<p>where <code>{host}</code> and <code>{port}</code>
represent the hostname
-and port number on which JBoss Web is running, <code>{command}</code>
-represents the Manager command you wish to execute, and
-<code>{parameters}</code> represents the query parameters
-that are specific to that command. In the illustrations below, customize
-the host and port appropriately for your installation.</p>
-
-<p>Most commands accept one or more of the following query parameters:</p>
-<ul>
-<li><strong>path</strong> - The context path (including the leading
slash)
- of the web application you are dealing with. To select the ROOT web
- application, specify "/". <strong>NOTE</strong> -
- It is not possible to perform administrative commands on the
- Manager application itself.</li>
-<li><strong>war</strong> - URL of a web application archive (WAR)
file,
- pathname of a directory which contains the web application, or a
- Context configuration ".xml" file. You can use URLs in any of the
- following formats:
- <ul>
- <li><strong>file:/absolute/path/to/a/directory</strong> - The
absolute
- path of a directory that contains the unpacked version of a web
- application. This directory will be attached to the context path
- you specify without any changes.</li>
- <li><strong>file:/absolute/path/to/a/webapp.war</strong> - The
absolute
- path of a web application archive (WAR) file. This is valid
- <strong>only</strong> for the <code>/deploy</code>
command, and is
- the only acceptable format to that command.</li>
- <li><strong>jar:file:/absolute/path/to/a/warfile.war!/</strong> -
The
- URL to a local web application archive (WAR) file. You can use any
- syntax that is valid for the <code>JarURLConnection</code> class
- for reference to an entire JAR file.</li>
- <li><strong>file:/absolute/path/to/a/context.xml</strong> - The
- absolute path of a web application Context configuration ".xml"
- file which contains the Context configuration element.</li>
- <li><strong>directory</strong> - The directory name for the web
- applciation context in the Host's application base directory.</li>
- <li><strong>webapp.war</strong> - The name of a web application war
file
- located in the Host's application base directory.</li>
- </ul></li>
-</ul>
-
-<p>Each command will return a response in <code>text/plain</code>
format
-(i.e. plain ASCII with no HTML markup), making it easy for both humans and
-programs to read). The first line of the response wil begin with either
-<code>OK</code> or <code>FAIL</code>, indicating whether the
requested
-command was successful or not. In the case of failure, the rest of the first
-line will contain a description of the problem that was encountered. Some
-commands include additional lines of information as described below.</p>
-
-<p><em>Internationalization Note</em> - The Manager application looks
up
-its message strings in resource bundles, so it is possible that the strings
-have been translated for your platform. The examples below show the English
-version of the messages.</p>
-
-<blockquote><em>
-<p><strong>WARNING:</strong> the legacy commands
<code>/install</code> and
-<code>/remove</code> are deprecated.
-They are presently equivalent to <code>/deploy</code> and
<code>/undeploy</code>,
-but could be removed in a future release.</p>
-</em></blockquote>
-
-<subsection name="Deploy A New Application Remotely">
-
-<source>
-http://localhost:8080/manager/deploy?path=/foo
-</source>
-
-<p>Upload the web application archive (WAR) file that is specified as the
-request data in this HTTP PUT request, install it into the
<code>appBase</code>
-directory of our corresponding virtual host, and start , using the directory
-name or the war file name without the .war extension as the path. The
-application can later be undeployed (and the corresponding application directory
-removed) by use of the <code>/undeploy</code> command.</p>
-
-<p>The .WAR file may include JBoss Web specific deployment configuration, by
-including a Context configuration XML file in
-<code>/META-INF/context.xml</code>.</p>
-
-<p>URL parameters include:
-<ul>
-<li><code>update</code>: When set to true, any existing update will be
- undeployed first. The default value is set to false.</li>
-<li><code>tag</code>: Specifying a tag name, this allows associating
the
- deployed webapp with a version number. The application version can
- be later redeployed when needed using only the tag.</li>
-</ul>
-</p>
-
-<p><strong>NOTE</strong> - This command is the logical
-opposite of the <code>/undeploy</code> command.</p>
-
-<p>If installation and startup is successful, you will receive a response
-like this:</p>
-<source>
-OK - Deployed application at context path /foo
-</source>
-
-<p>Otherwise, the response will start with <code>FAIL</code> and
include an
-error message. Possible causes for problems include:</p>
-<ul>
-<li><em>Application already exists at path /foo</em>
- <blockquote>
- <p>The context paths for all currently running web applications must be
- unique. Therefore, you must undeploy the existing web
- application using this context path, or choose a different context path
- for the new one. The <code>update</code> parameter may be specified as
- a parameter on the URL, with a value of <code>true</code> to avoid this
- error. In that case, an undeploy will be performed on an existing
- application before performing the deployment.</p>
- </blockquote></li>
-<li><em>Encountered exception</em>
- <blockquote>
- <p>An exception was encountered trying to start the new web application.
- Check the JBoss Web logs for the details, but likely explanations include
- problems parsing your <code>/WEB-INF/web.xml</code> file, or missing
- classes encountered when initializing application event listeners and
- filters.</p>
- </blockquote></li>
-</ul>
-
-</subsection>
-
-<subsection name="Deploy A New Application from a Local Path">
-
-<p>Deploy and start a new web application, attached to the specified context
-<code>path</code> (which must not be in use by any other web application).
-This command is the logical opposite of the <code>/undeploy</code>
command.</p>
-
-<p>There are a number of different ways the deploy command can be used.</p>
-
-<h3>Deploy a version of a previously deployed webapp</h3>
-
-<p>This can be used to deploy a previous version of a web application, which
-has been deployed using the <code>tag</code> attribute. Note that the work
-directory for the manager webapp will contain the previously deployed WARs;
-removing it would make the deployment fail.
-<source>
-http://localhost:8080/manager/deploy?path=/footoo&tag=footag
-</source>
-</p>
-
-<h3>Deploy a Directory or WAR by URL</h3>
-
-<p>Deploy a web application directory or ".war" file located on the JBoss
Web
-server. If no <code>path</code> is specified, the directory name or the war
file
-name without the ".war" extension is used as the path. The
<code>war</code>
-parameter specifies a URL (including the <code>file:</code> scheme) for
either
-a directory or a web application archive (WAR) file. The supported syntax for
-a URL referring to a WAR file is described on the Javadocs page for the
-<code>java.net.JarURLConnection</code> class. Use only URLs that refer to
-the entire WAR file.</p>
-
-<p>In this example the web application located in the directory
-<code>/path/to/foo</code> on the JBoss Web server is deployed as the
-web application context named <code>/footoo</code>.
-<source>
-http://localhost:8080/manager/deploy?path=/footoo&war=file:/path/to/foo
-</source>
-</p>
-
-<p>In this example the ".war" file
<code>/path/to/bar.war</code> on the
-JBoss Web server is deployed as the web application context named
-<code>/bar</code>. Notice that there is no <code>path</code>
parameter
-so the context path defaults to the name of the web application archive
-file without the ".war" extension.
-<source>
-http://localhost:8080/manager/deploy?war=jar:file:/path/to/bar.war!/
-</source>
-</p>
-
-<h3>Deploy a Directory or War from the Host appBase</h3>
-
-<p>Deploy a web application directory or ".war" file located in your
Host
-appBase directory. The directory name or the war file name without the ".war"
-extension is used as the path.</p>
-
-<p>In this example the web application located in a sub directory named
-<code>foo</code> in the Host appBase directory of the JBoss Web server is
-deployed as the web application context named <code>/foo</code>. Notice
-that the context path used is the name of the web application directory.
-<source>
-http://localhost:8080/manager/deploy?war=foo
-</source>
-</p>
-
-<p>In this example the ".war" file <code>bar.war</code>
located in your
-Host appBase directory on the JBoss Web server is deployed as the web
-application context named <code>/bar</code>.
-<source>
-http://localhost:8080/manager/deploy?war=bar.war
-</source>
-</p>
-
-<h3>Deploy using a Context configuration ".xml" file</h3>
-
-<p>If the Host deployXML flag is set to true you can deploy a web
-application using a Context configuration ".xml" file and an optional
-".war" file or web application directory. The context
<code>path</code>
-is not used when deploying a web application using a context ".xml"
-configuration file.</p>
-
-<p>A Context configuration ".xml" file can contain valid XML for a
-web application Context just as if it were configured in your
-JBoss Web <code>server.xml</code> configuration file. Here is an
-example:
-<source>
-<Context path="/foobar" docBase="/path/to/application/foobar"
- debug="0">
-
- <!-- Link to the user database we will get roles from -->
- <ResourceLink name="users" global="UserDatabase"
- type="org.apache.catalina.UserDatabase"/>
-
-</Context>
-</source>
-</p>
-
-<p>When the optional <code>war</code> parameter is set to the URL
-for a web application ".war" file or directory it overrides any
-docBase configured in the context configuration ".xml" file.</p>
-
-<p>Here is an example of deploying an application using a Context
-configuration ".xml" file.
-<source>
-http://localhost:8080/manager/deploy?config=file:/path/context.xml
-</source>
-</p>
-
-<p>Here is an example of deploying an application using a Context
-configuration ".xml" file and a web application ".war" file located
-on the server.
-<source>
-http://localhost:8080/manager/deploy?config=file:/path/context.xml&war=jar:file:/path/bar.war!/
-</source>
-</p>
-
-<h3>Deployment Notes</h3>
-
-<p>If the Host is configured with unpackWARs=true and you deploy a war
-file, the war will be unpacked into a directory in your Host appBase
-directory.</p>
-
-<p>If the application war or directory is installed in your Host appBase
-directory and either the Host is configured with autoDeploy=true or
-liveDeploy=true, the Context path must match the directory name or
-war file name without the ".war" extension.</p>
-
-<p>For security when untrusted users can manage web applications, the
-Host deployXML flag can be set to false. This prevents untrusted users
-from deploying web applications using a configuration XML file and
-also prevents them from deploying application directories or ".war"
-files located outside of their Host appBase.</p>
-
-
-<h3>Deploy Response</h3>
-
-<p>If installation and startup is successful, you will receive a response
-like this:</p>
-<source>
-OK - Deployed application at context path /foo
-</source>
-
-<p>Otherwise, the response will start with <code>FAIL</code> and
include an
-error message. Possible causes for problems include:</p>
-<ul>
-<li><em>Application already exists at path /foo</em>
- <blockquote>
- <p>The context paths for all currently running web applications must be
- unique. Therefore, you must undeploy the existing web
- application using this context path, or choose a different context path
- for the new one. The <code>update</code> parameter may be specified as
- a parameter on the URL, with a value of <code>true</code> to avoid this
- error. In that case, an undeploy will be performed on an existing
- application before performing the deployment.</p>
- </blockquote></li>
-<li><em>Document base does not exist or is not a readable
directory</em>
- <blockquote>
- <p>The URL specified by the <code>war</code> parameter must
identify a
- directory on this server that contains the "unpacked" version of a
- web application, or the absolute URL of a web application archive (WAR)
- file that contains this application. Correct the value specified by
- the <code>war</code> parameter.</p>
- </blockquote></li>
-<li><em>Encountered exception</em>
- <blockquote>
- <p>An exception was encountered trying to start the new web application.
- Check the JBoss Web logs for the details, but likely explanations include
- problems parsing your <code>/WEB-INF/web.xml</code> file, or missing
- classes encountered when initializing application event listeners and
- filters.</p>
- </blockquote></li>
-<li><em>Invalid application URL was specified</em>
- <blockquote>
- <p>The URL for the directory or web application that you specified
- was not valid. Such URLs must start with <code>file:</code>, and URLs
- for a WAR file must end in ".war".</p>
- </blockquote></li>
-<li><em>Invalid context path was specified</em>
- <blockquote>
- <p>The context path must start with a slash character. To reference the
- ROOT web application use "/".</p>
- </blockquote></li>
-<li><em>Context path must match the directory or WAR file name:</em>
- <blockquote>
- If the application war or directory is installed in your Host appBase
- directory and either the Host is configured with autoDeploy=true or
- liveDeploy=true, the Context path must match the directory name or
- war file name without the ".war" extension.
- </blockquote></li>
-<li><em>Only web applications in the Host web application directory can
- be installed</em>
- <blockquote>
- If the Host deployXML flag is set to false this error will happen
- if an attempt is made to deploy a web application directory or
- ".war" file outside of the Host appBase directory.
- </blockquote></li>
-</ul>
-
-</subsection>
-
-<subsection name="List Currently Deployed Applications">
-
-<source>
-http://localhost:8080/manager/list
-</source>
-
-<p>List the context paths, current status (<code>running</code> or
-<code>stopped</code>), and number of active sessions for all currently
-deployed web applications. A typical response immediately
-after starting JBoss Web might look like this:</p>
-<source>
-OK - Listed applications for virtual host localhost
-/webdav:running:0
-/examples:running:0
-/manager:running:0
-/:running:0
-</source>
-
-</subsection>
-
-<subsection name="Reload An Existing Application">
-
-<source>
-http://localhost:8080/manager/reload?path=/examples
-</source>
-
-<p>Signal an existing application to shut itself down and reload. This can
-be useful when the web application context is not reloadable and you have
-updated classes or property files in the <code>/WEB-INF/classes</code>
-directory or when you have added or updated jar files in the
-<code>/WEB-INF/lib</code> directory.
-</p>
-<p><strong>NOTE:</strong> The
<code>/WEB-INF/web.xml</code>
-web application configuration file is not reread on a reload.
-If you have made changes to your web.xml file you must stop
-then start the web application.
-</p>
-
-<p>If this command succeeds, you will see a response like this:</p>
-<source>
-OK - Reloaded application at context path /examples
-</source>
-
-<p>Otherwise, the response will start with <code>FAIL</code> and
include an
-error message. Possible causes for problems include:</p>
-<ul>
-<li><em>Encountered exception</em>
- <blockquote>
- <p>An exception was encountered trying to restart the web application.
- Check the JBoss Web logs for the details.</p>
- </blockquote></li>
-<li><em>Invalid context path was specified</em>
- <blockquote>
- <p>The context path must start with a slash character. To reference the
- ROOT web application use "/".</p>
- </blockquote></li>
-<li><em>No context exists for path /foo</em>
- <blockquote>
- <p>There is no deployed application on the context path
- that you specified.</p>
- </blockquote></li>
-<li><em>No context path was specified</em>
- <blockquote>
- The <code>path</code> parameter is required.
- </blockquote></li>
-<li><em>Reload not supported on WAR deployed at path /foo</em>
- <blockquote>
- Currently, application reloading (to pick up changes to the classes or
- <code>web.xml</code> file) is not supported when a web application is
- deployed directly from a WAR file. It only works when the web application
- is deployed from an unpacked directory. If you are using a WAR file,
- you should <code>undeploy</code> and then <code>deploy</code>
or
- <code>deploy</code> with the <code>update</code> parameter
the
- application again to pick up your changes.
- </blockquote></li>
-</ul>
-
-</subsection>
-
-<subsection name="List OS and JVM Properties">
-
-<source>
-http://localhost:8080/manager/serverinfo
-</source>
-
-<p>Lists information about the JBoss Web version, OS, and JVM
properties.</p>
-
-<p>If an error occurs, the response will start with <code>FAIL</code>
and
-include an error message. Possible causes for problems include:</p>
-<ul>
-<li><em>Encountered exception</em>
- <blockquote>
- <p>An exception was encountered trying to enumerate the system properties.
- Check the JBoss Web logs for the details.</p>
- </blockquote></li>
-</ul>
-
-</subsection>
-
-<subsection name="List Available Global JNDI Resources">
-
-<source>
-http://localhost:8080/manager/resources[?type=xxxxx]
-</source>
-
-<p>List the global JNDI resources that are available for use in resource
-links for context configuration files. If you specify the <code>type</code>
-request parameter, the value must be the fully qualified Java class name of
-the resource type you are interested in (for example, you would specify
-<code>javax.sql.DataSource</code> to acquire the names of all available
-JDBC data sources). If you do not specify the <code>type</code> request
-parameter, resources of all types will be returned.</p>
-
-<p>Depending on whether the <code>type</code> request parameter is
specfied
-or not, the first line of a normal response will be:</p>
-<pre>
- OK - Listed global resources of all types
-</pre>
-<p>or</p>
-<pre>
- OK - Listed global resources of type xxxxx
-</pre>
-<p>followed by one line for each resource. Each line is composed of fields
-delimited by colon characters (":"), as follows:</p>
-<ul>
-<li><em>Global Resource Name</em> - The name of this global JNDI
resource,
- which would be used in the <code>global</code> attribute of a
- <code><ResourceLink></code> element.</li>
-<li><em>Global Resource Type</em> - The fully qualified Java class name
of
- this global JNDI resource.</li>
-</ul>
-
-<p>If an error occurs, the response will start with <code>FAIL</code>
and
-include an error message. Possible causes for problems include:</p>
-<ul>
-<li><em>Encountered exception</em>
- <blockquote>
- <p>An exception was encountered trying to enumerate the global JNDI
- resources. Check the JBoss Web logs for the details.</p>
- </blockquote></li>
-<li><em>No global JNDI resources are available</em>
- <blockquote>
- <p>The JBoss Web server you are running has been configured without
- global JNDI resources.</p>
- </blockquote></li>
-</ul>
-
-
-</subsection>
-
-
-<subsection name="List Available Security Roles">
-
-<source>
-http://localhost:8080/manager/roles
-</source>
-
-<p>List the security role names (and corresponding descriptions) that are
-available in the <code>org.apache.catalina.UserDatabase</code> resource that
-is linked to the <code>users</code> resource reference in the web.xml file
-for the Manager web application. This would typically be used, for example,
-by a deployment tool that wanted to create
-<code><security-role-ref></code> elements to map security role
names
-used in a web application to the role names actually defined within the
-container.</p>
-
-<p>By default, the <code>users</code> resource reference is pointed at
the
-global <code>UserDatabase</code> resource. If you choose to utilize a
-different user database per virtual host, you should modify the
-<code><ResourceLink></code> element in the default
-<code>manager.xml</code> context configuration file to point at the global
-user database resource for this virtual host.</p>
-
-<p>When this command is executed, the first line of the response will
be:</p>
-<pre>
- OK - Listed security roles
-</pre>
-<p>followed by one line for each security role. Each line is composed of
-fields delimited by colon characters (":") as follows:</p>
-<ul>
-<li><em>Security Role Name</em> - A security role name that is known to
JBoss Web
- in the user database.</li>
-<li><em>Description</em> - Description of this security role (useful
in
- creating user interfaces for selecting roles.</li>
-</ul>
-
-<p>If an error occurs, the response will start with <code>FAIL</code>
and
-include an error message. Possible causes for problems include:</p>
-<ul>
-<li><em>Cannot resolve user database reference</em> - A JNDI error
prevented
- the successful lookup of the
<code>org.apache.catalina.UserDatabase</code>
- resource. Check the JBoss Web log files for a stack trace associated with
- this error.</li>
-<li><em>No user database is available</em> - You have not configured a
resource
- reference for the <code>users</code> resource that points at an
- appropriate user database instance. Check your <code>manager.xml</code>
- file and ensure that you have created an appropriate
- <code><ResourceLink></code> or
- <code><ResourceParams></code> element for this
resource.</li>
-</ul>
-
-</subsection>
-
-
-<subsection name="Session Statistics">
-
-<source>
-http://localhost:8080/manager/sessions?path=/examples
-</source>
-
-<p>Display the default session timeout for a web application, and the
-number of currently active sessions that fall within ten-minute ranges of
-their actual timeout times. For example, after restarting JBoss Web and then
-executing one of the JSP samples in the <code>/examples</code> web app,
-you might get something like this:</p>
-<source>
-OK - Session information for application at context path /examples
-Default maximum session inactive interval 30 minutes
-30 - <40 minutes:1 sessions
-</source>
-
-</subsection>
-
-
-<subsection name="Start an Existing Application">
-
-<source>
-http://localhost:8080/manager/start?path=/examples
-</source>
-
-<p>Signal a stopped application to restart, and make itself available again.
-Stopping and starting is useful, for example, if the database required by
-your application becomes temporarily unavailable. It is usually better to
-stop the web application that relies on this database rather than letting
-users continuously encounter database exceptions.</p>
-
-<p>If this command succeeds, you will see a response like this:</p>
-<source>
-OK - Started application at context path /examples
-</source>
-
-<p>Otherwise, the response will start with <code>FAIL</code> and
include an
-error message. Possible causes for problems include:</p>
-<ul>
-<li><em>Encountered exception</em>
- <blockquote>
- <p>An exception was encountered trying to start the web application.
- Check the JBoss Web logs for the details.</p>
- </blockquote></li>
-<li><em>Invalid context path was specified</em>
- <blockquote>
- <p>The context path must start with a slash character. To reference the
- ROOT web application use "/".</p>
- </blockquote></li>
-<li><em>No context exists for path /foo</em>
- <blockquote>
- <p>There is no deployed application on the context path
- that you specified.</p>
- </blockquote></li>
-<li><em>No context path was specified</em>
- <blockquote>
- The <code>path</code> parameter is required.
- </blockquote></li>
-</ul>
-
-</subsection>
-
-<subsection name="Stop an Existing Application">
-
-<source>
-http://localhost:8080/manager/stop?path=/examples
-</source>
-
-<p>Signal an existing application to make itself unavailable, but leave it
-deployed. Any request that comes in while an application is
-stopped will see an HTTP error 404, and this application will show as
-"stopped" on a list applications command.</p>
-
-<p>If this command succeeds, you will see a response like this:</p>
-<source>
-OK - Stopped application at context path /examples
-</source>
-
-<p>Otherwise, the response will start with <code>FAIL</code> and
include an
-error message. Possible causes for problems include:</p>
-<ul>
-<li><em>Encountered exception</em>
- <blockquote>
- <p>An exception was encountered trying to stop the web application.
- Check the JBoss Web logs for the details.</p>
- </blockquote></li>
-<li><em>Invalid context path was specified</em>
- <blockquote>
- <p>The context path must start with a slash character. To reference the
- ROOT web application use "/".</p>
- </blockquote></li>
-<li><em>No context exists for path /foo</em>
- <blockquote>
- <p>There is no deployed application on the context path
- that you specified.</p>
- </blockquote></li>
-<li><em>No context path was specified</em>
- <blockquote>
- The <code>path</code> parameter is required.
- </blockquote></li>
-</ul>
-
-</subsection>
-
-
-<subsection name="Undeploy an Existing Application">
-
-<source>
-http://localhost:8080/manager/undeploy?path=/examples
-</source>
-
-<p><strong><font color="red">WARNING</font> - This
command will delete any web
-application artifacts that exist within <code>appBase</code> directory
-(typically "webapps") for this virtual host</strong>.
-This will delete the the application .WAR, if present,
-the application directory resulting either from a deploy in unpacked form
-or from .WAR expansion as well as the XML Context definition from
-<code>$CATALINA_HOME/conf/[enginename]/[hostname]/</code> directory.
-If you simply want to take an application
-out of service, you should use the <code>/stop</code> command
instead.</p>
-
-<p>Signal an existing application to gracefully shut itself down, and
-remove it from JBoss Web (which also makes this context path available for
-reuse later). In addition, the document root directory is removed, if it
-exists in the <code>appBase</code> directory (typically "webapps")
for
-this virtual host. This command is the logical opposite of the
-<code>/deploy</code> command.</p>
-
-<p>If this command succeeds, you will see a response like this:</p>
-<source>
-OK - Undeployed application at context path /examples
-</source>
-
-<p>Otherwise, the response will start with <code>FAIL</code> and
include an
-error message. Possible causes for problems include:</p>
-<ul>
-<li><em>Encountered exception</em>
- <blockquote>
- <p>An exception was encountered trying to undeploy the web application.
- Check the JBoss Web logs for the details.</p>
- </blockquote></li>
-<li><em>Invalid context path was specified</em>
- <blockquote>
- <p>The context path must start with a slash character. To reference the
- ROOT web application use "/".</p>
- </blockquote></li>
-<li><em>No context exists for path /foo</em>
- <blockquote>
- <p>There is no deployed application on the context path
- that you specified.</p>
- </blockquote></li>
-<li><em>No context path was specified</em>
- <blockquote>
- The <code>path</code> parameter is required.
- </blockquote></li>
-</ul>
-
-</subsection>
-
-</section>
-
-<section name="Executing Manager Commands With Ant">
-
-<p>In addition to the ability to execute Manager commands via HTTP requests,
-as documented above, JBoss Web includes a convenient set of Task definitions
-for the <em>Ant</em> (version 1.4 or later) build tool. In order to use
these
-commands, you must perform the following setup operations:</p>
-<ul>
-<li>Download the binary distribution of Ant from
- <a href="http://ant.apache.org">http://ant.apache.org</a>.
- You must use version <strong>1.4</strong> or later.</li>
-<li>Install the Ant distribution in a convenient directory (called
- ANT_HOME in the remainder of these instructions).</li>
-<li>Copy the file <code>server/lib/catalina-ant.jar</code> from your
JBoss Web 6
- installation into Ant's library directory
(<code>$ANT_HOME/lib</code>).
- </li>
-<li>Add the <code>$ANT_HOME/bin</code> directory to your
<code>PATH</code>
- environment variable.</li>
-<li>Configure at least one username/password combination in your JBoss Web
- user database that includes the <code>manager</code> role.</li>
-</ul>
-
-<p>To use custom tasks within Ant, you must declare them first with a
-<code><taskdef></code> element. Therefore, your
<code>build.xml</code>
-file might look something like this:</p>
-
-<source>
-<project name="My Application" default="compile"
basedir=".">
-
- <!-- Configure the directory into which the web application is built -->
- <property name="build" value="${basedir}/build"/>
-
- <!-- Configure the context path for this application -->
- <property name="path" value="/myapp"/>
-
- <!-- Configure properties to access the Manager application -->
- <property name="url"
value="http://localhost:8080/manager"/>
- <property name="username" value="myusername"/>
- <property name="password" value="mypassword"/>
-
- <!-- Configure the custom Ant tasks for the Manager application -->
- <taskdef name="deploy"
classname="org.apache.catalina.ant.DeployTask"/>
- <taskdef name="list"
classname="org.apache.catalina.ant.ListTask"/>
- <taskdef name="reload"
classname="org.apache.catalina.ant.ReloadTask"/>
- <taskdef name="resources"
classname="org.apache.catalina.ant.ResourcesTask"/>
- <taskdef name="roles"
classname="org.apache.catalina.ant.RolesTask"/>
- <taskdef name="start"
classname="org.apache.catalina.ant.StartTask"/>
- <taskdef name="stop"
classname="org.apache.catalina.ant.StopTask"/>
- <taskdef name="undeploy"
classname="org.apache.catalina.ant.UndeployTask"/>
-
- <!-- Executable Targets -->
- <target name="compile" description="Compile web
application">
- <!-- ... construct web application in ${build} subdirectory, and
- generated a ${path}.war ... -->
- </target>
-
- <target name="deploy" description="Install web application"
- depends="compile">
- <deploy url="${url}" username="${username}"
password="${password}"
- path="${path}" war="file:${build}${path}.war"/>
- </target>
-
- <target name="reload" description="Reload web application"
- depends="compile">
- <reload url="${url}" username="${username}"
password="${password}"
- path="${path}"/>
- </target>
-
- <target name="undeploy" description="Remove web
application">
- <undeploy url="${url}" username="${username}"
password="${password}"
- path="${path}"/>
- </target>
-
-</project>
-</source>
-
-<p>Now, you can execute commands like <code>ant deploy</code> to deploy
the
-application to a running instance of JBoss Web, or <code>ant reload</code>
to
-tell JBoss Web to reload it. Note also that most of the interesting values in
-this <code>build.xml</code> file are defined as replaceable properties, so
-you can override their values from the command line. For example, you might
-consider it a security risk to include the real manager password in your
-<code>build.xml</code> file's source code. To avoid this, omit the
password
-property, and specify it from the command line:</p>
-<pre>
- ant -Dpassword=secret deploy
-</pre>
-
-<subsection name="Tasks output capture">
-
-<p>Using <em>Ant</em> version <strong>1.6.2</strong> or
later,
-the Catalina tasks offer the option to capture their output in
-properties or external files. They support directly the following subset of the
-<code><redirector></code> type attributes:
-</p>
-
- <attributes>
-
- <attribute name="output" required="false">
- <p>Name of a file to which to write the output. If
-the error stream is not also redirected to a file or property, it will
-appear in this output.</p>
- </attribute>
-
- <attribute name="error" required="false">
- <p>The file to which the standard error of the
-command should be redirected.</p>
- </attribute>
-
- <attribute name="logError" required="false">
- <p>This attribute is used when you wish to see
-error output in Ant's log and you are redirecting output to a
-file/property. The error output will not be included in the output
-file/property. If you redirect error with the <i>error</i> or
<i>errorProperty</i>
-attributes, this will have no effect.</p>
- </attribute>
-
- <attribute name="append" required="false">
- <p>Whether output and error files should be
-appended to or overwritten. Defaults to <code>false</code>.
- </p>
- </attribute>
-
- <attribute name="createemptyfiles" required="false">
- <p>Whether output and error files should be created
-even when empty. Defaults to <code>true</code>.</p>
- </attribute>
-
- <attribute name="outputproperty" required="false">
- <p>The name of a property in which the output of
-the command should be stored. Unless the error stream is redirected to
-a separate file or stream, this property will include the error output.</p>
- </attribute>
-
- <attribute name="errorproperty" required="false">
- <p>The name of a property in which the standard
-error of the command should be stored.</p>
- </attribute>
-
- <attribute name="alwaysLog" required="false">
- <p>This attribute is used when you wish to see the
-output you are capturing, appearing also in the Ant's log. It must not be
-used unless you are capturing task output.
-Defaults to <code>false</code>.
-<em>This attribute will be supported directly by
<code><redirector></code>
-in Ant 1.6.3</em></p>
- </attribute>
-
- <attribute name="failonerror" required="false">
- <p>This attribute is used when you wish to avoid that
-any manager command processing error terminates the ant execution. Defaults to
<code>true</code>.
-It must be set to <code>false</code>, if you want to capture error output,
-otherwise execution will terminate before anything can be captured.
-<br></br>
-This attribute acts only on manager command execution,
-any wrong or missing command attribute will still cause Ant execution
termination.</p>
- </attribute>
-
- </attributes>
-
-<p>They also support the embedded
<code><redirector></code> element
-in which you can specify
-its full set of attributes, but <code>input</code>,
<code>inputstring</code> and
-<code>inputencoding</code> that, even if accepted, are not used because they
have
-no meaning in this context.
-Refer to <a href="http://ant.apache.org">ant manual</a> for details
on
-<code><redirector></code> element attributes.
-</p>
-
-<p>
-Here is a sample build file extract that shows how this output redirection support
-can be used:
-</p>
-
-<source>
- <target name="manager.deploy"
- depends="context.status"
- if="context.notInstalled">
- <deploy url="${mgr.url}"
- username="${mgr.username}"
- password="${mgr.password}"
- path="${mgr.context.path}"
- config="${mgr.context.descriptor}"/>
- </target>
-
- <target name="manager.deploy.war"
- depends="context.status"
- if="context.deployable">
- <deploy url="${mgr.url}"
- username="${mgr.username}"
- password="${mgr.password}"
- update="${mgr.update}"
- path="${mgr.context.path}"
- war="${mgr.war.file}"/>
- </target>
-
- <target name="context.status">
- <property name="running"
value="${mgr.context.path}:running"/>
- <property name="stopped"
value="${mgr.context.path}:stopped"/>
-
- <list url="${mgr.url}"
- outputproperty="ctx.status"
- username="${mgr.username}"
- password="${mgr.password}">
- </list>
-
- <condition property="context.running">
- <contains string="${ctx.status}"
substring="${running}"/>
- </condition>
- <condition property="context.stopped">
- <contains string="${ctx.status}"
substring="${stopped}"/>
- </condition>
- <condition property="context.notInstalled">
- <and>
- <isfalse value="${context.running}"/>
- <isfalse value="${context.stopped}"/>
- </and>
- </condition>
- <condition property="context.deployable">
- <or>
- <istrue value="${context.notInstalled}"/>
- <and>
- <istrue value="${context.running}"/>
- <istrue value="${mgr.update}"/>
- </and>
- <and>
- <istrue value="${context.stopped}"/>
- <istrue value="${mgr.update}"/>
- </and>
- </or>
- </condition>
- <condition property="context.undeployable">
- <or>
- <istrue value="${context.running}"/>
- <istrue value="${context.stopped}"/>
- </or>
- </condition>
- </target>
-</source>
-
-<p><strong>WARNING:</strong> even if it doesn't make many sense,
and is always a bad idea,
-calling a Catalina task more than once,
-badly set Ant tasks depends chains may cause that a task be called
-more than once in the same Ant run, even if not intended to. A bit of caution should be
exercised when you are
-capturing output from that task, because this could lead to something unexpected:
-<ul>
-<li>when capturing in a property you will find in it only the output from the
<em>first</em> call, because
-Ant properties are immutable and once set they cannot be changed,
-</li>
-<li>when capturing in a file, each run will overwrite it and you will find in it
only the <em>last</em> call
-output, unless you are using the <code>append="true"</code>
attribute, in which case you will
-see the output of each task call appended to the file.
-</li>
-</ul>
-</p>
-
-</subsection>
-
-</section>
-
-<section name="Using the JMX Proxy Servlet">
-
- <subsection name="What is JMX Proxy Servlet">
- The JMX Proxy Servlet is a lightweight proxy to get and set the
- JBoss Web internals. (Or any class that has been exposed via an MBean)
- Its usage is not very user friendly but the UI is
- extremely help for integrating command line scripts for monitoring
- and changing the internals of JBoss Web. You can do two things with the proxy:
- get information and set information. For you to really understand the
- JMX Proxy Servlet, you should have a general understanding of JMX.
- If you don't know what JMX is, then prepare to be confused.
- </subsection>
-
- <subsection name="JMX Query command">
- This takes the form:
-<source>
-http://webserver/manager/jmxproxy/?qry=STUFF
-</source>
- Where <code>STUFF</code> is the JMX query you wish to perform. For
example,
- here are some queries you might wish to run:
- <ul>
- <li>
- <code>qry=*%3Atype%3DRequestProcessor%2C* -->
- type=RequestProcessor</code> which will locate all
- workers which can process requests and report
- their state.
- </li>
- <li>
- <code>qry=*%3Aj2eeType=Servlet%2c* -->
- j2eeType=Servlet</code> which return all loaded servlets.
- </li>
- <li>
-
<code>qry=Catalina%3Atype%3DEnvironment%2Cresourcetype%3DGlobal%2Cname%3DsimpleValue
-->
- Catalina:type=Environment,resourcetype=Global,name=simpleValue</code>
- which look for a specific MBean by the given name.
- </li>
- </ul>
- You'll need to experiment with this to really understand its capabilites.
- If you provide no <code>qry</code> parameter, then all of the MBeans
will
- be displayed. We really recommend looking at the JBoss Web source code and
- understand the JMX spec to get a better understanding of all the queries
- you may run.
- </subsection>
-
- <subsection name="JMX Set command">
- Now that you can query an MBean, its time to muck with JBoss Web's internals!
- The general form of the set command is :
-<source>
-http://webserver/manager/jmxproxy/?set=BEANNAME&att=MYATTRIBUTE&val=NEWVALUE
-</source>
- So you need to provide 3 request parameters:
- <ol>
- <li><code>set</code>: The full bean name</li>
- <li><code>att</code>: The attribute you wish to alter</li>
- <li><code>val</code>: The new value </li>
- </ol>
- If all goes ok, then it will say OK, otherwise an error message will be
- shown. For example, lets say we wish to turn up debugging on the fly for the
- <code>ErrorReportValve</code>. The following will set debugging to 10.
-<source>
-http://localhost:8080/manager/jmxproxy/?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost&att=debug&val=10
-</source>
- and my result is (YMMV):
-<source>
-Result: ok
-</source>
-
- Here is what I see if I pass in a bad value. Here is the URL I used,
- I try set debugging equal to 'cowbell':
-<source>
-http://localhost:8080/manager/jmxproxy/?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost&att=debug&val=cowbell
-</source>
- When I try that, my result is
-<source>
-Error: java.lang.NumberFormatException: For input string: "cowbell"
-</source>
- </subsection>
-
-
-</section>
-
-
-
-</body>
-
-</document>
Deleted: trunk/webapps/docs/mbeans-descriptor-howto.xml
===================================================================
--- trunk/webapps/docs/mbeans-descriptor-howto.xml 2011-09-08 14:43:49 UTC (rev 1831)
+++ trunk/webapps/docs/mbeans-descriptor-howto.xml 2011-09-08 16:06:13 UTC (rev 1832)
@@ -1,63 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE document [
- <!ENTITY project SYSTEM "project.xml">
-]>
-<document url="mbeans-descriptor-howto.html">
-
- &project;
-
- <properties>
- <author email="amyroh(a)apache.org">Amy Roh</author>
- <title>MBean Descriptor How To</title>
- </properties>
-
-<body>
-
-<section name="Introduction">
-
-<p>JBoss Web uses JMX MBeans as the technology for implementing
-manageability of JBoss Web.</p>
-
-<p>The descriptions of JMX MBeans for Catalina are in the mbeans-descriptor.xml
-file in each package.</p>
-
-<p>You will need to add MBean descriptions for your custom components
-in order to avoid a "ManagedBean is not found" exception.</p>
-
-</section>
-
-<section name="Adding MBean descriptions">
-
-<p>You may also add MBean descriptions for custom components in
-a mbeans-descriptor.xml file, located in the same package as the class files
-it describes.</p>
-
-<source>
- <mbean name="LDAPRealm"
- className="org.apache.catalina.mbeans.ClassNameMBean"
- description="Custom LDAPRealm"
- domain="Catalina"
- group="Realm"
- type="com.myfirm.mypackage.LDAPRealm">
-
- <attribute name="className"
- description="Fully qualified class name of the managed object"
- type="java.lang.String"
- writeable="false"/>
-
- <attribute name="debug"
- description="The debugging detail level for this component"
- type="int"/>
- .
- .
- .
-
- </mbean>
-</source>
-
-
-</section>
-
-</body>
-
-</document>
Deleted: trunk/webapps/docs/php.xml
===================================================================
--- trunk/webapps/docs/php.xml 2011-09-08 14:43:49 UTC (rev 1831)
+++ trunk/webapps/docs/php.xml 2011-09-08 16:06:13 UTC (rev 1832)
@@ -1,107 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE document [
- <!ENTITY project SYSTEM "project.xml">
-]>
-<document url="index.html">
-
- &project;
-
- <properties>
- <author email="mladen.turk(a)jboss.com">Mladen Turk</author>
- <author email="jfrederic.clere(a)jboss.com">Jean-Frederic
Clere</author>
- <title>Overview</title>
- </properties>
-
-<body>
-
-<section name="Introduction">
-<p>The PHP Module is a servlet that allows to run PHP embedded scripts.
-The servlet calls a native embedded PHP engine with libraries extentions.
-The PHP servlet allows to run most of the existing PHP scripts.
-</p>
-</section>
-
-<section name="Building">
-<p>
-To build simply run buildphp.sh.
-The buildphp.sh will detect you platform, download and build the dynamic libraries the
PHP library needs and
-build the PHP servlet itself. Should should get a tarfile that contains the libraries and
a war file with the examples.
-</p>
-Already build PHP servlets and libraries are available at:
-<a href="http://labs.jboss.com/jbossweb/downloads/php/">JBossWeb download
area</a>
-</section>
-
-<section name="Installing">
-After extracting the tarball corresponding to you platform. (For example in $JBOSS_HOME,
-where JBOSS_HOME should be something like jbossweb-1.0.0.GA).<br/>
-In $CATALINA_BASE (CATALINA_BASE should be
-something like jbossweb-1.0.0.GA/server/default/deploy/jbossweb.sar) do the
following:<br/>
-Edit in the <Server/> of <code>$CATALINA_BASE/server.xml</code>
and uncomment the following Listener entry:
-<source>
- <Listener
className="org.apache.catalina.servlets.php.LifecycleListener"/>
-</source>
-If you want to enable php in all contexts edit
<code>$CATALINA_BASE/conf/web.xml</code> and uncomment the php servlet
-description and its mapping:
-<source>
- <servlet>
- <servlet-name>php</servlet-name>
-
<servlet-class>org.apache.catalina.servlets.php.Handler</servlet-class>
- <init-param>
- <param-name>debug</param-name>
- <param-value>0</param-value>
- </init-param>
- <load-on-startup>6</load-on-startup>
- </servlet>
- <servlet>
- <servlet-name>phps</servlet-name>
-
<servlet-class>org.apache.catalina.servlets.php.Highlight</servlet-class>
- </servlet>
-<source>
-</source>
- <servlet-mapping>
- <servlet-name>php</servlet-name>
- <url-pattern>*.php</url-pattern>
- </servlet-mapping>
- <servlet-mapping>
- <servlet-name>phps</servlet-name>
- <url-pattern>*.phps</url-pattern>
- </servlet-mapping>
-</source>
-Edit the <code>$JBOSS_HOME/bin/run.conf</code> (JBOSS_HOME should be
something like jbossweb-1.0.0.GA) add the <code>LD_LIBRARY_PATH</code>
variable and modify/add (replace $JBOSS_HOME by its value)
-the java.library.path parameter of the JVM:
-<source>
-LD_LIBRARY_PATH=$JBOSS_HOME/PHP/lib
-export LD_LIBRARY_PATH
-</source>
-Copy the 2 libraries libphp5.so and libphp5servlet.so in $JBOSS_HOME/bin/native,
something like:
-<source>
-cp ./PHP/lib/libphp5.so bin/native
-cp ./PHP/lib/libphp5servlet.so bin/native
-</source>
-</section>
-<section name="Using the php demo scripts">
-The <code>php-examples.war</code> warfile of the tarball contains some php
demo scripts.
-The warfile should be located in $CATALINA_BASE.
-They are deployed under /php-examples to use them you only need to modify the
<code>$JBOSS_HOME/bin/run.conf</code> as described above.<br/>
-You don't have to modify the <code>$CATALINA_BASE/conf/web.xml</code>
-nor the <code>$CATALINA_BASE/server.xml</code> files.
-You have to start and restart the servlet container because of the environment
modifications.<br/>
-To use the examples, try
<code>http://localhost:8080/php-examples/index.php</code>.
-</section>
-<section name="Additing extension libraries">
-For the moment this feature is only supported on Solaris.
-Edit the <code>php.ini</code> file and add your library extensions as in the
following example:
-<source>
-extension_dir=/home/jfclere/SunOS_i386_tools/PHP/lib/php/extensions/no-debug-zts-20050922
-extension=openssl.so
-extension=pdo_pgsql.so
-extension=pgsql.so
-</source>
-</section>
-<section name="Installing on win32 machines">
-Copy the demo webapps/php-examples.war to ./server/default/deploy.<br/>
-Edit server/default/deploy/jbossweb.sar/server.xml as in other OS.<br/>
-Copy the dlls in bin/native
-</section>
-</body>
-</document>
Modified: trunk/webapps/docs/project.xml
===================================================================
--- trunk/webapps/docs/project.xml 2011-09-08 14:43:49 UTC (rev 1831)
+++ trunk/webapps/docs/project.xml 2011-09-08 16:06:13 UTC (rev 1832)
@@ -12,13 +12,11 @@
<body>
<menu name="User Guide">
- <item name="Docs Home" href="index.html"/>
+ <item name="Docs Home" href="index.html"/>
<item name="Introduction"
href="introduction.html"/>
- <item name="Setup" href="setup.html"/>
<item name="System Properties"
href="sysprops.html"/>
<item name="First webapp"
href="appdev/index.html"/>
<item name="Deployer"
href="deployer-howto.html"/>
- <item name="Manager"
href="manager-howto.html"/>
<item name="Realms and AAA"
href="realm-howto.html"/>
<item name="Security Manager"
href="security-manager-howto.html"/>
<item name="JNDI Resources"
href="jndi-resources-howto.html"/>
@@ -26,9 +24,6 @@
<item name="Classloading"
href="class-loader-howto.html"/>
<item name="JSPs"
href="jasper-howto.html"/>
<item name="SSL"
href="ssl-howto.html"/>
- <item name="PHP" href="php.html"/>
- <item name="SSI"
href="ssi-howto.html"/>
- <item name="CGI"
href="cgi-howto.html"/>
<item name="URL Rewriting"
href="rewrite.html"/>
<item name="Proxy Support"
href="proxy-howto.html"/>
<item name="MBean Descriptor"
href="mbeans-descriptor-howto.html"/>
@@ -53,9 +48,6 @@
<item name="Release Notes"
href="RELEASE-NOTES.txt"/>
<item name="Configuration"
href="config/index.html"/>
<item name="Javadocs"
href="api/index.html"/>
- <item name="JK 1.2 Documentation"
- href="http://tomcat.apache.org/connectors-doc/"/>
- <item name="Tomcat FAQ"
href="http://tomcat.apache.org/faq" />
</menu>
</body>
Deleted: trunk/webapps/docs/realm-howto.xml
===================================================================
--- trunk/webapps/docs/realm-howto.xml 2011-09-08 14:43:49 UTC (rev 1831)
+++ trunk/webapps/docs/realm-howto.xml 2011-09-08 16:06:13 UTC (rev 1832)
@@ -1,1471 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE document [
- <!ENTITY project SYSTEM "project.xml">
-]>
-<document url="realm-howto.html">
-
- &project;
-
- <properties>
- <author email="craigmcc(a)apache.org">Craig R.
McClanahan</author>
- <author email="yoavs(a)apache.org">Yoav Shapira</author>
- <author email="arjaquith(a)mindspring.com">Andrew R.
Jaquith</author>
- <title>Realm Configuration HOW-TO</title>
- </properties>
-
-<body>
-
-
-<section name="Table of Contents">
-
-<p>
-<a href="#Quick Start">Quick Start</a><br />
-<blockquote>
-<a href="#What is a Realm?">What is a Realm?</a><br />
-<a href="#Configuring a Realm">Configuring a Realm</a><br />
-</blockquote>
-<a href="#Common Features">Common Features</a><br />
-<blockquote>
-<a href="#Digested Passwords">Digested Passwords</a><br />
-<a href="#Example Application">Example Application</a><br />
-<a href="#Manager Application">Manager Application</a><br />
-<a href="#Realm Logging">Logging Within Realms</a><br />
-</blockquote>
-<a href="#Standard Realm Implementations">
-Standard Realm Implementations</a><br />
-<blockquote>
-<a href="#JDBCRealm">JDBCRealm</a><br />
-<a href="#DataSourceRealm">DataSourceRealm</a><br />
-<a href="#JNDIRealm">JNDIRealm</a><br />
-<a href="#MemoryRealm">MemoryRealm</a><br />
-<a href="#JAASRealm">JAASRealm</a><br />
-</blockquote>
-</p>
-
-</section>
-
-<section name="Quick Start">
-
-<p>This document describes how to configure JBoss Web to support
<em>container
-managed security</em>, by connecting to an existing "database" of
usernames,
-passwords, and user roles. You only need to care about this if you are using
-a web application that includes one or more
-<code><security-constraint></code> elements, and a
-<code><login-config></code> element defining how users are
required
-to authenticate themselves. If you are not utilizing these features, you can
-safely skip this document.</p>
-
-<p>For fundamental background information about container managed security,
-see the <a
href="http://java.sun.com/products/servlet/download.html">Se...
-Specification (Version 2.4)</a>, Section 12.</p>
-
-<p>For information about utilizing the <em>Single Sign On</em> feature
of
-JBoss Web (allowing a user to authenticate themselves once across the entire
-set of web applications associated with a virtual host), see
-<a href="config/host.html#Single Sign On">here</a>.</p>
-
-</section>
-
-
-<section name="Overview">
-
-
-<subsection name="What is a Realm?">
-
-<p>A <strong>Realm</strong> is a "database" of usernames and
passwords that
-identify valid users of a web application (or set of web applications), plus
-an enumeration of the list of <em>roles</em> associated with each valid
user.
-You can think of roles as similar to <em>groups</em> in Unix-like operating
-systems, because access to specific web application resources is granted to
-all users possessing a particular role (rather than enumerating the list of
-associated usernames). A particular user can have any number of roles
-associated with their username.</p>
-
-<p>Although the Servlet Specification describes a portable mechanism for
-applications to <em>declare</em> their security requirements (in the
-<code>web.xml</code> deployment descriptor), there is no portable API
-defining the interface between a servlet container and the associated user
-and role information. In many cases, however, it is desireable to "connect"
-a servlet container to some existing authentication database or mechanism
-that already exists in the production environment. Therefore, JBoss Web
-defines a Java interface (<code>org.apache.catalina.Realm</code>) that
-can be implemented by "plug in" components to establish this connection.
-Five standard plug-ins are provided, supporting connections to various
-sources of authentication information:</p>
-<ul>
-<li><a href="#JDBCRealm">JDBCRealm</a> - Accesses
authentication information
- stored in a relational database, accessed via a JDBC driver.</li>
-<li><a href="#DataSourceRealm">DataSourceRealm</a> - Accesses
authentication
- information stored in a relational database, accessed via a named JNDI
- JDBC DataSource.</li>
-<li><a href="#JNDIRealm">JNDIRealm</a> - Accesses
authentication information
- stored in an LDAP based directory server, accessed via a JNDI provider.
- </li>
-<li><a href="#MemoryRealm">MemoryRealm</a> - Accesses
authentication
- information stored in an in-memory object collection, which is initialized
- from an XML document (<code>conf/tomcat-users.xml</code>).</li>
-<li><a href="#JAASRealm">JAASRealm</a> - Accesses
authentication information
- through the Java Authentication & Authorization Service (JAAS)
- framework.</li>
-</ul>
-
-<p>It is also possible to write your own <code>Realm</code>
implementation,
-and integrate it with JBoss Web. To do so, you need to:
-<ul>
- <li>Implement <code>org.apache.catalina.Realm</code>,</li>
- <li>Place your compiled realm in $CATALINA_HOME/server/lib,</li>
- <li>Declare your realm as described in the "Configuring a Realm"
section below,</li>
- <li>Declare your realm to the <a
href="mbeans-descriptor-howto.html">MBeans Descriptor</a>.</li>
-</ul>
-</p>
-
-</subsection>
-
-
-<subsection name="Configuring a Realm">
-
-<p>Before getting into the details of the standard Realm implementations, it is
-important to understand, in general terms, how a Realm is configured. In
-general, you will be adding an XML element to your
<code>conf/server.xml</code>
-configuration file, that looks something like this:</p>
-
-<source>
-<Realm className="... class name for this implementation"
- ... other attributes for this implementation .../>
-</source>
-
-<p>The <code><Realm></code> element can be nested inside
any one of
-of the following <code>Container</code> elements. The location of the
-Realm element has a direct impact on the "scope" of that Realm
-(i.e. which web applications will share the same authentication information):
-</p>
-<ul>
-<li><em>Inside an <Engine> element</em> - This Realm will
be shared
- across ALL web applications on ALL virtual hosts, UNLESS it is overridden
- by a Realm element nested inside a subordinate
<code><Host></code>
- or <code><Context></code> element.</li>
-<li><em>Inside a <Host> element</em> - This Realm will be
shared across
- ALL web applications for THIS virtual host, UNLESS it is overridden
- by a Realm element nested inside a subordinate
<code><Context></code>
- element.</li>
-<li><em>Inside a <Context> element</em> - This Realm will
be used ONLY
- for THIS web application.</li>
-</ul>
-
-
-</subsection>
-
-
-</section>
-
-
-<section name="Common Features">
-
-
-<subsection name="Digested Passwords">
-
-<p>For each of the standard <code>Realm</code> implementations, the
-user's password (by default) is stored in clear text. In many
-environments, this is undesireable because casual observers of the
-authentication data can collect enough information to log on
-successfully, and impersonate other users. To avoid this problem, the
-standard implementations support the concept of <em>digesting</em>
-user passwords. This allows the stored version of the passwords to be
-encoded (in a form that is not easily reversible), but that the
-<code>Realm</code> implementation can still utilize for
-authentication.</p>
-
-<p>When a standard realm authenticates by retrieving the stored
-password and comparing it with the value presented by the user, you
-can select digested passwords by specifying the <code>digest</code>
-attribute on your <code><Realm></code> element. The value for
-this attribute must be one of the digest algorithms supported by the
-<code>java.security.MessageDigest</code> class (SHA, MD2, or MD5).
-When you select this option, the contents of the password that is
-stored in the <code>Realm</code> must be the cleartext version of the
-password, as digested by the specified algorithm.</p>
-
-<p>When the <code>authenticate()</code> method of the Realm is called,
the
-(cleartext) password specified by the user is itself digested by the same
-algorithm, and the result is compared with the value returned by the
-<code>Realm</code>. An equal match implies that the cleartext version of
the
-original password is the same as the one presented by the user, so that this
-user should be authorized.</p>
-
-<p>To calculate the digested value of a cleartext password, two convenience
-techniques are supported:</p>
-<ul>
-<li>If you are writing an application that needs to calculate digested
- passwords dynamically, call the static <code>Digest()</code> method of
the
- <code>org.apache.catalina.realm.RealmBase</code> class, passing the
- cleartext password and the digest algorithm name as arguments. This
- method will return the digested password.</li>
-<li>If you want to execute a command line utility to calculate the digested
- password, simply execute
-<source>
-java org.apache.catalina.realm.RealmBase \
- -a {algorithm} {cleartext-password}
-</source>
- and the digested version of this cleartext password will be returned to
- standard output.</li>
-</ul>
-
-<p>If using digested passwords with DIGEST authentication, the cleartext used
- to generate the digest is different. In the examples above
- <code>{cleartext-password}</code> must be replaced with
- <code>{username}:{realm}:{cleartext-password}</code>. For example, in a
- development environment this might take the form
- <code>testUser:localhost:8080:testPassword</code>.</p>
-
-<p>To use either of the above techniques, the
-<code>$CATALINA_HOME/lib/catalina.jar</code> and
-<code>$CATALINA_HOME/bin/tomcat-juli.jar</code> files will need to be
-on your class path to make the <code>RealmBase</code> class available.
-</p>
-
-<p>Non-ASCII usernames and/or passwords are supported using
-<source>java org.apache.catalina.realm.RealmBase \
- -a {algorithm} -e {encoding} {input}
-</source>
-but care is required to ensure that the non-ASCII input is
-correctly passed to the digester.
-The digester returns <code>{input}:{digest}</code>. If the input appears
-corrupted in the return, the digest will be invalid.</p>
-
-</subsection>
-
-
-
-<subsection name="Example Application">
-
-<p>The example application shipped with JBoss Web includes an area that is
-protected by a security constraint, utilizing form-based login. To access it,
-point your browser at
-<a
href="http://localhost:8080/examples/jsp/security/protected/">http://localhost:8080/examples/jsp/security/protected/</a>
-and log on with one of the usernames and passwords described for the default
-<a href="#MemoryRealm">MemoryRealm</a>.</p>
-
-</subsection>
-
-
-<subsection name="Manager Application">
-
-<p>If you wish to use the <a href="manager-howto.html">Manager
Application</a>
-to deploy and undeploy applications in a running JBoss Web installation, you
-MUST add the "manager" role to at least one username in your selected Realm
-implementation. This is because the manager web application itself uses a
-security constraint that requires role "manager" to access ANY request URI
-within that application.</p>
-
-<p>For security reasons, no username in the default Realm (i.e. using
-<code>conf/tomcat-users.xml</code> is assigned the "manager" role.
Therfore,
-no one will be able to utilize the features of this application until the
-JBoss Web administrator specifically assigns this role to one or more users.</p>
-
-</subsection>
-
-<subsection name="Realm Logging">
-
-<p>Debugging and exception messages logged by a <code>Realm</code>
will
- be recorded by the logging configuration associated with the container
- for the realm: its surrounding <a
href="config/context.html">Context</a>,
- <a href="config/host.html">Host</a>, or
- <a href="config/engine.html">Engine</a>.</p>
-
-</subsection>
-
-</section>
-
-
-<section name="Standard Realm Implementations">
-
-<subsection name="JDBCRealm">
-
-<h3>Introduction</h3>
-
-<p><strong>JDBCRealm</strong> is an implementation of the JBoss Web
-<code>Realm</code> interface that looks up users in a relational database
-accessed via a JDBC driver. There is substantial configuration flexibility
-that lets you adapt to existing table and column names, as long as your
-database structure conforms to the following requirements:</p>
-<ul>
-<li>There must be a table, referenced below as the <em>users</em>
table,
- that contains one row for every valid user that this <code>Realm</code>
- should recognize.</li>
-<li>The <em>users</em> table must contain at least two columns (it may
- contain more if your existing applications required it):
- <ul>
- <li>Username to be recognized by JBoss Web when the user logs in.</li>
- <li>Password to be recognized by JBoss Web when the user logs in.
- This value may in cleartext or digested - see below for more
- information.</li>
- </ul></li>
-<li>There must be a table, referenced below as the <em>user roles</em>
table,
- that contains one row for every valid role that is assigned to a
- particular user. It is legal for a user to have zero, one, or more than
- one valid role.</li>
-<li>The <em>user roles</em> table must contain at least two columns (it
may
- contain more if your existing applications required it):
- <ul>
- <li>Username to be recognized by JBoss Web (same value as is specified
- in the <em>users</em> table).</li>
- <li>Role name of a valid role associated with this user.</li>
- </ul></li>
-</ul>
-
-<h3>Quick Start</h3>
-
-<p>To set up JBoss Web to use JDBCRealm, you will need to follow these
steps:</p>
-<ol>
-<li>If you have not yet done so, create tables and columns in your database
- that conform to the requirements described above.</li>
-<li>Configure a database username and password for use by JBoss Web, that has
- at least read only access to the tables described above. (JBoss Web will
- never attempt to write to these tables.)</li>
-<li>Place a copy of the JDBC driver you will be using inside the
- <code>$CATALINA_HOME/lib</code> directory.
- Note that <strong>only</strong> JAR files are recognized!</li>
-<li>Set up a <code><Realm></code> element, as described
below, in your
- <code>$CATALINA_HOME/conf/server.xml</code> file.</li>
-<li>Restart JBoss Web if it is already running.</li>
-</ol>
-
-<h3>Realm Element Attributes</h3>
-
-<p>To configure JDBCRealm, you will create a
<code><Realm></code>
-element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code>
file,
-as described <a href="#Configuring a Realm">above</a>. The
following
-attributes are supported by this implementation:</p>
-
-<attributes>
-
- <attribute name="className" required="true">
- <p>The fully qualified Java class name of this Realm implementation.
- You <strong>MUST</strong> specify the value
- "<code>org.apache.catalina.realm.JDBCRealm</code>"
here.</p>
- </attribute>
-
- <attribute name="connectionName" required="true">
- <p>The database username used to establish a JDBC connection.</p>
- </attribute>
-
- <attribute name="connectionPassword" required="true">
- <p>The database password used to establish a JDBC connection.</p>
- </attribute>
-
- <attribute name="connectionURL" required="true">
- <p>The database URL used to establish a JDBC connection.</p>
- </attribute>
-
- <attribute name="digest" required="false">
- <p>The digest algorithm used to store passwords in non-plaintext formats.
- Valid values are those accepted for the algorithm name by the
- <code>java.security.MessageDigest</code> class. See
- <a href="#Digested Passwords">Digested Passwords</a> for more
- information. If not specified, passwords are stored in clear text.</p>
- </attribute>
-
- <attribute name="driverName" required="true">
- <p>The fully qualified Java class name of the JDBC driver to be used.
- Consult the documentation for your JDBC driver for the appropriate
- value.</p>
- </attribute>
-
- <attribute name="roleNameCol" required="true">
- <p>The name of the column, in the <em>user roles</em> table, that
- contains the name of a role assigned to this user.</p>
- </attribute>
-
- <attribute name="userCredCol" required="true">
- <p>The name of the column, in the <em>users</em> table, that
contains
- the password for this user (either in clear text, or digested if the
- <code>digest</code> attribute is set).</p>
- </attribute>
-
- <attribute name="userNameCol" required="true">
- <p>The name of the column, in the <em>users</em> and <em>user
roles</em>
- tables, that contains the username of this user.</p>
- </attribute>
-
- <attribute name="userRoleTable" required="true">
- <p>The name of the table that contains one row for each
<em>role</em>
- assigned to a particular <em>username</em>. This table must include at
- least the columns named by the <code>userNameCol</code> and
- <code>roleNameCol</code> attributes.</p>
- </attribute>
-
- <attribute name="userTable" required="true">
- <p>The name of the table that contains one row for each
<em>username</em>
- to be recognized by JBoss Web. This table must include at least the columns
- named by the <code>userNameCol</code> and
<code>userCredCol</code>
- attributes.</p>
- </attribute>
-
-</attributes>
-
-<h3>Example</h3>
-
-<p>An example SQL script to create the needed tables might look something
-like this (adapt the syntax as required for your particular database):</p>
-<source>
-create table users (
- user_name varchar(15) not null primary key,
- user_pass varchar(15) not null
-);
-
-create table user_roles (
- user_name varchar(15) not null,
- role_name varchar(15) not null,
- primary key (user_name, role_name)
-);
-</source>
-
-<p>Example <code>Realm</code> elements are included (commented out) in
the
-default <code>$CATALINA_HOME/conf/server.xml</code> file. Here's an
example
-for using a MySQL database called "authority", configured with the tables
-described above, and accessed with username "dbuser" and password
"dbpass":</p>
-<source>
-<Realm className="org.apache.catalina.realm.JDBCRealm"
debug="99"
- driverName="org.gjt.mm.mysql.Driver"
-
connectionURL="jdbc:mysql://localhost/authority?user=dbuser&amp;password=dbpass"
- userTable="users" userNameCol="user_name"
userCredCol="user_pass"
- userRoleTable="user_roles" roleNameCol="role_name"/>
-</source>
-
-<h3>Additional Notes</h3>
-
-<p>JDBCRealm operates according to the following rules:</p>
-<ul>
-<li>When a user attempts to access a protected resource for the first time,
- JBoss Web will call the <code>authenticate()</code> method of this
- <code>Realm</code>. Thus, any changes you have made to the database
- directly (new users, changed passwords or roles, etc.) will be immediately
- reflected.</li>
-<li>Once a user has been authenticated, the user (and his or her associated
- roles) are cached within JBoss Web for the duration of the user's login.
- (For FORM-based authentication, that means until the session times out or
- is invalidated; for BASIC authentication, that means until the user
- closes their browser). The cached user is <strong>not</strong> saved
and
- restored across sessions serialisations. Any changes to the database
- information for an already authenticated user will <strong>not</strong>
be
- reflected until the next time that user logs on again.</li>
-<li>Administering the information in the <em>users</em> and
<em>user roles</em>
- table is the responsibility of your own applications. JBoss Web does not
- provide any built-in capabilities to maintain users and roles.</li>
-</ul>
-
-</subsection>
-
-
-<subsection name="DataSourceRealm">
-
-<h3>Introduction</h3>
-
-<p><strong>DataSourceRealm</strong> is an implementation of the JBoss
Web
-<code>Realm</code> interface that looks up users in a relational database
-accessed via a JNDI named JDBC DataSource. There is substantial configuration
-flexibility that lets you adapt to existing table and column names, as long
-as your database structure conforms to the following requirements:</p>
-<ul>
-<li>There must be a table, referenced below as the <em>users</em>
table,
- that contains one row for every valid user that this <code>Realm</code>
- should recognize.</li>
-<li>The <em>users</em> table must contain at least two columns (it may
- contain more if your existing applications required it):
- <ul>
- <li>Username to be recognized by JBoss Web when the user logs in.</li>
- <li>Password to be recognized by JBoss Web when the user logs in.
- This value may in cleartext or digested - see below for more
- information.</li>
- </ul></li>
-<li>There must be a table, referenced below as the <em>user roles</em>
table,
- that contains one row for every valid role that is assigned to a
- particular user. It is legal for a user to have zero, one, or more than
- one valid role.</li>
-<li>The <em>user roles</em> table must contain at least two columns (it
may
- contain more if your existing applications required it):
- <ul>
- <li>Username to be recognized by JBoss Web (same value as is specified
- in the <em>users</em> table).</li>
- <li>Role name of a valid role associated with this user.</li>
- </ul></li>
-</ul>
-
-<h3>Quick Start</h3>
-
-<p>To set up JBoss Web to use DataSourceRealm, you will need to follow these
steps:</p>
-<ol>
-<li>If you have not yet done so, create tables and columns in your database
- that conform to the requirements described above.</li>
-<li>Configure a database username and password for use by JBoss Web, that has
- at least read only access to the tables described above. (JBoss Web will
- never attempt to write to these tables.)</li>
-<li>Configure a JNDI named JDBC DataSource for your database. Refer to the
- <a href="jndi-datasource-examples-howto.html">JNDI DataSource Example
HOW-TO</a>
- for information on how to configure a JNDI named JDBC DataSource.</li>
-<li>Set up a <code><Realm></code> element, as described
below, in your
- <code>$CATALINA_HOME/conf/server.xml</code> file.</li>
-<li>Restart JBoss Web if it is already running.</li>
-</ol>
-
-<h3>Realm Element Attributes</h3>
-
-<p>To configure DataSourceRealm, you will create a
<code><Realm></code>
-element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code>
file,
-as described <a href="#Configuring a Realm">above</a>. The
following
-attributes are supported by this implementation:</p>
-
-<attributes>
-
- <attribute name="className" required="true">
- <p>The fully qualified Java class name of this Realm implementation.
- You <strong>MUST</strong> specify the value
- "<code>org.apache.catalina.realm.DataSourceRealm</code>"
here.</p>
- </attribute>
-
- <attribute name="dataSourceName" required="true">
- <p>The JNDI named JDBC DataSource for your database. If the DataSource is
- local to the context, the name is relative to
<code>java:/comp/env</code>,
- and otherwise the name should match the name used to define the global
- DataSource.</p>
- </attribute>
-
- <attribute name="digest" required="false">
- <p>The digest algorithm used to store passwords in non-plaintext formats.
- Valid values are those accepted for the algorithm name by the
- <code>java.security.MessageDigest</code> class. See
- <a href="#Digested Passwords">Digested Passwords</a> for more
- information. If not specified, passwords are stored in clear text.</p>
- </attribute>
-
- <attribute name="localDataSource" required="false">
- <p>When the realm is nested inside a Context element, this allows the
- realm to use a DataSource defined for the Context rather than a global
- DataSource. If not specified, the default is <code>false</code>: use a
- global DataSource.</p>
- </attribute>
-
- <attribute name="roleNameCol" required="true">
- <p>The name of the column, in the <em>user roles</em> table, that
- contains the name of a role assigned to this user.</p>
- </attribute>
-
- <attribute name="userCredCol" required="true">
- <p>The name of the column, in the <em>users</em> table, that
contains
- the password for this user (either in clear text, or digested if the
- <code>digest</code> attribute is set).</p>
- </attribute>
-
- <attribute name="userNameCol" required="true">
- <p>The name of the column, in the <em>users</em> and <em>user
roles</em>
- tables, that contains the username of this user.</p>
- </attribute>
-
- <attribute name="userRoleTable" required="true">
- <p>The name of the table that contains one row for each
<em>role</em>
- assigned to a particular <em>username</em>. This table must include at
- least the columns named by the <code>userNameCol</code> and
- <code>roleNameCol</code> attributes.</p>
- </attribute>
-
- <attribute name="userTable" required="true">
- <p>The name of the table that contains one row for each
<em>username</em>
- to be recognized by JBoss Web. This table must include at least the columns
- named by the <code>userNameCol</code> and
<code>userCredCol</code>
- attributes.</p>
- </attribute>
-
-</attributes>
-
-<h3>Example</h3>
-
-<p>An example SQL script to create the needed tables might look something
-like this (adapt the syntax as required for your particular database):</p>
-<source>
-create table users (
- user_name varchar(15) not null primary key,
- user_pass varchar(15) not null
-);
-
-create table user_roles (
- user_name varchar(15) not null,
- role_name varchar(15) not null,
- primary key (user_name, role_name)
-);
-</source>
-
-<p>Here is an example for using a MySQL database called "authority",
configured
-with the tables described above, and accessed with the JNDI JDBC DataSource with
-name "java:/comp/env/jdbc/authority".</p>
-<source>
-<Realm className="org.apache.catalina.realm.DataSourceRealm"
debug="99"
- dataSourceName="jdbc/authority"
- userTable="users" userNameCol="user_name"
userCredCol="user_pass"
- userRoleTable="user_roles" roleNameCol="role_name"/>
-</source>
-
-<h3>Additional Notes</h3>
-
-<p>DataSourceRealm operates according to the following rules:</p>
-<ul>
-<li>When a user attempts to access a protected resource for the first time,
- JBoss Web will call the <code>authenticate()</code> method of this
- <code>Realm</code>. Thus, any changes you have made to the database
- directly (new users, changed passwords or roles, etc.) will be immediately
- reflected.</li>
-<li>Once a user has been authenticated, the user (and his or her associated
- roles) are cached within JBoss Web for the duration of the user's login.
- (For FORM-based authentication, that means until the session times out or
- is invalidated; for BASIC authentication, that means until the user
- closes their browser). The cached user is <strong>not</strong> saved
and
- restored across sessions serialisations. Any changes to the database
- information for an already authenticated user will <strong>not</strong>
be
- reflected until the next time that user logs on again.</li>
-<li>Administering the information in the <em>users</em> and
<em>user roles</em>
- table is the responsibility of your own applications. JBoss Web does not
- provide any built-in capabilities to maintain users and roles.</li>
-</ul>
-
-</subsection>
-
-
-<subsection name="JNDIRealm">
-
-<h3>Introduction</h3>
-
-<p><strong>JNDIRealm</strong> is an implementation of the JBoss Web
-<code>Realm</code> interface that looks up users in an LDAP directory
-server accessed by a JNDI provider (typically, the standard LDAP
-provider that is available with the JNDI API classes). The realm
-supports a variety of approaches to using a directory for
-authentication.</p>
-
-<h4>Connecting to the directory</h4>
-
-<p>The realm's connection to the directory is defined by the
-<strong>connectionURL</strong> configuration attribute. This is a URL
-whose format is defined by the JNDI provider. It is usually an LDAP
-URL that specifies the domain name of the directory server to connect
-to, and optionally the port number and distinguished name (DN) of the
-required root naming context.</p>
-
-<p>If you have more than one provider you can configure an
-<strong>alternateURL</strong>. If a socket connection can not be
-made to the provider at the <strong>connectionURL</strong> an
-attempt will be made to use the <strong>alternateURL</strong>.</p>
-
-<p>When making a connection in order to search the directory and
-retrieve user and role information, the realm authenticates itself to
-the directory with the username and password specified by the
-<strong>connectionName</strong> and
-<strong>connectionPassword</strong> properties. If these properties
-are not specified the connection is anonymous. This is sufficient in
-many cases.
-</p>
-
-
-<h4>Selecting the user's directory entry</h4>
-
-<p>Each user that can be authenticated must be represented in the
-directory by an individual entry that corresponds to an element in the
-initial <code>DirContext</code> defined by the
-<strong>connectionURL</strong> attribute. This user entry must have an
-attribute containing the username that is presented for
-authentication.</p>
-
-<p>Often the distinguished name of the user's entry contains the
-username presented for authentication but is otherwise the same for
-all users. In this case the <strong>userPattern</strong> attribute may
-be used to specify the DN, with "{0}" marking where
-the username should be substituted.</p>
-
-<p>Otherwise the realm must search the directory to find a unique entry
-containing the username. The following attributes configure this
-search:
-
- <ul>
- <li><strong>userBase</strong> - the entry that is the base of
- the subtree containing users. If not specified, the search
- base is the top-level context.</li>
-
- <li><strong>userSubtree</strong> - the search scope. Set to
- <code>true</code> if you wish to search the entire subtree
- rooted at the <strong>userBase</strong> entry. The default value
- of <code>false</code> requests a single-level search
- including only the top level.</li>
-
- <li><strong>userSearch</strong> - pattern specifying the LDAP
- search filter to use after substitution of the username.</li>
-
- </ul>
-</p>
-
-
-<h4>Authenticating the user</h4>
-
-<ul>
-<li>
-<p><b>Bind mode</b></p>
-
-<p>By default the realm authenticates a user by binding to
-the directory with the DN of the entry for that user and the password
-presented by the user. If this simple bind succeeds the user is considered to
-be authenticated.</p>
-
-<p>For security reasons a directory may store a digest of the user's
-password rather than the clear text version (see <a href="#Digested
-Passwords">Digested Passwords</a> for more information). In that case,
-as part of the simple bind operation the directory automatically
-computes the correct digest of the plaintext password presented by the
-user before validating it against the stored value. In bind mode,
-therefore, the realm is not involved in digest processing. The
-<strong>digest</strong> attribute is not used, and will be ignored if
-set.</p>
-</li>
-
-<li>
-<p><b>Comparison mode</b></p>
-<p>Alternatively, the realm may retrieve the stored
-password from the directory and compare it explicitly with the value
-presented by the user. This mode is configured by setting the
-<strong>userPassword</strong> attribute to the name of a directory
-attribute in the user's entry that contains the password.</p>
-
-<p>Comparison mode has some disadvantages. First, the
-<strong>connectionName</strong> and
-<strong>connectionPassword</strong> attributes must be configured to
-allow the realm to read users' passwords in the directory. For
-security reasons this is generally undesirable; indeed many directory
-implementations will not allow even the directory manager to read
-these passwords. In addition, the realm must handle password digests
-itself, including variations in the algorithms used and ways of
-representing password hashes in the directory. However, the realm may
-sometimes need access to the stored password, for example to support
-HTTP Digest Access Authentication (RFC 2069). (Note that HTTP digest
-authentication is different from the storage of password digests in
-the repository for user information as discussed above).
-</p>
-</li>
-</ul>
-
-<h4>Assigning roles to the user</h4>
-
-<p>The directory realm supports two approaches to the representation
-of roles in the directory:</p>
-
-<ul>
-<li>
-<p><b>Roles as explicit directory entries</b></p>
-
-<p>Roles may be represented by explicit directory entries. A role
-entry is usually an LDAP group entry with one attribute
-containing the name of the role and another whose values are the
-distinguished names or usernames of the users in that role. The
-following attributes configure a directory search to
-find the names of roles associated with the authenticated user:</p>
-
-<ul>
-<li><strong>roleBase</strong> - the base entry for the role search.
- If not specified, the search base is the top-level directory
- context.</li>
-
-<li><strong>roleSubtree</strong> - the search
- scope. Set to <code>true</code> if you wish to search the entire
- subtree rooted at the <code>roleBase</code> entry. The default
- value of <code>false</code> requests a single-level search
- including the top level only.</li>
-
-<li><strong>roleSearch</strong> - the LDAP search filter for
- selecting role entries. It optionally includes pattern
- replacements "{0}" for the distinguished name and/or "{1}" for
the
- username of the authenticated user.</li>
-
-<li><strong>roleName</strong> - the attribute in a role entry
- containing the name of that role.</li>
-
-</ul>
-
-</li>
-</ul>
-
-<ul>
-<li>
-<p><b>Roles as an attribute of the user entry</b></p>
-
-<p>Role names may also be held as the values of an attribute in the
-user's directory entry. Use <strong>userRoleName</strong> to specify
-the name of this attribute.</p>
-
-</li>
-</ul>
-<p>A combination of both approaches to role representation may be used.</p>
-
-<h3>Quick Start</h3>
-
-<p>To set up JBoss Web to use JNDIRealm, you will need to follow these
steps:</p>
-<ol>
-<li>Make sure your directory server is configured with a schema that matches
- the requirements listed above.</li>
-<li>If required, configure a username and password for use by JBoss Web, that has
- read only access to the information described above. (JBoss Web will
- never attempt to modify this information.)</li>
-<li>Place a copy of the JNDI driver you will be using (typically
- <code>ldap.jar</code> available with JNDI) inside the
- <code>$CATALINA_HOME/lib</code> directory.</li>
-<li>Set up a <code><Realm></code> element, as described
below, in your
- <code>$CATALINA_HOME/conf/server.xml</code> file.</li>
-<li>Restart JBoss Web if it is already running.</li>
-</ol>
-
-<h3>Realm Element Attributes</h3>
-
-<p>To configure JNDIRealm, you will create a
<code><Realm></code>
-element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code>
file,
-as described <a href="#Configuring a Realm">above</a>. The
following
-attributes are supported by this implementation:</p>
-
-<attributes>
- <attribute name="className" required="true">
- <p>The fully qualified Java class name of this Realm implementation.
- You <strong>MUST</strong> specify the value
- "<code>org.apache.catalina.realm.JNDIRealm</code>"
here.</p>
- </attribute>
-
-
- <attribute name="connectionName" required="false">
- <p>The directory username to use when establishing a
- connection to the directory for LDAP search operations. If not
- specified an anonymous connection is made, which is often
- sufficient unless you specify the <code>userPassword</code>
- property.</p>
- </attribute>
-
- <attribute name="connectionPassword" required="false">
- <p>The directory password to use when establishing a
- connection to the directory for LDAP search operations. If not
- specified an anonymous connection is made, which is often
- sufficient unless you specify the <code>userPassword</code>
- property.</p>
- </attribute>
-
- <attribute name="connectionURL" required="true">
- <p>The connection URL to be passed to the JNDI driver when
- establishing a connection to the directory.</p>
- </attribute>
-
- <attribute name="contextFactory" required="false">
- <p>The fully qualified Java class name of the JNDI context
- factory to be used for this connection. By default, the standard
- JNDI LDAP provider is used
- (<code>com.sun.jndi.ldap.LdapCtxFactory</code>).</p>
- </attribute>
-
- <attribute name="digest" required="false">
- <p>The digest algorithm to apply to the plaintext password offered
- by the user before comparing it with the value retrieved from the
- directory. Valid values are those accepted for the algorithm name
- by the <code>java.security.MessageDigest</code> class. See <a
- href="#Digested Passwords">Digested Passwords</a> for more
- information. If not specified the plaintext password is assumed to
- be retrieved. Not required unless <code>userPassword</code> is
- specified</p>
- </attribute>
-
- <attribute name="roleBase" required="false">
- <p>The base directory entry for performing role searches. If
- not specified, the top level element in the directory context
- will be used.</p>
- </attribute>
-
- <attribute name="roleName" required="false">
- <p>The name of the attribute that contains role names in the
- directory entries found by a role search. In addition you can
- use the <code>userRoleName</code> property to specify the name
- of an attribute, in the user's entry, containing additional
- role names. If <code>roleName</code> is not specified a role
- search does not take place, and roles are taken only from the
- user's entry.</p>
- </attribute>
-
- <attribute name="roleSearch" required="false">
- <p>The LDAP filter expression used for performing role
- searches, following the syntax supported by the
- <code>java.text.MessageFormat</code> class. Use
- <code>{0}</code> to substitute the distinguished name (DN) of
- the user, and/or <code>{1}</code> to substitute the
- username. If not specified a role search does not take place
- and roles are taken only from the attribute in the user's
- entry specified by the <code>userRoleName</code> property.</p>
- </attribute>
-
- <attribute name="roleSubtree" required="false">
- <p>Set to <code>true</code> if you want to search the entire
- subtree of the element specified by the <code>roleBase</code>
- property for role entries associated with the user. The
- default value of <code>false</code> causes only the top level
- to be searched.</p>
- </attribute>
-
- <attribute name="userBase" required="false">
- <p>The base element for user searches performed using the
- <code>userSearch</code> expression. If not specified, the top
- level element in the directory context will be used. Not used
- if you are using the <code>userPattern</code> expression.</p>
- </attribute>
-
- <attribute name="userPassword" required="false">
- <p>Name of the attribute in the user's entry containing the
- user's password. If you specify this value, JNDIRealm will
- bind to the directory using the values specified by
- <code>connectionName</code> and
- <code>connectionPassword</code> properties, and retrieve the
- corresponding attribute for comparison to the value specified
- by the user being authenticated. If the <code>digest</code>
- attribute is set, the specified digest algorithm is applied to
- the password offered by the user before comparing it with the
- value retrieved from the directory. If you do
- <strong>not</strong> specify this value, JNDIRealm will
- attempt a simple bind to the directory using the DN of the
- user's entry and password specified by the user, with a
- successful bind being interpreted as an authenticated
- user.</p>
- </attribute>
-
- <attribute name="userPattern" required="false">
- <p>A pattern for the distinguished name (DN) of the user's
- directory entry, following the syntax supported by the
- <code>java.text.MessageFormat</code> class with
- <code>{0}</code> marking where the actual username should be
- inserted. You can use this property instead of
- <code>userSearch</code>, <code>userSubtree</code> and
- <code>userBase</code> when the distinguished name contains the
- username and is otherwise the same for all users.</p>
- </attribute>
-
- <attribute name="userRoleName" required="false">
- <p>The name of an attribute in the user's directory entry
- containing zero or more values for the names of roles assigned
- to this user. In addition you can use the
- <code>roleName</code> property to specify the name of an
- attribute to be retrieved from individual role entries found
- by searching the directory. If <code>userRoleName</code> is
- not specified all the roles for a user derive from the role
- search.</p>
- </attribute>
-
- <attribute name="userSearch" required="false">
- <p>The LDAP filter expression to use when searching for a
- user's directory entry, with <code>{0}</code> marking where
- the actual username should be inserted. Use this property
- (along with the <code>userBase</code> and
- <code>userSubtree</code> properties) instead of
- <code>userPattern</code> to search the directory for the
- user's entry.</p>
- </attribute>
-
- <attribute name="userSubtree" required="false">
- <p>Set to <code>true</code> if you want to search the entire
- subtree of the element specified by the <code>userBase</code>
- property for the user's entry. The default value of
- <code>false</code> causes only the top level to be searched.
- Not used if you are using the <code>userPattern</code>
- expression.</p>
- </attribute>
-
-</attributes>
-
-<h3>Example</h3>
-
-<p>Creation of the appropriate schema in your directory server is beyond the
-scope of this document, because it is unique to each directory server
-implementation. In the examples below, we will assume that you are using a
-distribution of the OpenLDAP directory server (version 2.0.11 or later), which
-can be downloaded from
-<a href="http://www.openldap.org">http://www.openldap.org</a>.
Assume that
-your <code>slapd.conf</code> file contains the following settings
-(among others):</p>
-<source>
-database ldbm
-suffix dc="mycompany",dc="com"
-rootdn "cn=Manager,dc=mycompany,dc=com"
-rootpw secret
-</source>
-
-<p>We will assume for <code>connectionURL</code> that the directory
-server runs on the same machine as JBoss Web. See <a
-href="http://java.sun.com/products/jndi/docs.html">http://java.sun.com/products/jndi/docs.html</a>
-for more information about configuring and using the JNDI LDAP
-provider.</p>
-
-<p>Next, assume that this directory server has been populated with elements
-as shown below (in LDIF format):</p>
-
-<source>
-
-# Define top-level entry
-dn: dc=mycompany,dc=com
-objectClass: dcObject
-dc:mycompany
-
-# Define an entry to contain people
-# searches for users are based on this entry
-dn: ou=people,dc=mycompany,dc=com
-objectClass: organizationalUnit
-ou: people
-
-# Define a user entry for Janet Jones
-dn: uid=jjones,ou=people,dc=mycompany,dc=com
-objectClass: inetOrgPerson
-uid: jjones
-sn: jones
-cn: janet jones
-mail: j.jones(a)mycompany.com
-userPassword: janet
-
-# Define a user entry for Fred Bloggs
-dn: uid=fbloggs,ou=people,dc=mycompany,dc=com
-objectClass: inetOrgPerson
-uid: fbloggs
-sn: bloggs
-cn: fred bloggs
-mail: f.bloggs(a)mycompany.com
-userPassword: fred
-
-# Define an entry to contain LDAP groups
-# searches for roles are based on this entry
-dn: ou=groups,dc=mycompany,dc=com
-objectClass: organizationalUnit
-ou: groups
-
-# Define an entry for the "tomcat" role
-dn: cn=tomcat,ou=groups,dc=mycompany,dc=com
-objectClass: groupOfUniqueNames
-cn: tomcat
-uniqueMember: uid=jjones,ou=people,dc=mycompany,dc=com
-uniqueMember: uid=fbloggs,ou=people,dc=mycompany,dc=com
-
-# Define an entry for the "role1" role
-dn: cn=role1,ou=groups,dc=mycompany,dc=com
-objectClass: groupOfUniqueNames
-cn: role1
-uniqueMember: uid=fbloggs,ou=people,dc=mycompany,dc=com
-</source>
-
-<p>An example <code>Realm</code> element for the OpenLDAP directory
-server configured as described above might look like this, assuming
-that users use their uid (e.g. jjones) to login to the
-application and that an anonymous connection is sufficient to search
-the directory and retrieve role information:</p>
-
-<source>
-<Realm className="org.apache.catalina.realm.JNDIRealm"
debug="99"
- connectionURL="ldap://localhost:389"
- userPattern="uid={0},ou=people,dc=mycompany,dc=com"
- roleBase="ou=groups,dc=mycompany,dc=com"
- roleName="cn"
- roleSearch="(uniqueMember={0})"
-/>
-</source>
-
-<p>With this configuration, the realm will determine the user's
-distinguished name by substituting the username into the
-<code>userPattern</code>, authenticate by binding to the directory
-with this DN and the password received from the user, and search the
-directory to find the user's roles.</p>
-
-<p>Now suppose that users are expected to enter their email address
-rather than their userid when logging in. In this case the realm must
-search the directory for the user's entry. (A search is also necessary
-when user entries are held in multiple subtrees corresponding perhaps
-to different organizational units or company locations).</p>
-
-<p>Further, suppose that in addition to the group entries you want to
-use an attribute of the user's entry to hold roles. Now the entry for
-Janet Jones might read as follows:</p>
-
-<source>
-dn: uid=jjones,ou=people,dc=mycompany,dc=com
-objectClass: inetOrgPerson
-uid: jjones
-sn: jones
-cn: janet jones
-mail: j.jones(a)mycompany.com
-memberOf: role2
-memberOf: role3
-userPassword: janet
-</source>
-
-<p> This realm configuration would satisfy the new requirements:</p>
-
-<source>
-<Realm className="org.apache.catalina.realm.JNDIRealm"
debug="99"
- connectionURL="ldap://localhost:389"
- userBase="ou=people,dc=mycompany,dc=com"
- userSearch="(mail={0})"
- userRoleName="memberOf"
- roleBase="ou=groups,dc=mycompany,dc=com"
- roleName="cn"
- roleSearch="(uniqueMember={0})"
-/>
-</source>
-
-<p>Now when Janet Jones logs in as "j.jones(a)mycompany.com", the realm
-searches the directory for a unique entry with that value as its mail
-attribute and attempts to bind to the directory as
-<code>uid=jjones,ou=people,dc=mycompany,dc=com</code> with the given
-password. If authentication succeeds, she is assigned three roles:
-"role2" and "role3", the values of the "memberOf" attribute
in her
-directory entry, and "tomcat", the value of the "cn" attribute in
the
-only group entry of which she is a member.</p>
-
-<p>Finally, to authenticate the user by retrieving
-the password from the directory and making a local comparison in the
-realm, you might use a realm configuration like this:</p>
-
-<source>
-<Realm className="org.apache.catalina.realm.JNDIRealm"
debug="99"
- connectionName="cn=Manager,dc=mycompany,dc=com"
-connectionPassword="secret"
- connectionURL="ldap://localhost:389"
- userPassword="userPassword"
- userPattern="uid={0},ou=people,dc=mycompany,dc=com"
- roleBase="ou=groups,dc=mycompany,dc=com"
- roleName="cn"
- roleSearch="(uniqueMember={0})"
-/>
-</source>
-
-<p>However, as discussed above, the default bind mode for
-authentication is usually to be preferred.</p>
-
-<h3>Additional Notes</h3>
-
-<p>JNDIRealm operates according to the following rules:</p>
-<ul>
-<li>When a user attempts to access a protected resource for the first time,
- JBoss Web will call the <code>authenticate()</code> method of this
- <code>Realm</code>. Thus, any changes you have made to the directory
- (new users, changed passwords or roles, etc.) will be immediately
- reflected.</li>
-<li>Once a user has been authenticated, the user (and his or her associated
- roles) are cached within JBoss Web for the duration of the user's login.
- (For FORM-based authentication, that means until the session times out or
- is invalidated; for BASIC authentication, that means until the user
- closes their browser). The cached user is <strong>not</strong> saved
and
- restored across sessions serialisations. Any changes to the directory
- information for an already authenticated user will <strong>not</strong>
be
- reflected until the next time that user logs on again.</li>
-<li>Administering the information in the directory server
- is the responsibility of your own applications. JBoss Web does not
- provide any built-in capabilities to maintain users and roles.</li>
-</ul>
-
-</subsection>
-
-
-<subsection name="MemoryRealm">
-
-<h3>Introduction</h3>
-
-<p><strong>MemoryRealm</strong> is a simple demonstration
implementation of the
-JBoss Web <code>Realm</code> interface. It is not designed for production
use.
-At startup time, MemoryRealm loads information about all users, and their
-corresponding roles, from an XML document (by default, this document is loaded from
<code>$CATALINA_HOME/conf/tomcat-users.xml</code>). Changes to the data
-in this file are not recognized until JBoss Web is restarted.</p>
-
-<h3>Realm Element Attributes</h3>
-
-<p>To configure MemoryRealm, you will create a
<code><Realm></code>
-element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code>
file,
-as described <a href="#Configuring a Realm">above</a>. The
following
-attributes are supported by this implementation:</p>
-
-<attributes>
-
- <attribute name="className" required="true">
- <p>The fully qualified Java class name of this Realm implementation.
- You <strong>MUST</strong> specify the value
- "<code>org.apache.catalina.realm.MemoryRealm</code>"
here.</p>
- </attribute>
-
- <attribute name="digest" required="false">
- <p>The digest algorithm used to store passwords in non-plaintext formats.
- Valid values are those accepted for the algorithm name by the
- <code>java.security.MessageDigest</code> class. See
- <a href="#Digested Passwords">Digested Passwords</a> for more
- information. If not specified, passwords are stored in clear text.</p>
- </attribute>
-
- <attribute name="pathname" required="false">
- <p>Absolute or relative (to $CATALINA_HOME) pathname of the XML document
- containing our valid usernames, passwords, and roles. See below for more
- information on the format of this file. If not specified, the value
- <code>conf/tomcat-users.xml</code> is used.</p>
- </attribute>
-
-</attributes>
-
-<h3>User File Format</h3>
-
-<p>The users file (by default, <code>conf/tomcat-users.xml</code> must
be an
-XML document, with a root element <code><tomcat-users></code>.
Nested
-inside the root element will be a <code><user></code> element
for each
-valid user, consisting of the following attributes:</p>
-<ul>
-<li><strong>name</strong> - Username this user must log on
with.</li>
-<li><strong>password</strong> - Password this user must log on with
(in
- clear text if the <code>digest</code> attribute was not set on the
- <code><Realm></code> element, or digested appropriately as
- described <a href="#Digested Passwords">here</a>
otherwise).</li>
-<li><strong>roles</strong> - Comma-delimited list of the role names
- associated with this user.</li>
-</ul>
-
-<h3>Example</h3>
-
-<p>The default installation of JBoss Web is configured with a MemoryRealm
-nested inside the <code><Engine></code> element, so that it
applies
-to all virtual hosts and web applications. The default contents of the
-<code>conf/tomcat-users.xml</code> file is:</p>
-<source>
-<tomcat-users>
- <user name="tomcat" password="tomcat"
roles="tomcat" />
- <user name="role1" password="tomcat"
roles="role1" />
- <user name="both" password="tomcat"
roles="tomcat,role1" />
-</tomcat-users>
-</source>
-
-<h3>Additional Notes</h3>
-
-<p>MemoryRealm operates according to the following rules:</p>
-<ul>
-<li>When JBoss Web first starts up, it loads all defined users and their
- associated information from the users file. Changes to the data in
- this file will <strong>not</strong> be recognized until JBoss Web is
- restarted.</li>
-<li>When a user attempts to access a protected resource for the first time,
- JBoss Web will call the <code>authenticate()</code> method of this
- <code>Realm</code>.</li>
-<li>Once a user has been authenticated, the user (and his or her associated
- roles) are cached within JBoss Web for the duration of the user's login.
- (For FORM-based authentication, that means until the session times out or
- is invalidated; for BASIC authentication, that means until the user
- closes their browser). The cached user is <strong>not</strong> saved
and
- restored across sessions serialisations.</li>
-<li>Administering the information in the users file is the responsibility
- of your application. JBoss Web does not
- provide any built-in capabilities to maintain users and roles.</li>
-</ul>
-
-
-</subsection>
-
-
-<subsection name="JAASRealm">
-
-<h3>Introduction</h3>
-
- <p><strong>JAASRealm</strong> is an implementation of the JBoss
Web
-4 <code>Realm</code> interface that authenticates users through the Java
-Authentication & Authorization Service (JAAS) framework, a Java
-package that is available as an optional package in Java 2 SDK 1.3 and
-is fully integrated as of SDK 1.4 .</p>
- <p>Using JAASRealm gives the developer the ability to combine
-practically any conceivable security realm with JBoss Web's CMA. </p>
- <p>JAASRealm is prototype for JBoss Web of the proposed JAAS-based
-J2EE authentication framework for J2EE v1.4, based on the <a
- href="http://www.jcp.org/en/jsr/detail?id=196">JCP Specification
-Request 196</a> to enhance container-managed security and promote
-'pluggable' authentication mechanisms whose implementations would be
-container-independent.
- </p>
- <p>Based on the JAAS login module and principal (see
<code>javax.security.auth.spi.LoginModule</code>
-and <code>javax.security.Principal</code>), you can develop your own
-security mechanism or wrap another third-party mechanism for
-integration with the CMA as implemented by JBoss Web.
- </p>
-
- <h3>Quick Start</h3>
- <p>To set up JBoss Web to use JAASRealm with your own JAAS login module,
- you will need to follow these steps:</p>
- <ol>
- <li>Write your own LoginModule, User and Role classes based
-on JAAS (see
-<a
href="http://java.sun.com/j2se/1.4.1/docs/guide/security/jaas/tutori...
-JAAS Authentication Tutorial</a> and
-<a
href="http://java.sun.com/j2se/1.4.1/docs/guide/security/jaas/JAASLM...
JAAS Login Module
-Developer's Guide</a>) to be managed by the JAAS Login
-Context (<code>javax.security.auth.login.LoginContext</code>)
-When developing your LoginModule, note that JAASRealm's built-in
<code>CallbackHandler</code>
-+only recognizes the <code>NameCallback</code> and
<code>PasswordCallback</code> at present.
- </li>
- <li>Although not specified in JAAS, you should create
-seperate classes to distinguish between users and roles, extending
<code>javax.security.Principal</code>,
-so that JBoss Web can tell which Principals returned from your login
-module are users and which are roles (see
<code>org.apache.catalina.realm.JAASRealm</code>).
-Regardless, the first Principal returned is <em>always</em> treated as the
user Principal.
- </li>
- <li>Place the compiled classes on JBoss Web's classpath
- </li>
- <li>Set up a login.config file for Java (see <a
-
href="http://java.sun.com/j2se/1.4.1/docs/guide/security/jaas/tutori...
-LoginConfig file</a>) and tell JBoss Web where to find it by specifying
-its location to the JVM, for instance by setting the environment
-variable:
<code>JAVA_OPTS=-DJAVA_OPTS=-Djava.security.auth.login.config==$CATALINA_HOME/conf/jaas.config</code></li>
-
- <li>Configure your security-constraints in your web.xml for
-the resources you want to protect</li>
- <li>Configure the JAASRealm module in your server.xml </li>
- <li>Restart JBoss Web if it is already running.</li>
- </ol>
- <h3>Realm Element Attributes</h3>
- <p>To configure JAASRealm as for step 6 above, you create
-a <code><Realm></code> element and nest it in your
-<code>$CATALINA_HOME/conf/server.xml</code>
-file within your <code><Engine></code> node. The following
attributes
-are supported by this implementation:</p>
-
-<attributes>
-
- <attribute name="className" required="true">
- <p>The fully qualified Java class name of this Realm implementation.
- You <strong>MUST</strong> specify the value
- "<code>org.apache.catalina.realm.JAASRealm</code>"
here.</p>
- </attribute>
-
- <attribute name="appName" required="true">
- <p>The name of the application as configured in your login configuration file
- (<a
href="http://java.sun.com/j2se/1.4.1/docs/guide/security/jaas/tutori...
LoginConfig</a>).</p>
- </attribute>
-
- <attribute name="userClassNames" required="true">
- <p>A comma-seperated list of the names of the classes that you have made
- for your user <code>Principals</code>.</p>
- </attribute>
-
- <attribute name="roleClassNames" required="false">
- <p>A comma-seperated list of the names of the classes that you have made
- for your role <code>Principals</code>.</p>
- </attribute>
-
- <attribute name="useContextClassLoader" required="false">
- <p>Instructs JAASRealm to use the context class loader for loading the
user-specified
- <code>LoginModule</code> class and associated
<code>Principal</code> classes. The
- default value is <code>true</code>, which is backwards-compatible with
the way
- Tomcat 4 works. To load classes using the container's classloader, specify
- <code>false</code>.</p>
- </attribute>
-
-</attributes>
-
-<h3>Example</h3>
-
-<p>Here is an example of how your server.xml snippet should look.</p>
-
-<source>
-<Realm className="org.apache.catalina.realm.JAASRealm"
- appName="MyFooRealm"
- userClassNames="org.foobar.realm.FooUser"
- roleClassNames="org.foobar.realm.FooRole"
- debug="99"/>
-</source>
-
-<p>It is the responsibility of your login module to create and save User and
-Role objects representing Principals for the user
-(<code>javax.security.auth.Subject</code>). If your login module doesn't
-create a user object but also doesn't throw a login exception, then the
-JBoss Web CMA will break and you will be left at the
-http://localhost:8080/myapp/j_security_check URI or at some other
-unspecified location.</p>
-
- <p>The flexibility of the JAAS approach is two-fold: </p>
- <ul>
- <li>you can carry out whatever processing you require behind
-the scenes in your own login module.</li>
- <li>you can plug in a completely different LoginModule by changing the
configuration
-and restarting the server, without any code changes to your application.</li>
- </ul>
-
- <h3>Additional Notes</h3>
- <ul>
- <li>When a user attempts to access a protected resource for
- the first time, JBoss Web will call the
<code>authenticate()</code>
- method of this <code>Realm</code>. Thus, any changes you have
made in
- the security mechanism directly (new users, changed passwords or
- roles, etc.) will be immediately reflected.</li>
- <li>Once a user has been authenticated, the user (and his or
- her associated roles) are cached within JBoss Web for the duration of
- the user's login. For FORM-based authentication, that means until
- the session times out or is invalidated; for BASIC authentication,
- that means until the user closes their browser. Any changes to the
- security information for an already authenticated user will
<strong>not</strong>
- be reflected until the next time that user logs on again.</li>
- <li>As with other <code>Realm</code> implementations,
digested passwords
- are supported if the <code><Realm></code> element
in <code>server.xml</code>
- contains a <code>digest</code> attribute; JAASRealm's
<code>CallbackHandler</code>
- will digest the password prior to passing it back to the
<code>LoginModule</code></li>
- </ul>
-
-</subsection>
-
-
-<subsection name="CombinedRealm">
-
- <h3>Introduction</h3>
-
- <p><strong>CombinedRealm</strong> is an implementation of the
- <code>Realm</code> interface that authenticates users through one or
more
- sub-Realms.</p>
-
- <p>Using CombinedRealm gives the developer the ability to combine multiple
- Realms of the same or different types. This can be used to authenticate
- against different sources, provide fall back in case one Realm fails or for
- any other purpose that requires multiple Realms.</p>
-
- <p>Sub-realms are defined by nesting <code>Realm</code> elements
inside the
- <code>Realm</code> element that defines the CombinedRealm.
Authentication
- will be attempted against each <code>Realm</code> in the order they are
- listed. Authentication against any Realm will be sufficient to authenticate
- the user.</p>
-
- <h3>Realm Element Attributes</h3>
- <p>To configure CombinedRealm, you create a
<code><Realm></code>
- element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code>
- file within your <code><Engine></code> or
<code><Host></code>.
- You can also nest inside a <code><Context></code> node in
a
- <code>context.xml</code> file. The following attributes are supported by
- this implementation:</p>
-
-<attributes>
-
- <attribute name="className" required="true">
- <p>The fully qualified Java class name of this Realm implementation.
- You <strong>MUST</strong> specify the value
- "<code>org.apache.catalina.realm.CombinedRealm</code>"
here.</p>
- </attribute>
-
-</attributes>
-
-<h3>Example</h3>
-
-<p>Here is an example of how your server.xml snippet should look to use a
-UserDatabase Realm and a DataSource Realm.</p>
-
-<source>
-<Realm className="org.apache.catalina.realm.CombinedRealm" >
- <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
- resourceName="UserDatabase"/>
- <Realm className="org.apache.catalina.realm.DataSourceRealm"
debug="99"
- dataSourceName="jdbc/authority"
- userTable="users" userNameCol="user_name"
userCredCol="user_pass"
- userRoleTable="user_roles"
roleNameCol="role_name"/>
-<Realm/>
-</source>
-
-</subsection>
-
-</section>
-
-</body>
-
-</document>
Deleted: trunk/webapps/docs/ssi-howto.xml
===================================================================
--- trunk/webapps/docs/ssi-howto.xml 2011-09-08 14:43:49 UTC (rev 1831)
+++ trunk/webapps/docs/ssi-howto.xml 2011-09-08 16:06:13 UTC (rev 1832)
@@ -1,375 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE document [
- <!ENTITY project SYSTEM "project.xml">
-]>
-<document url="ssi-howto.html">
-
-&project;
-
-<properties>
-<author email="glenn(a)apache.org">Glenn L. Nielsen</author>
-<title>SSI How To</title>
-</properties>
-
-<body>
-
-<section name="Introduction">
-
-<p>SSI (Server Side Includes) are directives that are placed in HTML pages,
-and evaluated on the server while the pages are being served. They let you
-add dynamically generated content to an existing HTML page, without having
-to serve the entire page via a CGI program, or other dynamic technology.
-</p>
-
-<p>Within JBoss Web SSI support can be added when using JBoss Web as your
-HTTP server and you require SSI support. Typically this is done
-during development when you don't want to run a web server like Apache.</p>
-
-<p>JBoss Web SSI support implements the same SSI directives as Apache. See the
-<a
href="http://httpd.apache.org/docs/howto/ssi.html#basicssidirectives...
-Apache Introduction to SSI</a> for information on using SSI directives.</p>
-
-<p>SSI support is available as a servlet and as a filter. You should use one
-or the other to provide SSI support but not both.</p>
-
-<p>Servlet based SSI support is implemented using the class
-<code>org.apache.catalina.ssi.SSIServlet</code>. Traditionally, this
servlet
-is mapped to the URL pattern "*.shtml".</p>
-
-<p>Filter based SSI support is implemented using the class
-<code>org.apache.catalina.ssi.SSIFilter</code>. Traditionally, this filter
-is mapped to the URL pattern "*.shtml", though it can be mapped to
"*" as
-it will selectively enable/disable SSI processing based on mime types. The
-contentType init param allows you to apply SSI processing to JSP pages,
-javascript, or any other content you wish.</p>
-<p>By default SSI support is disabled in JBoss Web.</p>
-</section>
-
-<section name="Installation">
-
-<p><strong>CAUTION</strong> - SSI directives can be used to execute
programs
-external to the JBoss Web JVM. If you are using the Java SecurityManager this
-will bypass your security policy configuration in
<code>catalina.policy.</code>
-</p>
-
-<p>To use the SSI servlet, remove the XML comments from around the SSI servlet
-and servlet-mapping configuration in
-<code>$CATALINA_BASE/conf/web.xml</code>.</p>
-
-<p>To use the SSI filter, remove the XML comments from around the SSI filter
-and filter-mapping configuration in
-<code>$CATALINA_BASE/conf/web.xml</code>.</p>
-
-<p>Only Contexts which are marked as privileged may use SSI features (see the
-privileged property of the Context element).</p>
-
-</section>
-
-<section name="Servlet Configuration">
-
-<p>There are several servlet init parameters which can be used to
-configure the behaviour of the SSI servlet.
-<ul>
-<li><strong>buffered</strong> - Should output from this servlet be
buffered?
-(0=false, 1=true) Default 0 (false).</li>
-<li><strong>debug</strong> - Debugging detail level for messages
logged
-by this servlet. Default 0.</li>
-<li><strong>expires</strong> - The number of seconds before a page with
SSI
-directives will expire. Default behaviour is for all SSI directives to be
-evaluated for every request.</li>
-<li><strong>isVirtualWebappRelative</strong> - Should
"virtual" SSI directive
-paths be interpreted as relative to the context root, instead of the server
-root? (0=false, 1=true) Default 0 (false).</li>
-<li><strong>inputEncoding</strong> - The encoding to be assumed for
SSI
-resources if one cannot be determined from the resource itself. Default is
-the default platform encoding.</li>
-<li><strong>outputEncoding</strong> - The encoding to be used for the
result
-of the SSI processing. Default is UTF-8.</li>
-<li><strong>allowExec</strong> - Allow SSI exec. Default is
false.</li>
-</ul>
-</p>
-
-</section>
-
-<section name="Filter Configuration">
-
-<p>There are several filter init parameters which can be used to
-configure the behaviour of the SSI filter.
-<ul>
-<li><strong>contentType</strong> - A regex pattern that must be matched
before
-SSI processing is applied. When crafting your own pattern, don't forget that a
-mime content type may be followed by an optional character set in the form
-"mime/type; charset=set" that you must take into account. Default is
-"text/x-server-parsed-html(;.*)?".</li>
-<li><strong>debug</strong> - Debugging detail level for messages
logged
-by this servlet. Default 0.</li>
-<li><strong>expires</strong> - The number of seconds before a page with
SSI
-directives will expire. Default behaviour is for all SSI directives to be
-evaluated for every request.</li>
-<li><strong>isVirtualWebappRelative</strong> - Should
"virtual" SSI directive
-paths be interpreted as relative to the context root, instead of the server
-root? (0=false, 1=true) Default 0 (false).</li>
-<li><strong>allowExec</strong> - Allow SSI exec. Default is
false.</li>
-</ul>
-</p>
-
-</section>
-
-<section name="Directives">
-<p>Server Side Includes are invoked by embedding SSI directives in an HTML
document
- whose type will be processed by the SSI servlet. The directives take the form of an
HTML
- comment. The directive is replaced by the results of interpreting it before sending the
- page to the client. The general form of a directive is: </p>
-<p> <code><!--#directive [parm=value]
--></code></p>
-<p>The directives are:
-<ul>
-<li>
-<strong>config</strong> - <code><!--#config timefmt="%B
%Y" --></code>
-Used to set the format of dates and other items processed by SSI
-</li>
-<li>
-<strong>echo</strong> - <code><!--#echo
var="VARIABLE_NAME" --></code>
-will be replaced bt the value of the variable.
-</li>
-<li>
-<strong>exec</strong> - Used to run commands on the host system.
-</li>
-<li>
-<strong>include</strong> - <code><!--#include
virtual="file-name" --></code>
-inserts the contents
-</li>
-<li>
-<strong>flastmod</strong> - <code><!--#flastmod
file="filename.shtml" --></code>
-Returns the time that a file was lost modified.
-</li>
-<li>
-<strong>fsize</strong> - <code><!--#fsize
file="filename.shtml" --></code>
-Returns the size of a file.
-</li>
-<li>
-<strong>printenv</strong> - <code><!--#printenv
--></code>
-Returns the list of all the defined variables.
-</li>
-<li>
-<strong>set</strong> - <code><!--#set var="foo"
value="Bar" --></code>
-is used to assign a value to a user-defind variable.
-</li>
-<li>
-<strong>if elif endif else</strong> - Used to create conditional sections.
For example:</li>
-<code><!--#config timefmt="%A" --><br />
- <!--#if expr="$DATE_LOCAL = /Monday/" --><br />
- <p>Meeting at 10:00 on Mondays</p><br />
- <!--#elif expr="$DATE_LOCAL = /Friday/" --><br />
- <p>Turn in your time card</p><br />
- <!--#else --><br />
- <p>Yoga class at noon.</p><br />
- <!--#endif --></code>
- </ul>
-</p>
-See the
-<p> <a
href="http://httpd.apache.org/docs/howto/ssi.html#basicssidirectives...
-Apache Introduction to SSI</a> for more information on using SSI
directives.</p>
-</section>
-
-<section name="Variables">
-<p>The SSI servlet currently implements the following variables:
-</p>
-<table border="1">
-<tr>
-<th>Variable Name</th>
-<th>Description</th>
-</tr>
-
-<tr>
-<td>AUTH_TYPE</td>
-<td>
- The type of authentication used for this user: BASIC, FORM, etc.</td>
-</tr>
-
-<tr>
-<td>CONTENT_LENGTH</td>
-<td>
- The length of the data (in bytes or the number of
- characters) passed from a form.</td>
-</tr>
-
-<tr>
-<td>CONTENT_TYPE</td>
-<td>
- The MIME type of the query data, such as "text/html".</td>
-</tr>
-
-<tr>
-<td>DATE_GMT</td>
-<td>
-Current date and time in GMT</td>
-</tr>
-
-<tr>
-<td>DATE_LOCAL</td>
-<td>
-Current date and time in the local time zone</td>
-</tr>
-<tr>
-<td>DOCUMENT_NAME</td>
-<td>
-The current file</td>
-</tr>
-<tr>
-<td>DOCUMENT_URI</td>
-<td>
-Virtual path to the file</td>
-</tr>
-
-<tr>
-<td>GATEWAY_INTERFACE</td>
-<td>
- The revision of the Common Gateway Interface that the
- server uses if enabled: "CGI/1.1".</td>
-</tr>
-
-<tr>
-<td>HTTP_ACCEPT</td>
-<td>
- A list of the MIME types that the client can accept.</td>
-</tr>
-
-<tr>
-<td>HTTP_ACCEPT_ENCODING</td>
-<td>
- A list of the compression types that the client can accept.</td>
-</tr>
-
-<tr>
-<td>HTTP_ACCEPT_LANGUAGE</td>
-<td>
- A list of the laguages that the client can accept.</td>
-</tr>
-<tr>
-<td>HTTP_CONNECTION</td>
-<td>
- The way that the connection from the client is being managed:
- "Close" or "Keep-Alive".</td>
-</tr>
-<tr>
-<td>HTTP_HOST</td>
-<td>
- The web site that the client requested.</td>
-</tr>
-<tr>
-<td>HTTP_REFERER</td>
-<td>
- The URL of the document that the client linked from.</td>
-</tr>
-<tr>
-<td>HTTP_USER_AGENT</td>
-<td>
- The browser the client is using to issue the request.</td>
-</tr>
-<tr>
-<td>LAST_MODIFIED</td>
-<td>
-Last modification date and time for current file</td>
-</tr>
-<tr>
-<td>PATH_INFO</td>
-<td>
- Extra path information passed to a servlet.</td>
-</tr>
-<tr>
-<td>PATH_TRANSLATED</td>
-<td>
- The translated version of the path given by the
- variable PATH_INFO.</td>
-</tr>
-<tr>
-<td>QUERY_STRING</td>
-<td>
-The query string that follows the "?" in the URL.
-</td>
-</tr>
-<tr>
-<td>QUERY_STRING_UNESCAPED</td>
-<td>
-Undecoded query string with all shell metacharacters escaped
-with "\"</td>
-</tr>
-<tr>
-<td>REMOTE_ADDR</td>
-<td>
- The remote IP address of the user making the request.</td>
-</tr>
-<tr>
-<td>REMOTE_HOST</td>
-<td>
- The remote hostname of the user making the request.</td>
-</tr>
-<tr>
-<td>REMOTE_PORT</td>
-<td>
- The port number at remote IP address of the user making the request.</td>
-</tr>
-<tr>
-<td>REMOTE_USER</td>
-<td>
- The authenticated name of the user.</td>
-</tr>
-<tr>
-<td>REQUEST_METHOD</td>
-<td>
- The method with which the information request was
- issued: "GET", "POST" etc.</td>
-</tr>
-<tr>
-<td>REQUEST_URI</td>
-<td>
- The web page originally requested by the client.</td>
-</tr>
-<tr>
-<td>SCRIPT_FILENAME</td>
-<td>
- The location of the current web page on the server.</td>
-</tr>
-<tr>
-<td>SCRIPT_NAME</td>
-<td>
- The name of the web page.</td>
-</tr>
-<tr>
-<td>SERVER_ADDR</td>
-<td>
- The server's IP address.</td>
-</tr>
-<tr>
-<td>SERVER_NAME</td>
-<td>
- The server's hostname or IP address.</td>
-</tr>
-<tr>
-<td>SERVER_PORT</td>
-<td>
- The port on which the server received the request.</td>
-</tr>
-<tr>
-<td>SERVER_PROTOCOL</td>
-<td>
- The protocol used by the server. E.g. "HTTP/1.1".</td>
-</tr>
-<tr>
-<td>SERVER_SOFTWARE</td>
-<td>
- The name and version of the server software that is
- answering the client request.</td>
-</tr>
-<tr>
-<td>UNIQUE_ID</td>
-<td>
- A token used to identify the current session if one
- has been established.</td>
-</tr>
-</table>
-</section>
-
-</body>
-
-</document>
5333
days inactive
5333
days old
jbossweb-commits@lists.jboss.org
0 comments
1 participants
participants (1)
-
jbossweb-commits＠lists.jboss.org