View | Details | Raw Unified | Return to bug 55383
Collapse All | Expand All

(-)webapps/docs/images/docs-stylesheet.css (-5 / +15 lines)
Lines 184-198 Link Here
184
184
185
code {
185
code {
186
  background-color: rgb(224,255,255);
186
  background-color: rgb(224,255,255);
187
  padding: 0 0.1em;
188
}
187
}
189
188
190
div.codeBox pre code, code.attributeName, code.propertyName {
189
div.codeBox pre code, code.attributeName, code.propertyName, code.noHighlight {
191
  background-color: transparent;
190
  background-color: transparent;
192
}
191
}
193
div.codeBox {
192
div.codeBox {
194
  overflow: auto;
193
  overflow: auto;
195
  /* TODO: Maybe add margin-top and margin-bottom like with <p> */
194
  margin: 1em 0;
196
}
195
}
197
div.codeBox pre {
196
div.codeBox pre {
198
  margin: 0;
197
  margin: 0;
Lines 214-219 Link Here
214
}
213
}
215
214
216
215
216
table.defaultTable tr {
217
    border: 1px solid #CCC;
218
}
219
220
table.defaultTable tr:nth-child(even) {
221
    background-color: #FAFBFF;
222
}
223
224
table.defaultTable tr:nth-child(odd) {
225
    background-color: #EEEFFF;
226
}
227
217
table.defaultTable th {
228
table.defaultTable th {
218
  background-color: #88b;
229
  background-color: #88b;
219
  color: #fff;
230
  color: #fff;
Lines 228-235 Link Here
228
}
239
}
229
240
230
table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td {
241
table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td {
231
  border: 1px solid #777;
242
  padding: 5px 8px;
232
  padding: 5px;
233
  text-align: left;
243
  text-align: left;
234
}
244
}
235
245
(-)webapps/docs/maven-jars.xml (-5 / +9 lines)
Lines 38-50 Link Here
38
      Tomcat snapshots are located in the
38
      Tomcat snapshots are located in the
39
      <a href="http://people.apache.org/repo/m2-snapshot-repository/org/apache/tomcat/">Apache Snapshot Repository</a>.
39
      <a href="http://people.apache.org/repo/m2-snapshot-repository/org/apache/tomcat/">Apache Snapshot Repository</a>.
40
      The official URL is <source>http://people.apache.org/repo/m2-snapshot-repository/org/apache/tomcat/</source>
40
      The official URL is <source>http://people.apache.org/repo/m2-snapshot-repository/org/apache/tomcat/</source>
41
      Snapshots are done periodically, not on a regular basis, but when changes happen and the Tomcat team deems a new snapshot might
41
      <p>
42
      useful.
42
        Snapshots are done periodically, not on a regular basis, but when changes happen and the Tomcat team deems a new snapshot might
43
        useful.
44
      </p>
43
    </subsection>
45
    </subsection>
44
    <subsection name="Tomcat Releases">
46
    <subsection name="Tomcat Releases">
45
      Stable releases are published to the
47
      <p>
46
      <a href="http://repo2.maven.org/maven2/org/apache/tomcat/">Central
48
        Stable releases are published to the
47
      Maven Repositories</a>. The URL for this is
49
        <a href="http://repo2.maven.org/maven2/org/apache/tomcat/">Central
50
        Maven Repositories</a>. The URL for this is
51
      </p>
48
      <source>http://repo2.maven.org/maven2/org/apache/tomcat/</source>
52
      <source>http://repo2.maven.org/maven2/org/apache/tomcat/</source>
49
    </subsection>
53
    </subsection>
50
54
(-)webapps/docs/mbeans-descriptor-howto.xml (-9 / +7 lines)
Lines 52-79 Link Here
52
a mbeans-descriptor.xml file, located in the same package as the class files
52
a mbeans-descriptor.xml file, located in the same package as the class files
53
it describes.</p>
53
it describes.</p>
54
54
55
<source>
55
<source><![CDATA[  <mbean         name="LDAPRealm"
56
  &lt;mbean         name="LDAPRealm"
57
            className="org.apache.catalina.mbeans.ClassNameMBean"
56
            className="org.apache.catalina.mbeans.ClassNameMBean"
58
          description="Custom LDAPRealm"
57
          description="Custom LDAPRealm"
59
               domain="Catalina"
58
               domain="Catalina"
60
                group="Realm"
59
                group="Realm"
61
                 type="com.myfirm.mypackage.LDAPRealm"&gt;
60
                 type="com.myfirm.mypackage.LDAPRealm">
62
61
63
    &lt;attribute   name="className"
62
    <attribute   name="className"
64
          description="Fully qualified class name of the managed object"
63
          description="Fully qualified class name of the managed object"
65
                 type="java.lang.String"
64
                 type="java.lang.String"
66
            writeable="false"/&gt;
65
            writeable="false"/>
67
66
68
    &lt;attribute   name="debug"
67
    <attribute   name="debug"
69
          description="The debugging detail level for this component"
68
          description="The debugging detail level for this component"
70
                 type="int"/&gt;
69
                 type="int"/>
71
    .
70
    .
72
    .
71
    .
73
    .
72
    .
74
73
75
  &lt;/mbean&gt;
74
  </mbean>]]></source>
76
</source>
77
75
78
76
79
</section>
77
</section>
(-)webapps/docs/monitoring.xml (-297 / +278 lines)
Lines 60-91 Link Here
60
    java options for the service.
60
    java options for the service.
61
    For un*xes remove <code>"set "</code> from beginning of the line.
61
    For un*xes remove <code>"set "</code> from beginning of the line.
62
    </p>
62
    </p>
63
<source>
63
<source><![CDATA[set CATALINA_OPTS=-Dcom.sun.management.jmxremote
64
set CATALINA_OPTS=-Dcom.sun.management.jmxremote
65
  -Dcom.sun.management.jmxremote.port=%my.jmx.port%
64
  -Dcom.sun.management.jmxremote.port=%my.jmx.port%
66
  -Dcom.sun.management.jmxremote.ssl=false
65
  -Dcom.sun.management.jmxremote.ssl=false
67
  -Dcom.sun.management.jmxremote.authenticate=false
66
  -Dcom.sun.management.jmxremote.authenticate=false]]></source>
68
</source>
69
67
70
    <ol>
68
    <ol>
71
    <li>If you require authorization, add and change this:
69
    <li>If you require authorization, add and change this:
72
<source>
70
<source><![CDATA[  -Dcom.sun.management.jmxremote.authenticate=true
73
  -Dcom.sun.management.jmxremote.authenticate=true
74
  -Dcom.sun.management.jmxremote.password.file=../conf/jmxremote.password
71
  -Dcom.sun.management.jmxremote.password.file=../conf/jmxremote.password
75
  -Dcom.sun.management.jmxremote.access.file=../conf/jmxremote.access
72
  -Dcom.sun.management.jmxremote.access.file=../conf/jmxremote.access]]></source>
76
</source>
77
    </li>
73
    </li>
78
    <li>edit the access authorization file <em>$CATALINA_BASE/conf/jmxremote.access</em>:
74
    <li>edit the access authorization file <em>$CATALINA_BASE/conf/jmxremote.access</em>:
79
<source>
75
<source><![CDATA[monitorRole readonly
80
monitorRole readonly
76
controlRole readwrite]]></source>
81
controlRole readwrite
82
</source>
83
    </li>
77
    </li>
84
    <li>edit the password file <em>$CATALINA_BASE/conf/jmxremote.password</em>:
78
    <li>edit the password file <em>$CATALINA_BASE/conf/jmxremote.password</em>:
85
<source>
79
<source><![CDATA[monitorRole tomcat
86
monitorRole tomcat
80
controlRole tomcat]]></source>
87
controlRole tomcat
88
</source>
89
    <b>Tip</b>: The password file should be read-only and only accessible by the
81
    <b>Tip</b>: The password file should be read-only and only accessible by the
90
    operating system user Tomcat is running as.
82
    operating system user Tomcat is running as.
91
    </li>
83
    </li>
Lines 105-128 Link Here
105
   <p>The following example shows the JMX Accessor usage:<br/>
97
   <p>The following example shows the JMX Accessor usage:<br/>
106
   <em>Note:</em> The <code>name</code> attribute value was wrapped here to be
98
   <em>Note:</em> The <code>name</code> attribute value was wrapped here to be
107
   more readable. It has to be all on the same line, without spaces.</p>
99
   more readable. It has to be all on the same line, without spaces.</p>
108
   <table border="1">
100
   <source><![CDATA[<project name="Catalina Ant JMX"
109
   <tr><td><pre>
110
&lt;project name="Catalina Ant JMX"
111
      xmlns:jmx="antlib:org.apache.catalina.ant.jmx"
101
      xmlns:jmx="antlib:org.apache.catalina.ant.jmx"
112
      default="state"
102
      default="state"
113
      basedir="."&gt;
103
      basedir=".">
114
  &lt;property name="jmx.server.name" value="localhost" /&gt;
104
  <property name="jmx.server.name" value="localhost" />
115
  &lt;property name="jmx.server.port" value="9012" /&gt;
105
  <property name="jmx.server.port" value="9012" />
116
  &lt;property name="cluster.server.address" value="192.168.1.75" /&gt;
106
  <property name="cluster.server.address" value="192.168.1.75" />
117
  &lt;property name="cluster.server.port" value="9025" /&gt;
107
  <property name="cluster.server.port" value="9025" />
118
108
119
  &lt;target name="state" description="Show JMX Cluster state"&gt;
109
  <target name="state" description="Show JMX Cluster state">
120
    &lt;jmx:open
110
    <jmx:open
121
      host="${jmx.server.name}"
111
      host="${jmx.server.name}"
122
      port="${jmx.server.port}"
112
      port="${jmx.server.port}"
123
      username="controlRole"
113
      username="controlRole"
124
      password="tomcat"/&gt;
114
      password="tomcat"/>
125
    &lt;jmx:get
115
    <jmx:get
126
      name=
116
      name=
127
"Catalina:type=IDataSender,host=localhost,
117
"Catalina:type=IDataSender,host=localhost,
128
senderAddress=${cluster.server.address},senderPort=${cluster.server.port}"
118
senderAddress=${cluster.server.address},senderPort=${cluster.server.port}"
Lines 129-191 Link Here
129
      attribute="connected"
119
      attribute="connected"
130
      resultproperty="IDataSender.backup.connected"
120
      resultproperty="IDataSender.backup.connected"
131
      echo="false"
121
      echo="false"
132
    /&gt;
122
    />
133
    &lt;jmx:get
123
    <jmx:get
134
      name="Catalina:type=ClusterSender,host=localhost"
124
      name="Catalina:type=ClusterSender,host=localhost"
135
      attribute="senderObjectNames"
125
      attribute="senderObjectNames"
136
      resultproperty="senderObjectNames"
126
      resultproperty="senderObjectNames"
137
      echo="false"
127
      echo="false"
138
    /&gt;
128
    />
139
    &lt;!-- get current maxActiveSession from ClusterTest application
129
    <!-- get current maxActiveSession from ClusterTest application
140
       echo it to Ant output and store at
130
       echo it to Ant output and store at
141
       property &lt;em&gt;clustertest.maxActiveSessions.orginal&lt;/em&gt;
131
       property <em>clustertest.maxActiveSessions.orginal</em>
142
    --&gt;
132
    -->
143
    &lt;jmx:get
133
    <jmx:get
144
      name="Catalina:type=Manager,context=/ClusterTest,host=localhost"
134
      name="Catalina:type=Manager,context=/ClusterTest,host=localhost"
145
      attribute="maxActiveSessions"
135
      attribute="maxActiveSessions"
146
      resultproperty="clustertest.maxActiveSessions.orginal"
136
      resultproperty="clustertest.maxActiveSessions.orginal"
147
      echo="true"
137
      echo="true"
148
    /&gt;
138
    />
149
    &lt;!-- set maxActiveSession to 100
139
    <!-- set maxActiveSession to 100
150
    --&gt;
140
    -->
151
    &lt;jmx:set
141
    <jmx:set
152
      name="Catalina:type=Manager,context=/ClusterTest,host=localhost"
142
      name="Catalina:type=Manager,context=/ClusterTest,host=localhost"
153
      attribute="maxActiveSessions"
143
      attribute="maxActiveSessions"
154
      value="100"
144
      value="100"
155
      type="int"
145
      type="int"
156
    /&gt;
146
    />
157
    &lt;!-- get all sessions and split result as delimiter &lt;em&gt;SPACE&lt;/em&gt; for easy
147
    <!-- get all sessions and split result as delimiter <em>SPACE</em> for easy
158
       access all session ids directly with Ant property sessions.[0..n].
148
       access all session ids directly with Ant property sessions.[0..n].
159
    --&gt;
149
    -->
160
    &lt;jmx:invoke
150
    <jmx:invoke
161
      name="Catalina:type=Manager,context=/ClusterTest,host=localhost"
151
      name="Catalina:type=Manager,context=/ClusterTest,host=localhost"
162
      operation="listSessionIds"
152
      operation="listSessionIds"
163
      resultproperty="sessions"
153
      resultproperty="sessions"
164
      echo="false"
154
      echo="false"
165
      delimiter=" "
155
      delimiter=" "
166
    /&gt;
156
    />
167
    &lt;!-- Access session attribute &lt;em&gt;Hello&lt;/em&gt; from first session.
157
    <!-- Access session attribute <em>Hello</em> from first session.
168
    --&gt;
158
    -->
169
    &lt;jmx:invoke
159
    <jmx:invoke
170
      name="Catalina:type=Manager,context=/ClusterTest,host=localhost"
160
      name="Catalina:type=Manager,context=/ClusterTest,host=localhost"
171
      operation="getSessionAttribute"
161
      operation="getSessionAttribute"
172
      resultproperty="Hello"
162
      resultproperty="Hello"
173
      echo="false"
163
      echo="false"
174
    &gt;
164
    >
175
      &lt;arg value="${sessions.0}"/&gt;
165
      <arg value="${sessions.0}"/>
176
      &lt;arg value="Hello"/&gt;
166
      <arg value="Hello"/>
177
    &lt;/jmx:invoke&gt;
167
    </jmx:invoke>
178
    &lt;!-- Query for all application manager.of the server from all hosts
168
    <!-- Query for all application manager.of the server from all hosts
179
       and bind all attributes from all found manager MBeans.
169
       and bind all attributes from all found manager MBeans.
180
    --&gt;
170
    -->
181
    &lt;jmx:query
171
    <jmx:query
182
      name="Catalina:type=Manager,*"
172
      name="Catalina:type=Manager,*"
183
      resultproperty="manager"
173
      resultproperty="manager"
184
      echo="true"
174
      echo="true"
185
      attributebinding="true"
175
      attributebinding="true"
186
    /&gt;
176
    />
187
    &lt;!-- echo the create properties --&gt;
177
    <!-- echo the create properties -->
188
&lt;echo&gt;
178
<echo>
189
senderObjectNames: ${senderObjectNames.0}
179
senderObjectNames: ${senderObjectNames.0}
190
IDataSender.backup.connected: ${IDataSender.backup.connected}
180
IDataSender.backup.connected: ${IDataSender.backup.connected}
191
session: ${sessions.0}
181
session: ${sessions.0}
Lines 199-212 Link Here
199
 ${manager.ClusterTest.0.counterSend_EVT_SESSION_EXPIRED}
189
 ${manager.ClusterTest.0.counterSend_EVT_SESSION_EXPIRED}
200
manager.ClusterTest.0.counterSend_EVT_GET_ALL_SESSIONS:
190
manager.ClusterTest.0.counterSend_EVT_GET_ALL_SESSIONS:
201
 ${manager.ClusterTest.0.counterSend_EVT_GET_ALL_SESSIONS}
191
 ${manager.ClusterTest.0.counterSend_EVT_GET_ALL_SESSIONS}
202
&lt;/echo&gt;
192
</echo>
203
193
204
  &lt;/target&gt;
194
  </target>
205
195
206
&lt;/project&gt;
196
</project>]]></source>
207
</pre>
208
   </td></tr>
209
</table>
210
   <p><b>import:</b> Import the JMX Accessor Project with
197
   <p><b>import:</b> Import the JMX Accessor Project with
211
   <em>&lt;import file="${CATALINA.HOME}/bin/catalina-tasks.xml" /&gt;</em> and
198
   <em>&lt;import file="${CATALINA.HOME}/bin/catalina-tasks.xml" /&gt;</em> and
212
   reference the tasks with <em>jmxOpen</em>, <em>jmxSet</em>, <em>jmxGet</em>,
199
   reference the tasks with <em>jmxOpen</em>, <em>jmxSet</em>, <em>jmxGet</em>,
Lines 219-231 Link Here
219
206
220
<section name="JMXAccessorOpenTask - JMX open connection task">
207
<section name="JMXAccessorOpenTask - JMX open connection task">
221
<p>
208
<p>
222
List of Attributes<br/>
209
List of Attributes
223
<table border="1" cellpadding="5">
210
</p>
211
<table class="defaultTable">
224
212
225
  <tr>
213
  <tr>
226
    <th align="center" bgcolor="aqua">Attribute</th>
214
    <th>Attribute</th>
227
    <th align="center" bgcolor="aqua">Description</th>
215
    <th>Description</th>
228
    <th align="center" bgcolor="aqua">Default value</th>
216
    <th>Default value</th>
229
  </tr>
217
  </tr>
230
218
231
  <tr>
219
  <tr>
Lines 239-245 Link Here
239
    <td>host</td>
227
    <td>host</td>
240
    <td>Set the host, shortcut the very long URL syntax.
228
    <td>Set the host, shortcut the very long URL syntax.
241
    </td>
229
    </td>
242
    <td><code>localhost</code></td>
230
    <td><code class="noHighlight">localhost</code></td>
243
  </tr>
231
  </tr>
244
232
245
  <tr>
233
  <tr>
Lines 246-252 Link Here
246
    <td>port</td>
234
    <td>port</td>
247
    <td>Set the remote connection port
235
    <td>Set the remote connection port
248
    </td>
236
    </td>
249
    <td><code>8050</code></td>
237
    <td><code class="noHighlight">8050</code></td>
250
  </tr>
238
  </tr>
251
239
252
  <tr>
240
  <tr>
Lines 268-274 Link Here
268
    <td>Name of the internal connection reference. With this attribute you can
256
    <td>Name of the internal connection reference. With this attribute you can
269
        configure more the one connection inside the same Ant project.
257
        configure more the one connection inside the same Ant project.
270
    </td>
258
    </td>
271
    <td><code>jmx.server</code></td>
259
    <td><code class="noHighlight">jmx.server</code></td>
272
  </tr>
260
  </tr>
273
261
274
  <tr>
262
  <tr>
Lines 275-281 Link Here
275
    <td>echo</td>
263
    <td>echo</td>
276
    <td>Echo the command usage (for access analysis or debugging)
264
    <td>Echo the command usage (for access analysis or debugging)
277
    </td>
265
    </td>
278
    <td><code>false</code></td>
266
    <td><code class="noHighlight">false</code></td>
279
  </tr>
267
  </tr>
280
268
281
  <tr>
269
  <tr>
Lines 293-327 Link Here
293
  </tr>
281
  </tr>
294
282
295
</table>
283
</table>
284
285
<p>
286
Example to open a new JMX connection
296
</p>
287
</p>
297
<p>
288
<source><![CDATA[  <jmx:open
298
Example to open a new JMX connection<br/>
299
<source>
300
  &lt;jmx:open
301
    host="${jmx.server.name}"
289
    host="${jmx.server.name}"
302
    port="${jmx.server.port}"
290
    port="${jmx.server.port}"
303
  /&gt;
291
  />]]></source>
304
</source>
292
305
</p>
306
<p>
293
<p>
307
Example to open a JMX connection from URL, with authorization and
294
Example to open a JMX connection from URL, with authorization and
308
store at other reference <br/>
295
store at other reference
309
<source>
296
</p>
310
  &lt;jmx:open
297
<source><![CDATA[  <jmx:open
311
    url="service:jmx:rmi:///jndi/rmi://localhost:9024/jmxrmi"
298
    url="service:jmx:rmi:///jndi/rmi://localhost:9024/jmxrmi"
312
    ref="jmx.server.9024"
299
    ref="jmx.server.9024"
313
    username="controlRole"
300
    username="controlRole"
314
    password="tomcat"
301
    password="tomcat"
315
  /&gt;
302
  />]]></source>
316
</source>
317
</p>
318
303
319
<p>
304
<p>
320
Example to open a JMX connection from URL, with authorization and
305
Example to open a JMX connection from URL, with authorization and
321
store at other reference, but only when property <em>jmx.if</em> exists and
306
store at other reference, but only when property <em>jmx.if</em> exists and
322
<em>jmx.unless</em> not exists<br/>
307
<em>jmx.unless</em> not exists
323
<source>
308
</p>
324
  &lt;jmx:open
309
<source><![CDATA[  <jmx:open
325
    url="service:jmx:rmi:///jndi/rmi://localhost:9024/jmxrmi"
310
    url="service:jmx:rmi:///jndi/rmi://localhost:9024/jmxrmi"
326
    ref="jmx.server.9024"
311
    ref="jmx.server.9024"
327
    username="controlRole"
312
    username="controlRole"
Lines 328-336 Link Here
328
    password="tomcat"
313
    password="tomcat"
329
    if="jmx.if"
314
    if="jmx.if"
330
    unless="jmx.unless"
315
    unless="jmx.unless"
331
  /&gt;
316
  />]]></source>
332
</source>
317
333
</p>
334
<p><b>Note</b>: All properties from <em>jmxOpen</em> task also exists at all
318
<p><b>Note</b>: All properties from <em>jmxOpen</em> task also exists at all
335
other tasks and conditions.
319
other tasks and conditions.
336
</p>
320
</p>
Lines 342-354 Link Here
342
326
343
<section name="JMXAccessorGetTask:  get attribute value Ant task">
327
<section name="JMXAccessorGetTask:  get attribute value Ant task">
344
<p>
328
<p>
345
List of Attributes<br/>
329
List of Attributes
346
<table border="1" cellpadding="5">
330
</p>
331
<table class="defaultTable">
347
332
348
  <tr>
333
  <tr>
349
    <th align="center" bgcolor="aqua">Attribute</th>
334
    <th>Attribute</th>
350
    <th align="center" bgcolor="aqua">Description</th>
335
    <th>Description</th>
351
    <th align="center" bgcolor="aqua">Default value</th>
336
    <th>Default value</th>
352
  </tr>
337
  </tr>
353
338
354
  <tr>
339
  <tr>
Lines 369-375 Link Here
369
    <td>ref</td>
354
    <td>ref</td>
370
    <td>JMX Connection reference
