forked from apache/tomcat
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathfs-admin-objects.xml
More file actions
489 lines (397 loc) · 20.3 KB
/
fs-admin-objects.xml
File metadata and controls
489 lines (397 loc) · 20.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="fs-admin-objects.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig McClanahan</author>
<title>Administrative Apps - Administered Objects</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Administered Objects Overview">
<p>This document defines the <em>Administered Objects</em> that represent
the internal architectural components of the Catalina servlet container.
Associated with each is a set of <a href="fs-admin-opers.html">Supported
Operations</a> that can be performed when the administrative application is
"focused" on a particular configurable object.</p>
<p>The following Administered Objects are defined:</p>
<ul>
<li><a href="#Access_Logger">Access Logger</a></li>
<li><a href="#Connector">Connector</a></li>
<li><a href="#Context">Context</a></li>
<li><a href="#Default_Context">Default Context</a></li>
<li><a href="#Default_Deployment_Descriptor">Default Deployment Descriptor</a></li>
<li><a href="#Engine">Engine</a></li>
<li><a href="#Environment_Entry">Environment Entry</a></li>
<li><a href="#Host">Host</a></li>
<li><a href="#JDBC_Resource">JDBC Resource</a></li>
<li><a href="#Loader">Loader</a></li>
<li><a href="#Manager">Manager</a></li>
<li><a href="#Realm">Realm</a></li>
<li><a href="#Request_Filter">Request Filter</a></li>
<li><a href="#Server">Server</a></li>
<li><a href="#Service">Service</a></li>
</ul>
</section>
<section name="Access Logger">
<p>An <em>Access Logger</em> is an optional <code>Valve</code> that can
create request access logs in the same formats as those provided by
web servers. Such access logs are useful input to hit count and user
access tracking analysis programs. An Access Logger can be attached to
an <em>Engine</em>, a <em>Host</em>, a <em>Context</em>, or a <em>Default
Context</em>.</p>
<p>The standard component implementing an <em>Access Logger</em> is
<code>org.apache.catalina.valves.AccessLogValve</code>. It supports the
following configurable properties:</p>
<ul>
<li><code>debug</code> - Debugging detail level. [0]</li>
<li><code>directory</code> - Absolute or relative (to $CATALINA_BASE) path
of the directory into which access log files are created.
[logs].</li>
<li><code>pattern</code> - Pattern string defining the fields to be
included in the access log output, or "common" for the standard
access log pattern. See
<code>org.apache.catalina.valves.AccessLogValve</code> for more
information. [common]</li>
<li><code>prefix</code> - Prefix added to the beginning of each log file
name created by this access logger.</li>
<li><code>resolveHosts</code> - Should IP addresses be resolved to host
names in the log? [false]</li>
<li><code>suffix</code> - Suffix added to the end of each log file name
created by this access logger.</li>
</ul>
</section>
<section name="Connector">
<p>A <em>Connector</em> is the representation of a communications endpoint
by which requests are received from (and responses returned to) a Tomcat
client. The administrative applications shall support those connectors
that are commonly utilized in Tomcat installations, as described in detail
below.</p>
<p>For standalone use, the standard connector supporting the HTTP/1.1
protocol is <code>org.apache.catalina.connectors.http.HttpConnector</code>.
It supports the following configurable properties:</p>
<ul>
<li><code>acceptCount</code> - The maximum queue length of incoming
connections that have not yet been accepted. [10]</li>
<li><code>address</code> - For servers with more than one IP address, the
address upon which this connector should listen. [All Addresses]</li>
<li><code>bufferSize</code> - Default input buffer size (in bytes) for
requests created by this Connector. [2048]</li>
<li><code>debug</code> - Debugging detail level. [0]</li>
<li><code>enableLookups</code> - Should we perform DNS lookups on remote
IP addresses when <code>request.getRemoteHost()</code> is called?
[false]</li>
<li><code>maxProcessors</code> - The maximum number of processor threads
supported by this connector. [20]</li>
<li><code>minProcessors</code> - The minimum number of processor threads
to be created at container startup. [5]</li>
<li><code>port</code> - TCP/IP port number on which this Connector should
listen for incoming requests. [8080]</li>
<li><code>proxyName</code> - Host name to be returned when an application
calls <code>request.getServerName()</code>. [Value of Host: header]</li>
<li><code>proxyPort</code> - Port number to be returned when an application
calls <code>request.getServerPort()</code>. [Same as <code>port</code>]
</li>
</ul>
</section>
<section name="Context">
<p>A <em>Context</em> is the representation of an individual web application,
which is associated with a corresponding <em>Host</em>. Note that the
administrable properties of a <em>Context</em> do <strong>not</strong>
include any settings from inside the web application deployment descriptor
for that application.</p>
<p>The standard component implementing a <em>Context</em> is
<code>org.apache.catalina.core.StandardContext</code>. It supports the
following configurable properties:</p>
<ul>
<li><code>cookies</code> - Should be use cookies for session identifier
communication? [true]</li>
<li><code>crossContext</code> - Should calls to
<code>ServletContext.getServletContext()</code> return the actual
context responsible for the specified path? [false]</li>
<li><code>debug</code> - Debugging detail level. [0]</li>
<li><code>docBase</code> - The absolute or relative (to the
<code>appBase</code> of our owning <em>Host</em>) pathname of a
directory containing an unpacked web application, or of a web
application archive (WAR) file.</li>
<li><code>override</code> - Should settings in this <em>Context</em>
override corresponding settings in the <em>Default Context</em>?
[false]</li>
<li><code>path</code> - Context path for this web application, or an empty
string for the root application of a <em>Host</em>. [Inferred from
directory or WAR file name]</li>
<li><code>reloadable</code> - Should Tomcat monitor classes in the
<code>/WEB-INF/classes</code> directory for changes, and reload the
application if they occur? [false]</li>
<li><code>useNaming</code> - Should Tomcat provide a JNDI naming context,
containing preconfigured entries and resources, corresponding to the
requirements of the Java2 Enterprise Edition specification? [true]</li>
<li><code>workDir</code> - Absolute pathname of a scratch directory that is
provided to this web application. [Automatically assigned relative to
$CATALINA_BASE/work]</li>
</ul>
<p>Each <em>Context</em> is owned by a parent <em>Host</em>, and is
associated with:</p>
<ul>
<li>An optional <em>Access Logger</em> that logs all requests processed
by this web application.</li>
<li>Zero or more <em>Environment Entries</em> representing environment
entries for the JNDI naming context associated with a web
application.</li>
<li>Zero or more <em>JDBC Resources</em> representing database connection
pools associated with a web application.</li>
<li>A <em>Loader</em> representing the web application class loader used
by this web application.</li>
<li>A <em>Manager</em> representing the session manager used by this
web application.</li>
<li>An optional <em>Realm</em> used to provide authentication and access
control information for this web application.</li>
<li>Zero or more <em>Request Filters</em> used to limit access to this
web application based on remote host name or IP address.</li>
</ul>
</section>
<section name="Default Context">
<p>A <em>Default Context</em> represents a subset of the configurable
properties of a <em>Context</em>, and is used to set defaults for those
properties when web applications are automatically deployed. A <em>Default
Context</em> object can be associated with an <em>Engine</em> or a
<em>Host</em>. The following configurable properties are supported:</p>
<ul>
<li><code>cookies</code> - Should be use cookies for session identifier
communication? [true]</li>
<li><code>crossContext</code> - Should calls to
<code>ServletContext.getServletContext()</code> return the actual
context responsible for the specified path? [false]</li>
<li><code>reloadable</code> - Should Tomcat monitor classes in the
<code>/WEB-INF/classes</code> directory for changes, and reload the
application if they occur? [false]</li>
<li><code>useNaming</code> - Should Tomcat provide a JNDI naming context,
containing preconfigured entries and resources, corresponding to the
requirements of the Java2 Enterprise Edition specification? [true]</li>
</ul>
<p>Each <em>Default Context</em> is owned by a parent <em>Engine</em> or
<em>Host</em>, and is associated with:</p>
<ul>
<li>Zero or more <em>Environment Entries</em> representing environment
entries for the JNDI naming context associated with a web
application.</li>
<li>Zero or more <em>JDBC Resources</em> representing database connection
pools associated with a web application.</li>
<li>An optional <em>Loader</em> representing default configuration
properties for the Loader component of deployed web applications.</li>
<li>An optional <em>Manager</em> representing default configuration
properties for the Manager component of deployed web applications.</li>
</ul>
</section>
<section name="Default Deployment Descriptor">
<p>Default web application characteristics are configured in a special
deployment descriptor named <code>$CATALINA_BASE/conf/web.xml</code>. This
section describes the configurable components that may be stored there.</p>
<p><strong>FIXME</strong> - Complete the description of default servlets,
default mappings, default MIME types, and so on.</p>
</section>
<section name="Engine">
<p>An <em>Engine</em> is the representation of the entire Catalina
servlet container, and processes all requests for all of the associated
virtual hosts and web applications.</p>
<p>The standard component implementing an <em>Engine</em> is
<code>org.apache.catalina.core.StandardEngine</code>. It supports the
following configurable properties:</p>
<ul>
<li><code>debug</code> - Debugging detail level. [0]</li>
<li><code>defaultHost</code> - Name of the <em>Host</em> to which requests
will be directed if the requested host is unknown. [localhost]</li>
<li><code>name</code> - Logical name of this engine. [Tomcat Stand-Alone]
</li>
</ul>
<p>Each <em>Engine</em> is owned by a parent <em>Service</em>, and is
associated with:</p>
<ul>
<li>An optional <em>Access Logger</em> that logs all requests processed
by the entire container.</li>
<li>A <em>Default Context</em>, representing default properties of a
<em>Context</em> for automatically deployed applications for all
associated <em>Hosts</em> (unless overridden by a subordinate
component).</li>
<li>One or more <em>Hosts</em> representing individual virtual hosts
supported by this container.</li>
<li>A <em>Realm</em> used to provide authentication and access control
information for all virtual hosts and web applications (unless
overridden by a subordinate component).</li>
<li>Zero or more <em>Request Filters</em> used to limit access to the
entire container based on remote host name or IP address.</li>
</ul>
</section>
<section name="Environment Entry">
<p>An <em>Environment Entry</em> is the representation of a
<code><env-entry></code> element from a web application deployment
descriptor. It will cause the creation of a corresponding entry in the
JNDI naming context provided to the corresponding <em>Context</em>. The
following configurable properties are supported:</p>
<ul>
<li><code>description</code> - Description of this environment entry.</li>
<li><code>name</code> - Environment entry name (relative to the
<code>java:comp/env</code> context)</li>
<li><code>type</code> - Environment entry type (must be one of the fully
qualified Java classes listed in the servlet spec).</li>
<li><code>value</code> - Environment entry value (must be convertible from
String to the specified <code>type</code>.</li>
</ul>
</section>
<section name="Host">
<p>A <em>Host</em> is the representation of an individual virtual host,
which has a unique set of associated web applications.</p>
<p>The standard component implementing a <em>Host</em> is
<code>org.apache.catalina.core.StandardHost</code>. It supports the
following configurable properties:</p>
<ul>
<li><code>aliases</code> - Zero or more DNS names that are also associated
with this host (for example, a particular host might be named
<code>www.mycompany.com</code> with an alias <code>company.com</code>).
</li>
<li><code>appBase</code> - Absolute or relative (to $CATALINA_BASE) path
to a directory from which web applications will be automatically
deployed.</li>
<li><code>debug</code> - Debugging detail level. [0]</li>
<li><code>name</code> - DNS Name of the virtual host represented by this
object.</li>
<li><code>unpackWARs</code> - Should web application archive files
deployed by this virtual host be unpacked first? [true]</li>
</ul>
<p>Each <em>Host</em> is owned by a parent <em>Engine</em>, and is
associated with:</p>
<ul>
<li>An optional <em>Access Logger</em> that logs all requests processed
by this virtual host.</li>
<li>One or more <em>Contexts</em> representing the web applications
operating on this <em>Host</em>.</li>
<li>A <em>Default Context</em> representing default <em>Context</em>
properties for web applications that are automatically deployed
by this <em>Host</em>.</li>
<li>A optional <em>Realm</em> used to provide authentication and access
control information for all web applications associated with this
virtual host (unless overridden by a subordinate component).</li>
</ul>
<p><strong>FIXME</strong> - Should we support configuration of the
User Web Applications functionality?</p>
</section>
<section name="JDBC Resource">
<p>A <em>JDBC Resources</em> represents a database connection pool (i.e.
an implementation of <code>javax.sql.DataSource</code> that will be
configured and made available in the JNDI naming context associated with
a web application.</p>
<p><strong>FIXME</strong> - properties of this administered object</p>
</section>
<section name="Loader">
<p>A <em>Loader</em> represents a web application class loader that will
be utilized to provide class loading services for a particular
<em>Context</em>.</p>
<p>The standard component implementing a <em>Loader</em> is
<code>org.apache.catalina.loader.WebappLoader</code>. It supports
the following configurable properties:</p>
<ul>
<li><code>reloadable</code> - Should this class loader check for modified
classes and initiate automatic reloads? [Set automatically from the
<code>reloadable</code> property of the corresponding <em>Context</em>]
</li>
</ul>
<p>Each <em>Loader</em> is owned by a parent <em>Context</em>.</p>
</section>
<section name="Manager">
<p>A <em>Manager</em> represents a session manager that will be associated
with a particular web application. <strong>FIXME</strong> - Add support
for advanced session managers and their associated Stores.</p>
<p>The standard component implementing a <em>Manager</em> is
<code>org.apache.catalina.session.StandardManager</code>. It supports
the following configurable properties:</p>
<ul>
<li><code>maxActiveSessions</code> - The maximum number of active sessions
that are allowed, or -1 for no limit. [-1]</li>
</ul>
<p>Each <em>Manager</em> is owned by a parent <em>Context</em>.</p>
</section>
<section name="Realm">
<p>A <em>Realm</em> represents a "database" of information about authorized
users, their passwords, and the security roles assigned to them. This will
be used by the container in the implementation of container-managed security
in accordance with the Servlet Specification. Several alternative
implementations are supported.</p>
<p><code>org.apache.catalina.realm.MemoryRealm</code> initializes its user
information from a simple XML file at startup time. If changes are made
to the information in this file, the corresponding web applications using
it must be restarted for the changes to take effect. It supports the
following configurable properties:</p>
<ul>
<li><code>debug</code> - Debugging detail level. [0]</li>
<li><code>pathname</code> - Absolute or relative (to $CATALINA_BASE) path to
the XML file containing our user information. [conf/tomcat-users.xml]
</li>
</ul>
<p><code>org.apache.catalina.realm.JDBCRealm</code> uses a relational
database (accessed via JDBC APIs) to contain the user information. Changes
in the contents of this database take effect immediately; however, the roles
assigned to a particular user are calculated only when the user initially
logs on (and not per request). The following configurable properties
are supported:</p>
<ul>
<li><code>connectionName</code> - Database username to use when establishing
a JDBC connection.</li>
<li><code>connectionPassword</code> - Database password to use when
establishing a JDBC connection.</li>
<li><code>connectionURL</code> - Connection URL to use when establishing
a JDBC connection.</li>
<li><code>debug</code> - Debugging detail level. [0]</li>
<li><code>digest</code> - Name of the <code>MessageDigest</code> algorithm
used to encode passwords in the database, or a zero-length string for
no encoding. [Zero-length String]</li>
<li><code>driverName</code> - Fully qualified Java class name of the JDBC
driver to be utilized.</li>
<li><code>roleNameCol</code> - Name of the column, in the User Roles table,
which contains the role name.</li>
<li><code>userCredCol</code> - Name of the column, in the Users table,
which contains the password (encrypted or unencrypted).</li>
<li><code>userNameCol</code> - Name of the column, in both the Users and
User Roles tables, that contains the username.</li>
<li><code>userRoleTable</code> - Name of the User Roles table, which contains
one row per security role assigned to a particular user. This table must
contain the columns specified by the <code>userNameCol</code> and
<code>roleNameCol</code> properties.</li>
<li><code>userTable</code> - Name of the Users table, which contains one row
per authorized user. This table must contain the columns specified by
the <code>userNameCol</code> and <code>userCredCol</code> properties.
</li>
</ul>
<p><strong>FIXME</strong> - Should we provide mechanisms to edit the contents
of a "tomcat-users.xml" file through the admin applications?</p>
<p>Each <em>Realm</em> is owned by a parent <em>Engine</em>, <em>Host</em>,
or <em>Context</em>.</p>
</section>
<section name="Request Filter">
<p><strong>FIXME</strong> - complete this entry</p>
</section>
<section name="Server">
<p><strong>FIXME</strong> - complete this entry</p>
</section>
<section name="Service">
<p><strong>FIXME</strong> - complete this entry</p>
</section>
</body>
</document>