# Apache Tomcat 6.0

Version 6.0.36, Oct 16 2012

Links

- Docs Home
- FAQ

User Guide

- 1) Introduction
- 2) Setup
- 3) First webapp
- 4) Deployer
- 5) Manager
- 6) Realms and AAA
- 7) Security Manager
- 8) JNDI Resources
- 9) JDBC DataSources
- 10) Classloading
- 11) JSPs
- 12) SSL
- 13) SSI
- 14) CGI
- 15) Proxy Support
- 16) MBean Descriptor
- 17) Default Servlet
- 18) Clustering
- 19) Load Balancer
- 20) Connectors
- 21) Monitoring and Management
- 22) Logging
- 23) APR/Native
- 24) Virtual Hosting
- 25) Advanced IO
- 26) Additional Components
- 27) Mavenized

Reference

- Release Notes
- Configuration
- Javadocs
- JK 1.2 Documentation

Apache Tomcat Development

- Building
- Changelog
- Status
- Developers
- Architecture
- Functional Specs.

# Apache Tomcat 6.0

## Monitoring and Managing Tomcat

Table of Contents

> - Introduction
> - Enabling JMX Remote
> - Manage Tomcat with JMX remote Ant Tasks
> - JMXAccessorOpenTask - JMX open connection task
> - JMXAccessorGetTask: get attribute value Ant task
> - JMXAccessorSetTask: set attribute value Ant task
> - JMXAccessorInvokeTask: invoke MBean operation Ant task
> - JMXAccessorQueryTask: query MBean Ant task
> - JMXAccessorCreateTask: remote create MBean Ant task
> - JMXAccessorUnregisterTask: remote unregister MBean Ant task
> - JMXAccessorCondition: express condition
> - JMXAccessorEqualsCondition: equals MBean Ant condition

Introduction

> Monitoring is a key aspect of system administration. Looking inside a running server, obtaining some statistics or reconfiguring some aspects of an application are all daily administration tasks.

Enabling JMX Remote

> The Sun website includes the list of options and how to configure JMX Remote on Java 5: http://docs.oracle.com/javase/1.5.0/docs/guide/management/agent.html.

> The following is a quick configuration guide for Java 5:

> Add the following parameters to your Tomcat startup script:

>         set CATALINA_OPTS=-Dcom.sun.management.jmxremote \
>         -Dcom.sun.management.jmxremote.port=%my.jmx.port% \
>         -Dcom.sun.management.jmxremote.ssl=false \
>         -Dcom.sun.management.jmxremote.authenticate=false

> 1. If you require authorization, add and change this :

>            -Dcom.sun.management.jmxremote.authenticate=true \
>            -Dcom.sun.management.jmxremote.password.file=../conf/jmxremote.password \
>            -Dcom.sun.management.jmxremote.access.file=../conf/jmxremote.access \

> 2. edit the access authorization file $CATALINA_BASE/conf/jmxremote.access :

>        monitorRole readonly
>        controlRole readwrite

> 3. edit the password file $CATALINA_BASE/conf/jmxremote.password :

>        monitorRole tomcat
>        controlRole tomcat

>    Tip: The password file should be read-only and only accessible by the operating system user Tomcat is running as.
> Note:The JSR 160 JMX-Adaptor opens a second data channel on a random port. That is a problem when you have a local firewall installed.

Manage Tomcat with JMX remote Ant Tasks

> To simplify JMX usage with Ant 1.6.x, a set of tasks is provided that may be used with antlib.

> antlib: Copy your catalina-ant.jar from $CATALINA_HOME/lib to $ANT_HOME/lib.

> The following example shows the JMX Accessor usage:

>     <project name="Catalina Ant JMX"
>             xmlns:jmx="antlib:org.apache.catalina.ant.jmx"
>             default="state"
>             basedir=".">
>         <property name="jmx.server.name" value="localhost" />
>         <property name="jmx.server.port" value="9012" />
>         <property name="cluster.server.address" value="192.168.1.75" />
>         <property name="cluster.server.port" value="9025" />

