You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by rj...@apache.org on 2006/11/26 17:36:48 UTC
svn commit: r479378 - in /tomcat/connectors/trunk/jk/xdocs: changelog.xml
config/project.xml config/uriworkermap.xml project.xml
Author: rjung
Date: Sun Nov 26 08:36:47 2006
New Revision: 479378
URL: http://svn.apache.org/viewvc?view=rev&rev=479378
Log:
New doc page for uriworkermap.
Added:
tomcat/connectors/trunk/jk/xdocs/config/uriworkermap.xml (with props)
Modified:
tomcat/connectors/trunk/jk/xdocs/changelog.xml
tomcat/connectors/trunk/jk/xdocs/config/project.xml
tomcat/connectors/trunk/jk/xdocs/project.xml
Modified: tomcat/connectors/trunk/jk/xdocs/changelog.xml
URL: http://svn.apache.org/viewvc/tomcat/connectors/trunk/jk/xdocs/changelog.xml?view=diff&rev=479378&r1=479377&r2=479378
==============================================================================
--- tomcat/connectors/trunk/jk/xdocs/changelog.xml (original)
+++ tomcat/connectors/trunk/jk/xdocs/changelog.xml Sun Nov 26 08:36:47 2006
@@ -27,6 +27,9 @@
<subsection name="Native">
<changelog>
<update>
+ Docs: New page with description of uriworkermap. (rjung)
+ </update>
+ <update>
Docs: Added short description of max_packet_size to worker
reference. (rjung)
</update>
Modified: tomcat/connectors/trunk/jk/xdocs/config/project.xml
URL: http://svn.apache.org/viewvc/tomcat/connectors/trunk/jk/xdocs/config/project.xml?view=diff&rev=479378&r1=479377&r2=479378
==============================================================================
--- tomcat/connectors/trunk/jk/xdocs/config/project.xml (original)
+++ tomcat/connectors/trunk/jk/xdocs/config/project.xml Sun Nov 26 08:36:47 2006
@@ -14,6 +14,7 @@
</menu>
<menu name="Configuration">
<item name="Workers.properties" href="workers.html"/>
+ <item name="Uriworkermap.properties" href="uriworkermap.html"/>
<item name="Apache" href="apache.html"/>
<item name="IIS" href="iis.html"/>
</menu>
Added: tomcat/connectors/trunk/jk/xdocs/config/uriworkermap.xml
URL: http://svn.apache.org/viewvc/tomcat/connectors/trunk/jk/xdocs/config/uriworkermap.xml?view=auto&rev=479378
==============================================================================
--- tomcat/connectors/trunk/jk/xdocs/config/uriworkermap.xml (added)
+++ tomcat/connectors/trunk/jk/xdocs/config/uriworkermap.xml Sun Nov 26 08:36:47 2006
@@ -0,0 +1,247 @@
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document url="uriworkermap.html">
+
+ &project;
+
+ <properties>
+ <author email="rjung@apache.org">Rainer Jung</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>
+Exact and wildchar matches, shortcuts to map a directory and all including content.
+</li>
+<li>
+Exclusion rules, disabling of rules an defined preferences behaviour.
+</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 every 60 seconds for changes.
+New versions are automatically reloaded without web server restarts.
+</li>
+<li>
+Integration with the status worker.
+</li>
+<li>
+Support for comments in the rule file.
+</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 Preferences">
+<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.
+An 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>
+</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:
+An rule gets disabled, if it is suffixed with '-':
+<source>
+ # We are not in maintenance.
+ # The maintenance rule got defined someahere else.
+ -/*=maintenance
+</source>
+Exclusion rules can get disabled as well, then the rule starts with '-!'.
+</p>
+</subsection>
+
+<subsection name="Mapping preferences">
+<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="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:
+<source>
+ # To be completed
+</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 inhertis the JkMountFile from 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 60 seconds ago.
+</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 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>
+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).
+</p>
+</section>
+
+</body>
+</document>
Propchange: tomcat/connectors/trunk/jk/xdocs/config/uriworkermap.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: tomcat/connectors/trunk/jk/xdocs/config/uriworkermap.xml
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Modified: tomcat/connectors/trunk/jk/xdocs/project.xml
URL: http://svn.apache.org/viewvc/tomcat/connectors/trunk/jk/xdocs/project.xml?view=diff&rev=479378&r1=479377&r2=479378
==============================================================================
--- tomcat/connectors/trunk/jk/xdocs/project.xml (original)
+++ tomcat/connectors/trunk/jk/xdocs/project.xml Sun Nov 26 08:36:47 2006
@@ -14,6 +14,7 @@
</menu>
<menu name="Configuration">
<item name="Workers.properties" href="config/workers.html"/>
+ <item name="Uriworkermap.properties" href="config/uriworkermap.html"/>
<item name="Apache" href="config/apache.html"/>
<item name="IIS" href="config/iis.html"/>
</menu>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org