Home TOC Index

Configuring Services

Service elements are nested with the Server element. The Service element represents the combination of one or more Connector components that share a single engine component for processing incoming requests. The default configuration for Tomcat includes an Internal Service and a Java Web Services Developer Pack Service.

• The Internal Service uses port 8081. This service is used internally by the Tomcat Web applications such as JAXM provider and JAXM provideradmin contexts. These contexts are used by the JAXM Web applications contexts in the JWSDP Service.
• The Java Web Services Developer Pack Service uses port 8080, the standard port on which users can deploy their Web applications. For Java Servlet and JSP pages developers, this is the service to use.

It is possible to use admintool to add other services, which might use a different port. To create a new service,

1. Select Tomcat Server in the left pane.
2. Select Create New Service from the drop-down list in the right pane.
3. Enter the values for Service Name, Engine Name, Debug Level, and Default Hostname.

   The Service Name is the display name of this Service, which will be included in log messages if you choose a Logger (see Configuring Logger Elements).

---

Note: The name of each Service associated with a particular Server must be unique.

---

For each Service element defined, you can create or delete the following elements:

• Connector elements represent the interface between the Service and external clients that send requests to it and receive responses from it. See Configuring Connector Elements for more information.
• Host elements represent a virtual host, which is an association of a network name for a server (such as www.mycompany.com) with the particular server on which Tomcat is running. See Configuring Host Elements for more information.
• Logger elements represent a destination for logging, debugging, and error messages (including stack tracebacks) for Tomcat (Engine, Host, or Context). See Configuring Logger Elements for more information.
• User Realm elements represent a database of user names, passwords, and roles assigned to those users. See Configuring Realm Elements for more information.
• Valve elements represent a component that will be inserted into the request processing pipeline for the associated container (Engine, Host, or Context). See Configuring Valve Elements for more information.

Configuring Connector Elements

A Connector elements represent the interface between external clients sending requests to (and receiving responses from) a particular Service.

To edit a connector,

1. Expand the Service element in the left pane.
2. Select the Connector to edit.
3. Edit the values in the right pane.
4. Select Save to save the changes for this session. Select Commit Changes to save the changes for when Tomcat is restarted.

To create a new connector for a service,

1. Select the Service element in the left pane. It is highly recommended that you only modify the Java Web Services Developer Pack Service, or a service that you have created.
2. Select Create New Connector from the Available Actions list.
3. Enter the preferred values for the Connector. See Connector Attributes for more information on the options.
4. Select Save to save the changes for this session. Select Commit Changes to save the changes for when Tomcat is restarted.

To learn more about Connectors, read the documents titled Coyote HTTP/1.1 Connectors at <JWSDP_HOME>/docs/tomcat/config/coyote.html or the document titled JK 2 Connectors at <JWSDP_HOME>/docs/tomcat/config/jk2.html.

Types of Connectors

Using admintool, you can create the following types of Connectors:

• HTTP

  Selecting HTTP enables you to create a Connector component that supports the HTTP/1.1 protocol. It enables Tomcat to function as a stand-alone Web server, in addition to its ability to execute Java Servlets and JSP pages. A particular instance of this component listens for connections on a specific TCP port number on the server. One or more such Connectors can be configured as part of a single Service, each forwarding to the associated Engine to perform request processing and create the response.

• HTTPS

  Selecting HTTPS enables you to create an SSL HTTP/1.1 Connector. Secure Socket Layer (SSL) technology enables Web browsers and Web servers to communicate over a secure connection. In order to implement SSL, a Web server must have an associated keystore certificate for each external interface (IP address) that accepts secure connections. Installing and Configuring SSL Support on Tomcat contains detailed instructions on setting up an HTTPS connector.

• AJP

  Selecting AJP enables you to create a Connector component that communicates with a Web connector via the Apache JServ Protocol ("AJP"). This is used for cases where you wish to invisibly integrate Tomcat into an existing (or new) Apache installation, and you want Apache to handle the static content contained in the Web application, and/or utilize Apache's SSL processing. In many application environments, this will result in better overall performance than running your applications under Tomcat stand-alone using the HTTP/1.1 Connector. However, the only way to know for sure whether it will provide better performance for your application is to try it both ways.

Connector Attributes

When you create or modify any type of Connector, the attributes shown in Table A-3 may be set, as needed.

Table A-3 Common Connector Attributes 

