Details | Last modification | View Log | RSS feed
| Rev | Author | Line No. | Line |
|---|---|---|---|
| 771 | blopes | 1 | <!DOCTYPE html SYSTEM "about:legacy-compat"> |
| 2 | <html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="../images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 9 Configuration Reference (9.0.112) - The Manager Component</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="../images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="../images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 9 Configuration Reference</h1><div class="versionInfo"> |
||
| 3 | Version 9.0.112, |
||
| 4 | <time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul></div><div><h2>Top Level Elements</h2><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul></div><div><h2>Executors</h2><ul><li><a href="executor.html">Executor</a></li></ul></div><div><h2>Connectors</h2><ul><li><a href="http.html">HTTP/1.1</a></li><li><a href="http2.html">HTTP/2</a></li><li><a href="ajp.html">AJP</a></li></ul></div><div><h2>Containers</h2><ul><li><a href="context.html">Context</a></li><li><a href="engine.html">Engine</a></li><li><a href="host.html">Host</a></li><li><a href="cluster.html">Cluster</a></li></ul></div><div><h2>Nested Components</h2><ul><li><a href="cookie-processor.html">CookieProcessor</a></li><li><a href="credentialhandler.html">CredentialHandler</a></li><li><a href="globalresources.html">Global Resources</a></li><li><a href="jar-scanner.html">JarScanner</a></li><li><a href="jar-scan-filter.html">JarScanFilter</a></li><li><a href="listeners.html">Listeners</a></li><li><a href="loader.html">Loader</a></li><li><a href="manager.html">Manager</a></li><li><a href="realm.html">Realm</a></li><li><a href="resources.html">Resources</a></li><li><a href="sessionidgenerator.html">SessionIdGenerator</a></li><li><a href="valve.html">Valve</a></li></ul></div><div><h2>Cluster Elements</h2><ul><li><a href="cluster.html">Cluster</a></li><li><a href="cluster-manager.html">Manager</a></li><li><a href="cluster-channel.html">Channel</a></li><li><a href="cluster-membership.html">Channel/Membership</a></li><li><a href="cluster-sender.html">Channel/Sender</a></li><li><a href="cluster-receiver.html">Channel/Receiver</a></li><li><a href="cluster-interceptor.html">Channel/Interceptor</a></li><li><a href="cluster-valve.html">Valve</a></li><li><a href="cluster-deployer.html">Deployer</a></li><li><a href="cluster-listener.html">ClusterListener</a></li></ul></div><div><h2>web.xml</h2><ul><li><a href="filter.html">Filter</a></li></ul></div><div><h2>Other</h2><ul><li><a href="runtime-attributes.html">Runtime attributes</a></li><li><a href="systemprops.html">System properties</a></li><li><a href="jaspic.html">JASPIC</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>The Manager Component</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text"> |
||
| 5 | <ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li><li><a href="#Standard_Implementation">Standard Implementation</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Special_Features">Special Features</a><ol><li><a href="#Persistence_Across_Restarts">Persistence Across Restarts</a></li><li><a href="#Disable_Session_Persistence">Disable Session Persistence</a></li></ol></li></ul> |
||
| 6 | </div><h3 id="Introduction">Introduction</h3><div class="text"> |
||
| 7 | |||
| 8 | <p>The <strong>Manager</strong> element represents the <em>session |
||
| 9 | manager</em> that will be used to create and maintain HTTP sessions |
||
| 10 | as requested by the associated web application.</p> |
||
| 11 | |||
| 12 | <p>A Manager element MAY be nested inside a |
||
| 13 | <a href="context.html">Context</a> component. If it is not included, |
||
| 14 | a default Manager configuration will be created automatically, which |
||
| 15 | is sufficient for most requirements, — see |
||
| 16 | <em>Standard Manager Implementation</em> below for the details |
||
| 17 | of this configuration.</p> |
||
| 18 | |||
| 19 | </div><h3 id="Attributes">Attributes</h3><div class="text"> |
||
| 20 | |||
| 21 | <div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text"> |
||
| 22 | |||
| 23 | <p>All implementations of <strong>Manager</strong> |
||
| 24 | support the following attributes:</p> |
||
| 25 | |||
| 26 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 27 | Attribute |
||
| 28 | </th><th style="width: 85%;"> |
||
| 29 | Description |
||
| 30 | </th></tr><tr id="Attributes_Common Attributes_className"><td><code class="attributeName">className</code></td><td> |
||
| 31 | <p>Java class name of the implementation to use. This class must |
||
| 32 | implement the <code>org.apache.catalina.Manager</code> interface. |
||
| 33 | If not specified, the standard value (defined below) will be used.</p> |
||
| 34 | </td></tr><tr id="Attributes_Common Attributes_maxActiveSessions"><td><code class="attributeName">maxActiveSessions</code></td><td> |
||
| 35 | <p>The maximum number of active sessions that will be created by |
||
| 36 | this Manager, or <code>-1</code> (the default) for no limit.</p> |
||
| 37 | |||
| 38 | <p>When the limit is reached, any attempt to create a new session |
||
| 39 | (e.g. with <code>HttpServletRequest.getSession()</code> call) |
||
| 40 | will fail with an <code>IllegalStateException</code>.</p> |
||
| 41 | </td></tr><tr id="Attributes_Common Attributes_notifyAttributeListenerOnUnchangedValue"><td><code class="attributeName">notifyAttributeListenerOnUnchangedValue</code></td><td> |
||
| 42 | <p>If an attribute is added to the session and that attribute is already |
||
| 43 | present in the session under the same name will any |
||
| 44 | <code>HttpSessionAttributeListener</code> be notified that the attribute |
||
| 45 | has been replaced. If not specified, the default value of |
||
| 46 | <code>true</code> will be used.</p> |
||
| 47 | </td></tr><tr id="Attributes_Common Attributes_notifyBindingListenerOnUnchangedValue"><td><code class="attributeName">notifyBindingListenerOnUnchangedValue</code></td><td> |
||
| 48 | <p>If an attribute is added to the session, that attribute is already |
||
| 49 | present in the session under the same name and the attribute implements |
||
| 50 | <code>HttpSessionBindingListener</code>, will the listener be notified |
||
| 51 | that the attribute has been unbound and bound again. If not specified, |
||
| 52 | the default value of <code>false</code> will be used.</p> |
||
| 53 | </td></tr></table> |
||
| 54 | |||
| 55 | </div></div> |
||
| 56 | |||
| 57 | |||
| 58 | <div class="subsection"><h4 id="Standard_Implementation">Standard Implementation</h4><div class="text"> |
||
| 59 | |||
| 60 | <p>Tomcat provides two standard implementations of <strong>Manager</strong> |
||
| 61 | for use — the default one stores active sessions, while the optional one |
||
| 62 | stores active sessions that have been swapped out (in addition to saving |
||
| 63 | sessions across a restart of Tomcat) in a storage location that is selected |
||
| 64 | via the use of an appropriate <strong>Store</strong> nested element.</p> |
||
| 65 | |||
| 66 | <h3>Standard Manager Implementation</h3> |
||
| 67 | |||
| 68 | <p>The standard implementation of <strong>Manager</strong> is |
||
| 69 | <strong>org.apache.catalina.session.StandardManager</strong>. |
||
| 70 | It supports the following additional attributes (in addition to the |
||
| 71 | common attributes listed above):</p> |
||
| 72 | |||
| 73 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 74 | Attribute |
||
| 75 | </th><th style="width: 85%;"> |
||
| 76 | Description |
||
| 77 | </th></tr><tr id="Attributes_Standard Implementation_pathname"><td><code class="attributeName">pathname</code></td><td> |
||
| 78 | <p>Absolute or relative (to the work directory for this Context) |
||
| 79 | pathname of the file in which session state will be preserved |
||
| 80 | across application restarts, if possible. The default is |
||
| 81 | "SESSIONS.ser".<br>See |
||
| 82 | <a href="#Persistence_Across_Restarts">Persistence Across Restarts</a> |
||
| 83 | for more information. This persistence may be |
||
| 84 | disabled by setting this attribute to an empty string.</p> |
||
| 85 | </td></tr><tr id="Attributes_Standard Implementation_persistAuthentication"><td><code class="attributeName">persistAuthentication</code></td><td> |
||
| 86 | <p>Should authentication information be included when session state is |
||
| 87 | preserved across application restarts? If <code>true</code>, the session's |
||
| 88 | authentication is preserved so that the session remains authenticated |
||
| 89 | after the application has been restarted. If not specified, the default |
||
| 90 | value of <code>false</code> will be used.<br>See |
||
| 91 | <a href="#Persistence_Across_Restarts">Persistence Across Restarts</a> |
||
| 92 | for more information.</p> |
||
| 93 | |||
| 94 | <p>Please note that the session's <code>Principal</code> class as well |
||
| 95 | as its descendant classes are all subject to the |
||
| 96 | <strong>sessionAttributeValueClassNameFilter</strong>. If such a filter |
||
| 97 | is specified or a <code>SecurityManager</code> is enabled, the names of |
||
| 98 | the <code>Principal</code> class and descendant classes must match that |
||
| 99 | filter pattern in order to be restored.</p> |
||
| 100 | </td></tr><tr id="Attributes_Standard Implementation_persistAuthenticationNotes"><td><code class="attributeName">persistAuthenticationNotes</code></td><td> |
||
| 101 | <p>Should authentication notes (used during FORM authentication) be |
||
| 102 | included when session state is preserved across application restarts? |
||
| 103 | If <code>true</code>, the session's authentication notes are preserved |
||
| 104 | so that an in progress FORM authentication can continue after the |
||
| 105 | application has been restarted. If not specified, the default value of |
||
| 106 | <code>false</code> will be used.<br>See |
||
| 107 | <a href="#Persistence_Across_Restarts">Persistence Across Restarts</a> |
||
| 108 | for more information.</p> |
||
| 109 | </td></tr><tr id="Attributes_Standard Implementation_processExpiresFrequency"><td><code class="attributeName">processExpiresFrequency</code></td><td> |
||
| 110 | <p>Frequency of the session expiration, and related manager operations. |
||
| 111 | Manager operations will be done once for the specified amount of |
||
| 112 | backgroundProcess calls (i.e., the lower the amount, the more often the |
||
| 113 | checks will occur). The minimum value is 1, and the default value is 6. |
||
| 114 | </p> |
||
| 115 | </td></tr><tr id="Attributes_Standard Implementation_secureRandomClass"><td><code class="attributeName">secureRandomClass</code></td><td> |
||
| 116 | <p>Name of the Java class that extends |
||
| 117 | <code>java.security.SecureRandom</code> to use to generate session IDs. |
||
| 118 | If not specified, the default value is |
||
| 119 | <code>java.security.SecureRandom</code>.</p> |
||
| 120 | </td></tr><tr id="Attributes_Standard Implementation_secureRandomProvider"><td><code class="attributeName">secureRandomProvider</code></td><td> |
||
| 121 | <p>Name of the provider to use to create the |
||
| 122 | <code>java.security.SecureRandom</code> instances that generate session |
||
| 123 | IDs. If an invalid algorithm and/or provider is specified, the Manager |
||
| 124 | will use the platform default provider and the default algorithm. If not |
||
| 125 | specified, the platform default provider will be used.</p> |
||
| 126 | </td></tr><tr id="Attributes_Standard Implementation_secureRandomAlgorithm"><td><code class="attributeName">secureRandomAlgorithm</code></td><td> |
||
| 127 | <p>Name of the algorithm to use to create the |
||
| 128 | <code>java.security.SecureRandom</code> instances that generate session |
||
| 129 | IDs. If an invalid algorithm and/or provider is specified, the Manager |
||
| 130 | will use the platform default provider and the default algorithm. If not |
||
| 131 | specified, the default algorithm of SHA1PRNG will be used. If the |
||
| 132 | default algorithm is not supported, the platform default will be used. |
||
| 133 | To specify that the platform default should be used, do not set the |
||
| 134 | secureRandomProvider attribute and set this attribute to the empty |
||
| 135 | string.</p> |
||
| 136 | </td></tr><tr id="Attributes_Standard Implementation_sessionAttributeNameFilter"><td><code class="attributeName">sessionAttributeNameFilter</code></td><td> |
||
| 137 | <p>A regular expression used to filter which session attributes will be |
||
| 138 | serialized for clustering/replication, or storage to any persistent store. |
||
| 139 | An attribute will only be serialized if its name matches |
||
| 140 | this pattern. If the pattern is zero length or <code>null</code>, all |
||
| 141 | attributes are eligible for distribution. The pattern is anchored so the |
||
| 142 | session attribute name must fully match the pattern. As an example, the |
||
| 143 | value <code>(userName|sessionHistory)</code> will only distribute the |
||
| 144 | two session attributes named <code>userName</code> and |
||
| 145 | <code>sessionHistory</code>. If not specified, the default value of |
||
| 146 | <code>null</code> will be used.</p> |
||
| 147 | </td></tr><tr id="Attributes_Standard Implementation_sessionAttributeValueClassNameFilter"><td><code class="attributeName">sessionAttributeValueClassNameFilter</code></td><td> |
||
| 148 | <p>A regular expression used to filter which session attributes will be |
||
| 149 | serialized for clustering/replication, or storage to any persistent store. |
||
| 150 | An attribute will only be serialized if the implementation |
||
| 151 | class name of the value matches this pattern. If the pattern is zero |
||
| 152 | length or <code>null</code>, all attributes are eligible for |
||
| 153 | distribution. The pattern is anchored so the fully qualified class name |
||
| 154 | must fully match the pattern. If not specified, the default value of |
||
| 155 | <code>null</code> will be used unless a <code>SecurityManager</code> is |
||
| 156 | enabled in which case the default will be |
||
| 157 | <code>java\\.lang\\.(?:Boolean|Integer|Long|Number|String)|org\\.apache\\.catalina\\.realm\\.GenericPrincipal\\$SerializablePrincipal|\\[Ljava.lang.String;</code>.</p> |
||
| 158 | </td></tr><tr id="Attributes_Standard Implementation_warnOnSessionAttributeFilterFailure"><td><code class="attributeName">warnOnSessionAttributeFilterFailure</code></td><td> |
||
| 159 | <p>If <strong>sessionAttributeNameFilter</strong> or |
||
| 160 | <strong>sessionAttributeValueClassNameFilter</strong> blocks an |
||
| 161 | attribute, should this be logged at <code>WARN</code> level? If |
||
| 162 | <code>WARN</code> level logging is disabled then it will be logged at |
||
| 163 | <code>DEBUG</code>. The default value of this attribute is |
||
| 164 | <code>false</code> unless a <code>SecurityManager</code> is enabled in |
||
| 165 | which case the default will be <code>true</code>.</p> |
||
| 166 | </td></tr></table> |
||
| 167 | |||
| 168 | <h3>Persistent Manager Implementation</h3> |
||
| 169 | |||
| 170 | <p><strong>NOTE:</strong> You must set either the |
||
| 171 | <code>org.apache.catalina.session.StandardSession.ACTIVITY_CHECK</code> or |
||
| 172 | <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> |
||
| 173 | <a href="systemprops.html">system properties</a> to <code>true</code> for |
||
| 174 | the persistent manager to work correctly.</p> |
||
| 175 | |||
| 176 | <p>The persistent implementation of <strong>Manager</strong> is |
||
| 177 | <strong>org.apache.catalina.session.PersistentManager</strong>. In |
||
| 178 | addition to the usual operations of creating and deleting sessions, a |
||
| 179 | <code>PersistentManager</code> has the capability to swap active (but |
||
| 180 | idle) sessions out to a persistent storage mechanism, as well as to save |
||
| 181 | all sessions across a normal restart of Tomcat. The actual persistent |
||
| 182 | storage mechanism used is selected by your choice of a |
||
| 183 | <strong>Store</strong> element nested inside the <strong>Manager</strong> |
||
| 184 | element - this is required for use of <code>PersistentManager</code>.</p> |
||
| 185 | |||
| 186 | <p>This implementation of Manager supports the following attributes in |
||
| 187 | addition to the <a href="#Common_Attributes">Common Attributes</a> |
||
| 188 | described earlier.</p> |
||
| 189 | |||
| 190 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 191 | Attribute |
||
| 192 | </th><th style="width: 85%;"> |
||
| 193 | Description |
||
| 194 | </th></tr><tr id="Attributes_Standard Implementation_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 195 | <p>It has the same meaning as described in the |
||
| 196 | <a href="#Common_Attributes">Common Attributes</a> above. |
||
| 197 | You <strong>must</strong> specify |
||
| 198 | <code>org.apache.catalina.session.PersistentManager</code> to use |
||
| 199 | this manager implementation.</p> |
||
| 200 | </td></tr><tr id="Attributes_Standard Implementation_maxIdleBackup"><td><code class="attributeName">maxIdleBackup</code></td><td> |
||
| 201 | <p>The time interval (in seconds) since the last access to a session |
||
| 202 | before it is eligible for being persisted to the session store, or |
||
| 203 | <code>-1</code> to disable this feature. By default, this feature is |
||
| 204 | disabled.</p> |
||
| 205 | </td></tr><tr id="Attributes_Standard Implementation_maxIdleSwap"><td><code class="attributeName">maxIdleSwap</code></td><td> |
||
| 206 | <p>The maximum time a session may be idle before it is eligible to be |
||
| 207 | swapped to disk due to inactivity. Setting this to <code>-1</code> means |
||
| 208 | sessions should not be swapped out just because of inactivity. If this |
||
| 209 | feature is enabled, the time interval specified here should be equal to |
||
| 210 | or longer than the value specified for <code>maxIdleBackup</code>. By |
||
| 211 | default, this feature is disabled.</p> |
||
| 212 | </td></tr><tr id="Attributes_Standard Implementation_minIdleSwap"><td><code class="attributeName">minIdleSwap</code></td><td> |
||
| 213 | <p>The minimum time in seconds a session must be idle before it is |
||
| 214 | eligible to be swapped to disk to keep the active session count below |
||
| 215 | maxActiveSessions. Setting to <code>-1</code> means sessions will not be |
||
| 216 | swapped out to keep the active session count down. If specified, this |
||
| 217 | value should be less than that specified by <code>maxIdleSwap</code>. |
||
| 218 | By default, this value is set to <code>-1</code>.</p> |
||
| 219 | </td></tr><tr id="Attributes_Standard Implementation_persistAuthentication"><td><code class="attributeName">persistAuthentication</code></td><td> |
||
| 220 | <p>Should authentication information be included when sessions are |
||
| 221 | swapped out to persistent storage? If <code>true</code>, the session's |
||
| 222 | authentication is preserved so that the session remains authenticated |
||
| 223 | after being reloaded (swapped in) from persistent storage. If not |
||
| 224 | specified, the default value of <code>false</code> will be used.</p> |
||
| 225 | |||
| 226 | <p>Please note that the session's <code>Principal</code> class as well |
||
| 227 | as its descendant classes are all subject to the |
||
| 228 | <strong>sessionAttributeValueClassNameFilter</strong>. If such a filter |
||
| 229 | is specified or a <code>SecurityManager</code> is enabled, the names of |
||
| 230 | the <code>Principal</code> class and descendant classes must match that |
||
| 231 | filter pattern in order to be restored.</p> |
||
| 232 | </td></tr><tr id="Attributes_Standard Implementation_persistAuthenticationNotes"><td><code class="attributeName">persistAuthenticationNotes</code></td><td> |
||
| 233 | <p>Should authentication notes (used during FORM authentication) be |
||
| 234 | included when sessions are swapped out to persistent storage? If |
||
| 235 | <code>true</code>, the session's authentication notes (used during |
||
| 236 | FORM authentication) are preserved so that an in progress FORM |
||
| 237 | authentication can continue after being reloaded (swapped in) from |
||
| 238 | persistent storage. If not specified, the default value of |
||
| 239 | <code>false</code> will be used.</p> |
||
| 240 | |||
| 241 | <p>Please note that if it is possible that the session will be swapped |
||
| 242 | in to a different node to the node from which it was swapped out, all |
||
| 243 | nodes must be upgraded to at least 9.0.66 (the version where this |
||
| 244 | feature was introduced) before this feature is enabled else the swapping |
||
| 245 | in may fail.</p> |
||
| 246 | |||
| 247 | <p>This attribute has been removed for Tomcat 10.1.x onwards which |
||
| 248 | always persists FORM authenticaton notes.</p> |
||
| 249 | </td></tr><tr id="Attributes_Standard Implementation_processExpiresFrequency"><td><code class="attributeName">processExpiresFrequency</code></td><td> |
||
| 250 | <p>It is the same as described above for the |
||
| 251 | <code>org.apache.catalina.session.StandardManager</code> class. |
||
| 252 | </p> |
||
| 253 | </td></tr><tr id="Attributes_Standard Implementation_saveOnRestart"><td><code class="attributeName">saveOnRestart</code></td><td> |
||
| 254 | <p>Should all sessions be persisted and reloaded when Tomcat is shut |
||
| 255 | down and restarted (or when this application is reloaded)? By default, |
||
| 256 | this attribute is set to <code>true</code>.</p> |
||
| 257 | </td></tr><tr id="Attributes_Standard Implementation_secureRandomClass"><td><code class="attributeName">secureRandomClass</code></td><td> |
||
| 258 | <p>It is the same as described above for the |
||
| 259 | <code>org.apache.catalina.session.StandardManager</code> class. |
||
| 260 | </p> |
||
| 261 | </td></tr><tr id="Attributes_Standard Implementation_secureRandomProvider"><td><code class="attributeName">secureRandomProvider</code></td><td> |
||
| 262 | <p>It is the same as described above for the |
||
| 263 | <code>org.apache.catalina.session.StandardManager</code> class. |
||
| 264 | </p> |
||
| 265 | </td></tr><tr id="Attributes_Standard Implementation_secureRandomAlgorithm"><td><code class="attributeName">secureRandomAlgorithm</code></td><td> |
||
| 266 | <p>It is the same as described above for the |
||
| 267 | <code>org.apache.catalina.session.StandardManager</code> class. |
||
| 268 | </p> |
||
| 269 | </td></tr><tr id="Attributes_Standard Implementation_sessionAttributeNameFilter"><td><code class="attributeName">sessionAttributeNameFilter</code></td><td> |
||
| 270 | <p>A regular expression used to filter which session attributes will be |
||
| 271 | serialized for clustering/replication, or storage to any persistent store. |
||
| 272 | An attribute will only be serialized if its name matches |
||
| 273 | this pattern. If the pattern is zero length or <code>null</code>, all |
||
| 274 | attributes are eligible for distribution. The pattern is anchored so the |
||
| 275 | session attribute name must fully match the pattern. As an example, the |
||
| 276 | value <code>(userName|sessionHistory)</code> will only distribute the |
||
| 277 | two session attributes named <code>userName</code> and |
||
| 278 | <code>sessionHistory</code>. If not specified, the default value of |
||
| 279 | <code>null</code> will be used.</p> |
||
| 280 | </td></tr><tr id="Attributes_Standard Implementation_sessionAttributeValueClassNameFilter"><td><code class="attributeName">sessionAttributeValueClassNameFilter</code></td><td> |
||
| 281 | <p>A regular expression used to filter which session attributes will be |
||
| 282 | serialized for clustering/replication, or storage to any persistent store. |
||
| 283 | An attribute will only be serialized if the implementation |
||
| 284 | class name of the value matches this pattern. If the pattern is zero |
||
| 285 | length or <code>null</code>, all attributes are eligible for |
||
| 286 | distribution. The pattern is anchored so the fully qualified class name |
||
| 287 | must fully match the pattern. If not specified, the default value of |
||
| 288 | <code>null</code> will be used unless a <code>SecurityManager</code> is |
||
| 289 | enabled in which case the default will be |
||
| 290 | <code>java\\.lang\\.(?:Boolean|Integer|Long|Number|String)|org\\.apache\\.catalina\\.realm\\.GenericPrincipal\\$SerializablePrincipal|\\[Ljava.lang.String;</code>.</p> |
||
| 291 | </td></tr><tr id="Attributes_Standard Implementation_warnOnSessionAttributeFilterFailure"><td><code class="attributeName">warnOnSessionAttributeFilterFailure</code></td><td> |
||
| 292 | <p>If <strong>sessionAttributeNameFilter</strong> or |
||
| 293 | <strong>sessionAttributeValueClassNameFilter</strong> blocks an |
||
| 294 | attribute, should this be logged at <code>WARN</code> level? If |
||
| 295 | <code>WARN</code> level logging is disabled then it will be logged at |
||
| 296 | <code>DEBUG</code>. The default value of this attribute is |
||
| 297 | <code>false</code> unless a <code>SecurityManager</code> is enabled in |
||
| 298 | which case the default will be <code>true</code>.</p> |
||
| 299 | </td></tr></table> |
||
| 300 | |||
| 301 | <p>In order to successfully use a PersistentManager, you must nest inside |
||
| 302 | it a <strong><Store></strong> element, as described below.</p> |
||
| 303 | |||
| 304 | </div></div> |
||
| 305 | |||
| 306 | |||
| 307 | </div><h3 id="Nested_Components">Nested Components</h3><div class="text"> |
||
| 308 | |||
| 309 | <h3>All Manager Implementations</h3> |
||
| 310 | |||
| 311 | <p>All Manager implementations allow nesting of a |
||
| 312 | <strong><SessionIdGenerator></strong> element. It defines |
||
| 313 | the behavior of session id generation. All implementations |
||
| 314 | of the <a href="sessionidgenerator.html">SessionIdGenerator</a> allow the |
||
| 315 | following attributes: |
||
| 316 | </p> |
||
| 317 | |||
| 318 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 319 | Attribute |
||
| 320 | </th><th style="width: 85%;"> |
||
| 321 | Description |
||
| 322 | </th></tr><tr id="_Nested Components_sessionIdLength"><td><code class="attributeName">sessionIdLength</code></td><td> |
||
| 323 | <p>The length of the session ID may be changed with the |
||
| 324 | <strong>sessionIdLength</strong> attribute. |
||
| 325 | </p> |
||
| 326 | </td></tr></table> |
||
| 327 | |||
| 328 | <h3>Persistent Manager Implementation</h3> |
||
| 329 | |||
| 330 | <p>If you are using the <em>Persistent Manager Implementation</em> |
||
| 331 | as described above, you <strong>MUST</strong> nest a |
||
| 332 | <strong><Store></strong> element inside, which defines the |
||
| 333 | characteristics of the persistent data storage. Two implementations |
||
| 334 | of the <code><Store></code> element are currently available, |
||
| 335 | with different characteristics, as described below.</p> |
||
| 336 | |||
| 337 | <h5>File Based Store</h5> |
||
| 338 | |||
| 339 | <p>The <em>File Based Store</em> implementation saves swapped out |
||
| 340 | sessions in individual files (named based on the session identifier) |
||
| 341 | in a configurable directory. Therefore, you are likely to encounter |
||
| 342 | scalability problems as the number of active sessions increases, and |
||
| 343 | this should primarily be considered a means to easily experiment.</p> |
||
| 344 | |||
| 345 | <p>To configure this, add a <code><Store></code> nested inside |
||
| 346 | your <code><Manager></code> element with the following attributes: |
||
| 347 | </p> |
||
| 348 | |||
| 349 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 350 | Attribute |
||
| 351 | </th><th style="width: 85%;"> |
||
| 352 | Description |
||
| 353 | </th></tr><tr id="_Nested Components_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 354 | <p>Java class name of the implementation to use. This class must |
||
| 355 | implement the <code>org.apache.catalina.Store</code> interface. You |
||
| 356 | <strong>must</strong> specify |
||
| 357 | <code>org.apache.catalina.session.FileStore</code> |
||
| 358 | to use this implementation.</p> |
||
| 359 | </td></tr><tr id="_Nested Components_directory"><td><code class="attributeName">directory</code></td><td> |
||
| 360 | <p>Absolute or relative (to the temporary work directory for this web |
||
| 361 | application) pathname of the directory into which individual session |
||
| 362 | files are written. If not specified, the temporary work directory |
||
| 363 | assigned by the container is utilized.</p> |
||
| 364 | </td></tr></table> |
||
| 365 | |||
| 366 | |||
| 367 | <h5>Data source Based Store</h5> |
||
| 368 | |||
| 369 | <p>The <em>Data source Based Store</em> implementation saves swapped out |
||
| 370 | sessions in individual rows of a preconfigured table in a database |
||
| 371 | that is accessed via a data sourcer. With large numbers of swapped out |
||
| 372 | sessions, this implementation will exhibit improved performance over |
||
| 373 | the File Based Store described above.</p> |
||
| 374 | |||
| 375 | <p>To configure this, add a <code><Store></code> nested inside |
||
| 376 | your <code><Manager></code> element with the following attributes: |
||
| 377 | </p> |
||
| 378 | |||
| 379 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 380 | Attribute |
||
| 381 | </th><th style="width: 85%;"> |
||
| 382 | Description |
||
| 383 | </th></tr><tr id="_Nested Components_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 384 | <p>Java class name of the implementation to use. This class must |
||
| 385 | implement the <code>org.apache.catalina.Store</code> interface. You |
||
| 386 | <strong>must</strong> specify |
||
| 387 | <code>org.apache.catalina.session.DataSourceStore</code> |
||
| 388 | to use this implementation.</p> |
||
| 389 | </td></tr><tr id="_Nested Components_dataSourceName"><td><code class="attributeName">dataSourceName</code></td><td> |
||
| 390 | <p>Name of the JNDI resource for a JDBC DataSource-factory. Since this |
||
| 391 | code uses prepared statements, you might want to configure pooled |
||
| 392 | prepared statements as shown in |
||
| 393 | <a href="../jndi-resources-howto.html">the JNDI resources |
||
| 394 | How-To</a>.</p> |
||
| 395 | </td></tr><tr id="_Nested Components_localDataSource"><td><code class="attributeName">localDataSource</code></td><td> |
||
| 396 | <p>This allows the Store to use a DataSource defined for the Context |
||
| 397 | rather than a global DataSource. If not specified, the default is |
||
| 398 | <code>false</code>: use a global DataSource.</p> |
||
| 399 | </td></tr><tr id="_Nested Components_sessionAppCol"><td><code class="attributeName">sessionAppCol</code></td><td> |
||
| 400 | <p>Name of the database column, contained in the specified session table, |
||
| 401 | that contains the Engine, Host, and Web Application Context name in the |
||
| 402 | format <code>/Engine/Host/Context</code>. If not specified the default |
||
| 403 | value of <code>app</code> will be used.</p> |
||
| 404 | </td></tr><tr id="_Nested Components_sessionDataCol"><td><code class="attributeName">sessionDataCol</code></td><td> |
||
| 405 | <p>Name of the database column, contained in the specified session table, |
||
| 406 | that contains the serialized form of all session attributes for a swapped |
||
| 407 | out session. The column type must accept a binary object (typically called |
||
| 408 | a BLOB). If not specified the default value of <code>data</code> will be |
||
| 409 | used.</p> |
||
| 410 | </td></tr><tr id="_Nested Components_sessionIdCol"><td><code class="attributeName">sessionIdCol</code></td><td> |
||
| 411 | <p>Name of the database column, contained in the specified session table, |
||
| 412 | that contains the session identifier of the swapped out session. The |
||
| 413 | column type must accept character string data of at least as many |
||
| 414 | characters as are contained in session identifiers created by Tomcat |
||
| 415 | (typically 32). If not specified the default value of <code>id</code> will |
||
| 416 | be used.</p> |
||
| 417 | </td></tr><tr id="_Nested Components_sessionLastAccessedCol"><td><code class="attributeName">sessionLastAccessedCol</code></td><td> |
||
| 418 | <p>Name of the database column, contained in the specified session table, |
||
| 419 | that contains the <code>lastAccessedTime</code> property of this session. |
||
| 420 | The column type must accept a Java <code>long</code> (64 bits). If not |
||
| 421 | specified the default value of <code>maxinactive</code> will be used.</p> |
||
| 422 | </td></tr><tr id="_Nested Components_sessionMaxInactiveCol"><td><code class="attributeName">sessionMaxInactiveCol</code></td><td> |
||
| 423 | <p>Name of the database column, contained in the specified session table, |
||
| 424 | that contains the <code>maxInactiveInterval</code> property of this |
||
| 425 | session. The column type must accept a Java <code>integer</code> (32 |
||
| 426 | bits). If not specified, the default value of <code>maxinactive</code> |
||
| 427 | will be used.</p> |
||
| 428 | </td></tr><tr id="_Nested Components_sessionTable"><td><code class="attributeName">sessionTable</code></td><td> |
||
| 429 | <p>Name of the database table to be used for storing swapped out sessions. |
||
| 430 | This table must contain (at least) the database columns that are |
||
| 431 | configured by the other attributes of this element. If not specified the |
||
| 432 | default value of <code>tomcat$sessions</code> will be used.</p> |
||
| 433 | </td></tr><tr id="_Nested Components_sessionValidCol"><td><code class="attributeName">sessionValidCol</code></td><td> |
||
| 434 | <p>Name of the database column, contained in the specified session table, |
||
| 435 | that contains a flag indicating whether this swapped out session is still |
||
| 436 | valid or not. The column type must accept a single character. If not |
||
| 437 | specified the default value of <code>valid</code> will be used.</p> |
||
| 438 | </td></tr></table> |
||
| 439 | |||
| 440 | <p>Before attempting to use the data source Store for the first time, |
||
| 441 | you must create the table that will be used to store swapped out sessions. |
||
| 442 | Detailed SQL commands vary depending on the database you are using, but |
||
| 443 | a script like this will generally be required:</p> |
||
| 444 | |||
| 445 | <div class="codeBox"><pre><code>create table tomcat_sessions ( |
||
| 446 | session_id varchar(100) not null primary key, |
||
| 447 | valid_session char(1) not null, |
||
| 448 | max_inactive int not null, |
||
| 449 | last_access bigint not null, |
||
| 450 | app_name varchar(255), |
||
| 451 | session_data mediumblob, |
||
| 452 | KEY kapp_name(app_name) |
||
| 453 | );</code></pre></div> |
||
| 454 | |||
| 455 | <p>Note: The SQL command above does not use the default names for either the |
||
| 456 | table or the columns so the data source Store would need to be configured |
||
| 457 | to reflect this.</p> |
||
| 458 | |||
| 459 | </div><h3 id="Special_Features">Special Features</h3><div class="text"> |
||
| 460 | |||
| 461 | |||
| 462 | <div class="subsection"><h4 id="Persistence_Across_Restarts">Persistence Across Restarts</h4><div class="text"> |
||
| 463 | |||
| 464 | <p>Whenever Apache Tomcat is shut down normally and restarted, or when an |
||
| 465 | application reload is triggered, the standard Manager implementation |
||
| 466 | will attempt to serialize all currently active sessions to a disk |
||
| 467 | file located via the <code>pathname</code> attribute. All such saved |
||
| 468 | sessions will then be deserialized and activated (assuming they have |
||
| 469 | not expired in the mean time) when the application reload is completed.</p> |
||
| 470 | |||
| 471 | <p>In order to successfully restore the state of session attributes, |
||
| 472 | all such attributes MUST implement the <code>java.io.Serializable</code> |
||
| 473 | interface. You MAY cause the Manager to enforce this restriction by |
||
| 474 | including the <code><distributable></code> element in your web |
||
| 475 | application deployment descriptor (<code>/WEB-INF/web.xml</code>).</p> |
||
| 476 | |||
| 477 | <p>Note that, if <strong>persistAuthentication</strong> is also set to |
||
| 478 | <code>true</code>, the <code>Principal</code> class present in the session |
||
| 479 | MUST also implement the <code>java.io.Serializable</code> interface in order |
||
| 480 | to make authentication persistence work properly. The actual type of that |
||
| 481 | <code>Principal</code> class is determined by the <a href="realm.html"> |
||
| 482 | Realm</a> implementation used with the application. Tomcat's standard |
||
| 483 | <code>Principal</code> class instantiated by most of the Realms (except |
||
| 484 | <code>JAASRealm</code>) implements <code>java.io.Serializable</code>.</p> |
||
| 485 | |||
| 486 | <p>The persistence across restarts provided by the |
||
| 487 | <strong>StandardManager</strong> is a simpler implementation than that |
||
| 488 | provided by the <strong>PersistentManager</strong>. If robust, production |
||
| 489 | quality persistence across restarts is required then the |
||
| 490 | <strong>PersistentManager</strong> should be used with an appropriate |
||
| 491 | configuration.</p> |
||
| 492 | |||
| 493 | </div></div> |
||
| 494 | |||
| 495 | <div class="subsection"><h4 id="Disable_Session_Persistence">Disable Session Persistence</h4><div class="text"> |
||
| 496 | |||
| 497 | <p>As documented above, every web application by default has |
||
| 498 | standard manager implementation configured, and it performs session |
||
| 499 | persistence across restarts. To disable this persistence feature, create |
||
| 500 | a <a href="context.html">Context</a> configuration file for your web |
||
| 501 | application and add the following element there:</p> |
||
| 502 | |||
| 503 | <div class="codeBox"><pre><code><Manager pathname="" /></code></pre></div> |
||
| 504 | </div></div> |
||
| 505 | |||
| 506 | </div></div></div></div></div><footer><div id="footer"> |
||
| 507 | Copyright © 1999-2025, The Apache Software Foundation |
||
| 508 | <br> |
||
| 509 | Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo |
||
| 510 | are either registered trademarks or trademarks of the Apache Software |
||
| 511 | Foundation. |
||
| 512 | </div></footer></div></body></html> |