355
    <td>JMX Connection reference
371
    </td>
356
    </td>
372
    <td><code>jmx.server</code></td>
357
    <td><code class="noHighlight">jmx.server</code></td>
373
  </tr>
358
  </tr>
374
359
375
  <tr>
360
  <tr>
Lines 376-382 Link Here
376
    <td>echo</td>
361
    <td>echo</td>
377
    <td>Echo command usage (access and result)
362
    <td>Echo command usage (access and result)
378
    </td>
363
    </td>
379
    <td><code>false</code></td>
364
    <td><code class="noHighlight">false</code></td>
380
  </tr>
365
  </tr>
381
366
382
  <tr>
367
  <tr>
Lines 399-454 Link Here
399
    <td>When return value is an array, save result as property list
384
    <td>When return value is an array, save result as property list
400
    (<em>$resultproperty.[0..N]</em> and <em>$resultproperty.length</em>)
385
    (<em>$resultproperty.[0..N]</em> and <em>$resultproperty.length</em>)
401
    </td>
386
    </td>
402
    <td><code>true</code></td>
387
    <td><code class="noHighlight">true</code></td>
403
  </tr>
388
  </tr>
404
389
405
</table>
390
</table>
391
392
<p>
393
Example to get remote MBean attribute from default JMX connection
406
</p>
394
</p>
407
<p>
395
<source><![CDATA[  <jmx:get
408
Example to get remote MBean attribute from default JMX connection <br/>
409
<source>
410
  &lt;jmx:get
411
    name="Catalina:type=Manager,context=/servlets-examples,host=localhost"
396
    name="Catalina:type=Manager,context=/servlets-examples,host=localhost"
412
    attribute="maxActiveSessions"
397
    attribute="maxActiveSessions"
413
    resultproperty="servlets-examples.maxActiveSessions"
398
    resultproperty="servlets-examples.maxActiveSessions"
414
  /&gt;
399
  />]]></source>
415
</source>
400
401
<p>
402
Example to get and result array and split it at separate properties
416
</p>
403
</p>
417
<p>
404
<source><![CDATA[  <jmx:get
418
Example to get and result array and split it at separate properties<br/>
419
<source>
420
  &lt;jmx:get
421
      name="Catalina:type=ClusterSender,host=localhost"
405
      name="Catalina:type=ClusterSender,host=localhost"
422
      attribute="senderObjectNames"
406
      attribute="senderObjectNames"
423
      resultproperty="senderObjectNames"
407
      resultproperty="senderObjectNames"
424
  /&gt;
408
  />]]></source>
425
</source>
409
<p>
426
Access the senderObjectNames properties with:
410
Access the senderObjectNames properties with:
427
<source>
428
  ${senderObjectNames.length} give the number of returned sender list.
429
  ${senderObjectNames.[0..N]} found all sender object names
430
</source>
431
</p>
411
</p>
412
<source><![CDATA[  ${senderObjectNames.length} give the number of returned sender list.
413
  ${senderObjectNames.[0..N]} found all sender object names]]></source>
432
414
415
433
<p>
416
<p>
434
Example to get IDataSender attribute connected only when cluster is configured.<br/>
417
Example to get IDataSender attribute connected only when cluster is configured.<br/>
435
<em>Note:</em> The <code>name</code> attribute value was wrapped here to be
418
<em>Note:</em> The <code>name</code> attribute value was wrapped here to be
436
more readable. It has to be all on the same line, without spaces.
419
more readable. It has to be all on the same line, without spaces.
437
</p>
420
</p>
438
<source>
421
<source><![CDATA[
439
  &lt;jmx:query
422
  <jmx:query
440
    failonerror="false"
423
    failonerror="false"
441
    name="Catalina:type=Cluster,host=${tomcat.application.host}"
424
    name="Catalina:type=Cluster,host=${tomcat.application.host}"
442
    resultproperty="cluster"
425
    resultproperty="cluster"
443
  /&gt;
426
  />
444
  &lt;jmx:get
427
  <jmx:get
445
    name=
428
    name=
446
"Catalina:type=IDataSender,host=${tomcat.application.host},
429
"Catalina:type=IDataSender,host=${tomcat.application.host},
447
senderAddress=${cluster.backup.address},senderPort=${cluster.backup.port}"
430
senderAddress=${cluster.backup.address},senderPort=${cluster.backup.port}"
448
    attribute="connected"
431
    attribute="connected"
449
    resultproperty="datasender.connected"
432
    resultproperty="datasender.connected"
450
    if="cluster.0.name" /&gt;
433
    if="cluster.0.name" />]]></source>
451
</source>
452
434
453
</section>
435
</section>
454
436
Lines 457-469 Link Here
457
439
458
<section name="JMXAccessorSetTask:  set attribute value Ant task">
440
<section name="JMXAccessorSetTask:  set attribute value Ant task">
459
<p>
441
<p>
460
List of Attributes<br/>
442
List of Attributes
461
<table border="1" cellpadding="5">
443
</p>
444
<table class="defaultTable">
462
445
463
  <tr>
446
  <tr>
464
    <th align="center" bgcolor="aqua">Attribute</th>
447
    <th>Attribute</th>
465
    <th align="center" bgcolor="aqua">Description</th>
448
    <th>Description</th>
466
    <th align="center" bgcolor="aqua">Default value</th>
449
    <th>Default value</th>
467
  </tr>
450
  </tr>
468
451
469
  <tr>
452
  <tr>
Lines 491-497 Link Here
491
    <td>type</td>
474
    <td>type</td>
492
    <td>type of the attribute.
475
    <td>type of the attribute.
493
    </td>
476
    </td>
494
    <td>java.lang.String</td>
477
    <td><code class="noHighlight">java.lang.String</code></td>
495
  </tr>
478
  </tr>
496
479
497
  <tr>
480
  <tr>
Lines 498-504 Link Here
498
    <td>ref</td>
481
    <td>ref</td>
499
    <td>JMX Connection reference
482
    <td>JMX Connection reference
500
    </td>
483
    </td>
501
    <td><code>jmx.server</code></td>
484
    <td><code class="noHighlight">jmx.server</code></td>
502
  </tr>
485
  </tr>
503
486
504
  <tr>
487
  <tr>
Lines 505-527 Link Here
505
    <td>echo</td>
488
    <td>echo</td>
506
    <td>Echo command usage (access and result)
489
    <td>Echo command usage (access and result)
507
    </td>
490
    </td>
508
    <td><code>false</code></td>
491
    <td><code class="noHighlight">false</code></td>
509
  </tr>
492
  </tr>
510
493
511
</table>
494
</table>
495
496
<p>
497
Example to set remote MBean attribute value
512
</p>
498
</p>
513
<p>
499
<source><![CDATA[  <jmx:set
514
Example to set remote MBean attribute value<br/>
515
<source>
516
  &lt;jmx:set
517
    name="Catalina:type=Manager,context=/servlets-examples,host=localhost"
500
    name="Catalina:type=Manager,context=/servlets-examples,host=localhost"
518
    attribute="maxActiveSessions"
501
    attribute="maxActiveSessions"
519
    value="500"
502
    value="500"
520
    type="int"
503
    type="int"
521
  /&gt;
504
  />]]></source>
522
</source>
523
</p>
524
505
506
525
</section>
507
</section>
526
508
527
<!-- Invoke #########################################################################
509
<!-- Invoke #########################################################################
Lines 529-541 Link Here
529
511
530
<section name="JMXAccessorInvokeTask:  invoke MBean operation Ant task">
512
<section name="JMXAccessorInvokeTask:  invoke MBean operation Ant task">
531
<p>
513
<p>
532
List of Attributes<br/>
514
List of Attributes
533
<table border="1" cellpadding="5">
515
</p>
516
<table class="defaultTable">
534
517
535
  <tr>
518
  <tr>
536
    <th align="center" bgcolor="aqua">Attribute</th>
519
    <th>Attribute</th>
537
    <th align="center" bgcolor="aqua">Description</th>
520
    <th>Description</th>
538
    <th align="center" bgcolor="aqua">Default value</th>
521
    <th>Default value</th>
539
  </tr>
522
  </tr>
540
523
541
  <tr>
524
  <tr>
Lines 557-563 Link Here
557
    <td>ref</td>
540
    <td>ref</td>
558
    <td>JMX Connection reference
541
    <td>JMX Connection reference
559
    </td>
542
    </td>
560
    <td><code>jmx.server</code></td>
543
    <td><code class="noHighlight">jmx.server</code></td>
561
  </tr>
544
  </tr>
562
545
563
  <tr>
546
  <tr>
Lines 564-570 Link Here
564
    <td>echo</td>
547
    <td>echo</td>
565
    <td>Echo command usage (access and result)
548
    <td>Echo command usage (access and result)
566
    </td>
549
    </td>
567
    <td><code>false</code></td>
550
    <td><code class="noHighlight">false</code></td>
568
  </tr>
551
  </tr>
569
552
570
  <tr>
553
  <tr>
Lines 587-643 Link Here
587
    <td>When return value is an array, save result as property list
570
    <td>When return value is an array, save result as property list
588
    (<em>$resultproperty.[0..N]</em> and <em>$resultproperty.length</em>)
571
    (<em>$resultproperty.[0..N]</em> and <em>$resultproperty.length</em>)
589
    </td>
572
    </td>
590
    <td><code>true</code></td>
573
    <td><code class="noHighlight">true</code></td>
591
  </tr>
574
  </tr>
592
575
593
</table>
576
</table>
577
578
<p>
579
stop an application
594
</p>
580
</p>
581
<source><![CDATA[  <jmx:invoke
582
    name="Catalina:type=Manager,context=/servlets-examples,host=localhost"
583
    operation="stop"/>]]></source>
595
<p>
584
<p>
596
stop an application <br/>
597
<source>
598
  &lt;jmx:invoke
599
    name="Catalina:type=Manager,context=/servlets-examples,host=localhost"
600
    operation="stop"/&gt;