Attribute	Description
Accept Count	The maximum queue length for incoming connection requests when all possible request processing threads are in use. Any requests received when the queue is full will be refused. The default value is 10.
Connection Timeout	The number of milliseconds this Connector will wait, after accepting a connection, for the request URI line to be presented. The default value is 60000 (i.e. 60 seconds).
Debug Level	The debugging detail level of log messages generated by this component, with higher numbers creating more detailed output. If not specified, this attribute is set to zero (0).
Default Buffer Size	The size (in bytes) of the buffer to be provided for input streams created by this connector. By default, buffers of 2048 bytes will be provided.
Enable DNS Lookups	Whether or not you want calls to request.getRemoteHost() to perform DNS lookups in order to return the actual host name of the remote client. Set to True if you want calls to request.getRemoteHost() to perform DNS lookups in order to return the actual host name of the remote client. Set to False to skip the DNS lookup and return the IP address in String form instead (thereby improving performance).
IP Address	Specifies which address will be used for listening on the specified port, for servers with more than one IP address. By default, this port will be used on all IP addresses associated with the server.
Port Number	The TCP port number on which this Connector will create a server socket and await incoming connections. Your operating system will allow only one server application to listen to a particular port number on a particular IP address.
Redirect Port Number	The port number where Tomcat will automatically redirect the request if this Connector is supporting non-SSL requests, and a request is received for which a matching security constraint requires SSL transport.
Minimum	The number of request processing threads that will be created when this Connector is first started. This attribute should be set to a value smaller than that set for Maximum. The default value is 5.
Maximum	The maximum number of request processing threads to be created by this Connector, which therefore determines the maximum number of simultaneous requests that can be handled. If not specified, this attribute is set to 75.

When the Connector is of type HTTP or HTTPS, additional attributes are also available, as shown in Table A-4.

Table A-4 Attributes of HTTP/HTTPS Connectors 

Attribute	Description
Proxy Name	The server name to be returned for calls to request.getServerName() if this Connector is being used in a proxy configuration.
Proxy Port Number	The server port to be returned for calls to request.getServerPort() if this Connector is being used in a proxy configuration.

When the type of Connector is HTTPS, additional attributes as outlined in Table A-5 may also be set.

Table A-5 HTTPS Attributes 

Attribute	Description
Client Authentication	Whether or not you want the SSL stack to require a valid certificate chain from the client before accepting a connection. Set to True if you want the SSL stack to require a valid certificate chain from the client before accepting a connection. A False value (which is the default) will not require a certificate chain unless the client requests a resource protected by a security constraint that uses client-certificate authentication.
Keystore Filename	The path to and name of the keystore file where you have stored the server certificate to be loaded. By default, the file name is .keystore and the path name is the operating system home directory of the user that is running Tomcat. If you are using default values for the file name and path, you can leave this field blank. If you specify a keystore file name without specifying a path, admintool looks for the file in the <JWSDP_HOME> directory.
Keystore Password	The password used to access the server certificate from the specified keystore file. The default value is changeit.

---

Note: In order to use an SSL connector, you must use keytool to generate a keystore file. If you have generated a keystore file with the default name (.keystore) in the default directory (the operating system home directory of the user that is running Tomcat) with default password (changeit), you can leave the Keystore Filename and Keystore Password attributes empty when creating an SSL Connector. When the two properties are left empty, admintool will look for the keystore file with the default name (.keystore) and the default password (changeit) in the default location (the operating system home directory of the user that is running Tomcat). If you specify a keystore file name without specifying a path, admintool looks for the file in the <JWSDP_HOME> directory. Installing and Configuring SSL Support on Tomcat contains detailed instructions on setting up an HTTPS connector.

---

Configuring Host Elements

The Host element represents a virtual host, which is an association of a network name for a server (such as www.mycompany.com) with the particular server on which Tomcat is running. In order to be effective, this name must be registered in the Domain Name Service (DNS) server that manages the Internet domain to which you belong.

In many cases, system administrators wish to associate more than one network name (such as www.mycompany.com and company.com) with the same virtual host and applications. This can be accomplished using the Host Name Aliases feature described in Host Name Aliases.

One or more Host elements are nested inside a Service. Exactly one of the Hosts associated with each Service MUST have a name matching the defaultHost attribute of that Service. Inside the Host element, you can nest any of the following elements:

• Context elements, which are discussed in Configuring Context Elements.
• Logger Elements, which are discussed in Configuring Logger Elements.
• Valve Elements, which are discussed in Configuring Valve Elements.
• Host Aliases, which are discussed in Host Name Aliases.

To edit a Host,

1. Expand the Service element in the left pane.
2. Expand the Host element in the left pane.
3. Select the Host, or any of its Contexts, Valves, Loggers, or Aliases, to edit.
4. Edit the values in the right pane.
5. Select Save to save the changes for this session. Select Commit Changes to save the changes for when Tomcat is restarted.

To create a new Host for a service,

1. Select the Service element in the left pane. It is highly recommended that you only modify the Java Web Services Developer Pack Service, or a service that you have created.
2. Select Create New Host from the Available Actions list.
3. Enter the preferred values for the Host. See Host Attributes for more information on the options.
4. Select Save to save the changes for this session. Select Commit Changes to save the changes for when Tomcat is restarted.

To learn more about Hosts, read the document titled "Host Container" at <JWSDP_HOME>/docs/tomcat/config/host.html.

Host Attributes

The attributes shown in Table A-6 may be viewed, set, or modified for a Host.

Table A-6 Host Attributes 

Attribute	Description
Name	The network name of this virtual host, as registered in your Domain Name Service server. One of the Hosts nested within an Engine MUST have a name that matches the defaultHost setting for that Engine.
Application Base	The Application Base directory for this virtual host. This is the path name of a directory that may contain Web applications to be deployed on this virtual host. You may specify an absolute path name for this directory, or a path name that is relative to the directory under which Tomcat is installed.
Debug Level	The level of debugging detail logged by this Engine to the associated Logger. Higher numbers generate more detailed output. If not specified, the default debugging detail level is zero (0).
Unpack WARs	Whether or not you want Web applications that are deployed into this virtual host from a Web Application Archive (WAR) file to be unpacked into a disk directory structure. Set to True if you want Web applications that are deployed into this virtual host from a Web Application Archive (WAR) file to be unpacked into a disk directory structure or False to run the application directly from a WAR file. The default value is False.

