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
490
491
492
493
494
495
496
497
498
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html xmlns="http://www.w3.org/TR/xhtml1/strict">
<head>
<title>Configuration file</title>
<meta content="1999-2003 The Apache Software Foundation" name="copyright"/>
<meta content="$Date: 2003/03/06 19:45:27 $" name="last-changed"/>
<meta content="Costin Manolache" name="author"/>
<meta content="cmanolache@yahoo.com" name="email"/>
<meta content="Jean-Frederic Clere" name="author"/>
<meta content="jfrederic.clere@fujitsu-siemens.com" name="email"/>
<link href="..//style.css" type="text/css" rel="stylesheet"/>
<link href="../images/tomcat.ico" rel="shortcut icon"/>
</head>
<body link="#525D76" vlink="#525D76" alink="#525D76" text="#000000" bgcolor="#ffffff">
<a name="TOP"/>
<table width="100%" cellpadding="0" cellspacing="0" border="0">
<tr height="1">
<td class="nil" height="1" bgcolor="#ffffff" width="150">
<img hspace="0" vspace="0" height="1" width="150" border="0" src="../images/pixel.gif"/>
</td>
<td class="nil" height="1" bgcolor="#ffffff" width="*">
<img hspace="0" vspace="0" height="1" width="370" border="0" src="../images/pixel.gif"/>
</td>
</tr>
<tr>
<td width="*" colspan="2" class="logo" bgcolor="#ffffff">
<table width="100%" cellpadding="0" cellspacing="0" border="0">
<tr>
<td align="left">
<img align="left" height="48" width="505" border="0" src="../images/jakarta.gif"/>
</td>
<td align="right">
<img align="right" border="0" src="../images/mod_jk.jpg"/>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td colspan="2" width="*" align="right" class="head" bgcolor="#999999">
<nobr>
<a href="http://www.apache.org/" class="head">Apache Software Foundation</a> |
<a href="http://jakarta.apache.org/" class="head">Jakarta Project</a> |
<a href="http://jakarta.apache.org/tomcat/" class="head">Apache Tomcat</a>
</nobr>
</td>
</tr>
<tr>
<td valign="top" width="150" bgcolor="#ffffff">
<table class="menu" cellpadding="0" cellspacing="0" width="150" border="0">
<tr height="1">
<td class="nil" height="1" bgcolor="#cccccc" width="10">
<img hspace="0" vspace="0" height="1" width="10" border="0" src="../images/pixel.gif"/>
</td>
<td class="nil" height="1" bgcolor="#cccccc" width="140">
<img hspace="0" vspace="0" height="1" width="140" border="0" src="../images/pixel.gif"/>
</td>
</tr>
<tr height="6">
<td colspan="2" width="150" bgcolor="#d0d0d0">Presentation</td>
</tr>
<tr>
<td colspan="2" width="150" bgcolor="#cccccc">
<nobr>
<a class="menu" href="../index.html">Overview</a>
</nobr>
</td>
</tr>
<tr height="2"/>
<tr height="6"/>
<tr height="6">
<td colspan="2" width="150" bgcolor="#d0d0d0">Commons</td>
</tr>
<tr>
<td colspan="2" width="150" bgcolor="#cccccc">
<nobr>
<a class="menu" href="../common/AJPv13.html">AJPv13</a>
</nobr>
</td>
</tr>
<tr height="2"/>
<tr>
<td colspan="2" width="150" bgcolor="#cccccc">
<nobr>
<a class="menu" href="../common/AJPv13-extensions-proposal.html">AJPv13 extensions Proposal</a>
</nobr>
</td>
</tr>
<tr height="2"/>
<tr>
<td colspan="2" width="150" bgcolor="#cccccc">
<nobr>
<a class="menu" href="../common/doccontrib.html">How to Contribute to the Documentation</a>
</nobr>
</td>
</tr>
<tr height="2"/>
<tr>
<td colspan="2" width="150" bgcolor="#cccccc">
<nobr>
<a class="menu" href="../common/tools.html">Tools</a>
</nobr>
</td>
</tr>
<tr height="2"/>
<tr>
<td colspan="2" width="150" bgcolor="#cccccc">
<nobr>
<a class="menu" href="../faq.html">FAQ</a>
</nobr>
</td>
</tr>
<tr height="2"/>
<tr height="6"/>
<tr height="6">
<td colspan="2" width="150" bgcolor="#d0d0d0">JK</td>
</tr>
<tr>
<td colspan="2" width="150" bgcolor="#cccccc">
<nobr>
<a class="menu" href="../jk/quickhowto.html">Quick Start HowTo</a>
</nobr>
</td>
</tr>
<tr height="2"/>
<tr>
<td colspan="2" width="150" bgcolor="#cccccc">
<nobr>
<a class="menu" href="../jk/aphowto.html">Apache HowTo</a>
</nobr>
</td>
</tr>
<tr height="2"/>
<tr>
<td colspan="2" width="150" bgcolor="#cccccc">
<nobr>
<a class="menu" href="../jk/domhowto.html">Domino HowTo</a>
</nobr>
</td>
</tr>
<tr height="2"/>
<tr>
<td colspan="2" width="150" bgcolor="#cccccc">
<nobr>
<a class="menu" href="../jk/iishowto.html">IIS HowTo</a>
</nobr>
</td>
</tr>
<tr height="2"/>
<tr>
<td colspan="2" width="150" bgcolor="#cccccc">
<nobr>
<a class="menu" href="../jk/neshowto.html">Netscape/iPlanet HowTo</a>
</nobr>
</td>
</tr>
<tr height="2"/>
<tr>
<td colspan="2" width="150" bgcolor="#cccccc">
<nobr>
<a class="menu" href="../jk/workershowto.html">Workers HowTo</a>
</nobr>
</td>
</tr>
<tr height="2"/>
<tr height="6"/>
<tr height="6">
<td colspan="2" width="150" bgcolor="#d0d0d0">JK2</td>
</tr>
<tr height="6"/>
<tr height="6">
<td colspan="2" width="150" bgcolor="#d0d0d0">Configuration in the Tomcat</td>
</tr>
<tr>
<td colspan="2" width="150" bgcolor="#cccccc">
<nobr>
<a class="menu" href="../jk2/configtc.html">Configuration options</a>
</nobr>
</td>
</tr>
<tr height="2"/>
<tr>
<td colspan="2" width="150" bgcolor="#cccccc">
<nobr>
<a class="menu" href="../jk2/configtccom.html">Coyote/JK2 Handlers</a>
</nobr>
</td>
</tr>
<tr height="2"/>
<tr>
<td colspan="2" width="150" bgcolor="#cccccc">
<nobr>
<a class="menu" href="../jk2/configtcex.html">Examples</a>
</nobr>
</td>
</tr>
<tr height="2"/>
<tr height="6"/>
<tr height="6">
<td colspan="2" width="150" bgcolor="#d0d0d0">Configuration in the Web Server</td>
</tr>
<tr>
<td colspan="2" width="150" bgcolor="#cccccc">
<nobr>
<a class="menu" href="../jk2/configweb.html">Configuration file</a>
</nobr>
</td>
</tr>
<tr height="2"/>
<tr>
<td width="10" bgcolor="#cccccc"/>
<td width="140" bgcolor="#cccccc">
<a href="#Intro" class="menu">Intro</a>
</td>
</tr>
<tr height="1"/>
<tr>
<td width="10" bgcolor="#cccccc"/>
<td width="140" bgcolor="#cccccc">
<a href="#Config file format" class="menu">Config file format</a>
</td>
</tr>
<tr height="1"/>
<tr>
<td width="10" bgcolor="#cccccc"/>
<td width="140" bgcolor="#cccccc">
<a href="#Runtime reconfiguration" class="menu">Runtime reconfiguration</a>
</td>
</tr>
<tr height="1"/>
<tr>
<td width="10" bgcolor="#cccccc"/>
<td width="140" bgcolor="#cccccc">
<a href="#Changing 'graceful' stop state" class="menu">Changing 'graceful' stop state</a>
</td>
</tr>
<tr height="1"/>
<tr>
<td width="10" bgcolor="#cccccc"/>
<td width="140" bgcolor="#cccccc">
<a href="#Adding a new tomcat instance" class="menu">Adding a new tomcat instance</a>
</td>
</tr>
<tr height="1"/>
<tr>
<td width="10" bgcolor="#cccccc"/>
<td width="140" bgcolor="#cccccc">
<a href="#Advanced: reconfiguration using JMX" class="menu">Advanced: reconfiguration using JMX</a>
</td>
</tr>
<tr height="1"/>
<tr>
<td width="10" bgcolor="#cccccc"/>
<td width="140" bgcolor="#cccccc">
<a href="#Native server configuration" class="menu">Native server configuration</a>
</td>
</tr>
<tr height="1"/>
<tr>
<td width="10" bgcolor="#cccccc"/>
<td width="140" bgcolor="#cccccc">
<a href="#Config generators" class="menu">Config generators</a>
</td>
</tr>
<tr height="1"/>
<tr>
<td colspan="2" width="150" bgcolor="#cccccc">
<nobr>
<a class="menu" href="../jk2/configwebcom.html">Components</a>
</nobr>
</td>
</tr>
<tr height="2"/>
<tr>
<td colspan="2" width="150" bgcolor="#cccccc">
<nobr>
<a class="menu" href="../jk2/configwebex.html">Examples</a>
</nobr>
</td>
</tr>
<tr height="2"/>
<tr height="6"/>
<tr height="6">
<td colspan="2" width="150" bgcolor="#d0d0d0">Installation</td>
</tr>
<tr>
<td colspan="2" width="150" bgcolor="#cccccc">
<nobr>
<a class="menu" href="../jk2/installhowto.html">Installation of jk2 in the Web Server</a>
</nobr>
</td>
</tr>
<tr height="2"/>
<tr height="6"/>
<tr height="6">
<td colspan="2" width="150" bgcolor="#d0d0d0">Howto</td>
</tr>
<tr>
<td colspan="2" width="150" bgcolor="#cccccc">
<nobr>
<a class="menu" href="../jk2/confighowto.html">Quick Start JK2 Configuration Guide</a>
</nobr>
</td>
</tr>
<tr height="2"/>
<tr>
<td colspan="2" width="150" bgcolor="#cccccc">
<nobr>
<a class="menu" href="../jk2/vhosthowto.html">Apache 2.0.43 - Tomcat 4.1.12 - jk2 - virtual host HOWTO</a>
</nobr>
</td>
</tr>
<tr height="2"/>
<tr height="6"/>
</table>
</td>
<td class="body" valign="top" width="*" bgcolor="#ffffff">
<a name="Intro">
<table width="100%" cellpadding="0" cellspacing="0" border="0">
<tr>
<td align="left" valign="top" class="section" bgcolor="#525D76">
<img border="0" vspace="0" hspace="0" align="left" valign="top" src="../images/corner.gif"/>Intro</td>
</tr>
</table>
</a>
<p class="section">Jk2 uses an architecture and configuration mechanism modeled after JMX. It consist of
"jk_bean" components, with a registry and API that attempts to mirror JMX.</p>
<p class="section">As in JMX, multiple config formats and stores are possible. The default is a neutral .INI-style
file, and Apache2 also supports configuration in httpd.conf. Other formats and repositories can be
easily implemented, but the general concept is the same.</p>
<p class="section">Each component has a name, a type and a set of attributes. Reasonable defaults are provided, and
some components are created automatically using the defaults if not explicitely configured.
You need to specify the config only where you want to override the defaults.</p>
<br/>
<a name="Config file format">
<table width="100%" cellpadding="0" cellspacing="0" border="0">
<tr>
<td align="left" valign="top" class="section" bgcolor="#525D76">
<img border="0" vspace="0" hspace="0" align="left" valign="top" src="../images/corner.gif"/>Config file format</td>
</tr>
</table>
</a>
<p class="section">The config file is named "workers2.properties", located by default in ${serverRoot}/conf,
where ${serverRoot} is the web server dir, like /usr/local/apache. It is possible to modify the location
of the file using server-specific directives.</p>
<p class="section">Settings are grouped in sections - one section for each object. The section head is the component
name, and must include the type and local name of the component, separated by ":". Inside each section
you must define the attributes of the component. The attribute name is a simple string, with no '.' or
special characters. The value is a string - no quoting is currently supported. It should be noted that
the component name is processed to compute default for the component attributes - for example
[channel.socket:localhost:8009] name will create a socket channel object with host=locahost and
port=8009. You don't need to provide this information twice. It is highly recommended to use
this naming scheme for consistency, even if you could use any name and then specify the properties
explicitely.</p>
<p class="section">The general syntax is:
<pre class="section">
[TYPE:NAME]
PROPERTY=VALUE
</pre>
</p>
<p class="section">It is also possible to use an alternate format, mostly for backward compatibility:
<pre class="section">
TYPE:NAME.PROPERTY=VALUE
</pre>
</p>
<br/>
<a name="Runtime reconfiguration">
<table width="100%" cellpadding="0" cellspacing="0" border="0">
<tr>
<td align="left" valign="top" class="section" bgcolor="#525D76">
<img border="0" vspace="0" hspace="0" align="left" valign="top" src="../images/corner.gif"/>Runtime reconfiguration</td>
</tr>
</table>
</a>
<p class="section">The main purpose of this reconfiguration is to implement "graceful" shutdown and
to allow adding or disabling of more tomcat instances in the load balancing mode</p>
<p class="section">Each component has a "ver" attribute - it is initially set to the value in the
config file or 0 if this is not specified. Every time the config file is read, jk will
check the version number in the component, and reconfigure if it is different.</p>
<p class="section">If Jk2 reloads the config file, it detect modified components using "ver" and reconfigures them.
To avoid performance hits, the check is done only when the /jkstatus page is accessed - or
if the scoreboard signature changes. An access to /jkstatus will check the timestamp of the
config file and if a change is detected it'll reload the config file. In apache and multiprocess
servers - this can only affect the current process, so /jkstatus will increment the scoreboard mark.
All other processes in a multiprocess server will see the modified byte and reload before serving the next request.</p>
<p class="section">Changing the file and forcing a reload is currently the easiest way to reconfigure. A JMX proxy
is in experimental stage and will allow the user to perform all configuration in JMX - using same
tools that he uses for tomcat, and completely transparent. The internal implementation will also
save the file - it is the cleanest way to sync multi-process web servers.
</p>
<br/>
<a name="Changing 'graceful' stop state">
<table width="100%" cellpadding="0" cellspacing="0" border="0">
<tr>
<td align="left" valign="top" class="section" bgcolor="#525D76">
<img border="0" vspace="0" hspace="0" align="left" valign="top" src="../images/corner.gif"/>Changing 'graceful' stop state</td>
</tr>
</table>
</a>
<p class="section">Each tomcat instance corresponds to a "channel" jk component that defines the host and port. The
channel can be set in a special "graceful" mode or back to active by setting the corresponding attribute.
This mode disables sending any new requests to that tomcat instance - only requests for
an existing session are permitted.</p>
<p class="section">When you want to disable a tomcat instance, you should first set the channel in
"graceful" mode, then wait until all existing sessions expire or are completed. If the sessions
are serializable and tomcat is configured in clustering mode - you can also migrate the
sessions to a different instance.</p>
<p class="section">1. Edit workers2.properties. Find the channel. Change "graceful" to "1" to disable or "0"
to reactivate". Increment "ver".<br/>
2. Access /jkstatus page. You should see the value changed in the channel and worker info.</p>
<p class="section">When a worker is in this state, no new requests will be sent to that worker - only requests that have an
explicit session ID for that particular worker. It is recommended you wait for all sessions to expire
before stopping the tomcat instance, or you use a session migration mechanism.
</p>
<br/>
<a name="Adding a new tomcat instance">
<table width="100%" cellpadding="0" cellspacing="0" border="0">
<tr>
<td align="left" valign="top" class="section" bgcolor="#525D76">
<img border="0" vspace="0" hspace="0" align="left" valign="top" src="../images/corner.gif"/>Adding a new tomcat instance</td>
</tr>
</table>
</a>
<p class="section">1. Edit workers2.properties. Add a new channel. If you want, also add a worker.ajp entry -
but this is optional</p>
<p class="section">2. Access the /jkstatus page or triger reloading with a program. You should see the
new channel displayed in the status page, and requests should start going to the new tomcat instance</p>
<br/>
<a name="Advanced: reconfiguration using JMX">
<table width="100%" cellpadding="0" cellspacing="0" border="0">
<tr>
<td align="left" valign="top" class="section" bgcolor="#525D76">
<img border="0" vspace="0" hspace="0" align="left" valign="top" src="../images/corner.gif"/>Advanced: reconfiguration using JMX</td>
</tr>
</table>
</a>
<p class="section">This is very experimental. On tomcat side, you must enable the JMX proxy. This is done by
setting "modjk.webServerHost" and "modjk.webServerPort" in jk2.properties to point to the web server
port that contains /jkstatus. ( recent versions of jk and mod_jk are required ). You can also add mx4j-tools.jar to
server/lib and set "mx.port=PORT" in jk2.properties to enable the console, or use your favorite JMX
console or tools.</p>
<p class="section">When tomcat starts up, it'll connect to the web server and create JMX mbean proxies for each
mod_jk component. The data will be refreshed when JMX operations are performed - a set or invoke will
allways refresh, while get will use cached values and refresh only periodically ( 5 sec default ).</p>
<p class="section">Every time a change is made, the config file will be written ( for persistence and to allow other
processes to get the same change ). The scoreboard will be changed, and then all other server processes will
act just like in the case of a file change. All comments will be lost - you should use "info" attributes
in components and set "disabled" to 1 if you want to temporary disable some components.</p>
<br/>
<a name="Native server configuration">
<table width="100%" cellpadding="0" cellspacing="0" border="0">
<tr>
<td align="left" valign="top" class="section" bgcolor="#525D76">
<img border="0" vspace="0" hspace="0" align="left" valign="top" src="../images/corner.gif"/>Native server configuration</td>
</tr>
</table>
</a>
<p class="section">For Apache2 you can also use httpd.conf instead or in addition to workers2.properties.
Other servers may support similar configuration - for example using registry or their native
formats. This configuration mode is less tested - but provides some
unique advantages (and disadvantages )</p>
<p class="section">I'll describe the apache2 specifics, since this is the only one implemented. We use 2 directives - JkSet
is a top-level directive is used to set global config options, and JkUriSet is used to set options
for Location sections</p>
<p class="section">JkSet takes 2 parameters, the property name ( including component name ) and the value. (Note:
probably we should change it to 3 params, and separate the component name from property )</p>
<p class="section">Each Location that has a JkUriSet will automatically create a jk2 [uri] object,
using the Location path and the vhost. All JkUriSet directives will set attributes
in this [uri] object, exactly like properties in a ini file section</p>
<p class="section">You can mix workers2.properties and JkUriSet - for example workers and global options
can be set in worker2.properties, but all uri properties in httpd.conf. Some people
might preffer to have only one config file and use httpd.conf for all configuration.</p>
<p class="section">The biggest benefit is that Apache2 mapping is used instead of jk2 to detect the
requests that need to be sent to tomcat. Apache2 has been optimized and tuned to
server huge number of servers and uris - if you have only few the diference may be
hard to notice. Some people preffer to use the httpd.conf format and some tools
could be better used in this mode.</p>
<p class="section">One major problem is that reconfiguration is not supported if httpd.conf is used.
You can still enable/disable/add workers if you use workers2.properties, and
you could add or change uri properties in that file. </p>
<br/>
<a name="Config generators">
<table width="100%" cellpadding="0" cellspacing="0" border="0">
<tr>
<td align="left" valign="top" class="section" bgcolor="#525D76">
<img border="0" vspace="0" hspace="0" align="left" valign="top" src="../images/corner.gif"/>Config generators</td>
</tr>
</table>
</a>
<p class="section">There is work in progress to support automatic generation of the config file. The code is
included in org.apache.jk.config and consist of a number of ant tasks ( that work from CLI as well)
that process web.xml files and generate worker2.properties or server-specific config files</p>
<br/>
</td>
</tr>
</table>
</body>
</html>
|