601
</source>
602
Now you can find the sessionid at <em>${sessions.[0..N}</em> properties and access the count
585
Now you can find the sessionid at <em>${sessions.[0..N}</em> properties and access the count
603
with ${sessions.length} property.
586
with ${sessions.length} property.
604
</p>
587
</p>
605
<p>
588
<p>
606
Example to get all sessionids <br/>
589
Example to get all sessionids
607
<source>
590
</p>
608
  &lt;jmx:invoke
591
<source><![CDATA[  <jmx:invoke
609
    name="Catalina:type=Manager,context=/servlets-examples,host=localhost"
592
    name="Catalina:type=Manager,context=/servlets-examples,host=localhost"
610
    operation="listSessionIds"
593
    operation="listSessionIds"
611
    resultproperty="sessions"
594
    resultproperty="sessions"
612
    delimiter=" "
595
    delimiter=" "
613
  /&gt;
596
  />]]></source>
614
</source>
597
<p>
615
Now you can find the sessionid at <em>${sessions.[0..N}</em> properties and access the count
598
Now you can find the sessionid at <em>${sessions.[0..N}</em> properties and access the count
616
with ${sessions.length} property.
599
with ${sessions.length} property.
617
</p>
600
</p>
618
<p>
601
<p>
619
Example to get remote MBean session attribute from session ${sessionid.0}<br/>
602
Example to get remote MBean session attribute from session ${sessionid.0}
620
<source>
603
</p>
621
  &lt;jmx:invoke
604
<source><![CDATA[  <jmx:invoke
622
    name="Catalina:type=Manager,context=/ClusterTest,host=localhost"
605
    name="Catalina:type=Manager,context=/ClusterTest,host=localhost"
623
    operation="getSessionAttribute"
606
    operation="getSessionAttribute"
624
    resultproperty="hello"&gt;
607
    resultproperty="hello">
625
     &lt;arg value="${sessionid.0}"/&gt;
608
     <arg value="${sessionid.0}"/>
626
     &lt;arg value="Hello" /&gt;
609
     <arg value="Hello" />
627
  &lt;/jmx:invoke&gt;
610
  </jmx:invoke>]]></source>
628
</source>
611
629
</p>
630
<p>
612
<p>
631
Example to create a new access logger valve at vhost <em>localhost</em>
613
Example to create a new access logger valve at vhost <em>localhost</em>
632
<source>
614
</p>
633
 &lt;jmx:invoke
615
<source><![CDATA[ <jmx:invoke
634
         name="Catalina:type=MBeanFactory"
616
         name="Catalina:type=MBeanFactory"
635
         operation="createAccessLoggerValve"
617
         operation="createAccessLoggerValve"
636
         resultproperty="accessLoggerObjectName"
618
         resultproperty="accessLoggerObjectName"
637
 &gt;
619
 >
638
     &lt;arg value="Catalina:type=Host,host=localhost"/&gt;
620
     <arg value="Catalina:type=Host,host=localhost"/>
639
 &lt;/jmx:invoke&gt;
621
 </jmx:invoke>]]></source>
640
</source>
622
<p>
641
Now you can find new MBean with name stored at <em>${accessLoggerObjectName}</em>
623
Now you can find new MBean with name stored at <em>${accessLoggerObjectName}</em>
642
property.
624
property.
643
</p>
625
</p>
Lines 649-661 Link Here
649
631
650
<section name="JMXAccessorQueryTask:  query MBean Ant task">
632
<section name="JMXAccessorQueryTask:  query MBean Ant task">
651
<p>
633
<p>
652
List of Attributes<br/>
634
List of Attributes
653
<table border="1" cellpadding="5">
635
</p>
636
<table class="defaultTable">
654
637
655
  <tr>
638
  <tr>
656
    <th align="center" bgcolor="aqua">Attribute</th>
639
    <th>Attribute</th>
657
    <th align="center" bgcolor="aqua">Description</th>
640
    <th>Description</th>
658
    <th align="center" bgcolor="aqua">Default value</th>
641
    <th>Default value</th>
659
  </tr>
642
  </tr>
660
643
661
  <tr>
644
  <tr>
Lines 669-675 Link Here
669
    <td>ref</td>
652
    <td>ref</td>
670
    <td>JMX Connection reference
653
    <td>JMX Connection reference
671
    </td>
654
    </td>
672
    <td><code>jmx.server</code></td>
655
    <td><code class="noHighlight">jmx.server</code></td>
673
  </tr>
656
  </tr>
674
657
675
  <tr>
658
  <tr>
Lines 676-682 Link Here
676
    <td>echo</td>
659
    <td>echo</td>
677
    <td>Echo command usage (access and result)
660
    <td>Echo command usage (access and result)
678
    </td>
661
    </td>
679
    <td><code>false</code></td>
662
    <td><code class="noHighlight">false</code></td>
680
  </tr>
663
  </tr>
681
664
682
  <tr>
665
  <tr>
Lines 690-696 Link Here
690
    <td>attributebinduing</td>
673
    <td>attributebinduing</td>
691
    <td>bind ALL MBean attributes in addition to <em>name</em>
674
    <td>bind ALL MBean attributes in addition to <em>name</em>
692
    </td>
675
    </td>
693
    <td><code>false</code></td>
676
    <td><code class="noHighlight">false</code></td>
694
  </tr>
677
  </tr>
695
678
696
  <tr>
679
  <tr>
Lines 706-734 Link Here
706
    <td>When return value is an array, save result as property list
689
    <td>When return value is an array, save result as property list
707
    (<em>$resultproperty.[0..N]</em> and <em>$resultproperty.length</em>)
690
    (<em>$resultproperty.[0..N]</em> and <em>$resultproperty.length</em>)
708
    </td>
691
    </td>
709
    <td><code>true</code></td>
692
    <td><code class="noHighlight">true</code></td>
710
  </tr>
693
  </tr>
711
694
712
</table>
695
</table>
696
697
<p>
698
Get all Manager ObjectNames from all services and Hosts
713
</p>
699
</p>
700
<source><![CDATA[  <jmx:query
701
    name="Catalina:type=Manager,*
702
    resultproperty="manager" />]]></source>
714
<p>
703
<p>
715
Get all Manager ObjectNames from all services and Hosts <br/>
716
<source>
717
  &lt;jmx:query
718
    name="Catalina:type=Manager,*
719
    resultproperty="manager" /&gt;
720
</source>
721
Now you can find the Session Manager at <em>${manager.[0..N].name}</em>
704
Now you can find the Session Manager at <em>${manager.[0..N].name}</em>
722
properties and access the result object counter with ${manager.length} property.
705
properties and access the result object counter with ${manager.length} property.
723
</p>
706
</p>
724
<p>
707
<p>
725
Example to get the Manager from <em>servlet-examples</em> application an bind all MBean properties<br/>
708
Example to get the Manager from <em>servlet-examples</em> application an bind all MBean properties
726
<source>
709
</p>
727
  &lt;jmx:query
710
<source><![CDATA[  <jmx:query
728
    name="Catalina:type=Manager,context=/servlet-examples,host=localhost*"
711
    name="Catalina:type=Manager,context=/servlet-examples,host=localhost*"
729
    attributebinding="true"
712
    attributebinding="true"
730
    resultproperty="manager.servletExamples" /&gt;
713
    resultproperty="manager.servletExamples" />]]></source>
731
</source>
714
<p>
732
Now you can find the manager at <em>${manager.servletExamples.0.name}</em> property
715
Now you can find the manager at <em>${manager.servletExamples.0.name}</em> property
733
and can access all properties from this manager with <em>${manager.servletExamples.0.[manager attribute names]</em>}.
716
and can access all properties from this manager with <em>${manager.servletExamples.0.[manager attribute names]</em>}.
734
The result object counter from MBeans is stored ad ${manager.length} property.
717
The result object counter from MBeans is stored ad ${manager.length} property.
Lines 735-776 Link Here
735
</p>
718
</p>
736
719
737
<p>
720
<p>
738
Example to get all MBeans from a server and store inside an external XML property file<br/>
721
Example to get all MBeans from a server and store inside an external XML property file
739
<source>
722
</p>
740
&lt;project name="jmx.query"
723
<source><![CDATA[<project name="jmx.query"
741
            xmlns:jmx="antlib:org.apache.catalina.ant.jmx"
724
            xmlns:jmx="antlib:org.apache.catalina.ant.jmx"
742
            default="query-all" basedir="."&gt;
725
            default="query-all" basedir=".">
743
&lt;property name="jmx.host" value="localhost"/&gt;
726
<property name="jmx.host" value="localhost"/>
744
&lt;property name="jmx.port" value="8050"/&gt;
727
<property name="jmx.port" value="8050"/>
745
&lt;property name="jmx.username" value="controlRole"/&gt;
728
<property name="jmx.username" value="controlRole"/>
746
&lt;property name="jmx.password" value="tomcat"/&gt;
729
<property name="jmx.password" value="tomcat"/>
747
730
748
&lt;target name="query-all" description="Query all MBeans of a server"&gt;
731
<target name="query-all" description="Query all MBeans of a server">
749
  &lt;!-- Configure connection --&gt;
732
  <!-- Configure connection -->
750
  &lt;jmx:open
733
  <jmx:open
751
    host="${jmx.host}"
734
    host="${jmx.host}"
752
    port="${jmx.port}"
735
    port="${jmx.port}"
753
    ref="jmx.server"
736
    ref="jmx.server"
754
    username="${jmx.username}"
737
    username="${jmx.username}"
755
    password="${jmx.password}"/&gt;
738
    password="${jmx.password}"/>
756
739
757
  &lt;!-- Query MBean list --&gt;
740
  <!-- Query MBean list -->
758
  &lt;jmx:query
741
  <jmx:query
759
    name="*:*"
742
    name="*:*"
760
    resultproperty="mbeans"
743
    resultproperty="mbeans"
761
    attributebinding="false"/&gt;
744
    attributebinding="false"/>
762
745
763
  &lt;echoproperties
746
  <echoproperties
764
    destfile="mbeans.properties"
747
    destfile="mbeans.properties"
765
    prefix="mbeans."
748
    prefix="mbeans."
766
    format="xml"/&gt;
749
    format="xml"/>
767
750
768
  &lt;!-- Print results --&gt;
751
  <!-- Print results -->
769
  &lt;echo message=
752
  <echo message=
770
    "Number of MBeans in server ${jmx.host}:${jmx.port} is ${mbeans.length}"/&gt;
753
    "Number of MBeans in server ${jmx.host}:${jmx.port} is ${mbeans.length}"/>
771
&lt;/target&gt;
754
</target>
772
&lt;/project&gt;
755
</project>]]></source>
773
</source>
756
<p>
774
Now you can find all MBeans inside the file <em>mbeans.properties</em>.
757
Now you can find all MBeans inside the file <em>mbeans.properties</em>.
775
</p>
758
</p>
776
759
Lines 781-793 Link Here
781
764
782
<section name="JMXAccessorCreateTask:  remote create MBean Ant task">
765
<section name="JMXAccessorCreateTask:  remote create MBean Ant task">
783
<p>
766
<p>
784
List of Attributes<br/>
767
List of Attributes
785
<table border="1" cellpadding="5">
768
</p>
769
<table class="defaultTable">
786
770
787
  <tr>
771
  <tr>
788
    <th align="center" bgcolor="aqua">Attribute</th>
772
    <th>Attribute</th>
789
    <th align="center" bgcolor="aqua">Description</th>
773
    <th>Description</th>
790
    <th align="center" bgcolor="aqua">Default value</th>
774
    <th>Default value</th>
791
  </tr>
775
  </tr>
792
776
793
  <tr>
777
  <tr>
Lines 817-823 Link Here
817
    <td>ref</td>
801
    <td>ref</td>
818
    <td>JMX Connection reference
802
    <td>JMX Connection reference
819
    </td>
803
    </td>
820
    <td><code>jmx.server</code></td>
804
    <td><code class="noHighlight">jmx.server</code></td>
821
  </tr>
805
  </tr>
822
806
823
  <tr>
807
  <tr>
Lines 824-846 Link Here
824
    <td>echo</td>
808
    <td>echo</td>
825
    <td>Echo command usage (access and result)
809
    <td>Echo command usage (access and result)
826
    </td>
810
    </td>
827
    <td><code>false</code></td>
811
    <td><code class="noHighlight">false</code></td>
828
  </tr>
812
  </tr>
829
813
830
</table>
814
</table>
815
816
<p>
817
Example to create remote MBean
831
</p>
818
</p>
832
<p>
819
<source><![CDATA[  <jmx:create
833
Example to create remote MBean<br/>
834
<source>
835
  &lt;jmx:create
836
    ref="${jmx.reference}"
820
    ref="${jmx.reference}"
837
    name="Catalina:type=MBeanFactory"
821
    name="Catalina:type=MBeanFactory"
838
    className="org.apache.commons.modeler.BaseModelMBean"
822
    className="org.apache.commons.modeler.BaseModelMBean"
839
    classLoader="Catalina:type=ServerClassLoader,name=server"&gt;
823
    classLoader="Catalina:type=ServerClassLoader,name=server">
840
    &lt;arg value="org.apache.catalina.mbeans.MBeanFactory" /&gt;
824
    <arg value="org.apache.catalina.mbeans.MBeanFactory" />
841
  &lt;/jmx:create&gt;
825
  </jmx:create>]]></source>
842
</source>
826
843
</p>
844
<p>
827
<p>
845
    <b>Warning</b>: Many Tomcat MBeans can't be linked to their parent once<br/>
828
    <b>Warning</b>: Many Tomcat MBeans can't be linked to their parent once<br/>
846
    created. The Valve, Cluster and Realm MBeans are not automatically<br/>
829
    created. The Valve, Cluster and Realm MBeans are not automatically<br/>
Lines 855-867 Link Here
855
838
856
<section name="JMXAccessorUnregisterTask:  remote unregister MBean Ant task">
839
<section name="JMXAccessorUnregisterTask:  remote unregister MBean Ant task">
857
<p>
840
<p>
858
List of Attributes<br/>
841
List of Attributes
859
<table border="1" cellpadding="5">
842
</p>
843
<table class="defaultTable">
860
844
861
  <tr>
845
  <tr>
862
    <th align="center" bgcolor="aqua">Attribute</th>
846
    <th>Attribute</th>
863
    <th align="center" bgcolor="aqua">Description</th>
847
    <th>Description</th>
864
    <th align="center" bgcolor="aqua">Default value</th>
848
    <th>Default value</th>
865
  </tr>
849
  </tr>
866
850
867
  <tr>
851
  <tr>
Lines 875-881 Link Here
875
    <td>ref</td>
859
    <td>ref</td>
876
    <td>JMX Connection reference
860
    <td>JMX Connection reference
877
    </td>
861
    </td>
878
    <td><code>jmx.server</code></td>
862
    <td><code class="noHighlight">jmx.server</code></td>
879
  </tr>
863
  </tr>
880
864
881
  <tr>
865
  <tr>
Lines 882-900 Link Here
882
    <td>echo</td>
866
    <td>echo</td>
883
    <td>Echo command usage (access and result)
867
    <td>Echo command usage (access and result)
884
    </td>
868
    </td>
885
    <td><code>false</code></td>
869
    <td><code class="noHighlight">false</code></td>
886
  </tr>
870
  </tr>
887
871
888
</table>
872
</table>
873
874
<p>
875
Example to unregister remote MBean
889
</p>
876
</p>
890
<p>
877
<source><![CDATA[  <jmx:unregister
891
Example to unregister remote MBean<br/>
892
<source>
893
  &lt;jmx:unregister
894
    name="Catalina:type=MBeanFactory"
878
    name="Catalina:type=MBeanFactory"
895
  /&gt;
879
  />]]></source>
896
</source>
880
897
</p>
898
<p>
881
<p>
899
    <b>Warning</b>: A lot of Tomcat MBeans can't be unregister.<br/>
882
    <b>Warning</b>: A lot of Tomcat MBeans can't be unregister.<br/>
900
    The MBeans are not unlinked from their parent. Use <em>MBeanFacrory</em><br/>
883
    The MBeans are not unlinked from their parent. Use <em>MBeanFacrory</em><br/>
Lines 908-920 Link Here
908
891
909
<section name="JMXAccessorCondition:  express condition">
892
<section name="JMXAccessorCondition:  express condition">
910
<p>
893
<p>
911
List of Attributes<br/>
894
List of Attributes
912
<table border="1" cellpadding="5">
895
</p>
896
<table class="defaultTable">
913
897
914
  <tr>
898
  <tr>
915
    <th align="center" bgcolor="aqua">Attribute</th>
899
    <th>Attribute</th>
916
    <th align="center" bgcolor="aqua">Description</th>
900
    <th>Description</th>
917
    <th align="center" bgcolor="aqua">Default value</th>
901
    <th>Default value</th>
918
  </tr>
902
  </tr>
919
903
920
 <tr>
904
 <tr>
Lines 928-934 Link Here
928
    <td>host</td>
912
    <td>host</td>
929
    <td>Set the host, shortcut the very long URL syntax.
913
    <td>Set the host, shortcut the very long URL syntax.
930
    </td>
914
    </td>
931
    <td><code>localhost</code></td>
915
    <td><code class="noHighlight">localhost</code></td>
932
  </tr>
916
  </tr>
933
917
934
  <tr>
918
  <tr>
Lines 935-941 Link Here
935
    <td>port</td>
919
    <td>port</td>
936
    <td>Set the remote connection port
920
    <td>Set the remote connection port
937
    </td>
921
    </td>
938
    <td><code>8050</code></td>
922
    <td><code class="noHighlight">8050</code></td>
939
  </tr>
923
  </tr>
940
924
941
  <tr>
925
  <tr>
Lines 957-963 Link Here
957
    <td>Name of the internal connection reference. With this attribute you can
941
    <td>Name of the internal connection reference. With this attribute you can
958
        configure more the one connection inside the same Ant project.
942
        configure more the one connection inside the same Ant project.
959
    </td>
943
    </td>
960
    <td><code>jmx.server</code></td>
944
    <td><code class="noHighlight">jmx.server</code></td>
961
  </tr>
945
  </tr>
962
946
963
  <tr>
947
  <tr>
Lines 971-977 Link Here
971
    <td>echo</td>
955
    <td>echo</td>
972
    <td>Echo condition usage (access and result)
956
    <td>Echo condition usage (access and result)
973
    </td>
957
    </td>
974
    <td><code>false</code></td>
958
    <td><code class="noHighlight">false</code></td>
975
  </tr>
959
  </tr>
976
960
977
  <tr>
961
  <tr>
Lines 999-1005 Link Here
999
    <td>type</td>
983
    <td>type</td>
1000
    <td>Value type to express operation (support <em>long</em> and <em>double</em>)
984
    <td>Value type to express operation (support <em>long</em> and <em>double</em>)
1001
    </td>
985
    </td>
1002
    <td><code>long</code></td>
986
    <td><code class="noHighlight">long</code></td>
1003
  </tr>
987
  </tr>
1004
988
1005
  <tr>
989
  <tr>
Lines 1014-1033 Link Here
1014
    <li>&lt;= lesser than or equals (&amp;lt;=)</li>
998
    <li>&lt;= lesser than or equals (&amp;lt;=)</li>
1015
    </ul>
999
    </ul>
1016
    </td>
1000
    </td>
1017
    <td><code>==</code></td>
1001
    <td><code class="noHighlight">==</code></td>
1018
  </tr>
1002
  </tr>
1019
1003
1020
</table>
1004
</table>
1005
1006
<p>
1007
Wait for server connection and that cluster backup node is accessable
1021
</p>
1008
</p>
1022
<p>
1009
<source><![CDATA[<target name="wait">
1023
Wait for server connection and that cluster backup node is accessable<br/>
1010
  <waitfor maxwait="${maxwait}" maxwaitunit="second" timeoutproperty="server.timeout" >
1024
<source>
1011
    <and>
1025
&lt;target name="wait"&gt;
1012
      <socket server="${server.name}" port="${server.port}"/>
1026
  &lt;waitfor maxwait="${maxwait}" maxwaitunit="second" timeoutproperty="server.timeout" &gt;
1013
      <http url="${url}"/>
1027
    &lt;and&gt;
1014
      <jmx:condition
1028
      &lt;socket server="${server.name}" port="${server.port}"/&gt;
1029
      &lt;http url="${url}"/&gt;
1030
      &lt;jmx:condition
1031
        operation="=="
1015
        operation="=="
1032
        host="localhost"
1016
        host="localhost"
1033
        port="9014"
1017
        port="9014"
Lines 1037-1050 Link Here
1037
"Catalina:type=IDataSender,host=localhost,senderAddress=192.168.111.1,senderPort=9025"
1021
"Catalina:type=IDataSender,host=localhost,senderAddress=192.168.111.1,senderPort=9025"
1038
        attribute="connected"
1022
        attribute="connected"
1039
        value="true"
1023
        value="true"
1040
      /&gt;
1024
      />
1041
    &lt;/and&gt;
1025
    </and>
1042
  &lt;/waitfor&gt;
1026
  </waitfor>
1043
  &lt;fail if="server.timeout" message="Server ${url} don't answer inside ${maxwait} sec" /&gt;
1027
  <fail if="server.timeout" message="Server ${url} don't answer inside ${maxwait} sec" />
1044
  &lt;echo message="Server ${url} alive" /&gt;
1028
  <echo message="Server ${url} alive" />
1045
&lt;/target&gt;
1029
</target>]]></source>
1046
</source>
1047
</p>
1048
1030
1049
</section>
1031
</section>
1050
1032
Lines 1053-1065 Link Here
1053
1035
1054
<section name="JMXAccessorEqualsCondition:  equals MBean Ant condition">
1036
<section name="JMXAccessorEqualsCondition:  equals MBean Ant condition">
1055
<p>
1037
<p>
1056
List of Attributes<br/>
1038
List of Attributes
1057
<table border="1" cellpadding="5">
1039
</p>
1040
<table class="defaultTable">
1058
1041
1059
  <tr>
1042
  <tr>
1060
    <th align="center" bgcolor="aqua">Attribute</th>
1043
    <th>Attribute</th>
1061
    <th align="center" bgcolor="aqua">Description</th>
1044
    <th>Description</th>
1062
    <th align="center" bgcolor="aqua">Default value</th>
1045
    <th>Default value</th>
1063
  </tr>
1046
  </tr>
1064
1047
1065
 <tr>
1048
 <tr>
Lines 1073-1079 Link Here
1073
    <td>host</td>
1056
    <td>host</td>
1074
    <td>Set the host, shortcut the very long URL syntax.
1057
    <td>Set the host, shortcut the very long URL syntax.
1075
    </td>
1058
    </td>
1076
    <td><code>localhost</code></td>
1059
    <td><code class="noHighlight">localhost</code></td>
1077
  </tr>
1060
  </tr>
1078
1061
1079
  <tr>
1062
  <tr>
Lines 1080-1086 Link Here
1080
    <td>port</td>
1063
    <td>port</td>
1081
    <td>Set the remote connection port
1064
    <td>Set the remote connection port
1082
    </td>
1065
    </td>
1083
    <td><code>8050</code></td>
1066
    <td><code class="noHighlight">8050</code></td>
1084
  </tr>
1067
  </tr>
1085
1068
1086
  <tr>
1069
  <tr>
Lines 1102-1108 Link Here
1102
    <td>Name of the internal connection reference. With this attribute you can
1085
    <td>Name of the internal connection reference. With this attribute you can
1103
        configure more the one connection inside the same Ant project.
1086
        configure more the one connection inside the same Ant project.
1104
    </td>
1087
    </td>
1105
    <td><code>jmx.server</code></td>
1088
    <td><code class="noHighlight">jmx.server</code></td>
1106
  </tr>
1089
  </tr>
1107
1090
1108
  <tr>
1091
  <tr>
Lines 1117-1136 Link Here
1117
    <td>echo</td>
1100
    <td>echo</td>
1118
    <td>Echo condition usage (access and result)
1101
    <td>Echo condition usage (access and result)
1119
    </td>
1102
    </td>
1120
    <td><code>false</code></td>
1103
    <td><code class="noHighlight">false</code></td>
1121
  </tr>
1104
  </tr>
1122
1105
1123
</table>
1106
</table>
1107
1108
<p>
1109
Wait for server connection and that cluster backup node is accessible
1124
</p>
1110
</p>
1125
<p>
1111
<source><![CDATA[<target name="wait">
1126
Wait for server connection and that cluster backup node is accessible<br/>
1112
  <waitfor maxwait="${maxwait}" maxwaitunit="second" timeoutproperty="server.timeout" >
1127
<source>
1113
    <and>
1128
&lt;target name="wait"&gt;
1114
      <socket server="${server.name}" port="${server.port}"/>
1129
  &lt;waitfor maxwait="${maxwait}" maxwaitunit="second" timeoutproperty="server.timeout" &gt;
1115
      <http url="${url}"/>
1130
    &lt;and&gt;
1116
      <jmx:equals
1131
      &lt;socket server="${server.name}" port="${server.port}"/&gt;
1132
      &lt;http url="${url}"/&gt;
1133
      &lt;jmx:equals
1134
        host="localhost"
1117
        host="localhost"
1135
        port="9014"
1118
        port="9014"
1136
        username="controlRole"
1119
        username="controlRole"
Lines 1139-1152 Link Here
1139
"Catalina:type=IDataSender,host=localhost,senderAddress=192.168.111.1,senderPort=9025"
1122
"Catalina:type=IDataSender,host=localhost,senderAddress=192.168.111.1,senderPort=9025"
1140
        attribute="connected"
1123
        attribute="connected"
1141
        value="true"
1124
        value="true"
1142
      /&gt;
1125
      />
1143
    &lt;/and&gt;
1126
    </and>
1144
  &lt;/waitfor&gt;
1127
  </waitfor>
1145
  &lt;fail if="server.timeout" message="Server ${url} don't answer inside ${maxwait} sec" /&gt;
1128
  <fail if="server.timeout" message="Server ${url} don't answer inside ${maxwait} sec" />
1146
  &lt;echo message="Server ${url} alive" /&gt;
1129
  <echo message="Server ${url} alive" />
1147
&lt;/target&gt;
1130
</target>]]></source>
1148
</source>
1149
</p>
1150
1131
1151
</section>
1132
</section>
1152
1133
(-)webapps/docs/proxy-howto.xml (-34 / +28 lines)
Lines 71-124 Link Here
71
without having to configure a web connector such as <code>mod_jk</code>.
71
without having to configure a web connector such as <code>mod_jk</code>.
72
To accomplish this, you need to perform the following tasks:</p>
72
To accomplish this, you need to perform the following tasks:</p>
73
<ol>
73
<ol>
74
<li>Configure your copy of Apache so that it includes the
74
<li><p>Configure your copy of Apache so that it includes the
75
    <code>mod_proxy</code> module.  If you are building from source,
75
    <code>mod_proxy</code> module.  If you are building from source,
76
    the easiest way to do this is to include the
76
    the easiest way to do this is to include the
77
    <code>--enable-module=proxy</code> directive on the
77
    <code>--enable-module=proxy</code> directive on the
78
    <code>./configure</code> command line.</li>
78
    <code>./configure</code> command line.</p></li>
79
<li>If not already added for you, make sure that you are loading the
79
<li><p>If not already added for you, make sure that you are loading the
80
    <code>mod_proxy</code> module at Apache startup time, by using the
80
    <code>mod_proxy</code> module at Apache startup time, by using the
81
    following directives in your <code>httpd.conf</code> file:
81
    following directives in your <code>httpd.conf</code> file:</p>
82
<source>
82
<source><![CDATA[LoadModule proxy_module  {path-to-modules}/mod_proxy.so
83
LoadModule proxy_module  {path-to-modules}/mod_proxy.so
83
AddModule  mod_proxy.c]]></source></li>
84
AddModule  mod_proxy.c
84
<li><p>Include two directives in your <code>httpd.conf</code> file for
85
</source></li>
86
<li>Include two directives in your <code>httpd.conf</code> file for
87
    each web application that you wish to forward to Tomcat.  For
85
    each web application that you wish to forward to Tomcat.  For
88
    example, to forward an application at context path <code>/myapp</code>:
86
    example, to forward an application at context path <code>/myapp</code>:</p>
89
<source>
87
<source><![CDATA[ProxyPass         /myapp  http://localhost:8081/myapp
90
ProxyPass         /myapp  http://localhost:8081/myapp
88
ProxyPassReverse  /myapp  http://localhost:8081/myapp]]></source>
91
ProxyPassReverse  /myapp  http://localhost:8081/myapp
89
    <p>which tells Apache to forward URLs of the form
92
</source>
93
    which tells Apache to forward URLs of the form
94
    <code>http://localhost/myapp/*</code> to the Tomcat connector
90
    <code>http://localhost/myapp/*</code> to the Tomcat connector
95
    listening on port 8081.</li>
91
    listening on port 8081.</p></li>
96
<li>Configure your copy of Tomcat to include a special
92
<li><p>Configure your copy of Tomcat to include a special
97
    <code>&lt;Connector&gt;</code> element, with appropriate
93
    <code>&lt;Connector&gt;</code> element, with appropriate
98
    proxy settings, for example:
94
    proxy settings, for example:</p>
99
<source>
95
<source><![CDATA[<Connector port="8081" ...
100
&lt;Connector port="8081" ...
101
              proxyName="www.mycompany.com"
96
              proxyName="www.mycompany.com"
102
              proxyPort="80"/&gt;
97
              proxyPort="80"/>]]></source>
103
</source>
98
    <p>which will cause servlets inside this web application to think that
104
    which will cause servlets inside this web application to think that
105
    all proxied requests were directed to <code>www.mycompany.com</code>
99
    all proxied requests were directed to <code>www.mycompany.com</code>
106
    on port 80.</li>
100
    on port 80.</p></li>
107
<li>It is legal to omit the <code>proxyName</code> attribute from the
101
<li><p>It is legal to omit the <code>proxyName</code> attribute from the
108
    <code>&lt;Connector&gt;</code> element.  If you do so, the value
102
    <code>&lt;Connector&gt;</code> element.  If you do so, the value
109
    returned by <code>request.getServerName()</code> will by the host
103
    returned by <code>request.getServerName()</code> will by the host
110
    name on which Tomcat is running.  In the example above, it would be
104
    name on which Tomcat is running.  In the example above, it would be
111
    <code>localhost</code>.</li>
105
    <code>localhost</code>.</p></li>
112
<li>If you also have a <code>&lt;Connector&gt;</code> listening on port
106
<li><p>If you also have a <code>&lt;Connector&gt;</code> listening on port
113
    8080 (nested within the same <a href="config/service.html">Service</a>
107
    8080 (nested within the same <a href="config/service.html">Service</a>
114
    element), the requests to either port will share the same set of
108
    element), the requests to either port will share the same set of
115
    virtual hosts and web applications.</li>
109
    virtual hosts and web applications.</p></li>
116
<li>You might wish to use the IP filtering features of your operating
110
<li><p>You might wish to use the IP filtering features of your operating
117
    system to restrict connections to port 8081 (in this example) to
111
    system to restrict connections to port 8081 (in this example) to
118
    be allowed <strong>only</strong> from the server that is running
112
    be allowed <strong>only</strong> from the server that is running
119
    Apache.</li>
113
    Apache.</p></li>
120
<li>Alternatively, you can set up a series of web applications that are
114
<li><p>Alternatively, you can set up a series of web applications that are
121
    only available via proxying, as follows:
115
    only available via proxying, as follows:</p>
122
    <ul>
116
    <ul>
123
    <li>Configure another <code>&lt;Service&gt;</code> that contains
117
    <li>Configure another <code>&lt;Service&gt;</code> that contains
124
        only a <code>&lt;Connector&gt;</code> for the proxy port.</li>
118
        only a <code>&lt;Connector&gt;</code> for the proxy port.</li>
Lines 129-137 Link Here
129
    <li>Optionally, protect port 8081 with IP filters as described
123
    <li>Optionally, protect port 8081 with IP filters as described
130
        earlier.</li>
124
        earlier.</li>
131
    </ul></li>
125
    </ul></li>
132
<li>When requests are proxied by Apache, the web server will be recording
126
<li><p>When requests are proxied by Apache, the web server will be recording
133
    these requests in its access log.  Therefore, you will generally want to
127
    these requests in its access log.  Therefore, you will generally want to
134
    disable any access logging performed by Tomcat itself.</li>
128
    disable any access logging performed by Tomcat itself.</p></li>
135
</ol>
129
</ol>
136
130
137
<p>When requests are proxied in this manner, <strong>all</strong> requests
131
<p>When requests are proxied in this manner, <strong>all</strong> requests
(-)webapps/docs/realm-howto.xml (-129 / +94 lines)
Lines 53-59 Link Here
53
<p>For information about utilizing the <em>Single Sign On</em> feature of
53
<p>For information about utilizing the <em>Single Sign On</em> feature of
54
Tomcat (allowing a user to authenticate themselves once across the entire
54
Tomcat (allowing a user to authenticate themselves once across the entire
55
set of web applications associated with a virtual host), see
55
set of web applications associated with a virtual host), see
56
<a href="config/host.html#Single Sign On">here</a>.</p>
56
<a href="config/host.html#Single_Sign_On">here</a>.</p>
57
57
58
</section>
58
</section>
59
59
Lines 104-110 Link Here
104
</ul>
104
</ul>
105
105
106
<p>It is also possible to write your own <code>Realm</code> implementation,
106
<p>It is also possible to write your own <code>Realm</code> implementation,
107
and integrate it with Tomcat.  To do so, you need to:
107
and integrate it with Tomcat.  To do so, you need to:</p>
108
<ul>
108
<ul>
109
  <li>Implement <code>org.apache.catalina.Realm</code>,</li>
109
  <li>Implement <code>org.apache.catalina.Realm</code>,</li>
110
  <li>Place your compiled realm in $CATALINA_HOME/lib,</li>
110
  <li>Place your compiled realm in $CATALINA_HOME/lib,</li>
Lines 111-117 Link Here
111
  <li>Declare your realm as described in the "Configuring a Realm" section below,</li>
111
  <li>Declare your realm as described in the "Configuring a Realm" section below,</li>
112
  <li>Declare your realm to the <a href="mbeans-descriptor-howto.html">MBeans Descriptor</a>.</li>
112
  <li>Declare your realm to the <a href="mbeans-descriptor-howto.html">MBeans Descriptor</a>.</li>
113
</ul>
113
</ul>
114
</p>
115
114
116
</subsection>
115
</subsection>
117
116
Lines 123-132 Link Here
123
general, you will be adding an XML element to your <code>conf/server.xml</code>
122
general, you will be adding an XML element to your <code>conf/server.xml</code>
124
configuration file, that looks something like this:</p>
123
configuration file, that looks something like this:</p>
125
124
126
<source>
125
<source><![CDATA[<Realm className="... class name for this implementation"
127
&lt;Realm className="... class name for this implementation"
126
       ... other attributes for this implementation .../>]]></source>
128
       ... other attributes for this implementation .../&gt;
129
</source>
130
127
131
<p>The <code>&lt;Realm&gt;</code> element can be nested inside any one of
128
<p>The <code>&lt;Realm&gt;</code> element can be nested inside any one of
132
of the following <code>Container</code> elements.  The location of the
129
of the following <code>Container</code> elements.  The location of the
Lines 196-203 Link Here
196
    method will return the digested password.</li>
193
    method will return the digested password.</li>
197
<li>If you want to execute a command line utility to calculate the digested
194
<li>If you want to execute a command line utility to calculate the digested
198
    password, simply execute
195
    password, simply execute
199
<source>CATALINA_HOME/bin/digest.[bat|sh] -a {algorithm} {cleartext-password}
196
<source>CATALINA_HOME/bin/digest.[bat|sh] -a {algorithm} {cleartext-password}</source>
200
</source>
201
    and the digested version of this cleartext password will be returned to
197
    and the digested version of this cleartext password will be returned to
202
    standard output.</li>
198
    standard output.</li>
203
</ul>
199
</ul>
Lines 213-222 Link Here
213
   not specified in web.xml, the default value of <code>Authentication
209
   not specified in web.xml, the default value of <code>Authentication
214
   required</code> is used.</p>
210
   required</code> is used.</p>
215
211
216
<p>Non-ASCII usernames and/or passwords are supported using
212
<p>Non-ASCII usernames and/or passwords are supported using</p>
217
<source>CATALINA_HOME/bin/digest.[bat|sh] -a {algorithm} -e {encoding} {input}
213
<source>CATALINA_HOME/bin/digest.[bat|sh] -a {algorithm} -e {encoding} {input}</source>
218
</source>
214
<p>but care is required to ensure that the non-ASCII input is
219
but care is required to ensure that the non-ASCII input is
220
correctly passed to the digester.
215
correctly passed to the digester.
221
The digester returns <code>{input}:{digest}</code>. If the input appears
216
The digester returns <code>{input}:{digest}</code>. If the input appears
222
corrupted in the return, the digest will be invalid.</p>
217
corrupted in the return, the digest will be invalid.</p>
Lines 271-277 Link Here
271
266
272
<subsection name="JDBCRealm">
267
<subsection name="JDBCRealm">
273
268
274
<h3>Introduction</h3>
269
<h5>Introduction</h5>
275
270
276
<p><strong>JDBCRealm</strong> is an implementation of the Tomcat
271
<p><strong>JDBCRealm</strong> is an implementation of the Tomcat
277
<code>Realm</code> interface that looks up users in a relational database
272
<code>Realm</code> interface that looks up users in a relational database
Lines 303-309 Link Here
303
    </ul></li>
298
    </ul></li>
304
</ul>
299
</ul>
305
300
306
<h3>Quick Start</h3>
301
<h5>Quick Start</h5>
307
302
308
<p>To set up Tomcat to use JDBCRealm, you will need to follow these steps:</p>
303
<p>To set up Tomcat to use JDBCRealm, you will need to follow these steps:</p>
309
<ol>
304
<ol>
Lines 320-339 Link Here
320
<li>Restart Tomcat if it is already running.</li>
315
<li>Restart Tomcat if it is already running.</li>
321
</ol>
316
</ol>
322
317
323
<h3>Realm Element Attributes</h3>
318
<h5>Realm Element Attributes</h5>
324
319
325
<p>To configure JDBCRealm, you will create a <code>&lt;Realm&gt;</code>
320
<p>To configure JDBCRealm, you will create a <code>&lt;Realm&gt;</code>
326
element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code> file,
321
element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code> file,
327
as described <a href="#Configuring a Realm">above</a>. The attributes for the
322
as described <a href="#Configuring_a_Realm">above</a>. The attributes for the
328
JDBCRealm are defined in the <a href="config/realm.html">Realm</a> configuration
323
JDBCRealm are defined in the <a href="config/realm.html">Realm</a> configuration
329
documentation.</p>
324
documentation.</p>
330
325
331
<h3>Example</h3>
326
<h5>Example</h5>
332
327
333
<p>An example SQL script to create the needed tables might look something
328
<p>An example SQL script to create the needed tables might look something
334
like this (adapt the syntax as required for your particular database):</p>
329
like this (adapt the syntax as required for your particular database):</p>
335
<source>
330
<source>create table users (
336
create table users (
337
  user_name         varchar(15) not null primary key,
331
  user_name         varchar(15) not null primary key,
338
  user_pass         varchar(15) not null
332
  user_pass         varchar(15) not null
339
);
333
);
Lines 342-363 Link Here
342
  user_name         varchar(15) not null,
336
  user_name         varchar(15) not null,
343
  role_name         varchar(15) not null,
337
  role_name         varchar(15) not null,
344
  primary key (user_name, role_name)
338
  primary key (user_name, role_name)
345
);
339
);</source>
346
</source>
347
340
348
<p>Example <code>Realm</code> elements are included (commented out) in the
341
<p>Example <code>Realm</code> elements are included (commented out) in the
349
default <code>$CATALINA_BASE/conf/server.xml</code> file.  Here's an example
342
default <code>$CATALINA_BASE/conf/server.xml</code> file.  Here's an example
350
for using a MySQL database called "authority", configured with the tables
343
for using a MySQL database called "authority", configured with the tables
351
described above, and accessed with username "dbuser" and password "dbpass":</p>
344
described above, and accessed with username "dbuser" and password "dbpass":</p>
352
<source>
345
<source><![CDATA[<Realm className="org.apache.catalina.realm.JDBCRealm"
353
&lt;Realm className="org.apache.catalina.realm.JDBCRealm"
354
      driverName="org.gjt.mm.mysql.Driver"
346
      driverName="org.gjt.mm.mysql.Driver"
355
   connectionURL="jdbc:mysql://localhost/authority?user=dbuser&amp;amp;password=dbpass"
347
   connectionURL="jdbc:mysql://localhost/authority?user=dbuser&amp;password=dbpass"
356
       userTable="users" userNameCol="user_name" userCredCol="user_pass"
348
       userTable="users" userNameCol="user_name" userCredCol="user_pass"
357
   userRoleTable="user_roles" roleNameCol="role_name"/&gt;
349
   userRoleTable="user_roles" roleNameCol="role_name"/>]]></source>
358
</source>
359
350
360
<h3>Additional Notes</h3>
351
<h5>Additional Notes</h5>
361
352
362
<p>JDBCRealm operates according to the following rules:</p>
353
<p>JDBCRealm operates according to the following rules:</p>
363
<ul>
354
<ul>
Lines 384-390 Link Here
384
375
385
<subsection name="DataSourceRealm">
376
<subsection name="DataSourceRealm">
386
377
387
<h3>Introduction</h3>
378
<h5>Introduction</h5>
388
379
389
<p><strong>DataSourceRealm</strong> is an implementation of the Tomcat
380
<p><strong>DataSourceRealm</strong> is an implementation of the Tomcat
390
<code>Realm</code> interface that looks up users in a relational database
381
<code>Realm</code> interface that looks up users in a relational database
Lines 416-422 Link Here
416
    </ul></li>
407
    </ul></li>
417
</ul>
408
</ul>
418
409
419
<h3>Quick Start</h3>
410
<h5>Quick Start</h5>
420
411
421
<p>To set up Tomcat to use DataSourceRealm, you will need to follow these steps:</p>
412
<p>To set up Tomcat to use DataSourceRealm, you will need to follow these steps:</p>
422
<ol>
413
<ol>
Lines 433-452 Link Here
433
<li>Restart Tomcat if it is already running.</li>
424
<li>Restart Tomcat if it is already running.</li>
434
</ol>
425
</ol>
435
426
436
<h3>Realm Element Attributes</h3>
427
<h5>Realm Element Attributes</h5>
437
428
438
<p>To configure DataSourceRealm, you will create a <code>&lt;Realm&gt;</code>
429
<p>To configure DataSourceRealm, you will create a <code>&lt;Realm&gt;</code>
439
element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code> file,
430
element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code> file,
440
as described <a href="#Configuring a Realm">above</a>. The attributes for the
431
as described <a href="#Configuring_a_Realm">above</a>. The attributes for the
441
DataSourceRealm are defined in the <a href="config/realm.html">Realm</a>
432
DataSourceRealm are defined in the <a href="config/realm.html">Realm</a>
442
configuration documentation.</p>
433
configuration documentation.</p>
443
434
444
<h3>Example</h3>
435
<h5>Example</h5>
445
436
446
<p>An example SQL script to create the needed tables might look something
437
<p>An example SQL script to create the needed tables might look something
447
like this (adapt the syntax as required for your particular database):</p>
438
like this (adapt the syntax as required for your particular database):</p>
448
<source>
439
<source>create table users (
449
create table users (
450
  user_name         varchar(15) not null primary key,
440
  user_name         varchar(15) not null primary key,
451
  user_pass         varchar(15) not null
441
  user_pass         varchar(15) not null
452
);
442
);
Lines 455-474 Link Here
455
  user_name         varchar(15) not null,
445
  user_name         varchar(15) not null,
456
  role_name         varchar(15) not null,
446
  role_name         varchar(15) not null,
457
  primary key (user_name, role_name)
447
  primary key (user_name, role_name)
458
);
448
);</source>
459
</source>
460
449
461
<p>Here is an example for using a MySQL database called "authority", configured
450
<p>Here is an example for using a MySQL database called "authority", configured
462
with the tables described above, and accessed with the JNDI JDBC DataSource with
451
with the tables described above, and accessed with the JNDI JDBC DataSource with
463
name "java:/comp/env/jdbc/authority".</p>
452
name "java:/comp/env/jdbc/authority".</p>
464
<source>
453
<source><![CDATA[<Realm className="org.apache.catalina.realm.DataSourceRealm"
465
&lt;Realm className="org.apache.catalina.realm.DataSourceRealm"
466
   dataSourceName="jdbc/authority"
454
   dataSourceName="jdbc/authority"
467
   userTable="users" userNameCol="user_name" userCredCol="user_pass"
455
   userTable="users" userNameCol="user_name" userCredCol="user_pass"
468
   userRoleTable="user_roles" roleNameCol="role_name"/&gt;
456
   userRoleTable="user_roles" roleNameCol="role_name"/>]]></source>
469
</source>
470
457
471
<h3>Additional Notes</h3>
458
<h5>Additional Notes</h5>
472
459
473
<p>DataSourceRealm operates according to the following rules:</p>
460
<p>DataSourceRealm operates according to the following rules:</p>
474
<ul>
461
<ul>
Lines 495-501 Link Here
495
482
496
<subsection name="JNDIRealm">
483
<subsection name="JNDIRealm">
497
484
498
<h3>Introduction</h3>
485
<h5>Introduction</h5>
499
486
500
<p><strong>JNDIRealm</strong> is an implementation of the Tomcat
487
<p><strong>JNDIRealm</strong> is an implementation of the Tomcat
501
<code>Realm</code> interface that looks up users in an LDAP directory
488
<code>Realm</code> interface that looks up users in an LDAP directory
Lines 504-510 Link Here
504
supports a variety of approaches to using a directory for
491
supports a variety of approaches to using a directory for
505
authentication.</p>
492
authentication.</p>
506
493
507
<h4>Connecting to the directory</h4>
494
<h6>Connecting to the directory</h6>
508
495
509
<p>The realm's connection to the directory is defined by the
496
<p>The realm's connection to the directory is defined by the
510
<strong>connectionURL</strong> configuration attribute. This is a URL
497
<strong>connectionURL</strong> configuration attribute. This is a URL
Lines 528-534 Link Here
528
</p>
515
</p>
529
516
530
517
531
<h4>Selecting the user's directory entry</h4>
518
<h6>Selecting the user's directory entry</h6>
532
519
533
<p>Each user that can be authenticated must be represented in the
520
<p>Each user that can be authenticated must be represented in the
534
directory by an individual entry that corresponds to an element in the
521
directory by an individual entry that corresponds to an element in the
Lines 545-551 Link Here
545
532
546
<p>Otherwise the realm must search the directory to find a unique entry
533
<p>Otherwise the realm must search the directory to find a unique entry
547
containing the username. The following attributes configure this
534
containing the username. The following attributes configure this
548
search:
535
search:</p>
549
536
550
     <ul>
537
     <ul>
551
     <li><strong>userBase</strong> - the entry that is the base of
538
     <li><strong>userBase</strong> - the entry that is the base of
Lines 562-571 Link Here
562
         search filter to use after substitution of the username.</li>
549
         search filter to use after substitution of the username.</li>
563
550
564
    </ul>
551
    </ul>
565
</p>
566
552
567
553
568
<h4>Authenticating the user</h4>
554
<h6>Authenticating the user</h6>
569
555
570
<ul>
556
<ul>
571
<li>
557
<li>
Lines 577-584 Link Here
577
be authenticated.</p>
563
be authenticated.</p>
578
564
579
<p>For security reasons a directory may store a digest of the user's
565
<p>For security reasons a directory may store a digest of the user's
580
password rather than the clear text version (see <a href="#Digested
566
password rather than the clear text version (see
581
Passwords">Digested Passwords</a> for more information). In that case,
567
<a href="#Digested_Passwords">Digested Passwords</a> for more information). In that case,
582
as part of the simple bind operation the directory automatically
568
as part of the simple bind operation the directory automatically
583
computes the correct digest of the plaintext password presented by the
569
computes the correct digest of the plaintext password presented by the
584
user before validating it against the stored value. In bind mode,
570
user before validating it against the stored value. In bind mode,
Lines 612-618 Link Here
612
</li>
598
</li>
613
</ul>
599
</ul>
614
600
615
<h4>Assigning roles to the user</h4>
601
<h6>Assigning roles to the user</h6>
616
602
617
<p>The directory realm supports two approaches to the representation
603
<p>The directory realm supports two approaches to the representation
618
of roles in the directory:</p>
604
of roles in the directory:</p>
Lines 672-678 Link Here
672
</ul>
658
</ul>
673
<p>A combination of both approaches to role representation may be used.</p>
659
<p>A combination of both approaches to role representation may be used.</p>
674
660
675
<h3>Quick Start</h3>
661
<h5>Quick Start</h5>
676
662
677
<p>To set up Tomcat to use JNDIRealm, you will need to follow these steps:</p>
663
<p>To set up Tomcat to use JNDIRealm, you will need to follow these steps:</p>
678
<ol>
664
<ol>
Lines 686-700 Link Here
686
<li>Restart Tomcat if it is already running.</li>
672
<li>Restart Tomcat if it is already running.</li>
687
</ol>
673
</ol>
688
674
689
<h3>Realm Element Attributes</h3>
675
<h5>Realm Element Attributes</h5>
690
676
691
<p>To configure JNDIRealm, you will create a <code>&lt;Realm&gt;</code>
677
<p>To configure JNDIRealm, you will create a <code>&lt;Realm&gt;</code>
692
element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code> file,
678
element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code> file,
693
as described <a href="#Configuring a Realm">above</a>. The attributes for the
679
as described <a href="#Configuring_a_Realm">above</a>. The attributes for the
694
JNDIRealm are defined in the <a href="config/realm.html">Realm</a> configuration
680
JNDIRealm are defined in the <a href="config/realm.html">Realm</a> configuration
695
documentation.</p>
681
documentation.</p>
696
682
697
<h3>Example</h3>
683
<h5>Example</h5>
698
684
699
<p>Creation of the appropriate schema in your directory server is beyond the
685
<p>Creation of the appropriate schema in your directory server is beyond the
700
scope of this document, because it is unique to each directory server
686
scope of this document, because it is unique to each directory server
Lines 704-715 Link Here
704
<a href="http://www.openldap.org">http://www.openldap.org</a>.  Assume that
690
<a href="http://www.openldap.org">http://www.openldap.org</a>.  Assume that
705
your <code>slapd.conf</code> file contains the following settings
691
your <code>slapd.conf</code> file contains the following settings
706
(among others):</p>
692
(among others):</p>
707
<source>
693
<source>database ldbm
708
database ldbm
709
suffix dc="mycompany",dc="com"
694
suffix dc="mycompany",dc="com"
710
rootdn "cn=Manager,dc=mycompany,dc=com"
695
rootdn "cn=Manager,dc=mycompany,dc=com"
711
rootpw secret
696
rootpw secret</source>
712
</source>
713
697
714
<p>We will assume for <code>connectionURL</code> that the directory
698
<p>We will assume for <code>connectionURL</code> that the directory
715
server runs on the same machine as Tomcat.  See <a
699
server runs on the same machine as Tomcat.  See <a
Lines 720-728 Link Here
720
<p>Next, assume that this directory server has been populated with elements
704
<p>Next, assume that this directory server has been populated with elements
721
as shown below (in LDIF format):</p>
705
as shown below (in LDIF format):</p>
722
706
723
<source>
707
<source># Define top-level entry
724
725
# Define top-level entry
726
dn: dc=mycompany,dc=com
708
dn: dc=mycompany,dc=com
727
objectClass: dcObject
709
objectClass: dcObject
728
dc:mycompany
710
dc:mycompany
Lines 768-775 Link Here
768
dn: cn=role1,ou=groups,dc=mycompany,dc=com
750
dn: cn=role1,ou=groups,dc=mycompany,dc=com
769
objectClass: groupOfUniqueNames
751
objectClass: groupOfUniqueNames
770
cn: role1
752
cn: role1
771
uniqueMember: uid=fbloggs,ou=people,dc=mycompany,dc=com
753
uniqueMember: uid=fbloggs,ou=people,dc=mycompany,dc=com</source>
772
</source>
773
754
774
<p>An example <code>Realm</code> element for the OpenLDAP directory
755
<p>An example <code>Realm</code> element for the OpenLDAP directory
775
server configured as described above might look like this, assuming
756
server configured as described above might look like this, assuming
Lines 777-791 Link Here
777
application and that an anonymous connection is sufficient to search
758
application and that an anonymous connection is sufficient to search
778
the directory and retrieve role information:</p>
759
the directory and retrieve role information:</p>
779
760
780
<source>
761
<source><![CDATA[<Realm   className="org.apache.catalina.realm.JNDIRealm"
781
&lt;Realm   className="org.apache.catalina.realm.JNDIRealm"
782
     connectionURL="ldap://localhost:389"
762
     connectionURL="ldap://localhost:389"
783
       userPattern="uid={0},ou=people,dc=mycompany,dc=com"
763
       userPattern="uid={0},ou=people,dc=mycompany,dc=com"
784
          roleBase="ou=groups,dc=mycompany,dc=com"
764
          roleBase="ou=groups,dc=mycompany,dc=com"
785
          roleName="cn"
765
          roleName="cn"
786
        roleSearch="(uniqueMember={0})"
766
        roleSearch="(uniqueMember={0})"
787
/&gt;
767
/>]]></source>
788
</source>
789
768
790
<p>With this configuration, the realm will determine the user's
769
<p>With this configuration, the realm will determine the user's
791
distinguished name by substituting the username into the
770
distinguished name by substituting the username into the
Lines 803-810 Link Here
803
use an attribute of the user's entry to hold roles. Now the entry for
782
use an attribute of the user's entry to hold roles. Now the entry for
804
Janet Jones might read as follows:</p>
783
Janet Jones might read as follows:</p>
805
784
806
<source>
785
<source>dn: uid=jjones,ou=people,dc=mycompany,dc=com
807
dn: uid=jjones,ou=people,dc=mycompany,dc=com
808
objectClass: inetOrgPerson
786
objectClass: inetOrgPerson
809
uid: jjones
787
uid: jjones
810
sn: jones
788
sn: jones
Lines 812-824 Link Here
812
mail: j.jones@mycompany.com
790
mail: j.jones@mycompany.com
813
memberOf: role2
791
memberOf: role2
814
memberOf: role3
792
memberOf: role3
815
userPassword: janet
793
userPassword: janet</source>
816
</source>
817
794
818
<p> This realm configuration would satisfy the new requirements:</p>
795
<p> This realm configuration would satisfy the new requirements:</p>
819
796
820
<source>
797
<source><![CDATA[<Realm   className="org.apache.catalina.realm.JNDIRealm"
821
&lt;Realm   className="org.apache.catalina.realm.JNDIRealm"
822
     connectionURL="ldap://localhost:389"
798
     connectionURL="ldap://localhost:389"
823
          userBase="ou=people,dc=mycompany,dc=com"
799
          userBase="ou=people,dc=mycompany,dc=com"
824
        userSearch="(mail={0})"
800
        userSearch="(mail={0})"
Lines 826-833 Link Here
826
          roleBase="ou=groups,dc=mycompany,dc=com"
802
          roleBase="ou=groups,dc=mycompany,dc=com"
827
          roleName="cn"
803
          roleName="cn"
828
        roleSearch="(uniqueMember={0})"
804
        roleSearch="(uniqueMember={0})"
829
/&gt;
805
/>]]></source>
830
</source>
831
806
832
<p>Now when Janet Jones logs in as "j.jones@mycompany.com", the realm
807
<p>Now when Janet Jones logs in as "j.jones@mycompany.com", the realm
833
searches the directory for a unique entry with that value as its mail
808
searches the directory for a unique entry with that value as its mail
Lines 842-849 Link Here
842
the password from the directory and making a local comparison in the
817
the password from the directory and making a local comparison in the
843
realm, you might use a realm configuration like this:</p>
818
realm, you might use a realm configuration like this:</p>
844
819
845
<source>
820
<source><![CDATA[<Realm   className="org.apache.catalina.realm.JNDIRealm"
846
&lt;Realm   className="org.apache.catalina.realm.JNDIRealm"
847
    connectionName="cn=Manager,dc=mycompany,dc=com"
821
    connectionName="cn=Manager,dc=mycompany,dc=com"
848
connectionPassword="secret"
822
connectionPassword="secret"
849
     connectionURL="ldap://localhost:389"
823
     connectionURL="ldap://localhost:389"
Lines 852-864 Link Here
852
          roleBase="ou=groups,dc=mycompany,dc=com"
826
          roleBase="ou=groups,dc=mycompany,dc=com"
853
          roleName="cn"
827
          roleName="cn"
854
        roleSearch="(uniqueMember={0})"
828
        roleSearch="(uniqueMember={0})"
855
/&gt;
829
/>]]></source>
856
</source>
857
830
858
<p>However, as discussed above, the default bind mode for
831
<p>However, as discussed above, the default bind mode for
859
authentication is usually to be preferred.</p>
832
authentication is usually to be preferred.</p>
860
833
861
<h3>Additional Notes</h3>
834
<h5>Additional Notes</h5>
862
835
863
<p>JNDIRealm operates according to the following rules:</p>
836
<p>JNDIRealm operates according to the following rules:</p>
864
<ul>
837
<ul>
Lines 885-891 Link Here
885
858
886
<subsection name="UserDatabaseRealm">
859
<subsection name="UserDatabaseRealm">
887
860
888
<h3>Introduction</h3>
861
<h5>Introduction</h5>
889
862
890
<p><strong>UserDatabaseRealm</strong> is an implementation of the Tomcat
863
<p><strong>UserDatabaseRealm</strong> is an implementation of the Tomcat
891
<code>Realm</code> interface that uses a JNDI resource to store user
864
<code>Realm</code> interface that uses a JNDI resource to store user
Lines 897-930 Link Here
897
and their roles may all be editing dynamically, typically via JMX. Changes may
870
and their roles may all be editing dynamically, typically via JMX. Changes may
898
be saved and will be reflected in the XML file.</p>
871
be saved and will be reflected in the XML file.</p>
899
872
900
<h3>Realm Element Attributes</h3>
873
<h5>Realm Element Attributes</h5>
901
874
902
<p>To configure UserDatabaseRealm, you will create a <code>&lt;Realm&gt;</code>
875
<p>To configure UserDatabaseRealm, you will create a <code>&lt;Realm&gt;</code>
903
element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code> file,
876
element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code> file,
904
as described <a href="#Configuring a Realm">above</a>. The attributes for the
877
as described <a href="#Configuring_a_Realm">above</a>. The attributes for the
905
UserDatabaseRealm are defined in the <a href="config/realm.html">Realm</a>
878
UserDatabaseRealm are defined in the <a href="config/realm.html">Realm</a>
906
configuration documentation.</p>
879
configuration documentation.</p>
907
880
908
<h3>User File Format</h3>
881
<h5>User File Format</h5>
909
882
910
<p>The users file uses the same format as the
883
<p>The users file uses the same format as the
911
<a href="#MemoryRealm">MemoryRealm</a>.</p>
884
<a href="#MemoryRealm">MemoryRealm</a>.</p>
912
885
913
<h3>Example</h3>
886
<h5>Example</h5>
914
887
915
<p>The default installation of Tomcat is configured with a UserDatabaseRealm
888
<p>The default installation of Tomcat is configured with a UserDatabaseRealm
916
nested inside the <code>&lt;Engine&gt;</code> element, so that it applies
889
nested inside the <code>&lt;Engine&gt;</code> element, so that it applies
917
to all virtual hosts and web applications.  The default contents of the
890
to all virtual hosts and web applications.  The default contents of the
918
<code>conf/tomcat-users.xml</code> file is:</p>
891
<code>conf/tomcat-users.xml</code> file is:</p>
919
<source>
892
<source><![CDATA[<tomcat-users>
920
&lt;tomcat-users&gt;
893
  <user name="tomcat" password="tomcat" roles="tomcat" />
921
  &lt;user name="tomcat" password="tomcat" roles="tomcat" /&gt;
894
  <user name="role1"  password="tomcat" roles="role1"  />
922
  &lt;user name="role1"  password="tomcat" roles="role1"  /&gt;
895
  <user name="both"   password="tomcat" roles="tomcat,role1" />
923
  &lt;user name="both"   password="tomcat" roles="tomcat,role1" /&gt;
896
</tomcat-users>]]></source>
924
&lt;/tomcat-users&gt;
925
</source>
926
897
927
<h3>Additional Notes</h3>
898
<h5>Additional Notes</h5>
928
899
929
<p>UserDatabaseRealm operates according to the following rules:</p>
900
<p>UserDatabaseRealm operates according to the following rules:</p>
930
<ul>
901
<ul>
Lines 950-956 Link Here
950
921
951
<subsection name="MemoryRealm">
922
<subsection name="MemoryRealm">
952
923
953
<h3>Introduction</h3>
924
<h5>Introduction</h5>
954
925
955
<p><strong>MemoryRealm</strong> is a simple demonstration implementation of the
926
<p><strong>MemoryRealm</strong> is a simple demonstration implementation of the
956
Tomcat <code>Realm</code> interface.  It is not designed for production use.
927
Tomcat <code>Realm</code> interface.  It is not designed for production use.
Lines 959-973 Link Here
959
from <code>$CATALINA_BASE/conf/tomcat-users.xml</code>).  Changes to the data
930
from <code>$CATALINA_BASE/conf/tomcat-users.xml</code>).  Changes to the data
960
in this file are not recognized until Tomcat is restarted.</p>
931
in this file are not recognized until Tomcat is restarted.</p>
961
932
962
<h3>Realm Element Attributes</h3>
933
<h5>Realm Element Attributes</h5>
963
934
964
<p>To configure MemoryRealm, you will create a <code>&lt;Realm&gt;</code>
935
<p>To configure MemoryRealm, you will create a <code>&lt;Realm&gt;</code>
965
element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code> file,
936
element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code> file,
966
as described <a href="#Configuring a Realm">above</a>. The attributes for the
937
as described <a href="#Configuring_a_Realm">above</a>. The attributes for the
967
MemoryRealm are defined in the <a href="config/realm.html">Realm</a>
938
MemoryRealm are defined in the <a href="config/realm.html">Realm</a>
968
configuration documentation.</p>
939
configuration documentation.</p>
969
940
970
<h3>User File Format</h3>
941
<h5>User File Format</h5>
971
942
972
<p>The users file (by default, <code>conf/tomcat-users.xml</code> must be an
943
<p>The users file (by default, <code>conf/tomcat-users.xml</code> must be an
973
XML document, with a root element <code>&lt;tomcat-users&gt;</code>.  Nested
944
XML document, with a root element <code>&lt;tomcat-users&gt;</code>.  Nested
Lines 978-989 Link Here
978
<li><strong>password</strong> - Password this user must log on with (in
949
<li><strong>password</strong> - Password this user must log on with (in
979
    clear text if the <code>digest</code> attribute was not set on the
950
    clear text if the <code>digest</code> attribute was not set on the
980
    <code>&lt;Realm&gt;</code> element, or digested appropriately as
951
    <code>&lt;Realm&gt;</code> element, or digested appropriately as
981
    described <a href="#Digested Passwords">here</a> otherwise).</li>
952
    described <a href="#Digested_Passwords">here</a> otherwise).</li>
982
<li><strong>roles</strong> - Comma-delimited list of the role names
953
<li><strong>roles</strong> - Comma-delimited list of the role names
983
    associated with this user.</li>
954
    associated with this user.</li>
984
</ul>
955
</ul>
985
956
986
<h3>Additional Notes</h3>
957
<h5>Additional Notes</h5>
987
958
988
<p>MemoryRealm operates according to the following rules:</p>
959
<p>MemoryRealm operates according to the following rules:</p>
989
<ul>
960
<ul>
Lines 1011-1017 Link Here
1011
982
1012
<subsection name="JAASRealm">
983
<subsection name="JAASRealm">
1013
984
1014
<h3>Introduction</h3>
985
<h5>Introduction</h5>
1015
986
1016
        <p><strong>JAASRealm</strong> is an implementation of the Tomcat
987
        <p><strong>JAASRealm</strong> is an implementation of the Tomcat
1017
6 <code>Realm</code> interface that authenticates users through the Java
988
6 <code>Realm</code> interface that authenticates users through the Java
Lines 1032-1038 Link Here
1032
integration with the CMA as implemented by Tomcat.
1003
integration with the CMA as implemented by Tomcat.
1033
        </p>
1004
        </p>
1034
1005
1035
        <h3>Quick Start</h3>
1006
        <h5>Quick Start</h5>
1036
        <p>To set up Tomcat to use JAASRealm with your own JAAS login module,
1007
        <p>To set up Tomcat to use JAASRealm with your own JAAS login module,
1037
 you will need to follow these steps:</p>
1008
 you will need to follow these steps:</p>
1038
        <ol>
1009
        <ol>
Lines 1065-1071 Link Here
1065
          <li>Configure the JAASRealm module in your server.xml </li>
1036
          <li>Configure the JAASRealm module in your server.xml </li>
1066
          <li>Restart Tomcat if it is already running.</li>
1037
          <li>Restart Tomcat if it is already running.</li>
1067
        </ol>
1038
        </ol>
1068
        <h3>Realm Element Attributes</h3>
1039
        <h5>Realm Element Attributes</h5>
1069
        <p>To configure JAASRealm as for step 6 above, you create
1040
        <p>To configure JAASRealm as for step 6 above, you create
1070
a <code>&lt;Realm&gt;</code> element and nest it in your
1041
a <code>&lt;Realm&gt;</code> element and nest it in your
1071
<code>$CATALINA_BASE/conf/server.xml</code>
1042
<code>$CATALINA_BASE/conf/server.xml</code>
Lines 1073-1088 Link Here
1073
JAASRealm are defined in the <a href="config/realm.html">Realm</a>
1044
JAASRealm are defined in the <a href="config/realm.html">Realm</a>
1074
configuration documentation.</p>
1045
configuration documentation.</p>
1075
1046
1076
<h3>Example</h3>
1047
<h5>Example</h5>
1077
1048
1078
<p>Here is an example of how your server.xml snippet should look.</p>
1049
<p>Here is an example of how your server.xml snippet should look.</p>
1079
1050
1080
<source>
1051
<source><![CDATA[<Realm className="org.apache.catalina.realm.JAASRealm"
1081
&lt;Realm className="org.apache.catalina.realm.JAASRealm"
1082
                appName="MyFooRealm"
1052
                appName="MyFooRealm"
1083
    userClassNames="org.foobar.realm.FooUser"
1053
    userClassNames="org.foobar.realm.FooUser"
1084
     roleClassNames="org.foobar.realm.FooRole"/&gt;
1054
     roleClassNames="org.foobar.realm.FooRole"/>]]></source>
1085
</source>
1086
1055
1087
<p>It is the responsibility of your login module to create and save User and
1056
<p>It is the responsibility of your login module to create and save User and
1088
Role objects representing Principals for the user
1057
Role objects representing Principals for the user
Lines 1100-1106 Link Here
1100
and restarting the server, without any code changes to your application.</li>
1069
and restarting the server, without any code changes to your application.</li>
1101
        </ul>
1070
        </ul>
1102
1071
1103
        <h3>Additional Notes</h3>
1072
        <h5>Additional Notes</h5>
1104
        <ul>
1073
        <ul>
1105
          <li>When a user attempts to access a protected resource for
1074
          <li>When a user attempts to access a protected resource for
1106
              the first time, Tomcat will call the <code>authenticate()</code>
1075
              the first time, Tomcat will call the <code>authenticate()</code>
Lines 1125-1131 Link Here
1125
1094
1126
<subsection name="CombinedRealm">
1095
<subsection name="CombinedRealm">
1127
1096
1128
    <h3>Introduction</h3>
1097
    <h5>Introduction</h5>
1129
1098
1130
    <p><strong>CombinedRealm</strong> is an implementation of the Tomcat
1099
    <p><strong>CombinedRealm</strong> is an implementation of the Tomcat
1131
    <code>Realm</code> interface that authenticates users through one or more
1100
    <code>Realm</code> interface that authenticates users through one or more
Lines 1142-1148 Link Here
1142
    listed. Authentication against any Realm will be sufficient to authenticate
1111
    listed. Authentication against any Realm will be sufficient to authenticate
1143
    the user.</p>
1112
    the user.</p>
1144
1113
1145
    <h3>Realm Element Attributes</h3>
1114
    <h5>Realm Element Attributes</h5>
1146
    <p>To configure a CombinedRealm, you create a <code>&lt;Realm&gt;</code>
1115
    <p>To configure a CombinedRealm, you create a <code>&lt;Realm&gt;</code>
1147
    element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code>
1116
    element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code>
1148
    file within your <code>&lt;Engine&gt;</code> or <code>&lt;Host&gt;</code>.
1117
    file within your <code>&lt;Engine&gt;</code> or <code>&lt;Host&gt;</code>.
Lines 1149-1175 Link Here
1149
    You can also nest inside a <code>&lt;Context&gt;</code> node in a
1118
    You can also nest inside a <code>&lt;Context&gt;</code> node in a
1150
    <code>context.xml</code> file.</p>
1119
    <code>context.xml</code> file.</p>
1151
1120
1152
<h3>Example</h3>
1121
<h5>Example</h5>
1153
1122
1154
<p>Here is an example of how your server.xml snippet should look to use a
1123
<p>Here is an example of how your server.xml snippet should look to use a
1155
UserDatabase Realm and a DataSource Realm.</p>
1124
UserDatabase Realm and a DataSource Realm.</p>
1156
1125
1157
<source>
1126
<source><![CDATA[<Realm className="org.apache.catalina.realm.CombinedRealm" >
1158
&lt;Realm className="org.apache.catalina.realm.CombinedRealm" &gt;
1127
   <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
1159
   &lt;Realm className="org.apache.catalina.realm.UserDatabaseRealm"
1128
             resourceName="UserDatabase"/>
1160
             resourceName="UserDatabase"/&gt;
1129
   <Realm className="org.apache.catalina.realm.DataSourceRealm"
1161
   &lt;Realm className="org.apache.catalina.realm.DataSourceRealm"
1162
             dataSourceName="jdbc/authority"
1130
             dataSourceName="jdbc/authority"
1163
             userTable="users" userNameCol="user_name" userCredCol="user_pass"
1131
             userTable="users" userNameCol="user_name" userCredCol="user_pass"
1164
             userRoleTable="user_roles" roleNameCol="role_name"/&gt;
1132
             userRoleTable="user_roles" roleNameCol="role_name"/>
1165
&lt;/Realm&gt;
1133
</Realm>]]></source>
1166
</source>
1167
1134
1168
</subsection>
1135
</subsection>
1169
1136
1170
<subsection name="LockOutRealm">
1137
<subsection name="LockOutRealm">
1171
1138
1172
    <h3>Introduction</h3>
1139
    <h5>Introduction</h5>
1173
1140
1174
    <p><strong>LockOutRealm</strong> is an implementation of the Tomcat
1141
    <p><strong>LockOutRealm</strong> is an implementation of the Tomcat
1175
    <code>Realm</code> interface that extends the CombinedRealm to provide lock
1142
    <code>Realm</code> interface that extends the CombinedRealm to provide lock
Lines 1192-1198 Link Here
1192
    listed. Authentication against any Realm will be sufficient to authenticate
1159
    listed. Authentication against any Realm will be sufficient to authenticate
1193
    the user.</p>
1160
    the user.</p>
1194
1161
1195
    <h3>Realm Element Attributes</h3>
1162
    <h5>Realm Element Attributes</h5>
1196
    <p>To configure a LockOutRealm, you create a <code>&lt;Realm&gt;</code>
1163
    <p>To configure a LockOutRealm, you create a <code>&lt;Realm&gt;</code>
1197
    element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code>
1164
    element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code>
1198
    file within your <code>&lt;Engine&gt;</code> or <code>&lt;Host&gt;</code>.
1165
    file within your <code>&lt;Engine&gt;</code> or <code>&lt;Host&gt;</code>.
Lines 1201-1217 Link Here
1201
    LockOutRealm are defined in the <a href="config/realm.html">Realm</a>
1168
    LockOutRealm are defined in the <a href="config/realm.html">Realm</a>
1202
    configuration documentation.</p>
1169
    configuration documentation.</p>
1203
1170
1204
<h3>Example</h3>
1171
<h5>Example</h5>
1205
1172
1206
<p>Here is an example of how your server.xml snippet should look to add lock out
1173
<p>Here is an example of how your server.xml snippet should look to add lock out
1207
functionality to a UserDatabase Realm.</p>
1174
functionality to a UserDatabase Realm.</p>
1208
1175
1209
<source>
1176
<source><![CDATA[<Realm className="org.apache.catalina.realm.LockOutRealm" >
1210
&lt;Realm className="org.apache.catalina.realm.LockOutRealm" &gt;
1177
   <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
1211
   &lt;Realm className="org.apache.catalina.realm.UserDatabaseRealm"
1178
             resourceName="UserDatabase"/>
1212
             resourceName="UserDatabase"/&gt;
1179
</Realm>]]></source>
1213
&lt;/Realm&gt;
1214
</source>
1215
1180
1216
</subsection>
1181
</subsection>
1217
1182
(-)webapps/docs/rewrite.xml (-97 / +84 lines)
Lines 108-183 Link Here
108
          where <em>NAME_OF_VARIABLE</em> can be a string taken
108
          where <em>NAME_OF_VARIABLE</em> can be a string taken
109
          from the following list:
109
          from the following list:
110
110
111
          <table border="1">
111
          <ul>
112
112
          <li>
113
            <tr>
113
          <p><b>HTTP headers:</b></p>
114
              <th>HTTP headers:</th> <th>connection &amp; request:</th> <th></th>
114
          <p>
115
            </tr>
115
            HTTP_USER_AGENT<br />
116
116
            HTTP_REFERER<br />
117
            <tr>
117
            HTTP_COOKIE<br />
118
              <td>
118
            HTTP_FORWARDED<br />
119
                 HTTP_USER_AGENT<br />
119
            HTTP_HOST<br />
120
                 HTTP_REFERER<br />
120
            HTTP_PROXY_CONNECTION<br />
121
                 HTTP_COOKIE<br />
121
            HTTP_ACCEPT<br />
122
                 HTTP_FORWARDED<br />
122
          </p>
123
                 HTTP_HOST<br />
123
          </li>
124
                 HTTP_PROXY_CONNECTION<br />
124
          <li>
125
                 HTTP_ACCEPT<br />
125
          <p><b>connection &amp; request:</b></p>
126
              </td>
126
          <p>
127
127
            REMOTE_ADDR<br />
128
              <td>
128
            REMOTE_HOST<br />
129
                 REMOTE_ADDR<br />
129
            REMOTE_PORT<br />
130
                 REMOTE_HOST<br />
130
            REMOTE_USER<br />
131
                 REMOTE_PORT<br />
131
            REMOTE_IDENT<br />
132
                 REMOTE_USER<br />
132
            REQUEST_METHOD<br />
133
                 REMOTE_IDENT<br />
133
            SCRIPT_FILENAME<br />
134
                 REQUEST_METHOD<br />
134
            REQUEST_PATH<br />
135
                 SCRIPT_FILENAME<br />
135
            CONTEXT_PATH<br />
136
                 REQUEST_PATH<br />
136
            SERVLET_PATH<br />
137
                 CONTEXT_PATH<br />
137
            PATH_INFO<br />
138
                 SERVLET_PATH<br />
138
            QUERY_STRING<br />
139
                 PATH_INFO<br />
139
            AUTH_TYPE<br />
140
                 QUERY_STRING<br />
140
          </p>
141
                 AUTH_TYPE<br />
141
          </li>
142
              </td>
142
          <li>
143
143
          <p><b>server internals:</b></p>
144
              <td></td>
144
          <p>
145
            </tr>
145
            DOCUMENT_ROOT<br />
146
146
            SERVER_NAME<br />
147
            <tr>
147
            SERVER_ADDR<br />
148
              <th>server internals:</th> <th>date and time:</th> <th>specials:</th>
148
            SERVER_PORT<br />
149
            </tr>
149
            SERVER_PROTOCOL<br />
150
150
            SERVER_SOFTWARE<br />
151
            <tr>
151
          </p>
152
              <td>
152
          </li>
153
                 DOCUMENT_ROOT<br />
153
          <li>
154
                 SERVER_NAME<br />
154
          <p><b>date and time:</b></p>
155
                 SERVER_ADDR<br />
155
          <p>
156
                 SERVER_PORT<br />
156
            TIME_YEAR<br />
157
                 SERVER_PROTOCOL<br />
157
            TIME_MON<br />
158
                 SERVER_SOFTWARE<br />
158
            TIME_DAY<br />
159
              </td>
159
            TIME_HOUR<br />
160
160
            TIME_MIN<br />
161
              <td>
161
            TIME_SEC<br />
162
                 TIME_YEAR<br />
162
            TIME_WDAY<br />
163
                 TIME_MON<br />
163
            TIME<br />
164
                 TIME_DAY<br />
164
          </p>
165
                 TIME_HOUR<br />
165
          </li>
166
                 TIME_MIN<br />
166
          <li>
167
                 TIME_SEC<br />
167
          <p><b>specials:</b></p>
168
                 TIME_WDAY<br />
168
          <p>
169
                 TIME<br />
169
            THE_REQUEST<br />
170
              </td>
170
            REQUEST_URI<br />
171
171
            REQUEST_FILENAME<br />
172
              <td>
172
            HTTPS<br />
173
                 THE_REQUEST<br />
173
          </p>
174
                 REQUEST_URI<br />
174
          </li>
175
                 REQUEST_FILENAME<br />
175
          </ul>
176
                 HTTPS<br />
176
          
177
              </td>
178
            </tr>
179
          </table>
180
181
                <p>These variables all
177
                <p>These variables all
182
                correspond to the similarly named HTTP
178
                correspond to the similarly named HTTP
183
                MIME-headers and Servlet API methods.
179
                MIME-headers and Servlet API methods.
Lines 324-334 Link Here
324
320
325
          </ul>
321
          </ul>
326
322
327
<note><title>Note:</title>
323
<strong>Note:</strong>
328
              All of these tests can
324
              All of these tests can
329
              also be prefixed by an exclamation mark ('!') to
325
              also be prefixed by an exclamation mark ('!') to
330
              negate their meaning.
326
              negate their meaning.
331
</note>
327
332
        </li>
328
        </li>
333
329
334
        <li>You can also set special flags for
330
        <li>You can also set special flags for
Lines 354-365 Link Here
354
          Use this to combine rule conditions with a local OR
350
          Use this to combine rule conditions with a local OR
355
          instead of the implicit AND. Typical example:
351
          instead of the implicit AND. Typical example:
356
352
357
<source>
353
<source>RewriteCond %{REMOTE_HOST}  ^host1.*  [OR]
358
RewriteCond %{REMOTE_HOST}  ^host1.*  [OR]
359
RewriteCond %{REMOTE_HOST}  ^host2.*  [OR]
354
RewriteCond %{REMOTE_HOST}  ^host2.*  [OR]
360
RewriteCond %{REMOTE_HOST}  ^host3.*
355
RewriteCond %{REMOTE_HOST}  ^host3.*
361
RewriteRule ...some special stuff for any of these hosts...
356
RewriteRule ...some special stuff for any of these hosts...</source>
362
</source>
363
357
364
          Without this flag you would have to write the condition/rule
358
          Without this flag you would have to write the condition/rule
365
          pair three times.
359
          pair three times.
Lines 374-388 Link Here
374
        ``<code>User-Agent:</code>'' header of the request, you can
368
        ``<code>User-Agent:</code>'' header of the request, you can
375
        use the following: </p>
369
        use the following: </p>
376
370
377
<source>
371
<source>RewriteCond  %{HTTP_USER_AGENT}  ^Mozilla.*
378
RewriteCond  %{HTTP_USER_AGENT}  ^Mozilla.*
379
RewriteRule  ^/$                 /homepage.max.html  [L]
372
RewriteRule  ^/$                 /homepage.max.html  [L]
380
373
381
RewriteCond  %{HTTP_USER_AGENT}  ^Lynx.*
374
RewriteCond  %{HTTP_USER_AGENT}  ^Lynx.*
382
RewriteRule  ^/$                 /homepage.min.html  [L]
375
RewriteRule  ^/$                 /homepage.min.html  [L]
383
376
384
RewriteRule  ^/$                 /homepage.std.html  [L]
377
RewriteRule  ^/$                 /homepage.std.html  [L]</source>
385
</source>
386
378
387
        <p>Explanation: If you use a browser which identifies itself
379
        <p>Explanation: If you use a browser which identifies itself
388
        as 'Mozilla' (including Netscape Navigator, Mozilla etc), then you
380
        as 'Mozilla' (including Netscape Navigator, Mozilla etc), then you
Lines 404-417 Link Here
404
    <p>The maps are implemented using an interface that users must implement. Its class
396
    <p>The maps are implemented using an interface that users must implement. Its class
405
    name is <code>org.apache.catalina.valves.rewrite.RewriteMap</code>, and its code is:</p>
397
    name is <code>org.apache.catalina.valves.rewrite.RewriteMap</code>, and its code is:</p>
406
398
407
<source>
399
<source><![CDATA[package org.apache.catalina.valves.rewrite;
408
package org.apache.catalina.valves.rewrite;
409
400
410
public interface RewriteMap {
401
public interface RewriteMap {
411
    public String setParameters(String params);
402
    public String setParameters(String params);
412
    public String lookup(String key);
403
    public String lookup(String key);
413
}
404
}]]></source>
414
</source>
415
405
416
  </subsection>
406
  </subsection>
417
407
Lines 435-440 Link Here
435
      <p>Some hints on the syntax of regular
425
      <p>Some hints on the syntax of regular
436
      expressions:</p>
426
      expressions:</p>
437
427
428
<!-- TODO: Why is the following pre-formatted non-wrappable text? -->
438
<pre>
429
<pre>
439
<strong>Text:</strong>
430
<strong>Text:</strong>
440
  <strong><code>.</code></strong>           Any single character
431
  <strong><code>.</code></strong>           Any single character
Lines 473-479 Link Here
473
        <em>Mastering Regular Expressions, 2nd Edition</em><br />
464
        <em>Mastering Regular Expressions, 2nd Edition</em><br />
474
         Jeffrey E.F. Friedl<br />
465
         Jeffrey E.F. Friedl<br />
475
         O'Reilly &amp; Associates, Inc. 2002<br />
466
         O'Reilly &amp; Associates, Inc. 2002<br />
476
         ISBN 0-596-00289-0<br />
467
         ISBN 978-0-596-00289-3<br />
477
      </p>
468
      </p>
478
469
479
      <p>In the rules, the NOT character
470
      <p>In the rules, the NOT character
Lines 492-498 Link Here
492
cannot use <code>$N</code> in the substitution string!
483
cannot use <code>$N</code> in the substitution string!
493
</p>
484
</p>
494
485
495
      <p>The <a id="rhs" name="rhs"><em>substitution</em></a> of a
486
      <p>The <em id="rhs" >substitution</em> of a
496
      rewrite rule is the string which is substituted for (or
487
      rewrite rule is the string which is substituted for (or
497
      replaces) the original URL which <em>Pattern</em>
488
      replaces) the original URL which <em>Pattern</em>
498
      matched. In addition to plain text, it can include</p>
489
      matched. In addition to plain text, it can include</p>
Lines 538-545 Link Here
538
      to apply more than one pattern before substitution occurs.</p>
529
      to apply more than one pattern before substitution occurs.</p>
539
530
540
531
541
      <p>Additionally you can set special <a name="rewriteflags"
532
      <p>Additionally you can set special <span
542
      id="rewriteflags">flags</a> for <em>Substitution</em> by
533
      id="rewriteflags">flags</span> for <em>Substitution</em> by
543
      appending <strong><code>[</code><em>flags</em><code>]</code></strong>
534
      appending <strong><code>[</code><em>flags</em><code>]</code></strong>
544
      as the third argument to the <code>RewriteRule</code>
535
      as the third argument to the <code>RewriteRule</code>
545
      directive. <em>Flags</em> is a comma-separated list of any of the
536
      directive. <em>Flags</em> is a comma-separated list of any of the
Lines 639-647 Link Here
639
          '%24', and '%3B', respectively); this flag prevents this
630
          '%24', and '%3B', respectively); this flag prevents this
640
          from happening. This allows percent symbols to appear in
631
          from happening. This allows percent symbols to appear in
641
          the output, as in
632
          the output, as in
642
<example>
633
          <source>RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE]</source>