Host Name Aliases

In many server environments, Network Administrators have configured more than one network name (in the Domain Name Service (DNS) server) that resolve to the IP address of the same server. Normally, each such network name would be configured as a separate Host element with its own set of Web applications.

However, in some circumstances it is desirable for two or more network names to resolve to the same virtual host, running the same set of applications. A common use case for this scenario is a corporate Web site where users should be able to utilize either www.mycompany.com or company.com to access exactly the same content and applications.

Tomcat supports virtual hosts, which are multiple "hosts + domain names" mapped to a single IP. Usually, each host name is mapped to a host in Tomcat, for example, www.foo.com is mapped to localhost, or www.foo1.com is mapped to localhost1. In some cases, various host names can be mapped to the same host, for example www.foo.com and www.foo1.com can both be mapped to localhost. In this situation, you will see both of these aliases listed under localhost in admintool.

To use Host Aliases, the DNS server must have the host names registered to the IP of the server on which Tomcat will be running.

To create a new Host alias,

1. Select the Host element in the left pane.
2. Select Create New Alias from the Available Actions list.
3. Enter the name for the Alias.
4. Select Save to save the changes for this session. Select Commit Changes to save the changes for when Tomcat is restarted.

Configuring Context Elements

The Context element represents a Web application that is run within a particular virtual host. Each Web application is based on a Web Application Archive (WAR) file or a directory containing the Web application in its unpacked form. For more information about WAR files, see Web Application Archives.

When an HTTP request is received, Tomcat selects the Web application that will be used to process the request. To select the Web application, Tomcat matches the longest prefix of the Request URI against the context path of each defined Context. Once a Context is selected, it selects an appropriate Servlet to process the incoming request, based on the Servlet mappings defined in the Web application deployment descriptor, which must be located at <web_app_root>/WEB-INF/web.xml.

You can define as many Context elements within a Host element as you wish, but each must have a unique context path. At least one Context must include a context path equal to a zero-length string. This Context becomes the default Web application for this virtual host and is used to process all requests that do not match any other Context's context path.

To edit a Context,

1. Expand the Service element in the left pane.
2. Expand the Host element in the left pane.
3. Select the Context to edit.
4. Edit the values in the right pane.
5. Select Save to save the changes for this session. Select Commit Changes to save the changes for when Tomcat is restarted.

To create a new Context for a service,

1. Select the Service element in the left pane.
2. Select the Host element in the left pane to which you want to add the Context.
3. Select Create New Context from the Available Actions list.
4. Enter the preferred values for the Context. See Context Attributes for more information on the options.
5. Select Save to save the changes for this session. Select Commit Changes to save the changes for when Tomcat is restarted.

To learn more about Contexts, read the document titled "The Context Container" at <JWSDP_HOME>/docs/tomcat/config/context.html.

Context Attributes

The Context element page contains three types of properties:

• Context Properties, described in Table A-7.
• Loader Properties, described in Table A-8.
• Session Manager Properties, described in Table A-9.

The attributes shown in Table A-7 may be viewed, set, or modified for Context properties.

Table A-7 Context Properties

Attribute	Description
Cookies	Set to True if you want cookies to be used for session identifier communication if supported by the client. Set to False if you want to disable the use of cookies for session identifier communication and rely only on URL rewriting by the application. The default value is True.
Cross Context	Set to True if you want calls to ServletContext.getContext() within this application to successfully return a request dispatcher for other Web applications running on this virtual host. Set to False in security-conscious environment to make getContext() always return null. The default value is False.
Debug Level	The level of debugging detail logged by this Engine to the associated Logger. Higher numbers generate more detailed output. If not specified, the default debugging detail level is zero (0).
Document Base	The Document Base (also known as the Context Root) directory for this Web application is the path to the Web Application Archive file (if this Web application is being executed directly from the WAR file). You may specify an absolute path name for this directory or WAR file, or a path name that is relative to the application base directory of the owning Host.
Override	Set to True to have explicit settings in this Context element override any corresponding settings in the DefaultContext element associated with our owning Host. By default, settings in the DefaultContext element will be used.The default value is False.
Path	The context path of this Web application, which is matched against the beginning of each request URI to select the appropriate Web application for processing. All of the context paths within a particular Host must be unique. If you specify a context path of an empty string (""), you are defining the default Web application for this Host, which will process all requests not assigned to other Contexts.
Reloadable	Set to True if you want Tomcat to monitor classes in /WEB-INF/classes/ and /WEB-INF/lib for changes and automatically reload the Web application if a change is detected. This feature is very useful during application development, but it requires significant runtime overhead and is not recommended for use on deployed production applications. You can use the Manager Web application to trigger reloads of deployed applications on demand. The default value is False.
Use Naming	Set to True to have Tomcat enable a JNDI InitialContext for this Web application that is compatible with Java2 Enterprise Edition (J2EE) platform conventions.The default value is False.
Working Directory	Path to a scratch directory to be for temporary read-write use by Servlets within the associated Web application. This directory will be made visible to Servlets in the Web application by a Servlet context attribute (of type java.io.File) named javax.servlet.context.tempdir as described in the Servlet Specification. If not specified, a suitable directory underneath <JWSDP_HOME>/work will be provided.

