Tomcat Admin Tool

Tomcat Admin Tool

Overview

The admintool webapp can to set up users and contexts while Tomcat is runnng. Log in with a user name/password that has been assigned the role of admin. User names and passwords are defined in:
$TOMCAT_HOME/conf/tomcat-users.xml

Syntax looks like:
  <user name="name" 
   password="password" 
   roles="admin, manager, provider" />
Changes are written to:
$TOMCAT_HOME/conf/server.xml

The previous version of server.xml is backed up in the same directory with an date suffix. For example, server.xml.2002-06-15.12-11-54. To restore a previous configuration, shut down Tomcat, mv the old file to server.xml, and restart Tomcat. This document contains information about using admintool to configure the behavior of Tomcat. For more information on these configuration elements, read the Tomcat Configuration Reference, which can be found at $TOMCAT_HOME/docs/tomcat/config/index.html.

This document does not attempt to describe which configurations should be used to perform specific tasks. For information of this type, refer to one of the following documents:

Class Loader How-To. This document discusses decisions that application developers and deployers must make about where to place class and resource files to make them available to webapps. This document can be found at $TOMCAT_HOME/docs/tomcat/class-loader-howto.html.
JNDI Resources How-To. This document discusses configuring JNDI Resources, Tomcat Standard Resource Factories, JDBC Data Sources, and Custom Resource Factories. This document can be found at $TOMCAT_HOME/docs/tomcat/jndi-resources-howto.html.
Manager Application How-To. This document describes using the Manager Application to deploy a new webapp, undeploy an existing application, or reload an existing application without having to shut down and restart Tomcat. This document can be found at $TOMCAT_HOME/docs/tomcat/manager-howto.html.
Proxy Support How-To. This document discusses running behind a proxy server (or a web server that is configured to behave like a proxy server). In particular, this document discusses how to manage the values returned by the calls from webapps that ask for the server name and port number to which the request was directed for processing. This document can be found at $TOMCAT_HOME/docs/tomcat/proxy-howto.html.
Realm Configuration How-To. This document discusses how to configure Tomcat to support container-managed security by connecting to an existing database of user names, passwords, and user roles. This document can be found at $TOMCAT_HOME/docs/tomcat/realm-howto.html.
Security Manager How-To. This document discusses the use of a SecurityManager while running Tomcat to protect your server from unauthorized servlets, JSPs, JSP beans, and tag libraries. This document can be found at $TOMCAT_HOME/docs/tomcat/security-manager-howto.html.
SSL Configuration How-To. This document discusses how to install and configure SSL support on Tomcat. Configuring SSL support on Tomcat using Java WSDP is discussed in Installing and Configuring SSL Support on Tomcat. The Tomcat documentation at $TOMCAT_HOME/docs/tomcat/ssl-howto.html also discusses this topic, however, the information in this tutorial is more up-to-date for the version of Tomcat shipped with the Java WSDP.

Configuring Tomcat

As you can see in Figure A-1, admintool presents a hierarchy of elements that can be configured to customize the Tomcat JSP/Servlet container to your needs. The Server element represents the characteristics of the entire JSP/Servlet container.

Setting Server Properties

Select Tomcat Server in the left pane. The Server Properties display in the right pane. The Server element represents the entire JSP/Servlet container. The server properties are shown in Table A-2.

Property
Description

Port Number
The TCP/IP port number on which this server waits for a shutdown command. This connection must be initiated from the same server computer that is running this instance of Tomcat. The default value is 8005. Values less than 1024 will generate a warning, as special software capabilities are required when using this port

Debug Level
The level of debugging detail logged by this server. Higher numbers generate more detailed output. If not specified, the default debugging detail level is zero (0).

Shutdown
The command string that must be received via a TCP/IP connection to the specified port number in order to shut down Tomcat. The value for this property must contain at least 6 characters. The default value is SHUTDOWN.

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 Internal and a Java Web Services Developer Pack services.

The Internal Service uses port 8081. This service is used internally by the Tomcat webapps such as JAXM provider and JAXM provideradmin contexts. These contexts are used by the JAXM webapps contexts in the JWSDP Service.
The Java Web Services Developer Pack Service uses port 8080, the standard port on which users can deploy their webapps. 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,

Select Tomcat Server in the left pane.
Select Create New Service from the drop-down list in the right pane.
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,

Expand the Service element in the left pane.
Select the Connector to edit.
Edit the values in the right pane.
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,

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.
Select Create New Connector from the Available Actions list.
Enter the preferred values for the Connector. See Connector Attributes for more information on the options.
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 $TOMCAT_HOME/docs/tomcat/config/coyote.html or the document titled JK 2 Connectors at $TOMCAT_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 webapp, 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.

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.

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.

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 $TOMCAT_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, 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 properti

Property	Description
Port Number	The TCP/IP port number on which this server waits for a shutdown command. This connection must be initiated from the same server computer that is running this instance of Tomcat. The default value is 8005. Values less than 1024 will generate a warning, as special software capabilities are required when using this port
Debug Level	The level of debugging detail logged by this server. Higher numbers generate more detailed output. If not specified, the default debugging detail level is zero (0).
Shutdown	The command string that must be received via a TCP/IP connection to the specified port number in order to shut down Tomcat. The value for this property must contain at least 6 characters. The default value is SHUTDOWN.

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.

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.

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 $TOMCAT_HOME directory.
Keystore Password	The password used to access the server certificate from the specified keystore file. The default value is changeit.