| <?xml version="1.0"?> |
| <!DOCTYPE document [ |
| <!ENTITY project SYSTEM "project.xml"> |
| ]> |
| <document url="apache.html"> |
| |
| &project; |
| |
| <properties> |
| <author email="mturk@apache.org">Mladen Turk</author> |
| <title>Configuring Apache</title> |
| </properties> |
| |
| <body> |
| |
| <section name="Configuration Directives"> |
| <p> |
| Here are the all directives supported by Apache: |
| </p> |
| <attributes name="Directive"> |
| <attribute name="JkWorkersFile" required="false"><p> |
| The name of a worker file for the Tomcat servlet containers |
| </p></attribute> |
| <attribute name="JkWorkerProperty" required="false"><p> |
| Enables setting workers.properties inside Apache configuration file. |
| This directive is available in jk1.2.7 version and later. |
| </p></attribute> |
| <attribute name="JkMount" required="false"><p> |
| A mount point from a context to a Tomcat worker |
| </p></attribute> |
| <attribute name="JkMountFile" required="false"><p> |
| File containing multiple mappings from a context to a Tomcat worker |
| </p></attribute> |
| <attribute name="JkUnMount" required="false"><p> |
| A no mount point from a context to a Tomcat worker |
| This directive is available in jk1.2.7 version and later. |
| </p></attribute> |
| <attribute name="JkMountCopy" required="false"><p> |
| Should the base server mounts be copied to the virtual server. |
| </p></attribute> |
| <attribute name="JkLogFile" required="false"><p> |
| Full or server relative path to the Tomcat Connector module log file |
| </p></attribute> |
| <attribute name="JkLogLevel" required="false"><p> |
| The Tomcat Connector module log level, can be debug, info, warn |
| error or trace |
| </p></attribute> |
| <attribute name="JkLogStampFormat" required="false"><p> |
| The Tomcat Connector module <b>date</b> log format, follow strftime syntax |
| </p></attribute> |
| <attribute name="JkRequestLogFormat" required="false"><p> |
| Request log format string. See detailed description below. |
| </p></attribute> |
| <attribute name="JkAutoAlias" required="false"><p> |
| Automatically Alias webapp context directories into the Apache |
| document space. |
| </p></attribute> |
| <attribute name="JkHTTPSIndicator" required="false"><p> |
| Name of the Apache environment variable that contains SSL indication |
| </p></attribute> |
| <attribute name="JkCERTSIndicator" required="false"><p> |
| Name of the Apache environment variable that contains SSL client certificates |
| </p></attribute> |
| <attribute name="JkCIPHERIndicator" required="false"><p> |
| Name of the Apache environment variable that contains SSL client cipher |
| </p></attribute> |
| <attribute name="JkSESSIONIndicator" required="false"><p> |
| Name of the Apache environment variable that contains SSL session |
| </p></attribute> |
| <attribute name="JkKEYSIZEIndicator" required="false"><p> |
| Name of the Apache environment variable that contains SSL key size in use |
| </p></attribute> |
| <attribute name="JkExtractSSL" required="false"><p> |
| Turns on SSL processing and information gathering by mod_jk |
| </p></attribute> |
| <attribute name="JkOptions" required="false"><p> |
| Set one of more options to configure the mod_jk module. See below for |
| details about this directive |
| </p></attribute> |
| <attribute name="JkEnvVar" required="false"><p> |
| Adds a name of environment variable that should be sent to servlet-engine |
| </p></attribute> |
| |
| <attribute name="JkShmFile" required="false"><p> |
| Shared memory file name. Used only on unix platforms. |
| </p></attribute> |
| <attribute name="JkShmSize" required="false"><p> |
| Size of the shared memory file name. Default is 64 k. |
| </p></attribute> |
| |
| </attributes> |
| </section> |
| |
| <section name="Configuration Directives Types"> |
| <p> |
| We'll discuss here the mod_jk directive types. |
| </p> |
| |
| <subsection name="Define workers"> |
| <p> |
| <b>JkWorkersFile</b> specify the location where mod_jk will find the workers definitions. |
| Take a look at <a href="workers.html">Workers documentation</a> for detailed description. |
| |
| <source> |
| |
| JkWorkersFile /etc/httpd/conf/workers.properties |
| </source> |
| |
| <br/> |
| <br/> |
| </p> |
| </subsection> |
| |
| <subsection name="Logging"> |
| <p> |
| <b>JkLogFile</b> specify the location where mod_jk is going to place its log file. |
| </p> |
| |
| <source> |
| JkLogFile /var/log/httpd/mod_jk.log |
| </source> |
| |
| <p> |
| Since JK 1.2.3 for Apache 2.0 and JK 1.2.16 for Apache 1.3 this can also |
| be used for piped logging: |
| </p> |
| |
| <source> |
| JkLogFile "|/usr/bin/rotatelogs /var/log/httpd/mod_jk.log 86400" |
| </source> |
| |
| <p> |
| <b>JkLogLevel</b> |
| set the log level between : |
| </p> |
| |
| <ul> |
| <li> |
| <b>info</b> log will contain standard mod_jk activity (default). |
| </li> |
| <li> |
| <b>warn</b> log will contain non fatal error reports. |
| </li> |
| <li> |
| <b>error</b> log will contain also error reports. |
| </li> |
| <li> |
| <b>debug</b> log will contain all information on mod_jk activity |
| </li> |
| <li> |
| <b>trace</b> log will contain all tracing information on mod_jk activity |
| </li> |
| </ul> |
| |
| <source> |
| JkLogLevel info |
| </source> |
| |
| <p> |
| <code>info</code> should be your default selection for normal operations. |
| <br/> |
| <br/> |
| </p> |
| |
| <p> |
| <b>JkLogStampFormat</b> will configure the date/time format found on mod_jk log file. |
| Using the strftime() format string it's set by<br /> |
| default to <b>"[%a %b %d %H:%M:%S %Y]"</b> |
| </p> |
| |
| <source> |
| JkLogStampFormat "[%a %b %d %H:%M:%S %Y] " |
| </source> |
| |
| <p> |
| <br/> |
| <br/> |
| </p> |
| |
| <p> |
| <b>JkRequestLogFormat</b> will configure the format of mod_jk individual request logging. |
| Request logging is configured and enabled on a per virtual host basis. |
| To enable request logging for a virtual host just add a JkRequestLogFormat config. |
| The syntax of the format string is similar to the Apache LogFormat command, |
| here is a list of the available request log format options: |
| </p> |
| |
| <p> |
| <attributes name="Options"> |
| <attribute name="%b" required="false">Bytes sent, excluding HTTP headers (CLF format)</attribute> |
| <attribute name="%B" required="false">Bytes sent, excluding HTTP headers</attribute> |
| <attribute name="%H" required="false">The request protocol</attribute> |
| <attribute name="%m" required="false">The request method</attribute> |
| <attribute name="%p" required="false">The canonical Port of the server serving the request</attribute> |
| <attribute name="%q" required="false">The query string (prepended with a ? if a query string exists, otherwise an empty string)</attribute> |
| <attribute name="%r" required="false">First line of request</attribute> |
| <attribute name="%s" required="false">Request HTTP status code</attribute> |
| <attribute name="%T" required="false">Request duration, elapsed time to handle request in seconds '.' micro seconds</attribute> |
| <attribute name="%U" required="false">The URL path requested, not including any query string.</attribute> |
| <attribute name="%v" required="false">The canonical ServerName of the server serving the request</attribute> |
| <attribute name="%V" required="false">The server name according to the UseCanonicalName setting</attribute> |
| <attribute name="%w" required="false">Tomcat worker name</attribute> |
| </attributes> |
| |
| <source> |
| JkRequestLogFormat "%w %V %T" |
| </source> |
| |
| <br/> |
| <br/> |
| </p> |
| |
| </subsection> |
| |
| <subsection name="Forwarding"> |
| <p> |
| The directive JkOptions allow you to set many forwarding options which will enable (+) |
| or disable (-) following option. |
| <br/> |
| <br/> |
| </p> |
| |
| <p> |
| JkOptions <b>ForwardKeySize</b>, you ask mod_jk, when using ajp13, to forward also the SSL Key Size as |
| required by Servlet API 2.3. |
| This flag shouldn't be set when servlet engine is Tomcat 3.2.x (on by default). |
| |
| <source> |
| JkOptions +ForwardKeySize |
| </source> |
| |
| <br/> |
| <br/> |
| </p> |
| |
| <p> |
| JkOptions <b>ForwardURICompat</b>, you told mod_jk to send the URI to Tomcat normally, |
| which is less spec compliant but mod_rewrite compatible, |
| use it for compatibility with Tomcat 3.2.x engines (on by default). |
| |
| <source> |
| JkOptions +ForwardURICompat |
| </source> |
| |
| <br/> |
| <br/> |
| </p> |
| |
| <p> |
| JkOptions <b>ForwardURICompatUnparsed</b>, the forwarded URI |
| is unparsed, it's spec compliant but broke mod_rewrite. |
| |
| <source> |
| JkOptions +ForwardURICompatUnparsed |
| </source> |
| |
| <br/> |
| <br/> |
| </p> |
| |
| <p> |
| JkOptions <b>ForwardURIEscaped</b>, the forwarded URI is escaped and |
| Tomcat (since 3.3 rc2) will do the decoding part. |
| |
| <source> |
| JkOptions +ForwardURIEscaped |
| </source> |
| |
| <br/> |
| <br/> |
| </p> |
| |
| <p> |
| JkOptions <b>ForwardDirectories</b> is used in conjunction with <b>DirectoryIndex</b> |
| directive of Apache web server. As such mod_dir should be available to Apache, |
| statically or dynamically (DSO) |
| <br/> |
| <br/> |
| </p> |
| |
| <p> |
| When DirectoryIndex is configured, Apache will create sub-requests for |
| each of the local-url's specified in the directive, to determine if there is a |
| local file that matches (this is done by stat-ing the file). |
| </p> |
| |
| <p> |
| If ForwardDirectories is set to false (default) and Apache doesn't find any |
| files that match, Apache will serve the content of the directory (if directive |
| Options specifies Indexes for that directory) or a <code>403 Forbidden</code> response (if |
| directive Options doesn't specify Indexes for that directory). |
| </p> |
| |
| <p> |
| If ForwarDirectories is set to true and Apache doesn't find any files that |
| match, the request will be forwarded to Tomcat for resolution. This is used in |
| cases when Apache cannot see the index files on the file system for various |
| reasons: Tomcat is running on a different machine, the JSP file has been |
| precompiled etc. |
| </p> |
| |
| <p>Note that locally visible files will take precedence over the |
| ones visible only to Tomcat (i.e. if Apache can see the file, that's the one |
| that's going to get served). This is important if there is more then one type of |
| file that Tomcat normally serves - for instance Velocity pages and JSP pages. |
| |
| <source> |
| JkOptions +ForwardDirectories |
| </source> |
| <br/> |
| <br/> |
| </p> |
| |
| <p> |
| JkOptions <b>ForwardLocalAddress</b>, you told mod_jk to send the local address, |
| of the Apache web server instead remote client address. This can be used by |
| Tomcat remote address valve for allowing connections only from registered Apache |
| web servers. |
| |
| <source> |
| JkOptions +ForwardLocalAddress |
| </source> |
| |
| <br/> |
| <br/> |
| </p> |
| |
| <p> |
| JkOptions <b>FlushPackets</b>, you told mod_jk to make a flush after each AJP |
| packet received from Tomcat. |
| |
| <source> |
| JkOptions +FlushPackets |
| </source> |
| |
| <br/> |
| <br/> |
| </p> |
| |
| <p> |
| The directive <b>JkEnvVar</b> allow you to forward an environment vars from Apache server to Tomcat engine. |
| |
| <source> |
| JkEnvVar SSL_CLIENT_V_START |
| </source> |
| <br/> |
| <br/> |
| </p> |
| |
| </subsection> |
| |
| <subsection name="Assigning URLs to Tomcat"> |
| <p> |
| If you have created a custom or local version of mod_jk.conf-local as noted above, |
| you can change settings such as the workers or URL prefix. |
| </p> |
| <p> |
| <b>JkMount</b> directive assign specific URLs to Tomcat. |
| In general the structure of a JkMount directive is: |
| </p> |
| |
| <source> |
| JkMount [URL prefix] [Worker name] |
| </source> |
| |
| <source> |
| # send all requests ending in .jsp to worker1 |
| JkMount /*.jsp worker1 |
| # send all requests ending /servlet to worker1 |
| JkMount /*/servlet/ worker1 |
| # send all requests jsp requests to files located in /otherworker will go worker2 |
| JkMount /otherworker/*.jsp worker2 |
| </source> |
| |
| <p> |
| You can use the JkMount directive at the top level or inside <VirtualHost> |
| sections of your httpd.conf file. |
| </p> |
| <p><b>JkUnmount</b> directive acts as an opposite to JkMount and blocks access |
| to a particular URL. The purpose is to be able to filter out the particular content |
| types from mounted context. The following example mounts /servlet/* |
| context, but all .gif files that belongs to that context are not served. |
| </p> |
| <source> |
| # send all requests ending with /servlet to worker1 |
| JkMount /servlet/* worker1 |
| # do not send requests ending with .gif to worker1 |
| JkUnMount /servlet/*.gif worker1 |
| </source> |
| <p> |
| JkUnMount takes precedence over JkMount directives, meaning that the JK |
| will first look for unmount and then for mount directives. The following |
| example will block all .gif files. |
| </p> |
| <source> |
| # do not send requests ending with .gif to worker1 |
| JkUnMount /*.gif worker1 |
| # The .gif files will not be mounted cause JkUnMount takes |
| # precedence over JkMount directive |
| JkMount /servlet/*.gif worker1 |
| </source> |
| |
| <p> |
| <b>JkAutoAlias</b> directive automatically <b>Alias</b> webapp context directories into |
| the Apache document space. It enables Apache to serve a static context while Tomcat |
| serving dynamic context. This directive is used for convenience so that you don't |
| have to put an apache Alias directive for each application directory inside Tomcat's |
| webapp directory. |
| </p> |
| |
| <source> |
| # enter the full path to the tomcat webapps directory |
| JkAutoAlias /opt/tomtact/webapps |
| </source> |
| <p>The following example shows how to serve a dynamic context by |
| Tomcat and static using Apache. The webapps directory has to |
| be accessible by apache.</p> |
| |
| <source> |
| # enter the full path to the tomcat webapps directory |
| JkAutoAlias /opt/tomtact/webapps |
| |
| # Mount 'servlets-examples' directory. It's physical location |
| # is assumed to be in the /opt/tomtact/webapps/servlets-examples |
| # ajp13w is a worker defined in the workers.properties |
| JkMount /servlets-examples/* ajp13w |
| |
| # Unmount desired static content from servlets-examples webapp. |
| # This content will be served by the httpd directly. |
| JkUnMount /servlets-examples/*.gif ajp13w |
| JkUnMount /servlets-examples/*.jpg ajp13w |
| </source> |
| <p>Note that you can have a single JkAutoAlias directive per virtual |
| host inside your httpd.conf |
| </p> |
| <p> |
| <b>JkWorkerProperty</b> is a new directive available from JK 1.2.7 |
| version. It is a convenient method for setting directives that are |
| usually set inside <b>workers.propeties</b>file. The parameter for |
| that directive is raw line from workers.properties file. |
| </p> |
| <source> |
| # Just like workers.properties but exact line is prefixed |
| # with JkWorkerProperty |
| |
| # Minimal jk configuration |
| JkWorkerProperty worker.list=ajp13w |
| JkWorkerProperty worker.ajp13w.type=ajp13 |
| JkWorkerProperty worker.ajp13w.host=localhost |
| JkWorkerProperty worker.ajp13w.port=8009 |
| </source> |
| <p> |
| <b>JkMountFile</b> is a new directive available from JK 1.2.9 |
| version. It is used for dynamic updates of mount points at runtime. |
| When the mount file is changed, JK will reload it's content. |
| </p> |
| <source> |
| # Load mount points |
| |
| JkMountFile conf/uriworkermap.properties |
| </source> |
| <p>If mount point uri starts with minus '-' char the mount point |
| will be disabled. |
| </p> |
| <source> |
| # Sample uriworkermap.properties file |
| |
| /servlets-examples/*=ajp13w |
| # Do not map .jpeg files |
| !/servlets-examples/*.jpeg=ajp13w |
| # Make jsp examples initially disabled |
| -/jsp-examples/*=ajp13w |
| </source> |
| <p>At run time you can change the content of this file. For example |
| removing minus char will enable the uri mapping. You can add any |
| number of new entries at runtime that reflects the newly deployed |
| applications. Apache will reload the file and update the mount |
| points within 60 second interval. |
| </p> |
| |
| </subsection> |
| </section> |
| </body> |
| </document> |