643
    RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE]
644
</example>
645
          which would turn '<code>/foo/zed</code>' into a safe
634
          which would turn '<code>/foo/zed</code>' into a safe
646
          request for '<code>/bar?arg=P1=zed</code>'.
635
          request for '<code>/bar?arg=P1=zed</code>'.
647
        </li>
636
        </li>
Lines 678-685 Link Here
678
        data to the query string via a rewrite rule.</li>
667
        data to the query string via a rewrite rule.</li>
679
668
680
         <li>'<strong><code>redirect|R</code>
669
         <li>'<strong><code>redirect|R</code>
681
          [=<em>code</em>]</strong>' (force <a id="redirect"
670
          [=<em>code</em>]</strong>' (force <span id="redirect">
682
          name="redirect"><strong>r</strong>edirect</a>)<br />
671
          <strong>r</strong>edirect</span>)<br />
683
          Prefix <em>Substitution</em> with
672
          Prefix <em>Substitution</em> with
684
          <code>http://thishost[:thisport]/</code> (which makes the
673
          <code>http://thishost[:thisport]/</code> (which makes the
685
          new URL a URI) to force a external redirection. If no
674
          new URL a URI) to force a external redirection. If no
Lines 716-730 Link Here
716
        <li>
705
        <li>
717
        '<strong><code>type|T</code></strong>=<em>MIME-type</em>'