The Loader Properties section enables you to configure the Web application class loader that will be used to load Servlet and JavaBeans classes for this Web application. Normally, the default configuration of the class loader will be sufficient. The attributes shown in Table A-8 may be viewed, set, or modified for Loader properties.

Table A-8 Loader Properties

Attribute	Description
Check Interval	The number of seconds between checks for modified classes and resources if Reloadable has been set to True. The default value is 15 seconds.
Debug Level	The level of debugging detail logged by this Engine to the associated Logger. Higher numbers generate more detailed output. If not specified, the default debugging detail level is zero (0).
Reloadable	Set to True if you want Tomcat to monitor classes in /WEB-INF/classes/ and /WEB-INF/lib for changes and automatically reload the Web application if a change is detected. This feature is very useful during application development, but it requires significant runtime overhead and is not recommended for use on deployed production applications. You can use the Manager Web application when you need to trigger reloads of deployed applications on demand.The default value is False.

The Session Manager Properties enable you to configure the session manager that will be used to create, destroy, and persist HTTP sessions for this Web application. Normally, the default configuration of the session manager will be sufficient. The attributes shown in Table A-9 may be viewed, set, or modified for Session Manager properties.

Table A-9 Session Manager Properties

Attribute	Description
Check Interval	The number of seconds between checks for expired sessions for this manager. The default value is 60 seconds.The default value is 60.
Debug Level	The level of debugging detail logged by this Manager to the associated Logger. Higher numbers generate more detailed output. If not specified, the default debugging detail level is zero (0).
Session ID Initializer	Tomcat provides two standard implementations of Session Managers. org.apache.catalina.session.StandardManager stores active sessions. org.apache.catalina.session.PersistentManager persistently stores active sessions that have been swapped out (in addition to saving sessions across a restart of Tomcat) in a storage location that is selected via the use of an appropriate Store nested element. In addition to the usual operations of creating and deleting sessions, a PersistentManager has the capability to swap active (but idle) sessions out to a persistent storage mechanism, as well as to save all sessions across a normal restart of Tomcat. The actual persistent storage mechanism that is used is selected by your choice of a Store element nested inside the Manager element - this is required for use of PersistentManager.
Maximum Active Sessions.	The maximum number of active sessions that will be created by this Manager, or -1 (the default) for no limit.

Configuring Logger Elements

A Logger element represents a destination for logging, debugging, and error messages (including stack tracebacks) for Tomcat.

If you are interested in producing access logs as a Web server does (for example, to run hit count analysis software), you will want to configure an Access Log Valve component on your Engine, Host, or Context.

Using admintool, you can create 3 types of loggers:

• SystemOutLogger

  The Standard Output Logger records all logged messages to the stream to which the standard output of Tomcat is pointed. The default Tomcat startup script points this at the file logs/catalina.out relative to the directory where Tomcat is installed.

• SystemErrLogger

  The Standard Error Logger records all logged messages to the stream to which the standard error output of Tomcat is pointed. The default Tomcat startup script points this at the file logs/catalina.out relative to the directory where Tomcat is installed.

• FileLogger

  The File Logger records all logged messages to disk file(s) in a specified directory. The actual filenames of the log files are created from a configured prefix, the current date in YYYY-MM-DD format, and a configured suffix. On the first logged message after midnight each day, the current log file will be closed and a new file opened for the new date, without your having to shut down Tomcat in order to perform this switch.

To edit a Logger,

1. Expand the Service element in the left pane.
2. Select the Logger to edit.
3. Edit the values in the right pane.
4. Select Save to save the changes for this session. Select Commit Changes to save the changes for when Tomcat is restarted.

To create a new Logger for a service,

1. Select the Service element in the left pane. It is highly recommended that you only modify the Java Web Services Developer Pack Service, or a service that you have created.
2. Select Create New Logger from the Available Actions list.
3. Enter the preferred values for the Logger. See Logger Attributes for more information on the options.
4. Select Save to save the changes for this session. Select Commit Changes to save the changes for when Tomcat is restarted.

To learn more about Loggers, read the document titled "Logger Component" at <JWSDP_HOME>/docs/tomcat/config/logger.html.

Logger Attributes

Common attributes for all of the Logger types are outlined in Table A-10.

Table A-10 Logger Attributes 

Attribute	Description
Type	The type of Logger to create.
Debug Level	The level of debugging detail logged by this Logger. Higher numbers generate more detailed output. If not specified, the default debugging detail level is zero (0).
Verbosity Level	The verbosity level for this logger. Messages with a higher verbosity level than the specified value will be silently ignored. Available levels are 0 (fatal messages only), 1 (errors), 2 (warnings), 3 (information), and 4 (debug). If not specified, the default value will be 0 (fatal messages only).

