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
|
<?xml version="1.0"?>
<!--
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="uriworkermap.html">
&project;
<properties>
<author email="rjung@apache.org">Rainer Jung</author>
<author email="mturk@apache.org">Mladen Turk</author>
<title>uriworkermap.properties configuration</title>
</properties>
<body>
<section name="Introduction">
<br/>
<p>
The forwarding of requests from the web server to tomcat gets configured by defining mapping rules.
Such a rule maps requests to workers. The request part of the map is described by a URI pattern,
the worker by it's worker name.
</p>
<p>
The so-called <b>uriworkermap</b> file is a mechanism of defining rules,
which works for all web servers. There exist also other web server specific configuration
options for defining rules, which will be mostly discussed on the reference pages for
configuring tomcat connectors for the individual web servers.
</p>
<p>
The name of the file is usually uriworkermap.properties,
although this is configurable in the web server.
Please consult the web server specific documentation pages on
how to enable the uriworkermap file.
</p>
<p>
The main features supported by the uriworkermap file are
<ul>
<li>
Support for comments in the rule file.
</li>
<li>
Exact and wildchar matches, shortcuts to map a directory and all including content.
</li>
<li>
Exclusion rules, disabling of rules and rule priorities.
</li>
<li>
Rule extensions, modifying worker behaviour per rule.
</li>
<li>
Virtual host integration: uri mapping rules can be expressed per virtual host.
The details are web server specific though.
</li>
<li>
Dynamic reloading: The file gets checked periodically for changes.
New versions are automatically reloaded without web server restarts.
</li>
<li>
Integration with the status worker.
</li>
</ul>
The following sections describe these aspects in more detail.
</p>
</section>
<section name="Syntax">
<br/>
<subsection name="Line format">
<br/>
<p>
The file has a line based format. There are no continuation characters,
so each rule needs to be defined on a single line. Each rule is a pair consisting
of a URI pattern and a worker name, combined by an equals sign '=':
<source>
/myapp=myworker
</source>
The URI pattern is case sensitive.
</p>
</subsection>
<subsection name="Comments, white space">
<br/>
<p>
All text after and including the character '#' gets ignored and can be used for comments.
Leading and trailing white space gets trimmed around the URI pattern and also around the worker name.
The following definitions are all equivalent:
<source>
# This is a white space example
/myapp=myworker
/myapp=myworker
/myapp = myworker
</source>
</p>
</subsection>
<subsection name="URI patterns">
<br/>
<p>
Inside the URI pattern three special characters can be used, '*', '?' and '|'.
The character '*' is a wildchar that matches any number of arbitrary characters
in the URI, '?' matches exactly one character.
Each URI pattern has to start with the character '/', or with '*' or with '?',
optionally prefixed by any combination of the modifiers '!' and '-' (see next section).
<source>
# Mapping the URI /myapp1 and everything under /myapp1/:
/myapp1=myworker-a
/myapp1/*=myworker-a
# Mapping all URI which end with a common suffix:
*.jsp=myworker
*.do=myworker
</source>
Since the first case of mapping a certain location and everything inside
it is very common, the character '|' gives a handy shortcut:
<source>
# Mapping the URI /myapp1 and everything under /myapp1/:
/myapp1|/*=myworker-a
</source>
The pattern 'X|Y' is exactly equivalent to the two maps 'X' and 'XY'.
</p>
</subsection>
</section>
<section name="Exclusion, Disabling and Priorities">
<br/>
<subsection name="Exclusions and rule disabling">
<br/>
<p>
Exclusion rules allows to define exclusions from URI rules, which would forward
requests to tomcat. If the exclusion rule matches, the request will not be forwarded.
This is usually used to serve static content by the web server.
A rule is an exclusion rule, if it is suffixed with '!':
<source>
# Mapping the URI /myapp and everything under /myapp/:
/myapp|/*=myworker
# Exclude the subdirectory static:
!/myapp/static|/*=myworker
# Exclude some suffixes:
!*.html=myworker
</source>
An exclusion rule overrides a normal mapping rule only, if the worker names in the
normal rule and in the exclusion rule are the same. Starting with version 1.2.26 of JK
you can apply an exclusion rule to any worker, by using the star character '*' as
the worker name in the exclusion rule.
More complex patterns in exclusion worker names are not allowed.
<source>
# Mapping the webapps /myapp1 and /myapp2:
/myapp1|/*=myworker1
/myapp2|/*=myworker2
# Exclude the all subdirectories static for all workers:
!/*/static|/*=*
# Exclude some suffixes for all workers:
!*.html=*
</source>
</p>
<p>
Rule disabling comes into play, if your web server merges rules from various sources,
and you want to disable any rule defined previously. Since the uriworkermap file gets
reloaded dynamically, you can use this to temporarily disable request forwarding:
A rule gets disabled, if it is suffixed with '-':
<source>
# We are not in maintenance.
# The maintenance rule got defined somewhere else.
-/*=maintenance
</source>
Exclusion rules can get disabled as well, then the rule starts with '-!'.
</p>
</subsection>
<subsection name="Mapping priorities">
<br/>
<p>
The most restrictive URI pattern is applied first. More precisely the URI patterns are
sorted by the number of '/' characters in the pattern (highest number first), and
rules with equal numbers are sorted by their string length (longest first).
</p>
<p>
If both distinctions still do not suffice, then the defining source of the rule is considered.
Rules defined in uriworkermap.properties come first, before rules defined by JkMount (Apache)
and inside workers.properties using the mount attribute.
</p>
<p>
All disabled rules are ignored. Exclusion rules are applied after all normal rules
have been applied.
</p>
<p>
There is no defined behaviour, for the following configuration conflict:
using literally the same URI pattern in the same defining source but with
different worker targets.
</p>
</subsection>
</section>
<section name="Rule extensions">
<br/>
<p>
Rule extensions were added in version 1.2.27 and are not available in earlier versions.
</p>
<subsection name="Syntax">
<br/>
<p>
Rule extensions are additional attributes, that can be attached to any rule.
They are added at the end of the rule, each extension separated by a semicolon:
<source>
# This is an extension example,
# setting a reply_timeout of 1 minute
# only for this mapping.
/myapp=myworker;reply_timeout=60000
#
# This is an example using multiple extensions
/myapp=myloadbalancer;reply_timeout=60000;stopped=member1
</source>
Attributes set via rule extensions always overwrite conflicting
configurations in the worker definition file.
</p>
</subsection>
<subsection name="Extension reply_timeout">
<br/>
<p>
The extension <code>reply_timeout</code> sets a reply timeout for a single mapping rule.
<source>
# Setting a reply_timeout of 1 minute
# only for this mapping.
/myapp=myworker;reply_timeout=60000
</source>
It overrides any <code>reply_timeout</code> defined for the worker. The extension allows
to set a reasonable default reply timeout to the worker, and a more relaxed
reply timeout to URLs, which are known to start time intensive tasks.
For a general description of reply timeouts see the
<a href="../generic_howto/timeouts.html#Reply Timeout">timeouts</a> documentation.
</p>
</subsection>
<subsection name="Extension sticky_ignore">
<br/>
<p>
The extension <code>sticky_ignore</code> will disable session stickyness for a single
mapping rule.
<source>
# Disable session stickyness
# only for this mapping.
/myapp/loginform.jsp=myworker;sticky_ignore=1
</source>
This extension can be useful to optimize load balancing when using
cookie based session stickyness. In this case, as long as she keeps
her browser open, any request by a user who started a session will
be send to the same Tomcat instance, even if he left the part of
the application which uses the session. You can for instance
set this environment variable when a user requests a login form
to ensure, that this initial session request is balanced non-sticky.
</p>
<p>
This extension is available since version 1.2.33.
</p>
</subsection>
<subsection name="Extension stateless">
<br/>
<p>
The extension <code>stateless</code> is only useful when using session based
load balancing. In this case normally any request which does not come with
a session id counts as a new session. If you mark a mapping rule with
the <code>stateless</code> extension, then the requests matching the mapping
rule will not count as a new session, even if they do not come with a session
id.
<source>
# Don't let static content trash our session balancing
/myapp/static/*=myworker;stateless=1
</source>
This extension is available since version 1.2.33.
</p>
</subsection>
<subsection name="Extensions active/disabled/stopped">
<br/>
<p>
The extensions <code>active</code>, <code>disabled</code>, and <code>stopped</code>
can be used in a load balancer mapping rule to set selected members
of the load balancer into a special activation state.
<source>
# Stop forwarding only for member1 of loadbalancer
/myapp=myloadbalancer;stopped=member1
</source>
Multiple members must be separated by commas or white space:
<source>
# Stop forwarding for member01 and member02 of loadbalancer
# Disable forwarding for member21 and member22 of loadbalancer
/myapp=myloadbalancer;stopped=member01,member02;disabled=member21,member22
</source>
For the precise meaning of the activation states see the description of
<a href="../reference/workers.html#Advanced Worker Directives">activation</a>.
</p>
</subsection>
<subsection name="Extension fail_on_status">
<br/>
<p>
The extension <code>fail_on_status</code> can be used in any rule:
<source>
# Send 503 instead of 404 and 500,
# and if we get a 503 also set the worker to error
/myapp=myworker;fail_on_status=-404,-500,503
</source>
Multiple status codes must be separated by commas.
For the precise meaning of the attribute see the description of
<a href="../reference/workers.html#Advanced Worker Directives">fail_on_status</a>.
</p>
</subsection>
<subsection name="Extension use_server_errors">
<br/>
<p>
The extension <code>use_server_errors</code> allows to let the web server
send an error page, instead of the backend (e.g. Tomcat) error page.
This is useful, if one wants to send customized error pages, but those are
not part of all web applications. They can then be put onto the web server.
</p>
<p>
The value of <code>use_server_errors</code> is a positive number.
Any request send to the backend, that returns with an http status
code bigger or equal to <code>use_server_errors</code>, will
be answered to the client with the error page of the web server
for this status code.
<source>
# Use web server error page for all errors
/myapp=myworker;use_server_errors=400
# Use web server error page only for technical errors
/myotherapp=myworker;use_server_errors=500
</source>
</p>
</subsection>
<subsection name="Extensions session_cookie and session_path">
<br/>
<p>
The extensions <code>session_cookie</code> and <code>session_path</code>
allows to define the load balancer worker attributes of the same name
per mount.
</p>
</subsection>
</section>
<section name="Virtual host integration">
<br/>
<subsection name="IIS">
<br/>
<p>
When using IIS you can restrict individual rules to special virtual hosts
by prefixing the URI pattern with the virtual host information.
The rules is that the url must be prefixed with the host name.
<source>
# Use www.foo.org as virtual host
/www.foo.org/myapp/*=myworker
# Use www.bar.org as virtual host
/www.bar.org/myapp/*=myworker
# Normal mapping
/mysecondapp/*=myworker
</source>
</p>
<p>
Note that /mysecondapp/* will be mapped to all virtual hosts present.
In case one needs to prevent the mappings to some particular virtual host then
the exclusion rule must be used
<source>
# Make sure the myapp is accessible by all virtual hosts
/myapp/*=myworker
# Disable mapping myapp for www.foo.org virtual host
!/www.foo.org/myapp/*=myworker
</source>
</p>
</subsection>
<subsection name="Apache httpd">
<br/>
<p>
For Apache you can define individual uriworkermap files per virtual host.
The directive JkMountFile can be used in the main server and in each virtual host.
If a virtual host does not use JkMountfile, but JkMountCopy is set to 'On',
then it inherits the JkMountFile from the main server. If you want all vhost to inherit
mounts from the main server, you can set JkMountCopy to 'All' in the main server.
</p>
</subsection>
</section>
<section name="Dynamic reloading">
<br/>
<p>
When a request is being processed, tomcat connectors check the file modification time
of the uriworkermap file. To keep the performance penalty low, this happens only,
if the last check happened at least n seconds ago.
</p>
<p>
For Apache you can configure the interval "n" using the directive JkMountFileReload,
for IIS you would use the attribute worker_mount_reload.
The default value is 60 seconds. A value of "0" turns off the reloading.
</p>
<p>
If the file changed, it gets reloaded completely. If there exist rules coming
from other sources than the uriworkermap file (e.g. the workers.properties mount
attribute or JkMount with Apache httpd), the new uriworkermap file gets dynamically
merged with these ones exactly like when you do a web server restart.
</p>
<p>
Until version 1.2.19 reloading behaved slightly differently: it continuously added
the full contents of the uriworkermap file to the rule mapping. The merging rules
were, that duplicated got eliminated and old rules could be disabled, by defining the
rule as disabled in the new file. Rules never got deleted.
</p>
</section>
<section name="Status worker integration">
<br/>
<p>
The configuration view of the status worker also shows the various mapping rules.
After each worker's configuration, the rules are listed, that forward to this worker.
The list contains four columns:
<ul>
<li>
the name of the virtual server
</li>
<li>
the URI pattern, prefixed with '-' for a disabled pattern and '!' for an exclusion pattern
</li>
<li>
the type of the rule: Exact or Wildchar
</li>
<li>
and the source of the rule definition: 'worker definition' for the workers.properties file (mount attribute),
'JkMount' for Apache httpd JkMount and it's relatives and finally 'uriworkermap' for the uriworkermap file.
</li>
</ul>
</p>
<p>
<b>Note: </b>The following restriction has been removed starting with version 1.2.26.
<br/>
For Apache httpd, there is an important subtlety: the request going to the status worker
gets executed in the context of some server (main or virtual). The status worker will only show the
mapping rules, that are defined for this server (main or virtual).
<br/>
Until version 1.2.25 the list contained three columns:
<ul>
<li>
the type of the rule: Exact or Wildchar, eventually prefixed with Disabled or Unmount (for exclusion rules)
</li>
<li>
the URI pattern
</li>
<li>
and the source of the rule definition: 'worker definition' for the workers.properties file (mount attribute),
'JkMount' for Apache httpd JkMount and it's relatives and finally 'uriworkermap' for the uriworkermap file.
</li>
</ul>
</p>
</section>
</body>
</document>
|