706
        '<strong><code>type|T</code></strong>=<em>MIME-type</em>'
718
        (force MIME <strong>t</strong>ype)<br />
707
        (force MIME <strong>t</strong>ype)<br />
719
         Force the <glossary>MIME-type</glossary> of the target file to be
708
         Force the MIME-type of the target file to be
720
        <em>MIME-type</em>. This can be used to
709
        <em>MIME-type</em>. This can be used to
721
        set up the content-type based on some conditions.
710
        set up the content-type based on some conditions.
722
        For example, the following snippet allows <code>.php</code> files to
711
        For example, the following snippet allows <code>.php</code> files to
723
        be <em>displayed</em> by <code>mod_php</code> if they are called with
712
        be <em>displayed</em> by <code>mod_php</code> if they are called with
724
        the <code>.phps</code> extension:
713
        the <code>.phps</code> extension:
725
        <example>
714
        <source>RewriteRule ^(.+\.php)s$ $1 [T=application/x-httpd-php-source]</source>
726
            RewriteRule ^(.+\.php)s$ $1 [T=application/x-httpd-php-source]
727
        </example>
728
        </li>
715
        </li>
729
      </ul>
716
      </ul>
730
717
(-)webapps/docs/security-howto.xml (-3 / +1 lines)
Lines 279-287 Link Here
279
      can be changed by creating the file