If you are using a Logger of type FileLogger, additional attributes that may be set are shown in Table A-11.

Table A-11 FileLogger Attributes 

Attribute	Description
Directory	The absolute or relative path name of a directory in which log files created by this logger will be placed. If a relative path is specified, it is interpreted as relative to the directory in which Tomcat is installed. If no directory attribute is specified, the default value is logs (relative to the directory in which Tomcat is installed).
Prefix	The prefix added to the start of each log file's name. If not specified, the default value is catalina. To specify no prefix, use a zero-length string.
Suffix	The suffix added to the end of each log file's name. If not specified, the default value is .log. To specify no suffix, use a zero-length string.
Timestamp	Whether or not all logged messages are to be date and time stamped. Set to True to cause all logged messages to be date and time stamped. Set to False to skip date/time stamping.

Configuring Realm Elements

A Realm element represents a database of user names, passwords, and roles (similar to Unix groups) assigned to those users. Different implementations of Realm allow Tomcat to be integrated into environments where such authentication information is already being created and maintained, and then to utilize that information to implement container managed security (as described in the Java Servlet Specification, available online at http://java.sun.com/products/servlet/download.html).

The Realm created inside the Service in which Tomcat is running can not be added or deleted. In the Java WSDP, this is the Service (Java Web Services Developer Pack). You can create a Realm inside a Service you have defined and added to Tomcat.

To edit a Realm,

1. Expand the Service element in the left pane.
2. Select the Realm to edit.
3. Edit the values in the right pane.
4. Select Save to save the changes for this session. Select Commit Changes to save the changes for when Tomcat is restarted.

A Realm can be created inside any container Engine, Host, or Context. There can be only one instance of a Realm under each of these. Realms associated with an Engine or a Host are automatically inherited by lower-level containers, unless explicitly overridden. To add a new Realm,

1. Select the service, host, or context under which the new Realm is to be created.
2. Select the Create New Realm option from the Available Actions list. Select the type of Realm. Depending on the type of Realm you choose, the attributes vary.

There are several standard Realm implementations available, including:

• JDBCRealm

  The JDBC Database Realm connects Tomcat to a relational database, accessed through an appropriate JDBC driver, to perform lookups of use names, passwords, and their associated roles. Because the lookup is done each time it is required, changes to the database will be immediately reflected in the information used to authenticate new logins. Attributes for the JDBC Database Realm implementation are shown in JDBCRealm Attributes.

• JNDIRealm

  The JNDI Directory Realm connects Tomcat to an LDAP Directory, accessed through an appropriate JNDI driver, to perform lookups of user names, passwords, and their associated roles. Because the lookup is done each time it is required, changes to the directory will be immediately reflected in the information used to authenticate new logins. Attributes for the JNDI Database Realm implementation are shown in JNDIRealm Attributes.

• MemoryRealm

  The Memory Based Realm is a simple Realm implementation that reads an XML file to configure valid users, passwords, and roles. The file format and default file location are identical to those currently supported by Tomcat 3.x. This implementation is intended solely to get up and running with container managed security - it is NOT intended for production use. As such, there are no mechanisms for updating the in-memory collection of users when the content of the underlying data file is changed. Attributes for the Memory Realm implementation are shown in MemoryRealm Attributes.

• UserDatabaseRealm

  UserDatabaseRealm is an implementation of Realm based on an implementation of UserDatabase made available through the global JNDI resources configured for the instance of Tomcat. The Resource Name parameter is set to the global JNDI resources name for the configured instance of UserDatabase to be consulted. Attributes for the User Database Realm implementation are shown in UserDatabaseRealm Attributes.

To learn more about Realms, read the document titled Realm Component at <JWSDP_HOME>/docs/tomcat/config/realm.html or Realm Configuration How To at <JWSDP_HOME>/docs/tomcat/realm-howto.html.

JDBCRealm Attributes

The JDBC Database Realm connects Tomcat to a relational database, accessed through an appropriate JDBC driver, to perform lookups of use names, passwords, and their associated roles. Because the lookup is done each time it is required, changes to the database will be immediately reflected in the information used to authenticate new logins. Attributes for the JDBC Database Realm implementation are shown in Table A-12.

Table A-12 JDBCRealm Attributes

Attribute	Description
Database Driver	Fully qualified Java class name of the JDBC driver to be used to connect to the authentication database.
Database Password	The database password to use when establishing the JDBC connection.
Database URL	The connection URL to be passed to the JDBC driver when establishing a database connection.
Database User Name	The database user name to use when establishing the JDBC connection.
Debug Level	The level of debugging detail logged by this Engine. Higher numbers generate more detailed output. If not specified, the default debugging detail level is zero (0).
Digest Algorithm	The name of the MessageDigest algorithm used to encode user passwords stored in the database. If not specified, user passwords are assumed to be stored in text.
Password Column	Name of the in the userscontains the user's credentials (i.e. password). If a value for Digest Algorithm is specified, the component will assume that the passwords have been encoded with the specified algorithm. Otherwise, they will be assumed to be in clear text.
Role Name Column	Name of the column, in the user rolestable, which contains a role name assigned to the corresponding user.
User Name Column	Name of the column, in the usersand user rolestable, that contains the user's user name.
User Role Table	Name of the user rolestable, which must contain columns named by the User Name Column and Role Name Column attributes.
User Table	Name of the userstable, which must contain columns named by the User Name Column and Password Column attributes.

JNDIRealm Attributes

The JNDI Directory Realm connects Tomcat to an LDAP Directory, accessed through an appropriate JNDI driver, to perform lookups of user names, passwords, and their associated roles. Because the lookup is done each time it is required, changes to the directory will be immediately reflected in the information used to authenticate new logins.

A rich set of attributes lets you configure the required connection to the underlying directory, as well as the element and attribute names used to retrieve the required information. Attributes for the JNDI Directory Realm implementation are shown in Table A-14.

Table A-13 JNDIRealm Attributes

Attribute	Description
Connection Name	The directory user name to use when establishing the JNDI connection. This attribute is required if you specify the User Password attribute, and is not used otherwise.
Connection Password	The directory password to use when establishing the JNDI connection. This attribute is required if you specify the User Password property, and is not used otherwise.
Connection URL	The connection URL to be passed to the JNDI driver when establishing a connection to the directory.
Context Factory	Fully qualified Java class name of the factory class used to acquire our JNDI InitialContext. By default, assumes that the standard JNDI LDAP provider will be utilized.
Debug Level	The level of debugging detail logged by this Engine. Higher numbers generate more detailed output. If not specified, the default debugging detail level is zero (0).
Digest Algorithm	The name of the MessageDigest algorithm used to encode user passwords stored in the database. If not specified, user passwords are assumed to be stored in clear text.
Role Base Element	The base directory element for performing role searches.
Role Name	The name of the directory attribute to retrieve when selecting the assigned roles for a user. If not specified, use the User Role Name attribute to specify the name of an attribute in the user's entry that contains zero or more role names assigned to this user.
Role Search Pattern	The LDAP search expression to use when selecting roles for a particular user, with {0} marking where the actual user name should be inserted. For more information on patterns, see Values for the Pattern Attribute.
Search Role Subtree	Set to True to search subtrees of the elements selected by the Role Search Pattern expression. Set to False to not search subtrees. The default value is False.
User Role Name	The name of a directory attribute in the user's entry containing zero or more values for the names of roles assigned to this user. If not specified, use the Role Name attribute to specify the name of a particular attribute that is retrieved from individual role entries associated with this user.
* User Base Element (userBase)	The entry that is the base of the subtree containing users. If not specified, the search base is the top-level context. This option is not used when using the userPattern (User Pattern) expression. This attribute (userBase) is not accessible through admintool. See Specifying Realm Attributes in Server.xml for information on setting this attribute.
*User Pattern (userPattern)	The LDAP search expression to use when retrieving the attributes of a particular user, with {0} marking where the actual user name should be inserted. Use this attribute instead of User Search Pattern if you want to select a particular single entry based on the user name. This attribute (userPattern) is not accessible through admintool. See Specifying Realm Attributes in Server.xml for information on setting this attribute.
Search User Subtree	Set to True if you are using the User Search Pattern to search for authenticated users and you want to search subtrees of the element specified by the User Base Element. The default value of False causes only the specified level to be searched. Not used if you are using the User Pattern expression.
User Password	Name of the LDAP element containing the user's password. If you specify this value, JNDIRealm will bind to the directory using the values specified by the Connection Name and Connection Password attributes and retrieve the corresponding attribute for comparison to the value specified by the user being authenticated. If you do not specify this value, JNDIRealm will attempt to bind to the directory using the user name and password specified by the user, with a successful bind being interpreted as an authenticated user.
User Search Pattern	The LDAP search expression to use when retrieving the attributes of a particular user, with {0} marking where the actual user name should be inserted. Use this attribute instead of User Pattern to search the entire directory (instead of retrieving a particular named entry) under the optional additional control of the User Base Element and Search User Subtree attributes.

Table A-14 JNDIRealm Attributes

Attribute	Description
Connection Name	The directory user name to use when establishing the JNDI connection. This attribute is required if you specify the User Password attribute, and is not used otherwise.
Connection Password	The directory password to use when establishing the JNDI connection. This attribute is required if you specify the User Password property, and is not used otherwise.
Connection URL	The connection URL to be passed to the JNDI driver when establishing a connection to the directory.
Context Factory	Fully qualified Java class name of the factory class used to acquire our JNDI InitialContext. By default, assumes that the standard JNDI LDAP provider will be utilized.
Debug Level	The level of debugging detail logged by this Engine. Higher numbers generate more detailed output. If not specified, the default debugging detail level is zero (0).
Digest Algorithm	The name of the MessageDigest algorithm used to encode user passwords stored in the database. If not specified, user passwords are assumed to be stored in clear-text.
Role Base Element	The base directory element for performing role searches.
Role Name	The name of the directory attribute to retrieve when selecting the assigned roles for a user. If not specified, use the User Role Name attribute to specify the name of an attribute, in the user's entry, that contains zero or more role names assigned to this user.
Role Search Pattern	The LDAP search expression to use when selecting roles for a particular user, with {0} marking where the actual user name should be inserted. For more information on patterns, see Values for the Pattern Attribute.
Search Role Subtree	Set to True to search subtrees of the elements selected by the Role Search Pattern expression. Set to False to not search subtrees. The default value is False.
User Role Name	The name of a directory attribute, in the user's entry, containing zero or more values for the names of roles assigned to this user. If not specified, use the Role Name attribute to specify the name of a particular attribute that is retrieved from individual role entries associated with this user.
Search User Subtree	Set to True if you are using the User Search Pattern to search for authenticated users, and you want to search subtrees of the element specified by the User Base Element. The default value of False causes only the specified level to be searched. Not used if you are using the User Pattern expression.
User Password	Name of the LDAP element containing the user's password. If you specify this value, JNDIRealm will bind to the directory using the values specified by Connection Name and Connection Password attributes and retrieve the corresponding attribute for comparison to the value specified by the user being authenticated. If you do not specify this value, JNDIRealm will attempt to bind to the directory using the user name and password specified by the user, with a successful bind being interpreted as an authenticated user.
User Search Pattern	The LDAP search expression to use when retrieving the attributes of a particular user, with {0} marking where the actual user name should be inserted. Use this attribute when you want to search the entire directory instead of retrieving a particular named entry.

Specifying Realm Attributes in Server.xml

The two attributes that may be specified for JNDI Realm that are not available through admintool at this time are User Base Element (userBase) and User Pattern (userPattern). The User Base Element (userBase) is the base element for user searches performed using the User Search Pattern. The User Base Element can be set to the base of the subtree containing users. If the User Base Element is not specified, the search base is the top-level context. The User Search Pattern and Search User Subtree attributes would still depend on the User Base Element, using the default value of an empty string ("") for this attribute.

Use the User Pattern (userPattern) attribute to define the LDAP search expression to use when retrieving the attributes of a particular user, with {0} marking where the actual user name should be inserted. Use this attribute instead of User Search Pattern if you want to select a particular single entry based on the user name.

To use either of these attributes,

1. Edit <JWSDP_HOME>/conf/server.xml.
2. Find or create the section titled for JNDIRealm.
3. Add code such as the following for userPattern:

   <Realm   className="org.apache.catalina.realm.JNDIRealm"
     debug="99"
     connectionName="cn=Manager,dc=mycompany,dc=com"
     connectionPassword="secret"
     connectionURL="ldap://localhost:389"
     roleBase="dc=roles,dc=person,dc=net"
     roleName="cn"
     roleSearch="(uniqueMember={0})"
     roleSubtree="false"
     userPassword="userPassword"
     userPattern="cn={0},dc=mycompany,dc=com"
   />
    
   

4. Or code such as the following for userBase:

   <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})" 
   />
    
   