>         <target name="state" description="Show JMX Cluster state">
>             <jmx:open
>                 host="${jmx.server.name}"
>                 port="${jmx.server.port}"
>                 username="controlRole"
>                 password="tomcat"/>
>             <jmx:get
>                 name="Catalina:type=IDataSender,host=localhost,senderAddress=${cluster.server.address},senderPort=${cluster.server.port}"
>                 attribute="connected"
>                 resultproperty="IDataSender.backup.connected"
>                 echo="false"
>             />
>            <jmx:get
>                 name="Catalina:type=ClusterSender,host=localhost"
>                 attribute="senderObjectNames"
>                 resultproperty="senderObjectNames"
>                 echo="false"
>             />
>             <!-- get current maxActiveSession from ClusterTest application
>                  echo it to Ant output and store at
>                  property <em>clustertest.maxActiveSessions.orginal</em>
>             -->
>            <jmx:get
>                 name="Catalina:type=Manager,path=/ClusterTest,host=localhost"
>                 attribute="maxActiveSessions"
>                 resultproperty="clustertest.maxActiveSessions.orginal"
>                 echo="true"
>             />
>             <!-- set maxActiveSession to 100
>             -->
>             <jmx:set
>                 name="Catalina:type=Manager,path=/ClusterTest,host=localhost"
>                 attribute="maxActiveSessions"
>                 value="100"
>                 type="int"
>             />
>             <!-- get all sessions and split result as delimiter <em>SPACE</em> for easy
>                  access all session ids directly with Ant property sessions.[0..n].
>             -->
>             <jmx:invoke
>                 name="Catalina:type=Manager,path=/ClusterTest,host=localhost"
>                 operation="listSessionIds"
>                 resultproperty="sessions"
>                 echo="false"
>                 delimiter=" "
>             />
>             <!-- Access session attribute <em>Hello</em> from first session.
>             -->
>             <jmx:invoke
>                 name="Catalina:type=Manager,path=/ClusterTest,host=localhost"
>                 operation="getSessionAttribute"
>                 resultproperty="Hello"
>                 echo="false"
>             >
>               <arg value="${sessions.0}"/>
>               <arg value="Hello"/>
>             </jmx:invoke>
>             <!-- Query for all application manager.of the server from all hosts
>                  and bind all attributes from all found manager MBeans.
>             -->
>             <jmx:query
>                 name="Catalina:type=Manager,*"
>                 resultproperty="manager"
>                 echo="true"
>                 attributebinding="true"
>             />
>             <!-- echo the create properties -->
>             <echo>
>                senderObjectNames: ${senderObjectNames.0}
>                IDataSender.backup.connected: ${IDataSender.backup.connected}
>                session: ${sessions.0}
>                manager.length: ${manager.length}
>                manager.0.name: ${manager.0.name}
>                manager.1.name: ${manager.1.name}
>                hello: ${Hello}
>                manager.ClusterTest.0.name: ${manager.ClusterTest.0.name}
>                manager.ClusterTest.0.activeSessions: ${manager.ClusterTest.0.activeSessions}
>                manager.ClusterTest.0.counterSend_EVT_SESSION_EXPIRED: ${manager.ClusterTest.0.counterSend_EVT_SESSION_EXPIRED}
>                manager.ClusterTest.0.counterSend_EVT_GET_ALL_SESSIONS: ${manager.ClusterTest.0.counterSend_EVT_GET_ALL_SESSIONS}
>             </echo>

>         </target>

>     </project>

> import: Import the JMX Accessor Project with <import file="${CATALINA.HOME}/bin/catalina-tasks.xml" /> and reference the tasks with jmxOpen, jmxSet, jmxGet, jmxQuery, jmxInvoke, jmxEquals and jmxCondition.

JMXAccessorOpenTask - JMX open connection task

> List of Attributes

> Attribute | Description | Default value
> --- | --- | ---
> url | Set JMX connection URL - service:jmx:rmi:///jndi/rmi://localhost:8050/jmxrmi |
> host | Set the host, shortcut the very long URL syntax. | `localhost`
> port | Set the remote connection port | `8050`
> username | remote JMX connection user name. |
> password | remote JMX connection password. |
> ref | Name of the internal connection reference. With this attribute you can configure more the one connection inside the same Ant project. | `jmx.server`
> echo | Echo the command usage (for access analysis or debugging) | `false`
> if | Only execute if a property of the given name exists in the current project. |
> unless | Only execute if a property of the given name not exists in the current project. |

> Example to open a new JMX connection

>         <jmx:open
>                 host="${jmx.server.name}"
>                 port="${jmx.server.port}"
>         />

> Example to open a JMX connection from URL, with authorization and store at other reference