279
      can be changed by creating the file
280
      CATALINA_BASE/lib/org/apache/catalina/util/ServerInfo.properties with
280
      CATALINA_BASE/lib/org/apache/catalina/util/ServerInfo.properties with
281
      content as follows:</p>
281
      content as follows:</p>
282
      <source>
282
      <source>server.info=Apache Tomcat/7.0.x</source>
283
server.info=Apache Tomcat/7.0.x
284
      </source>
285
      <p>Modify the values as required. Note that this will also change the version
283
      <p>Modify the values as required. Note that this will also change the version
286
      number reported in some of the management tools and may make it harder to
284
      number reported in some of the management tools and may make it harder to
287
      determine the real version installed. The CATALINA_HOME/bin/version.bat|sh
285
      determine the real version installed. The CATALINA_HOME/bin/version.bat|sh
(-)webapps/docs/security-manager-howto.xml (-24 / +12 lines)
Lines 48-56 Link Here
48
48
49
  <p>Imagine if someone who is authorized to publish JSPs on your site
49
  <p>Imagine if someone who is authorized to publish JSPs on your site
50
  inadvertently included the following in their JSP:</p>
50
  inadvertently included the following in their JSP:</p>
51
<source>
51
<source><![CDATA[<% System.exit(1); %>]]></source>
52
&lt;% System.exit(1); %&gt;
53
</source>
54
52
55
  <p>Every time this JSP was executed by Tomcat, Tomcat would exit.
53
  <p>Every time this JSP was executed by Tomcat, Tomcat would exit.
56
  Using the Java SecurityManager is just one more line of defense a
54
  Using the Java SecurityManager is just one more line of defense a
Lines 116-124 Link Here
116
    used to do wild card matching for a JNDI named file resource when
114
    used to do wild card matching for a JNDI named file resource when
117
    granting permission.  For example, you might include the following
115
    granting permission.  For example, you might include the following
118
    in your policy file:</p>
116
    in your policy file:</p>
119
<source>
117
<source>permission  org.apache.naming.JndiPermission  "jndi://localhost/examples/*";</source>
120
permission  org.apache.naming.JndiPermission  "jndi://localhost/examples/*";
121
</source>
122
118
123
    <p>A Permission entry like this is generated dynamically for each web
119
    <p>A Permission entry like this is generated dynamically for each web
124
    application that is deployed, to allow it to read its own static resources
120
    application that is deployed, to allow it to read its own static resources
Lines 159-171 Link Here
159
155
160
  <p>Entries in the <code>catalina.policy</code> file use the standard
156
  <p>Entries in the <code>catalina.policy</code> file use the standard
161
  <code>java.policy</code> file format, as follows:</p>
157
  <code>java.policy</code> file format, as follows:</p>
162
<source>
158
<source><![CDATA[// Example policy file entry
163
// Example policy file entry
164
159
165
grant [signedBy &lt;signer&gt;,] [codeBase &lt;code source&gt;] {
160
grant [signedBy <signer>,] [codeBase <code source>] {
166
  permission  &lt;class&gt;  [&lt;name&gt; [, &lt;action list&gt;]];
161
  permission  <class>  [<name> [, <action list>]];
167
};
162
};]]></source>
168
</source>
169
163
170
  <p>The <strong>signedBy</strong> and <strong>codeBase</strong> entries are
164
  <p>The <strong>signedBy</strong> and <strong>codeBase</strong> entries are
171
  optional when granting permissions.  Comment lines begin with "//" and
165
  optional when granting permissions.  Comment lines begin with "//" and
Lines 190-199 Link Here
190
  <p>Once you have configured the <code>catalina.policy</code> file for use
184
  <p>Once you have configured the <code>catalina.policy</code> file for use
191
  with a SecurityManager, Tomcat can be started with a SecurityManager in
185
  with a SecurityManager, Tomcat can be started with a SecurityManager in
192
  place by using the "-security" option:</p>
186
  place by using the "-security" option:</p>
193
<source>
187
<source>$CATALINA_HOME/bin/catalina.sh start -security    (Unix)
194
$CATALINA_HOME/bin/catalina.sh start -security    (Unix)
188
%CATALINA_HOME%\bin\catalina start -security      (Windows)</source>
195
%CATALINA_HOME%\bin\catalina start -security      (Windows)
196
</source>
197
189
198
</section>
190
</section>
199
<section name="Configuring Package Protection in Tomcat">
191
<section name="Configuring Package Protection in Tomcat">
Lines 211-218 Link Here
211
203
212
  <p>The default <code>$CATALINA_BASE/conf/catalina.properties</code> file
204
  <p>The default <code>$CATALINA_BASE/conf/catalina.properties</code> file
213
  looks like this:</p>
205
  looks like this:</p>
214
<source>
206
<source><![CDATA[#
215
#
216
# List of comma-separated packages that start with or equal this string
207
# List of comma-separated packages that start with or equal this string
217
# will cause a security exception to be thrown when
208
# will cause a security exception to be thrown when
218
# passed to checkPackageAccess unless the
209
# passed to checkPackageAccess unless the
Lines 231-238 Link Here
231
# the class loaders supplied with the JDK call checkPackageDefinition.
222
# the class loaders supplied with the JDK call checkPackageDefinition.
232
#
223
#
233
package.definition=sun.,java.,org.apache.catalina.,org.apache.coyote.,
224
package.definition=sun.,java.,org.apache.catalina.,org.apache.coyote.,
234
org.apache.tomcat.,org.apache.jasper.
225
org.apache.tomcat.,org.apache.jasper.]]></source>
235
</source>
236
  <p>Once you have configured the <code>catalina.properties</code> file for use
226
  <p>Once you have configured the <code>catalina.properties</code> file for use
237
  with a SecurityManager, remember to re-start Tomcat.</p>
227
  with a SecurityManager, remember to re-start Tomcat.</p>
238
</section>
228
</section>
Lines 248-257 Link Here
248
  is done by setting a system property before starting Tomcat.  The easiest
238
  is done by setting a system property before starting Tomcat.  The easiest
249
  way to do this is via the <code>CATALINA_OPTS</code> environment variable.
239
  way to do this is via the <code>CATALINA_OPTS</code> environment variable.
250
  Execute this command:</p>
240
  Execute this command:</p>
251
<source>
241
<source>export CATALINA_OPTS=-Djava.security.debug=all    (Unix)
252
export CATALINA_OPTS=-Djava.security.debug=all    (Unix)
242
set CATALINA_OPTS=-Djava.security.debug=all       (Windows)</source>
253
set CATALINA_OPTS=-Djava.security.debug=all       (Windows)
254
</source>
255
243
256
  <p>before starting Tomcat.</p>
244
  <p>before starting Tomcat.</p>
257
245
(-)webapps/docs/setup.xml (-24 / +20 lines)
Lines 50-56 Link Here
50
      based installers, with only a few items of interest.
50
      based installers, with only a few items of interest.
51
    </p>
51
    </p>
52
52
53
    <p>
53
54
      <ul>
54
      <ul>
55
        <li><strong>Installation as a service</strong>: Tomcat will be
55
        <li><strong>Installation as a service</strong>: Tomcat will be
56
            installed as a Windows service no matter what setting is selected.
56
            installed as a Windows service no matter what setting is selected.
Lines 76-83 Link Here
76
            for information on how to manage Tomcat as a Windows service.
76
            for information on how to manage Tomcat as a Windows service.
77
            </li>
77
            </li>
78
      </ul>
78
      </ul>
79
    </p>
80
79
80
81
    <p>The installer will create shortcuts allowing starting and configuring
81
    <p>The installer will create shortcuts allowing starting and configuring
82
       Tomcat. It is important to note that the Tomcat administration web
82
       Tomcat. It is important to note that the Tomcat administration web
83
       application can only be used when Tomcat is running.</p>
83
       application can only be used when Tomcat is running.</p>
Lines 106-136 Link Here
106
    <p>Please note that you should use the GNU make (gmake) instead of
106
    <p>Please note that you should use the GNU make (gmake) instead of
107
       the native BSD make on FreeBSD systems.</p>
107
       the native BSD make on FreeBSD systems.</p>
108
108
109
<source>
109
<source>cd $CATALINA_HOME/bin
110
    cd $CATALINA_HOME/bin
110
tar xvfz commons-daemon-native.tar.gz
111
    tar xvfz commons-daemon-native.tar.gz
111
cd commons-daemon-1.0.x-native-src/unix
112
    cd commons-daemon-1.0.x-native-src/unix
112
./configure
113
    ./configure
113
make
114
    make
114
cp jsvc ../..
115
    cp jsvc ../..
115
cd ../..</source>
116
    cd ../..
117
</source>
118
116
119
    <p>Tomcat can then be run as a daemon using the following commands.</p>
117
    <p>Tomcat can then be run as a daemon using the following commands.</p>
120
118
121
<source>
119
<source>CATALINA_BASE=$CATALINA_HOME
122
    CATALINA_BASE=$CATALINA_HOME
120
cd $CATALINA_HOME
123
    cd $CATALINA_HOME
121
./bin/jsvc \
124
    ./bin/jsvc \
122
    -classpath $CATALINA_HOME/bin/bootstrap.jar:$CATALINA_HOME/bin/tomcat-juli.jar \
125
        -classpath $CATALINA_HOME/bin/bootstrap.jar:$CATALINA_HOME/bin/tomcat-juli.jar \
123
    -outfile $CATALINA_BASE/logs/catalina.out \
126
        -outfile $CATALINA_BASE/logs/catalina.out \
124
    -errfile $CATALINA_BASE/logs/catalina.err \
127
        -errfile $CATALINA_BASE/logs/catalina.err \
125
    -Dcatalina.home=$CATALINA_HOME \
128
        -Dcatalina.home=$CATALINA_HOME \
126
    -Dcatalina.base=$CATALINA_BASE \
129
        -Dcatalina.base=$CATALINA_BASE \
127
    -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager \
130
        -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager \
128
    -Djava.util.logging.config.file=$CATALINA_BASE/conf/logging.properties \
131
        -Djava.util.logging.config.file=$CATALINA_BASE/conf/logging.properties \
129
    org.apache.catalina.startup.Bootstrap</source>
132
        org.apache.catalina.startup.Bootstrap
133
</source>
134
130
135
    <p>You may also need to specify <code>-jvm server</code> if the JVM defaults
131
    <p>You may also need to specify <code>-jvm server</code> if the JVM defaults
136
       to using a server VM rather than a client VM. This has been observed on
132
       to using a server VM rather than a client VM. This has been observed on
(-)webapps/docs/ssi-howto.xml (-18 / +19 lines)
Lines 88-94 Link Here
88
<section name="Servlet Configuration">
88
<section name="Servlet Configuration">
89
89
90
<p>There are several servlet init parameters which can be used to
90
<p>There are several servlet init parameters which can be used to
91
configure the behaviour of the SSI servlet.
91
configure the behaviour of the SSI servlet.</p>
92
<ul>
92
<ul>
93
<li><strong>buffered</strong> - Should output from this servlet be buffered?
93
<li><strong>buffered</strong> - Should output from this servlet be buffered?
94
(0=false, 1=true) Default 0 (false).</li>
94
(0=false, 1=true) Default 0 (false).</li>
Lines 108-121 Link Here
108
<li><strong>allowExec</strong> - Is the exec command enabled? Default is
108
<li><strong>allowExec</strong> - Is the exec command enabled? Default is
109
false.</li>
109
false.</li>
110
</ul>
110
</ul>
111
</p>
112
111
112
113
</section>
113
</section>
114
114
115
<section name="Filter Configuration">
115
<section name="Filter Configuration">
116
116
117
<p>There are several filter init parameters which can be used to
117
<p>There are several filter init parameters which can be used to
118
configure the behaviour of the SSI filter.
118
configure the behaviour of the SSI filter.</p>
119
<ul>
119
<ul>
120
<li><strong>contentType</strong> - A regex pattern that must be matched before
120
<li><strong>contentType</strong> - A regex pattern that must be matched before
121
SSI processing is applied. When crafting your own pattern, don't forget that a
121
SSI processing is applied. When crafting your own pattern, don't forget that a
Lines 133-140 Link Here
133
<li><strong>allowExec</strong> - Is the exec command enabled? Default is
133
<li><strong>allowExec</strong> - Is the exec command enabled? Default is
134
false.</li>
134
false.</li>
135
</ul>
135
</ul>
136
</p>
137
136
137
138
</section>
138
</section>
139
139
140
<section name="Directives">
140
<section name="Directives">
Lines 143-149 Link Here
143
 comment. The directive is replaced by the results of interpreting it before sending the
143
 comment. The directive is replaced by the results of interpreting it before sending the
144
 page to the client. The general form of a directive is: </p>
144
 page to the client. The general form of a directive is: </p>