UserDatabaseRealm Attributes

UserDatabaseRealm is an implementation of Realm based on an implementation of UserDatabase made available through the global JNDI resources configured for the instance of Tomcat. The resourceName parameter is set to the global JNDI resources name for the configured instance of UserDatabase to be consulted. Attributes for the User Database Realm implementation are shown in Table A-15.

Table A-15 UserDataBaseRealm Attributes

Attribute	Description
Debug Level	The level of debugging detail logged by this Engine. Higher numbers generate more detailed output. If not specified, the default debugging detail level is zero (0).
Resource Name	The global JNDI resources name for the configured instance of UserDatabase to be consulted.

MemoryRealm Attributes

The Memory Based Realm is a simple Realm implementation that reads an XML file to configure valid users, passwords, and roles. The file format and default file location are identical to those currently supported by Tomcat 3.x. This implementation is intended solely to get up and running with container managed security - it is NOT intended for production use. As such, there are no mechanisms for updating the in-memory collection of users when the content of the underlying data file is changed. Attributes for the Memory Realm implementation are shown in Table A-16.

Table A-16 MemoryRealm Attributes

Attribute	Description
Debug Level	The level of debugging detail logged by this Engine. Higher numbers generate more detailed output. If not specified, the default debugging detail level is zero (0).
Path Name	Absolute or relative to <JWSDP_HOME> path name to the XML file containing user information. If no path name is specified, the default value is <JWSDP_HOME>/conf/tomcat-users.xml.