>         <jmx:open
>                 url="service:jmx:rmi:///jndi/rmi://localhost:9024/jmxrmi"
>                 ref="jmx.server.9024"
>                 username="controlRole"
>                 password="tomcat"
>         />

> Example to open a JMX connection from URL, with authorization and store at other reference, but only when property jmx.if exists and jmx.unless not exists

>         <jmx:open
>                 url="service:jmx:rmi:///jndi/rmi://localhost:9024/jmxrmi"
>                 ref="jmx.server.9024"
>                 username="controlRole"
>                 password="tomcat"
>                 if="jmx.if"
>                 unless="jmx.unless"
>         />

> Note: All properties from jmxOpen task also exists at all other tasks and conditions.

JMXAccessorGetTask: get attribute value Ant task

> List of Attributes

> Attribute | Description | Default value
> --- | --- | ---
> name | Full qualified JMX ObjectName -- Catalina:type=Server |
> attribute | Existing MBean attribute (see Tomcat MBean description above) |
> ref | JMX Connection reference | `jmx.server`
> echo | Echo command usage (access and result) | `false`
> resultproperty | Save result at this project property |
> delimiter | Split result with delimiter (java.util.StringTokenizier) and use resultproperty as prefix to store tokens. |
> separatearrayresults | When return value is an array, save result as property list ($resultproperty.[0..N] and $resultproperty.length) | `true`

> Example to get remote MBean attribute from default JMX connection

>         <jmx:get
>             name="Catalina:type=Manager,path=/servlets-examples,host=localhost"
>             attribute="maxActiveSessions"
>             resultproperty="servlets-examples.maxActiveSessions"
>         />

> Example to get and result array and split it at separate properties

>         <jmx:get
>             name="Catalina:type=ClusterSender,host=localhost"
>             attribute="senderObjectNames"
>             resultproperty="senderObjectNames"
>         />

> Access the senderObjectNames properties with:

>         ${senderObjectNames.length} give the number of returned sender list.
>         ${senderObjectNames.[0..N]} found all sender object names

> Example to get IDataSender attribute connected only when cluster is configured.

>     <jmx:query
>         failonerror="false"
>         name="Catalina:type=Cluster,host=${tomcat.application.host}"
>         resultproperty="cluster"
>     />
>     <jmx:get
>         name="Catalina:type=IDataSender,host=${tomcat.application.host},senderAddress=${cluster.backup.address},senderPort=${cluster.backup.port}"
>         attribute="connected"
>         resultproperty="datasender.connected"
>         if="cluster.0.name" />

JMXAccessorSetTask: set attribute value Ant task

> List of Attributes

> Attribute | Description | Default value
> --- | --- | ---
> name | Full qualified JMX ObjectName -- Catalina:type=Server |
> attribute | Existing MBean attribute (see Tomcat MBean description above) |
> value | value that set to attribute |
> type | type of the attribute. | java.lang.String
> ref | JMX Connection reference | `jmx.server`
> echo | Echo command usage (access and result) | `false`

> Example to set remote MBean attribute value

>         <jmx:set
>             name="Catalina:type=Manager,path=/servlets-examples,host=localhost"
>             attribute="maxActiveSessions"
>             value="500"
>             type="int"
>         />

JMXAccessorInvokeTask: invoke MBean operation Ant task

> List of Attributes

> Attribute | Description | Default value
> --- | --- | ---
> name | Full qualified JMX ObjectName -- Catalina:type=Server |
> operation | Existing MBean operation (see Tomcat funcspecs/fs-admin-opers.html). |
> ref | JMX Connection reference | `jmx.server`
> echo | Echo command usage (access and result) | `false`
> resultproperty | Save result at this project property |
> delimiter | Split result with delimiter (java.util.StringTokenizier) and use resultproperty as prefix to store tokens. |
> separatearrayresults | When return value is an array, save result as property list ($resultproperty.[0..N] and $resultproperty.length) | `true`

> stop an application

>         <jmx:invoke
>             name="Catalina:type=Manager,path=/servlets-examples,host=localhost"
>             operation="stop"/>

