Download FAQ History |  | API Search Feedback

> ## 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 a Java Web Services Developer Pack 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

> 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 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-2 may be set, as needed.

> Table A-2 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-3.

> Table A-3 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-4 may also be set.

> Table A-4 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 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-5 may be viewed, set, or modified for a Host.

> Table A-5 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 Aliases 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 Applications.

> 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-6.
> - Loader Properties, described in Table A-7.
> - Session Manager Properties, described in Table A-8.

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

> Table A-6 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 the 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 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-7 may be viewed, set, or modified for Loader properties.

> Table A-7 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-8 may be viewed, set, or modified for Session Manager properties.

> Table A-8 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.
> 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-9.

> Table A-9 Logger Attributes
> Attribute | Description
> --- | ---
> Type | The type of Logger to create: `SystemOutLogger`, `SystemErrLogger`, or `FileLogger`.
> 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). The default value is 0 (fatal messages only).

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

> Table A-10 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 edited or deleted, and no other Realm can be added to this service. 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 User 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 user 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-11.

> Table A-11 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 column in the users table that contains 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 roles table, which contains a role name assigned to the corresponding user.
> User Name Column | Name of the column, in the users and user roles table, that contains the user's user name.
> User Role Table | Name of the user roles table, which must contain columns named by the User Name Column and Role Name Column attributes.
> User Table | Name of the users table, 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-12.

> Table A-12 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 | 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 User Pattern is specified.
> 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 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 Search Pattern if you want to select a particular single entry based on the user name.
> User Search | 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.

> #### 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-13.

> Table A-13 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. 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-14.

> Table A-14 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 | The path to the XML file containing user information. The path is specified absolute or relative to <JWSDP_HOME>. 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-15.

> Table A-15 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>. 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. 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. The default is False.
> 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-16.

> Table A-16 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-17.

> Table A-17 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.

Download FAQ History |  | API Search Feedback

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