Configuring Valve Elements

A Valve element represents a component that will be inserted into the request processing pipeline for Tomcat. Individual Valves have distinct processing capabilities, and are described individually below.

To edit a Valve,

1. Expand the Service element in the left pane.
2. Select the Valve to edit.
3. Edit the values in the right pane.
4. Select Save to save the changes for this session. Select Commit Changes to save the changes for when Tomcat is restarted.

To create a new Valve for a service,

1. Select the Service element in the left pane. It is highly recommended that you only modify the Java Web Services Developer Pack Service, or a service that you have created.
2. Select Create New Valve from the Available Actions list.
3. Enter the preferred values for the Valve. See Valve Attributes for more information on the options.
4. Select Save to save the changes for this session. Select Commit Changes to save the changes for when Tomcat is restarted.

To learn more about Valves, read the document titled "Valve Component" at <JWSDP_HOME>/docs/tomcat/config/valve.html.

Valve Attributes

There are 5 types of Valves available in this release, and each has its own set of attributes, listed in the following sections.

AccessLogValve Attributes

The Access Log Valve creates log files in the same format as those created by standard Web servers. These logs can later be analyzed by standard log analysis tools to track page hit counts, user session activity, and so on. The Access Log Valve shares many of the configuration and behavior characteristics of the File Logger, including the automatic rollover of log files at midnight each night. An Access Log Valve can be associated with any Tomcat container, and will record ALL requests processed by that container. Attributes for AccessLogValve are shown in Table A-17.