> Now you can find the sessionid at ${sessions.[0..N} properties and access the count with ${sessions.length} property.

> Example to get all sessionids

>         <jmx:invoke
>             name="Catalina:type=Manager,path=/servlets-examples,host=localhost"
>             operation="listSessionIds"
>             resultproperty="sessions"
>             delimiter=" "
>         />

> Now you can find the sessionid at ${sessions.[0..N} properties and access the count with ${sessions.length} property.

> Example to get remote MBean session attribute from session ${sessionid.0}

>         <jmx:invoke
>             name="Catalina:type=Manager,path=/ClusterTest,host=localhost"
>             operation="getSessionAttribute"
>             resultproperty="hello">
>              <arg value="${sessionid.0}"/>
>              <arg value="Hello" />
>      </jmx:invoke>

> Example to create a new access logger valve at vhost localhost

>      <jmx:invoke
>              name="Catalina:type=MBeanFactory"
>              operation="createAccessLoggerValve"
>              resultproperty="accessLoggerObjectName"
>      >
>          <arg value="Catalina:type=Host,host=localhost"/>
>      </jmx:invoke>

> Now you can find new MBean with name stored at ${accessLoggerObjectName} property.

JMXAccessorQueryTask: query MBean Ant task

> List of Attributes

> Attribute | Description | Default value
> --- | --- | ---
> name | JMX ObjectName query string -- Catalina:type=Manager,* |
> ref | JMX Connection reference | `jmx.server`
> echo | Echo command usage (access and result) | `false`
> resultproperty | Prefix project property name to all founded MBeans (mbeans.[0..N].objectname) |
> attributebinduing | bind ALL MBean attributes in addition to name | `false`
> delimiter | Split result with delimiter (java.util.StringTokenizier) and use resultproperty as prefix to store tokens. |
> separatearrayresults | When return value is an array, save result as property list ($resultproperty.[0..N] and $resultproperty.length) | `true`

> Get all Manager ObjectNames from all services and Hosts

>       <jmx:query
>                name="Catalina:type=Manager,*
>                resultproperty="manager" />

> Now you can find the Session Manager at ${manager.[0..N].name} properties and access the result object counter with ${manager.length} property.

> Example to get the Manager from servlet-examples application an bind all MBean properties

>       <jmx:query
>                name="Catalina:type=Manager,path=/servlet-examples,host=localhost*"
>                attributebinding="true"
>                resultproperty="manager.servletExamples" />

> Now you can find the manager at ${manager.servletExamples.0.name} property and can access all properties from this manager with ${manager.servletExamples.0.[manager attribute names]}. The result object counter from MBeans is stored ad ${manager.length} property.

> Example to get all MBeans from a server and store inside an external XML property file

>     <project name="jmx.query"
>                 xmlns:jmx="antlib:org.apache.catalina.ant.jmx"
>                 default="query-all" basedir=".">
>     <property name="jmx.host" value="localhost"/>
>     <property name="jmx.port" value="8050"/>
>     <property name="jmx.username" value="controlRole"/>
>     <property name="jmx.password" value="tomcat"/>

>     <target name="query-all" description="Query all MBeans of a server">
>     <!-- Configure connection -->
>     <jmx:open
>         host="${jmx.host}"
>         port="${jmx.port}"
>         ref="jmx.server"
>         username="${jmx.username}"
>         password="${jmx.password}"/>
>     <!-- Query MBean list -->
>     <jmx:query
>         name="*:*"
>         resultproperty="mbeans"
>         attributebinding="false"/>

>     <echoproperties
>         destfile="mbeans.properties"
>         prefix="mbeans."
>         format="xml"/>

>     <!-- Print results -->
>     <echo
>         message="Number of MBeans in server ${jmx.host}:${jmx.port} is ${mbeans.length}"/>
>     </target>
>     </project>

> Now you can find all MBeans inside the file mbeans.properties.

JMXAccessorCreateTask: remote create MBean Ant task

> List of Attributes

> Attribute | Description | Default value
> --- | --- | ---
> name | Full qualified JMX ObjectName -- Catalina:type=MBeanFactory |
> className | Existing MBean full qualified class name (see Tomcat MBean description above) |
> classLoader | ObjectName of server or web application classloader ( Catalina:type=ServerClassLoader,name=[server,common,shared] or Catalina:type=WebappClassLoader,path=/myapps,host=localhost) |
> ref | JMX Connection reference | `jmx.server`
> echo | Echo command usage (access and result) | `false`

> Example to create remote MBean

>         <jmx:create
>                  ref="${jmx.reference}"
>                  name="Catalina:type=MBeanFactory"
>                  className="org.apache.commons.modeler.BaseModelMBean"
>                  classLoader="Catalina:type=ServerClassLoader,name=server">
>                  <Arg value="org.apache.catalina.mbeans.MBeanFactory" />
>         </jmx:create>

> Warning: Many Tomcat MBeans can't be linked to their parent once
> created. The Valve, Cluster and Realm MBeans are not automatically
> connected with their parent. Use the MBeanFacrory create
> operation instead.

JMXAccessorUnregisterTask: remote unregister MBean Ant task

> List of Attributes

> Attribute | Description | Default value
> --- | --- | ---
> name | Full qualified JMX ObjectName -- Catalina:type=MBeanFactory |
> ref | JMX Connection reference | `jmx.server`
> echo | Echo command usage (access and result) | `false`

> Example to unregister remote MBean

>         <jmx:unregister
>             name="Catalina:type=MBeanFactory"
>         />

> Warning: A lot of Tomcat MBeans can't be unregister.
> The MBeans are not unlinked from their parent. Use MBeanFacrory
> remove operation instead.

JMXAccessorCondition: express condition

> List of Attributes

> Attribute | Description | Default value
> --- | --- | ---
> url | Set JMX connection URL - service:jmx:rmi:///jndi/rmi://localhost:8050/jmxrmi |
> host | Set the host, shortcut the very long URL syntax. | `localhost`
> port | Set the remote connection port | `8050`
> username | remote JMX connection user name. |
> password | remote JMX connection password. |
> ref | Name of the internal connection reference. With this attribute you can configure more the one connection inside the same Ant project. | `jmx.server`
> name | Full qualified JMX ObjectName -- Catalina:type=Server |
> echo | Echo condition usage (access and result) | `false`
> if | Only execute if a property of the given name exists in the current project. |
> unless | Only execute if a property of the given name not exists in the current project. |
> value (requiered) | Second arg for operation |
> type | Value type to express operation (support long and double) | `long`
> operation | express one
> - == equals
> - != not equals
> - > greater than (&gt;)
> - >= greater than or equals (&gt;=)
> - < lesser than (&lt;)
> - <= lesser than or equals (&lt;=)
> `==`

> Wait for server connection and that cluster backup node is accessable

>           <target name="wait">
>              <waitfor maxwait="${maxwait}" maxwaitunit="second" timeoutproperty="server.timeout" >
>                 <and>
>                     <socket server="${server.name}" port="${server.port}"/>
>                     <http url="${url}"/>
>                     <jmx:condition
>                         operation="=="
>                         host="localhost"
>                         port="9014"
>                         username="controlRole"
>                         password="tomcat"
>                         name="Catalina:type=IDataSender,host=localhost,senderAddress=192.168.111.1,senderPort=9025"
>                         attribute="connected"
>                         value="true"
>                     />
>                 </and>
>             </waitfor>
>             <fail if="server.timeout" message="Server ${url} don't answer inside ${maxwait} sec" />
>             <echo message="Server ${url} alive" />
>         </target>

JMXAccessorEqualsCondition: equals MBean Ant condition

> List of Attributes

> Attribute | Description | Default value
> --- | --- | ---
> url | Set JMX connection URL - service:jmx:rmi:///jndi/rmi://localhost:8050/jmxrmi |
> host | Set the host, shortcut the very long URL syntax. | `localhost`
> port | Set the remote connection port | `8050`
> username | remote JMX connection user name. |
> password | remote JMX connection password. |
> ref | Name of the internal connection reference. With this attribute you can configure more the one connection inside the same Ant project. | `jmx.server`
> name | Full qualified JMX ObjectName -- Catalina:type=Server |
> echo | Echo condition usage (access and result) | `false`

> Wait for server connection and that cluster backup node is accessible

>           <target name="wait">
>              <waitfor maxwait="${maxwait}" maxwaitunit="second" timeoutproperty="server.timeout" >
>                 <and>
>                     <socket server="${server.name}" port="${server.port}"/>
>                     <http url="${url}"/>
>                     <jmx:equals
>                         host="localhost"
>                         port="9014"
>                         username="controlRole"
>                         password="tomcat"
>                         name="Catalina:type=IDataSender,host=localhost,senderAddress=192.168.111.1,senderPort=9025"
>                         attribute="connected"
>                         value="true"
>                     />
>                 </and>
>             </waitfor>
>             <fail if="server.timeout" message="Server ${url} don't answer inside ${maxwait} sec" />
>             <echo message="Server ${url} alive" />
>         </target>

Copyright © 1999-2012, Apache Software Foundation