145
<p> <code>&lt;!--#directive [parm=value] --&gt;</code></p>
145
<p> <code>&lt;!--#directive [parm=value] --&gt;</code></p>
146
<p>The directives are:
146
<p>The directives are:</p>
147
<ul>
147
<ul>
148
<li>
148
<li>
149
<strong>config</strong> - <code>&lt;!--#config timefmt=&quot;%B %Y&quot; --&gt;</code>
149
<strong>config</strong> - <code>&lt;!--#config timefmt=&quot;%B %Y&quot; --&gt;</code>
Lines 177-195 Link Here
177
is used to assign a value to a user-defind variable.
177
is used to assign a value to a user-defind variable.
178
</li>
178
</li>
179
<li>
179
<li>
180
<strong>if elif endif else</strong> - Used to create conditional sections. For example:</li>
180
<strong>if elif endif else</strong> - Used to create conditional sections. For example:
181
<code>&lt;!--#config timefmt="%A" --&gt;<br />
181
<source><![CDATA[<!--#config timefmt="%A" -->
182
  &lt;!--#if expr="$DATE_LOCAL = /Monday/" --&gt;<br />
182
<!--#if expr="$DATE_LOCAL = /Monday/" -->
183
  &lt;p&gt;Meeting at 10:00 on Mondays&lt;/p&gt;<br />
183
<p>Meeting at 10:00 on Mondays</p>
184
  &lt;!--#elif expr="$DATE_LOCAL = /Friday/" --&gt;<br />
184
<!--#elif expr="$DATE_LOCAL = /Friday/" -->
185
  &lt;p&gt;Turn in your time card&lt;/p&gt;<br />
185
<p>Turn in your time card</p>
186
  &lt;!--#else --&gt;<br />
186
<!--#else -->
187
  &lt;p&gt;Yoga class at noon.&lt;/p&gt;<br />
187
<p>Yoga class at noon.</p>
188
  &lt;!--#endif --&gt;</code>
188
<!--#endif -->]]></source>
189
 </ul>
189
</li>
190
</p>
190
</ul>
191
<p>
191
See the
192
See the
192
<p> <a href="http://httpd.apache.org/docs/howto/ssi.html#basicssidirectives">
193
<a href="http://httpd.apache.org/docs/howto/ssi.html#basicssidirectives">
193
Apache Introduction to SSI</a> for more information on using SSI directives.</p>
194
Apache Introduction to SSI</a> for more information on using SSI directives.</p>
194
</section>
195
</section>
195
196
Lines 196-202 Link Here
196
<section name="Variables">
197
<section name="Variables">
197
<p>The SSI servlet currently implements the following variables:
198
<p>The SSI servlet currently implements the following variables:
198
</p>
199
</p>
199
<table border="1">
200
<table class="defaultTable">
200
<tr>
201
<tr>
201
<th>Variable Name</th>
202
<th>Variable Name</th>
202
<th>Description</th>
203
<th>Description</th>
(-)webapps/docs/ssl-howto.xml (-114 / +83 lines)
Lines 36-68 Link Here
36
36
37
<section name="Quick Start">
37
<section name="Quick Start">
38
38
39
    <blockquote><em>
39
   
40
    <p>The description below uses the variable name $CATALINA_BASE to refer the
40
    <p><em>The description below uses the variable name $CATALINA_BASE to refer the
41
    base directory against which most relative paths are resolved. If you have
41
    base directory against which most relative paths are resolved. If you have
42
    not configured Tomcat for multiple instances by setting a CATALINA_BASE
42
    not configured Tomcat for multiple instances by setting a CATALINA_BASE
43
    directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
43
    directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
44
    the directory into which you have installed Tomcat.</p>
44
    the directory into which you have installed Tomcat.</em></p>
45
    </em></blockquote>
45
    
46
46
47
<p>To install and configure SSL support on Tomcat, you need to follow
47
<p>To install and configure SSL support on Tomcat, you need to follow
48
these simple steps.  For more information, read the rest of this HOW-TO.</p>
48
these simple steps.  For more information, read the rest of this HOW-TO.</p>
49
<ol>
49
<ol>
50
<li>Create a keystore file to store the server&apos;s private key and
50
<li><p>Create a keystore file to store the server&apos;s private key and
51
self-signed certificate by executing the following command:
51
self-signed certificate by executing the following command:</p>
52
<p>Windows:</p>
52
<p>Windows:</p>
53
<source>
53
<source>%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA</source>
54
%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
55
</source>
56
<p>Unix:</p>
54
<p>Unix:</p>
57
<source>
55
<source>$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA</source>
58
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
56
59
</source>
57
<p>and specify a password value of "changeit".</p></li>
60
<p></p>
58
<li><p>Uncomment the "SSL HTTP/1.1 Connector" entry in
61
    and specify a password value of "changeit".</li><br/><br/>
62
<li>Uncomment the "SSL HTTP/1.1 Connector" entry in
63
    <code>$CATALINA_BASE/conf/server.xml</code> and modify as described in
59
    <code>$CATALINA_BASE/conf/server.xml</code> and modify as described in
64
    the <a href="#Configuration">Configuration section</a> below.</li>
60
    the <a href="#Configuration">Configuration section</a> below.</p></li>
65
    <br/><br/>
61
66
</ol>
62
</ol>
67
63
68
64
Lines 213-236 Link Here
213
they exist before importing the key using <code>keytool</code>.
209
they exist before importing the key using <code>keytool</code>.
214
</p>
210
</p>
215
<p>To import an existing certificate signed by your own CA into a PKCS12
211
<p>To import an existing certificate signed by your own CA into a PKCS12
216
keystore using OpenSSL you would execute a command like:
212
keystore using OpenSSL you would execute a command like:</p>
217
<source>openssl pkcs12 -export -in mycert.crt -inkey mykey.key \
213
<source>openssl pkcs12 -export -in mycert.crt -inkey mykey.key \
218
                        -out mycert.p12 -name tomcat -CAfile myCA.crt \
214
                        -out mycert.p12 -name tomcat -CAfile myCA.crt \
219
                        -caname root -chain
215
                        -caname root -chain</source>
220
</source>
216
<p>For more advanced cases, consult the <a href="http://www.openssl.org/">OpenSSL
221
For more advanced cases, consult the <a href="http://www.openssl.org/">OpenSSL
222
documentation</a>.
217
documentation</a>.
223
</p>
218
</p>
224
<p>To create a new keystore from scratch, containing a single self-signed
219
<p>To create a new keystore from scratch, containing a single self-signed
225
Certificate, execute the following from a terminal command line:</p>
220
Certificate, execute the following from a terminal command line:</p>
226
<p>Windows:</p>
221
<p>Windows:</p>
227
<source>
222
<source>%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA</source>
228
%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
229
</source>
230
<p>Unix:</p>
223
<p>Unix:</p>
231
<source>
224
<source>$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA</source>
232
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
233
</source>
234
225
235
<p>(The RSA algorithm should be preferred as a secure algorithm, and this
226
<p>(The RSA algorithm should be preferred as a secure algorithm, and this
236
also ensures general compatibility with other servers and components.)</p>
227
also ensures general compatibility with other servers and components.)</p>
Lines 243-257 Link Here
243
reflect this new location in the <code>server.xml</code> configuration file,
234
reflect this new location in the <code>server.xml</code> configuration file,
244
as described later.  For example:</p>
235
as described later.  For example:</p>
245
<p>Windows:</p>
236
<p>Windows:</p>
246
<source>
237
<source>%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA \
247
%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA \
238
  -keystore \path\to\my\keystore</source>
248
  -keystore \path\to\my\keystore
249
</source>
250
<p>Unix:</p>
239
<p>Unix:</p>
251
<source>
240
<source>$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA \
252
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA \
241
  -keystore /path/to/my/keystore</source>
253
  -keystore /path/to/my/keystore
254
</source>
255
242
256
<p>After executing this command, you will first be prompted for the keystore
243
<p>After executing this command, you will first be prompted for the keystore
257
password.  The default password used by Tomcat is "<code>changeit</code>"
244
password.  The default password used by Tomcat is "<code>changeit</code>"
Lines 281-290 Link Here
281
<subsection name="Edit the Tomcat Configuration File">
268
<subsection name="Edit the Tomcat Configuration File">
282
<p>
269
<p>
283
Tomcat can use two different implementations of SSL:
270
Tomcat can use two different implementations of SSL:
271
</p>
284
<ul>
272
<ul>
285
<li>the JSSE implementation provided as part of the Java runtime (since 1.4)</li>
273
<li>the JSSE implementation provided as part of the Java runtime (since 1.4)</li>
286
<li>the APR implementation, which uses the OpenSSL engine by default.</li>
274
<li>the APR implementation, which uses the OpenSSL engine by default.</li>
287
</ul>
275
</ul>
276
<p>
288
The exact configuration details depend on which implementation is being used.
277
The exact configuration details depend on which implementation is being used.
289
The implementation used by Tomcat is chosen automatically unless it is overriden as described below.
278
The implementation used by Tomcat is chosen automatically unless it is overriden as described below.
290
If the installation uses <a href="apr.html">APR</a>
279
If the installation uses <a href="apr.html">APR</a>
Lines 296-341 Link Here
296
  To avoid auto configuration you can define which implementation to use by specifying a classname
285
  To avoid auto configuration you can define which implementation to use by specifying a classname
297
  in the <b>protocol</b> attribute of the Connector.<br/>
286
  in the <b>protocol</b> attribute of the Connector.<br/>
298
  To define a Java (JSSE) connector, regardless of whether the APR library is loaded or not do:
287
  To define a Java (JSSE) connector, regardless of whether the APR library is loaded or not do:
299
<source>
288
</p>
300
&lt;!-- Define a blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 --&gt;
289
<source><![CDATA[<!-- Define a blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 -->
301
&lt;Connector protocol="org.apache.coyote.http11.Http11Protocol"
290
<Connector protocol="org.apache.coyote.http11.Http11Protocol"
302
           port="8443" .../&gt;
291
           port="8443" .../>
303
292
304
&lt;!-- Define a non-blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 --&gt;
293
<!-- Define a non-blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 -->
305
&lt;Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
294
<Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
306
           port="8443" .../&gt;
295
           port="8443" .../>]]></source>
307
</source>
296
<p>Alternatively, to specify an APR connector (the APR library must be available) use:</p>
308
Alternatively, to specify an APR connector (the APR library must be available) use:
297
<source><![CDATA[<!-- Define a APR SSL Coyote HTTP/1.1 Connector on port 8443 -->
309
<source>
298
<Connector protocol="org.apache.coyote.http11.Http11AprProtocol"
310
&lt;!-- Define a APR SSL Coyote HTTP/1.1 Connector on port 8443 --&gt;
299
           port="8443" .../>]]></source>
311
&lt;Connector protocol="org.apache.coyote.http11.Http11AprProtocol"
312
           port="8443" .../&gt;
313
</source>
314
300
315
</p>
316
301
317
<p>If you are using APR, you have the option of configuring an alternative engine to OpenSSL.
302
<p>If you are using APR, you have the option of configuring an alternative engine to OpenSSL.</p>
318
<source>
303
<source><![CDATA[<Listener className="org.apache.catalina.core.AprLifecycleListener"
319
&lt;Listener className="org.apache.catalina.core.AprLifecycleListener"
304
          SSLEngine="someengine" SSLRandomSeed="somedevice" />]]></source>
320
          SSLEngine="someengine" SSLRandomSeed="somedevice" /&gt;
305
<p>The default value is</p>
321
</source>
306
<source><![CDATA[<Listener className="org.apache.catalina.core.AprLifecycleListener"
322
The default value is
307
          SSLEngine="on" SSLRandomSeed="builtin" />]]></source>
323
<source>
308
<p>
324
&lt;Listener className="org.apache.catalina.core.AprLifecycleListener"
325
          SSLEngine="on" SSLRandomSeed="builtin" /&gt;
326
</source>
327
So to use SSL under APR, make sure the SSLEngine attribute is set to something other than <code>off</code>.
309
So to use SSL under APR, make sure the SSLEngine attribute is set to something other than <code>off</code>.
328
The default value is <code>on</code> and if you specify another value, it has to be a valid engine name.
310
The default value is <code>on</code> and if you specify another value, it has to be a valid engine name.
329
<br/>
311
<br/>
330
If you haven't compiled in SSL support into your Tomcat Native library, then you can turn this initialization off
312
If you haven't compiled in SSL support into your Tomcat Native library, then you can turn this initialization off
331
<source>
313
</p>
332
&lt;Listener className="org.apache.catalina.core.AprLifecycleListener"
314
<source><![CDATA[<Listener className="org.apache.catalina.core.AprLifecycleListener"
333
          SSLEngine="off" /&gt;
315
          SSLEngine="off" />]]></source>
334
</source>
316
<p>
335
SSLRandomSeed allows to specify a source of entropy. Productive system needs a reliable source of entropy
317
SSLRandomSeed allows to specify a source of entropy. Productive system needs a reliable source of entropy
336
but entropy may need a lot of time to be collected therefore test systems could use no blocking entropy
318
but entropy may need a lot of time to be collected therefore test systems could use no blocking entropy
337
sources like "/dev/urandom" that will allow quicker starts of Tomcat.
319
sources like "/dev/urandom" that will allow quicker starts of Tomcat.
338
339
</p>
320
</p>
340
321
341
<p>The final step is to configure the Connector in the
322
<p>The final step is to configure the Connector in the
Lines 346-377 Link Here
346
file installed with Tomcat.  To configure an SSL connector that uses JSSE, you
327
file installed with Tomcat.  To configure an SSL connector that uses JSSE, you
347
will need to remove the comments and edit it so it looks something like
328
will need to remove the comments and edit it so it looks something like
348
this:</p>
329
this:</p>
349
<source>
330
<source><![CDATA[<!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
350
&lt;!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 --&gt;
331
<Connector
351
&lt;Connector
352
           protocol="HTTP/1.1"
332
           protocol="HTTP/1.1"
353
           port="8443" maxThreads="200"
333
           port="8443" maxThreads="200"
354
           scheme="https" secure="true" SSLEnabled="true"
334
           scheme="https" secure="true" SSLEnabled="true"
355
           keystoreFile="${user.home}/.keystore" keystorePass="changeit"
335
           keystoreFile="${user.home}/.keystore" keystorePass="changeit"
356
           clientAuth="false" sslProtocol="TLS"/&gt;
336
           clientAuth="false" sslProtocol="TLS"/>]]></source>
357
</source>
358
<p>
337
<p>
359
  The example above will throw an error if you have the APR and the Tomcat
338
  The example above will throw an error if you have the APR and the Tomcat
360
  Native libraries in your path, as Tomcat will try to use the APR connector.
339
  Native libraries in your path, as Tomcat will try to use the APR connector.
361
  The APR connector uses different attributes for many SSL settings,
340
  The APR connector uses different attributes for many SSL settings,
362
  particularly keys and certificates. An example of an APR configuration is:
341
  particularly keys and certificates. An example of an APR configuration is:</p>
363
<source>
342
<source><![CDATA[<!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
364
&lt;!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 --&gt;
343
<Connector
365
&lt;Connector
366
           protocol="HTTP/1.1"
344
           protocol="HTTP/1.1"
367
           port="8443" maxThreads="200"
345
           port="8443" maxThreads="200"
368
           scheme="https" secure="true" SSLEnabled="true"
346
           scheme="https" secure="true" SSLEnabled="true"
369
           SSLCertificateFile="/usr/local/ssl/server.crt"
347
           SSLCertificateFile="/usr/local/ssl/server.crt"
370
           SSLCertificateKeyFile="/usr/local/ssl/server.pem"
348
           SSLCertificateKeyFile="/usr/local/ssl/server.pem"
371
           SSLVerifyClient="optional" SSLProtocol="TLSv1"/&gt;
349
           SSLVerifyClient="optional" SSLProtocol="TLSv1"/>]]></source>
372
</source>
373
</p>
374
350
351
375
<p>You will note that the example SSL connector elements are commented out by
352
<p>You will note that the example SSL connector elements are commented out by
376
default. You can either remove the comment tags from around the the example SSL
353
default. You can either remove the comment tags from around the the example SSL
377
connector you wish to use or add a new Connector element of your own. In either
354
connector you wish to use or add a new Connector element of your own. In either
Lines 378-384 Link Here
378
case, you will need to configure the SSL Connector for your requirements
355
case, you will need to configure the SSL Connector for your requirements
379
and environment. The configuration options and information on which attributes
356
and environment. The configuration options and information on which attributes
380
are mandatory, are documented in the SSL Support section of the
357
are mandatory, are documented in the SSL Support section of the
381
<a href="config/http.html#SSL Support">HTTP connector</a> configuration
358
<a href="config/http.html#SSL_Support">HTTP connector</a> configuration
382
reference. Make sure that you use the correct attributes for the connector you
359
reference. Make sure that you use the correct attributes for the connector you
383
are using. The BIO and NIO connectors use JSSE whereas the APR/native connector
360
are using. The BIO and NIO connectors use JSSE whereas the APR/native connector
384
uses APR.</p>
361
uses APR.</p>
Lines 390-409 Link Here
390
(outside the scope of this document) is necessary to run Tomcat on port
367
(outside the scope of this document) is necessary to run Tomcat on port
391
numbers lower than 1024 on many operating systems.</p>
368
numbers lower than 1024 on many operating systems.</p>
392
369
393
  <blockquote><em>
370
  
394
  <p>If you change the port number here, you should also change the
371
  <p><em>If you change the port number here, you should also change the
395
  value specified for the <code>redirectPort</code> attribute on the
372
  value specified for the <code>redirectPort</code> attribute on the
396
  non-SSL connector.  This allows Tomcat to automatically redirect
373
  non-SSL connector.  This allows Tomcat to automatically redirect
397
  users who attempt to access a page with a security constraint specifying
374
  users who attempt to access a page with a security constraint specifying
398
  that SSL is required, as required by the Servlet Specification.</p>
375
  that SSL is required, as required by the Servlet Specification.</em></p>
399
  </em></blockquote>
376
  
400
377
401
<p>After completing these configuration changes, you must restart Tomcat as
378
<p>After completing these configuration changes, you must restart Tomcat as
402
you normally do, and you should be in business.  You should be able to access
379
you normally do, and you should be in business.  You should be able to access
403
any web application supported by Tomcat via SSL.  For example, try:</p>
380
any web application supported by Tomcat via SSL.  For example, try:</p>
404
<source>
381
<source>https://localhost:8443</source>
405
https://localhost:8443
406
</source>
407
<p>and you should see the usual Tomcat splash page (unless you have modified
382
<p>and you should see the usual Tomcat splash page (unless you have modified
408
the ROOT web application).  If this does not work, the following section
383
the ROOT web application).  If this does not work, the following section
409
contains some troubleshooting tips.</p>
384
contains some troubleshooting tips.</p>
Lines 474-480 Link Here
474
449
475
<li>When Tomcat starts up, I get an exception like
450
<li>When Tomcat starts up, I get an exception like
476
    "java.io.FileNotFoundException: {some-directory}/{some-file} not found".
451
    "java.io.FileNotFoundException: {some-directory}/{some-file} not found".
477
    <blockquote>
452
478
    <p>A likely explanation is that Tomcat cannot find the keystore file
453
    <p>A likely explanation is that Tomcat cannot find the keystore file
479
    where it is looking.  By default, Tomcat expects the keystore file to
454
    where it is looking.  By default, Tomcat expects the keystore file to
480
    be named <code>.keystore</code> in the user home directory under which
455
    be named <code>.keystore</code> in the user home directory under which
Lines 481-518 Link Here
481
    Tomcat is running (which may or may not be the same as yours :-).  If
456
    Tomcat is running (which may or may not be the same as yours :-).  If
482
    the keystore file is anywhere else, you will need to add a
457
    the keystore file is anywhere else, you will need to add a
483
    <code>keystoreFile</code> attribute to the <code>&lt;Factory&gt;</code>
458
    <code>keystoreFile</code> attribute to the <code>&lt;Factory&gt;</code>
484
    element in the <a href="#Edit the Tomcat Configuration File">Tomcat
459
    element in the <a href="#Edit_the_Tomcat_Configuration_File">Tomcat
485
    configuration file</a>.</p>
460
    configuration file</a>.</p>
486
    </blockquote></li>
461
    </li>
487
462
488
<li>When Tomcat starts up, I get an exception like
463
<li>When Tomcat starts up, I get an exception like
489
    "java.io.FileNotFoundException:  Keystore was tampered with, or
464
    "java.io.FileNotFoundException:  Keystore was tampered with, or
490
    password was incorrect".
465
    password was incorrect".
491
    <blockquote>
466
492
    <p>Assuming that someone has not <em>actually</em> tampered with
467
    <p>Assuming that someone has not <em>actually</em> tampered with
493
    your keystore file, the most likely cause is that Tomcat is using
468
    your keystore file, the most likely cause is that Tomcat is using
494
    a different password than the one you used when you created the
469
    a different password than the one you used when you created the
495
    keystore file.  To fix this, you can either go back and
470
    keystore file.  To fix this, you can either go back and
496
    <a href="#Prepare the Certificate Keystore">recreate the keystore
471
    <a href="#Prepare_the_Certificate_Keystore">recreate the keystore
497
    file</a>, or you can add or update the <code>keystorePass</code>
472
    file</a>, or you can add or update the <code>keystorePass</code>
498
    attribute on the <code>&lt;Connector&gt;</code> element in the
473
    attribute on the <code>&lt;Connector&gt;</code> element in the
499
    <a href="#Edit the Tomcat Configuration File">Tomcat configuration
474
    <a href="#Edit_the_Tomcat_Configuration_File">Tomcat configuration
500
    file</a>.  <strong>REMINDER</strong> - Passwords are case sensitive!</p>
475
    file</a>.  <strong>REMINDER</strong> - Passwords are case sensitive!</p>
501
    </blockquote></li>
476
    </li>
502
477
503
<li>When Tomcat starts up, I get an exception like
478
<li>When Tomcat starts up, I get an exception like
504
    "java.net.SocketException: SSL handshake errorjavax.net.ssl.SSLException: No
479
    "java.net.SocketException: SSL handshake errorjavax.net.ssl.SSLException: No
505
    available certificate or key corresponds to the SSL cipher suites which are
480
    available certificate or key corresponds to the SSL cipher suites which are
506
    enabled."
481
    enabled."
507
    <blockquote>
482
508
    <p>A likely explanation is that Tomcat cannot find the alias for the server
483
    <p>A likely explanation is that Tomcat cannot find the alias for the server
509
    key within the specified keystore. Check that the correct
484
    key within the specified keystore. Check that the correct
510
    <code>keystoreFile</code> and <code>keyAlias</code> are specified in the
485
    <code>keystoreFile</code> and <code>keyAlias</code> are specified in the
511
    <code>&lt;Connector&gt;</code> element in the
486
    <code>&lt;Connector&gt;</code> element in the
512
    <a href="#Edit the Tomcat Configuration File">Tomcat configuration file</a>.
487
    <a href="#Edit_the_Tomcat_Configuration_File">Tomcat configuration file</a>.
513
    <strong>REMINDER</strong> - <code>keyAlias</code> values may be case
488
    <strong>REMINDER</strong> - <code>keyAlias</code> values may be case
514
    sensitive!</p>
489
    sensitive!</p>
515
    </blockquote></li>
490
    </li>
516
491
517
</ul>
492
</ul>
518
493
Lines 527-533 Link Here
527
<section name="Using the SSL for session tracking in your application">
502
<section name="Using the SSL for session tracking in your application">
528
  <p>This is a new feature in the Servlet 3.0 specification. Because it uses the
503
  <p>This is a new feature in the Servlet 3.0 specification. Because it uses the
529
     SSL session ID associated with the physical client-server connection there
504
     SSL session ID associated with the physical client-server connection there
530
     are some limitations. They are:
505
     are some limitations. They are:</p>
531
    <ul>
506
    <ul>
532
      <li>Tomcat must have a connector with the attribute
507
      <li>Tomcat must have a connector with the attribute
533
          <strong>isSecure</strong> set to <code>true</code>.</li>
508
          <strong>isSecure</strong> set to <code>true</code>.</li>
Lines 538-551 Link Here
538
          session replication as the SSL session IDs will be different on each
513
          session replication as the SSL session IDs will be different on each
539
          node.</li>
514
          node.</li>
540
    </ul>
515
    </ul>
541
  </p>
542
516
543
  <p>
517
  <p>
544
    To enable SSL session tracking you need to use a context listener to set the
518
    To enable SSL session tracking you need to use a context listener to set the
545
    tracking mode for the context to be just SSL (if any other tracking mode is
519
    tracking mode for the context to be just SSL (if any other tracking mode is
546
    enabled, it will be used in preference). It might look something like:
520
    enabled, it will be used in preference). It might look something like:</p>
547
    <source>
521
    <source><![CDATA[package org.apache.tomcat.example;
548
package org.apache.tomcat.example;
549
522
550
import java.util.EnumSet;
523
import java.util.EnumSet;
551
524
Lines 564-578 Link Here
564
    @Override
537
    @Override
565
    public void contextInitialized(ServletContextEvent event) {
538
    public void contextInitialized(ServletContextEvent event) {
566
        ServletContext context = event.getServletContext();
539
        ServletContext context = event.getServletContext();
567
        EnumSet&lt;SessionTrackingMode&gt; modes =
540
        EnumSet<SessionTrackingMode> modes =
568
            EnumSet.of(SessionTrackingMode.SSL);
541
            EnumSet.of(SessionTrackingMode.SSL);
569
542
570
        context.setSessionTrackingModes(modes);
543
        context.setSessionTrackingModes(modes);
571
    }
544
    }
572
545
573
}
546
}]]></source>
574
    </source>
547
575
  </p>