Table A-17 AccessLogValve Attributes 

Attribute	Description
Debug Level	The level of debugging detail logged by this Logger. Higher numbers generate more detailed output. If not specified, the default debugging detail level is zero (0).
Directory	The absolute or relative path name of a directory in which log files created by this valve will be placed. If a relative path is specified, it is interpreted as relative to <JWSDP_HOME>. If no directory attribute is specified, the default value is logs (relative to <JWSDP_HOME>).
Pattern	A formatting layout identifying the various information fields from the request and response to be logged, or the word common or combined to select a standard format. See Values for the Pattern Attribute for more information.
Prefix	The prefix added to the start of each log file's name. If not specified, the default value is access_log. To specify no prefix, use a zero-length string.
Resolve Hosts	Whether or not to convert the IP address of the remote host into the corresponding host name via a DNS lookup. Set to True to convert the IP address of the remote host into the corresponding host name via a DNS lookup. Set to False to skip this lookup, and report the remote IP address instead.
Suffix	The suffix added to the end of each log file's name. If not specified, the default value is "". To specify no suffix, use a zero-length string.

Values for the Pattern Attribute

Values for the pattern attribute are made up of literal text strings, combined with pattern identifiers prefixed by the "%" character to cause replacement by the corresponding variable value from the current request and response. The following pattern codes are supported:

• %a - Remote IP address
• %A - Local IP address
• %b - Bytes sent, excluding HTTP headers, or '-' if zero
• %B - Bytes sent, excluding HTTP headers
• %h - Remote host name (or IP address if resolveHosts is false)
• %H - Request protocol
• %l - Remote logical user name from identd (always returns '-')
• %m - Request method (GET, POST, etc.)
• %p - Local port on which this request was received
• %q - Query string (prepended with a '?' if it exists)
• %r - First line of the request (method and request URI)
• %s - HTTP status code of the response
• %S - User session ID
• %t - Date and time, in Common Log Format
• %u - Remote user that was authenticated (if any), else '-'
• %U - Requested URL path
• %v - Local server name

The shorthand pattern name common (which is also the default) corresponds to %h %l %u %t "%r" %s %b. The shorthand pattern name combined appends the values of the Referrer and User-Agent headers, each in double quotes, to the common pattern.

RemoteAddrValve Attributes

Remote Address Valve allows you to compare the IP address of the client that submitted this request against one or more regular expressions, and either allow the request to continue or refuse to process the request from this client. A Remote Address Valve must accept any request presented to this container for processing before it will be passed on.

Attributes for this Valve are listed in Table A-18.

Table A-18 RemoteAddrValve Attributes 

Attribute	Description
Allow IP Addresses	A comma-separated list of regular expression patterns that the remote client's IP address is compared to. If this attribute is specified, the remote address MUST match for this request to be accepted. If this attribute is not specified, all requests will be accepted UNLESS the remote address matches a deny pattern.
Deny IP Addresses	A comma-separated list of regular expression patterns that the remote client's IP address is compared to. If this attribute is specified, the remote address MUST NOT match for this request to be accepted. If this attribute is not specified, request acceptance is governed solely by the Allow IP Addresses attribute.

RemoteHostValve Attributes

The Remote Host Valve allows you to compare the host name of the client that submitted this request against one or more regular expressions, and either allow the request to continue or refuse to process the request from this client. A Remote Host Valve must accept any request presented to this container for processing before it will be passed on.

Attributes for the RemoteHostValve are outlined in Table A-19.

Table A-19 RemoteHostValve Attributes 

Attribute	Description
Allow these Hosts	A comma-separated list of regular expression patterns that the remote client's host name is compared to. If this attribute is specified, the remote hostname MUST match for this request to be accepted. If this attribute is not specified, all requests will be accepted UNLESS the remote host name matches a deny pattern.
Deny these Hosts	A comma-separated list of regular expression patterns that the remote client's host name is compared to. If this attribute is specified, the remote host name MUST NOT match for this request to be accepted. If this attribute is not specified, request acceptance is governed solely by the Allow These Hosts attribute.

RequestDumperValve Attributes

The Request Dumper Valve is a useful tool in debugging interactions with a client application (or browser) that is sending HTTP requests to your Tomcat-based server. When configured, it causes details about each request processed by its associated Engine, Host, or Context to be logged to the Logger that corresponds to that container. This Valve has no specific attributes.

SingleSignOn Attributes

The Single Sign On Valve is utilized when you wish to give users the ability to sign on to any one of the Web applications associated with your virtual host, and then have their identity recognized by all other Web applications on the same virtual host. This Valve has a Debug Level attribute.

Home TOC Index

This tutorial contains information on the 1.0 version of the Java Web Services Developer Pack.

All of the material in The Java Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.