576
  <p>Note: SSL session tracking is implemented for the BIO and NIO connectors.
548
  <p>Note: SSL session tracking is implemented for the BIO and NIO connectors.
577
     It is not yet implemented for the APR connector.</p>
549
     It is not yet implemented for the APR connector.</p>
578
550
Lines 580-598 Link Here
580
552
581
<section name="Miscellaneous Tips and Bits">
553
<section name="Miscellaneous Tips and Bits">
582
554
583
<p>To access the SSL session ID from the request, use:<br />
555
<p>To access the SSL session ID from the request, use:</p>
584
556
585
  <code>
557
  <source><![CDATA[String sslID = (String)request.getAttribute("javax.servlet.request.ssl_session_id");]]></source>
586
    String sslID = (String)request.getAttribute("javax.servlet.request.ssl_session_id");
558
<p>
587
  </code>
588
<br />
589
For additional discussion on this area, please see
559
For additional discussion on this area, please see
590
<a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=22679">Bugzilla</a>.
560
<a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=22679">Bugzilla</a>.
591
</p>
561
</p>
592
562
593
  <p>To terminate an SSL session, use:
563
  <p>To terminate an SSL session, use:</p>
594
    <source>
564
    <source><![CDATA[// Standard HTTP session invalidation
595
// Standard HTTP session invalidation
596
session.invalidate();
565
session.invalidate();
597
566
598
// Invalidate the SSL Session
567
// Invalidate the SSL Session
Lines 603-610 Link Here
603
572
604
// Close the connection since the SSL session will be active until the connection
573
// Close the connection since the SSL session will be active until the connection
605
// is closed
574
// is closed
606
response.setHeader("Connection", "close");
575
response.setHeader("Connection", "close");]]></source>
607
    </source>
576
  <p>
608
    Note that this code is Tomcat specific due to the use of the
577
    Note that this code is Tomcat specific due to the use of the
609
    SSLSessionManager class. This is currently only available for the BIO and
578
    SSLSessionManager class. This is currently only available for the BIO and
610
    NIO connectors, not the APR/native connector.
579
    NIO connectors, not the APR/native connector.
(-)webapps/docs/virtual-hosting-howto.xml (-22 / +12 lines)
Lines 50-61 Link Here
50
      At the simplest, edit the <a href="config/engine.html">Engine</a> portion
50
      At the simplest, edit the <a href="config/engine.html">Engine</a> portion
51
      of your <code>server.xml</code> file to look like this:
51
      of your <code>server.xml</code> file to look like this:
52
    </p>
52
    </p>
53
    <source>
53
    <source><![CDATA[<Engine name="Catalina" defaultHost="ren">
54
&lt;Engine name="Catalina" defaultHost="ren"&gt;
54
    <Host name="ren"    appBase="renapps"/>
55
    &lt;Host name="ren"    appBase="renapps"/&gt;
55
    <Host name="stimpy" appBase="stimpyapps"/>
56
    &lt;Host name="stimpy" appBase="stimpyapps"/&gt;
56
</Engine>]]></source>
57
&lt;/Engine&gt;
58
    </source>
59
    <p>
57
    <p>
60
      Note that the directory structures under the appBase for each host should
58
      Note that the directory structures under the appBase for each host should
61
      not overlap each other.
59
      not overlap each other.
Lines 71-80 Link Here
71
    <p>
69
    <p>
72
      Create directories for each of the virtual hosts:
70
      Create directories for each of the virtual hosts:
73
    </p>
71
    </p>
74
    <source>
72
    <source>mkdir $CATALINA_HOME/renapps
75
mkdir $CATALINA_HOME/renapps
73
mkdir $CATALINA_HOME/stimpyapps</source>
76
mkdir $CATALINA_HOME/stimpyapps
77
    </source>
78
  </section>
74
  </section>
79
75
80
  <section name="Configuring Your Contexts">
76
  <section name="Configuring Your Contexts">
Lines 106-115 Link Here
106
        Create a structure under <code>$CATALINA_HOME/conf/Catalina</code>
102
        Create a structure under <code>$CATALINA_HOME/conf/Catalina</code>
107
        corresponding to your virtual hosts, e.g.:
103
        corresponding to your virtual hosts, e.g.:
108
      </p>
104
      </p>
109
      <source>
105
      <source>mkdir $CATALINA_HOME/conf/Catalina/ren
110
mkdir $CATALINA_HOME/conf/Catalina/ren
106
mkdir $CATALINA_HOME/conf/Catalina/stimpy</source>
111
mkdir $CATALINA_HOME/conf/Catalina/stimpy
112
      </source>
113
      <p>
107
      <p>
114
        Note that the ending directory name "Catalina" represents the
108
        Note that the ending directory name "Catalina" represents the
115
        <code>name</code> attribute of the
109
        <code>name</code> attribute of the
Lines 118-136 Link Here
118
      <p>
112
      <p>
119
        Now, for your default webapps, add:
113
        Now, for your default webapps, add:
120
      </p>
114
      </p>
121
      <source>
115
      <source>$CATALINA_HOME/conf/Catalina/ren/ROOT.xml
122
$CATALINA_HOME/conf/Catalina/ren/ROOT.xml
116
$CATALINA_HOME/conf/Catalina/stimpy/ROOT.xml</source>
123
$CATALINA_HOME/conf/Catalina/stimpy/ROOT.xml
124
      </source>
125
      <p>
117
      <p>
126
        If you want to use the Tomcat manager webapp for each host, you'll also
118
        If you want to use the Tomcat manager webapp for each host, you'll also
127
        need to add it here:
119
        need to add it here:
128
      </p>
120
      </p>
129
      <source>
121
      <source>cd $CATALINA_HOME/conf/Catalina
130
cd $CATALINA_HOME/conf/Catalina
131
cp localhost/manager.xml ren/
122
cp localhost/manager.xml ren/
132
cp localhost/manager.xml stimpy/
123
cp localhost/manager.xml stimpy/</source>
133
      </source>
134
    </subsection>
124
    </subsection>
135
    <subsection name="Further Information">
125
    <subsection name="Further Information">
136
      <p>
126
      <p>
(-)webapps/docs/windows-auth-howto.xml (-2 / +2 lines)
Lines 39-45 Link Here
39
authenticated automatically, the client machine used by the user must also be
39
authenticated automatically, the client machine used by the user must also be
40
part of the domain.</p>
40
part of the domain.</p>
41
<p>There are several options for implementing integrated Windows authentication
41
<p>There are several options for implementing integrated Windows authentication
42
with Apache Tomcat. They are:
42
with Apache Tomcat. They are:</p>
43
<ul>
43
<ul>
44
<li>Built-in Tomcat support.</li>
44
<li>Built-in Tomcat support.</li>
45
<li>Use a third party library such as Waffle.</li>
45
<li>Use a third party library such as Waffle.</li>
Lines 46-52 Link Here
46
<li>Use a reverse proxy that supports Windows authentication to perform the
46
<li>Use a reverse proxy that supports Windows authentication to perform the
47
authentication step such as IIS or httpd.</li>
47
authentication step such as IIS or httpd.</li>
48
</ul>
48
</ul>
49
The configuration of each of these options is discussed in the following
49
<p>The configuration of each of these options is discussed in the following
50
sections.</p>
50
sections.</p>
51
</section>
51
</section>
52
52
(-)webapps/docs/windows-service-howto.xml (-86 / +72 lines)
Lines 44-62 Link Here
44
    services.
44
    services.
45
</p>
45
</p>
46
    <p>The available command line options are:</p>
46
    <p>The available command line options are:</p>
47
<p>
47
48
    <table>
48
    <table class="defaultTable">
49
    <tr><th>//ES//</th>
49
    <tr><td><b>//ES//</b></td>
50
        <td>Edit service configuration</td>
50
        <td>Edit service configuration</td>
51
        <td>This is the default operation. It is called if the no option is
51
        <td>This is the default operation. It is called if the no option is
52
            provided but the executable is renamed to <b>servicenameW.exe</b></td>
52
            provided but the executable is renamed to <b>servicenameW.exe</b></td>
53
    </tr>
53
    </tr>
54
    <tr><th>//MS//</th>
54
    <tr><td><b>//MS//</b></td>
55
        <td>Monitor service</td>
55
        <td>Monitor service</td>
56
        <td>Put the icon in the system tray</td>
56
        <td>Put the icon in the system tray</td>
57
    </tr>
57
    </tr>
58
    </table>
58
    </table>
59
</p>
59
60
</section>
60
</section>
61
<section name="Command line arguments">
61
<section name="Command line arguments">
62
<p>
62
<p>
Lines 63-98 Link Here
63
    Each command line directive is in the form of <b>//XX//ServiceName</b>
63
    Each command line directive is in the form of <b>//XX//ServiceName</b>
64
</p>
64
</p>
65
    <p>The available command line options are:</p>
65
    <p>The available command line options are:</p>
66
<p>
66
67
    <table>
67
    <table class="defaultTable">
68
    <tr><th>//TS//</th>
68
    <tr><td><b>//TS//</b></td>
69
        <td>Run the service as console application</td>
69
        <td>Run the service as console application</td>
70
        <td>This is the default operation. It is called if the no option is
70
        <td>This is the default operation. It is called if the no option is
71
            provided. The ServiceName is the name of the executable without
71
            provided. The ServiceName is the name of the executable without
72
            exe suffix, meaning Tomcat7</td>
72
            exe suffix, meaning Tomcat7</td>
73
    </tr>
73
    </tr>
74
    <tr><th>//RS//</th>
74
    <tr><td><b>//RS//</b></td>
75
        <td>Run the service</td>
75
        <td>Run the service</td>
76
        <td>Called only from ServiceManager</td>
76
        <td>Called only from ServiceManager</td>
77
    </tr>
77
    </tr>
78
    <tr><th>//SS//</th>
78
    <tr><td><b>//SS//</b></td>
79
        <td>Stop the service</td>
79
        <td>Stop the service</td>
80
        <td></td>
80
        <td></td>
81
    </tr>
81
    </tr>
82
    <tr><th>//US//</th>
82
    <tr><td><b>//US//</b></td>
83
        <td>Update service parameters</td>
83
        <td>Update service parameters</td>
84
        <td></td>
84
        <td></td>
85
    </tr>
85
    </tr>
86
    <tr><th>//IS//</th>
86
    <tr><td><b>//IS//</b></td>
87
        <td>Install service</td>
87
        <td>Install service</td>
88
        <td></td>
88
        <td></td>
89
    </tr>
89
    </tr>
90
    <tr><th>//DS//</th>
90
    <tr><td><b>//DS//</b></td>
91
        <td>Delete service</td>
91
        <td>Delete service</td>
92
        <td>Stops the service if running</td>
92
        <td>Stops the service if running</td>
93
    </tr>
93
    </tr>
94
    </table>
94
    </table>
95
</p>
95
96
</section>
96
</section>
97
<section name="Command line parameters">
97
<section name="Command line parameters">
98
<p>
98
<p>
Lines 101-115 Link Here
101
    be appended to the existing option.
101
    be appended to the existing option.
102
    If the environment variable with the same name as command line parameter but
102
    If the environment variable with the same name as command line parameter but
103
    prefixed with <code>PR_</code> exists it will take precedence.
103
    prefixed with <code>PR_</code> exists it will take precedence.
104
    For example:
104
    For example:</p>
105
<source>set PR_CLASSPATH=xx.jar</source>
105
<source>set PR_CLASSPATH=xx.jar</source>
106
</p>
106
107
<p>is equivalent to providing
107
<p>is equivalent to providing</p>
108
<source>--Classpath=xx.jar</source>
108
<source>--Classpath=xx.jar</source>
109
</p>
110
<p> as command line parameter.</p>
109
<p> as command line parameter.</p>
111
<p>
110
112
    <table>
111
    <table class="defaultTable">
113
    <tr>
112
    <tr>
114
    <th>ParameterName</th>
113
    <th>ParameterName</th>
115
    <th>Default</th>
114
    <th>Default</th>
Lines 202-208 Link Here
202
    <td>Thread stack size in KB</td>
201
    <td>Thread stack size in KB</td>
203
    </tr>
202
    </tr>
204
    <tr>
203
    <tr>
205
    <tr>
206
    <td>--StartImage</td>
204
    <td>--StartImage</td>
207
    <td></td>
205
    <td></td>
208
    <td>Executable that will be run.</td>
206
    <td>Executable that will be run.</td>
Lines 234-239 Link Here
234
    <td>executable</td>
232
    <td>executable</td>
235
    <td>Can one of <b>jvm</b> <b>java</b> or <b>exe</b></td>
233
    <td>Can one of <b>jvm</b> <b>java</b> or <b>exe</b></td>
236
    </tr>
234
    </tr>
235
	<tr>
237
    <td>--StopImage</td>
236
    <td>--StopImage</td>
238
    <td></td>
237
    <td></td>
239
    <td>Executable that will be run on Stop service signal.</td>
238
    <td>Executable that will be run on Stop service signal.</td>
Lines 298-304 Link Here
298
    <td>Redirected stderr filename</td>
297
    <td>Redirected stderr filename</td>
299
    </tr>
298
    </tr>
300
    </table>
299
    </table>
301
</p>
300
302
</section>
301
</section>
303
<section name="Installing services">
302
<section name="Installing services">
304
<p>
303
<p>
Lines 309-385 Link Here
309
</p>
308
</p>
310
<p>
309
<p>
311
<strong>NOTE:</strong> On Windows Vista or any other operating system with User
310
<strong>NOTE:</strong> On Windows Vista or any other operating system with User
312
Account Control (UAC) you must either disable UAC or right-click on cmd.exe and
311
Account Control (UAC) enabled you must
313
select "Run as administrator" in order to run this script. If UAC is enabled
312
<!-- either disable UAC or [NOTE: Disabling UAC is mostly not a good idea,
314
neither being logged on with an Administrator account, nor using the
313
except on Windows Server OSes]  -->
314
right-click on cmd.exe and
315
select "Run as administrator" in order to run this script. On Windows 8 (or later) or
316
Windows Server 2012 (or later), you can open an elevated command prompt
317
for the current directory from the explorer
318
by clicking on the "File" menu bar.<br/>
319
If UAC is enabled,
320
neither being logged on with an Administrator account nor using the
315
<code>/user</code> switch is sufficient.
321
<code>/user</code> switch is sufficient.
316
</p>
322
</p>
317
<p>
323
318
<source>
324
<source>Install the service named 'Tomcat7'
319
Install the service named 'Tomcat7'
325
C:\> service.bat install</source>
320
C:\> service.bat install
326
321
</source>
322
</p>
323
<p>There is a 2nd optional parameter that lets you specify the name of the
327
<p>There is a 2nd optional parameter that lets you specify the name of the
324
service, as displayed in Windows services.</p>
328
service, as displayed in Windows services.</p>
329
330
<source>Install the service named 'MyService'
331
C:\> service.bat install MyService</source>
332
325
<p>
333
<p>
326
<source>
327
Install the service named 'MyService'
328
C:\> service.bat install MyService
329
</source>
330
</p>
331
<p>
332
If using tomcat7.exe, you need to use the <b>//IS//</b> parameter.</p>
334
If using tomcat7.exe, you need to use the <b>//IS//</b> parameter.</p>
333
<p>
335
334
<source>
336
<source>Install the service named 'Tomcat7'
335
Install the service named 'Tomcat7'
336
C:\> tomcat7 //IS//Tomcat7 --DisplayName="Apache Tomcat 7" \
337
C:\> tomcat7 //IS//Tomcat7 --DisplayName="Apache Tomcat 7" \
337
C:\> --Install="C:\Program Files\Tomcat\bin\tomcat7.exe" --Jvm=auto \
338
C:\> --Install="C:\Program Files\Tomcat\bin\tomcat7.exe" --Jvm=auto \
338
C:\> --StartMode=jvm --StopMode=jvm \
339
C:\> --StartMode=jvm --StopMode=jvm \
339
C:\> --StartClass=org.apache.catalina.startup.Bootstrap --StartParams=start \
340
C:\> --StartClass=org.apache.catalina.startup.Bootstrap --StartParams=start \
340
C:\> --StopClass=org.apache.catalina.startup.Bootstrap --StopParams=stop
341
C:\> --StopClass=org.apache.catalina.startup.Bootstrap --StopParams=stop</source>
341
</source>
342
342
</p>
343
</section>
343
</section>
344
<section name="Updating services">
344
<section name="Updating services">
345
<p>
345
<p>
346
To update the service parameters, you need to use the <b>//US//</b> parameter.
346
To update the service parameters, you need to use the <b>//US//</b> parameter.
347
</p>
347
</p>
348
<p>
348
349
<source>
349
<source>Update the service named 'Tomcat7'
350
Update the service named 'Tomcat7'
351
C:\> tomcat7 //US//Tomcat7 --Description="Apache Tomcat Server - http://tomcat.apache.org/ " \
350
C:\> tomcat7 //US//Tomcat7 --Description="Apache Tomcat Server - http://tomcat.apache.org/ " \
352
C:\> --Startup=auto --Classpath=%JAVA_HOME%\lib\tools.jar;%CATALINA_HOME%\bin\bootstrap.jar
351
C:\> --Startup=auto --Classpath=%JAVA_HOME%\lib\tools.jar;%CATALINA_HOME%\bin\bootstrap.jar</source>
353
</source>
352
354
</p>
355
<p>If you gave the service an optional name, you need to specify it like this:
353
<p>If you gave the service an optional name, you need to specify it like this:
356
</p>
354
</p>
357
<p>
355
358
<source>
356
<source>Update the service named 'MyService'
359
Update the service named 'MyService'
360
C:\> tomcat7 //US//MyService --Description="Apache Tomcat Server - http://tomcat.apache.org/ " \
357
C:\> tomcat7 //US//MyService --Description="Apache Tomcat Server - http://tomcat.apache.org/ " \
361
C:\> --Startup=auto --Classpath=%JAVA_HOME%\lib\tools.jar;%CATALINA_HOME%\bin\bootstrap.jar
358
C:\> --Startup=auto --Classpath=%JAVA_HOME%\lib\tools.jar;%CATALINA_HOME%\bin\bootstrap.jar</source>
362
</source>
359
363
</p>
364
</section>
360
</section>
365
<section name="Removing services">
361
<section name="Removing services">
366
<p>
362
<p>
367
To remove the service, you need to use the <b>//DS//</b> parameter.<br/>
363
To remove the service, you need to use the <b>//DS//</b> parameter.<br/>
368
If the service is running it will be stopped and then deleted.</p>
364
If the service is running it will be stopped and then deleted.</p>
369
<p>
365
370
<source>
366
<source>Remove the service named 'Tomcat7'
371
Remove the service named 'Tomcat7'
367
C:\> tomcat7 //DS//Tomcat7</source>
372
C:\> tomcat7 //DS//Tomcat7
368
373
</source>
374
</p>
375
<p>If you gave the service an optional name, you need to specify it like this:
369
<p>If you gave the service an optional name, you need to specify it like this:
376
</p>
370
</p>
377
<p>
371
378
<source>
372
<source>Remove the service named 'MyService'
379
Remove the service named 'MyService'
373
C:\> tomcat7 //DS//MyService</source>
380
C:\> tomcat7 //DS//MyService
374
381
</source>
382
</p>
383
</section>
375
</section>
384
<section name="Debugging services">
376
<section name="Debugging services">
385
<p>
377
<p>
Lines 388-401 Link Here
388
<b>CTRL+BREAK</b>.
380
<b>CTRL+BREAK</b>.
389
If you rename the tomcat7.exe to testservice.exe then you can just execute the
381
If you rename the tomcat7.exe to testservice.exe then you can just execute the
390
testservice.exe and this command mode will be executed by default.</p>
382
testservice.exe and this command mode will be executed by default.</p>
391
<p>
383
392
<source>
384
<source>Run the service named 'Tomcat7' in console mode
393
Run the service named 'Tomcat7' in console mode
394
C:\> tomcat7 //TS//Tomcat7 [additional arguments]
385
C:\> tomcat7 //TS//Tomcat7 [additional arguments]
395
Or simply execute:
386
Or simply execute:
396
C:\> tomcat7
387
C:\> tomcat7</source>
397
</source>
388
398
</p>
399
</section>
389
</section>
400
<section name="Multiple Instances">
390
<section name="Multiple Instances">
401
<p>
391
<p>
Lines 425-431 Link Here
425
<p>
415
<p>
426
You must edit CATALINA_BASE\conf\server.xml to specify a unique IP/port for the
416
You must edit CATALINA_BASE\conf\server.xml to specify a unique IP/port for the
427
instance to listen on. Find the line that contains
417
instance to listen on. Find the line that contains
428
<pre>&lt;Connector port="8080" ...</pre> and add an address attribute and/or
418
<code>&lt;Connector port="8080" ...</code> and add an address attribute and/or
429
update the port number so as to specify a unique IP/port combination.</p>
419
update the port number so as to specify a unique IP/port combination.</p>
430
<p>
420
<p>
431
To install an instance, first set the CATALINA_HOME environment variable to the
421
To install an instance, first set the CATALINA_HOME environment variable to the
Lines 432-444 Link Here
432
name of the Tomcat installation directory. Then create a second environment
422
name of the Tomcat installation directory. Then create a second environment
433
variable CATALINA_BASE and point this to the instance folder. Then run "service
423
variable CATALINA_BASE and point this to the instance folder. Then run "service
434
install" command specifying a service name.</p>
424
install" command specifying a service name.</p>
435
<p>
425
436
<source>
426
<source>set CATALINA_HOME=c:\tomcat_7
437
set CATALINA_HOME=c:\tomcat_7
438
set CATALINA_BASE=c:\tomcat_7\instances\instance1
427
set CATALINA_BASE=c:\tomcat_7\instances\instance1
439
service install instance1
428
service install instance1</source>
440
</source>
429
441
</p>
442
<p>
430
<p>
443
To modify the service settings, you can run <b>tomcat7w //ES//instance1</b>.
431
To modify the service settings, you can run <b>tomcat7w //ES//instance1</b>.
444
</p>
432
</p>
Lines 445-456 Link Here
445
<p>
433
<p>
446
For additional instances, create additional instance folder, update the
434
For additional instances, create additional instance folder, update the
447
CATALINA_BASE environment variable, and run the service install again.</p>
435
CATALINA_BASE environment variable, and run the service install again.</p>
448
<p>
436
449
<source>
437
<source>set CATALINA_BASE=c:\tomcat_7\instances\instance2
450
set CATALINA_BASE=c:\tomcat_7\instances\instance2
438
service install instance2</source>
451
service install instance2
439
452
</source>
453
</p>
454
</section>
440
</section>
455
</body>
441
</body>
456
</document>
442
</document>

Return to bug 55383