tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cos...@apache.org
Subject cvs commit: jakarta-tomcat-connectors/jk/doc/jk2 config.html jk2.html
Date Fri, 22 Mar 2002 20:49:53 GMT
costin      02/03/22 12:49:53

  Added:       jk/doc/jk2 config.html jk2.html
  Log:
  Added an initial documentation for the new jk2 design and an initial
  documentation for the default config.
  
  PLEASE, REVIEW !
  
  Revision  Changes    Path
  1.1                  jakarta-tomcat-connectors/jk/doc/jk2/config.html
  
  Index: config.html
  ===================================================================
  <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  <html>
  <head>
    <title></title>
      
  </head>
  <body>
           
  <h3>Config options<br>
   </h3>
       <br>
           
  <table cellpadding="2" cellspacing="2" border="1"
   style="text-align: left; width: 100%;">
         <tbody>
           <tr>
             <th valign="top">Property name<br>
             </th>
             <th valign="top">Default<br>
             </th>
             <th valign="top">Description<br>
             </th>
           </tr>
           <tr>
         </tr>
       <tr>
           <td valign="top" colspan="2" style="font-weight: bold;">       logger.file<br>
                    </td>
          <td valign="top">Log jk messages to a file. <br>
   Name: 'logger'<br>
          </td>
         </tr>
      <tr>
         </tr>
          <tr>
             <td valign="top">level<br>
             </td>
             <td valign="top">INFO<br>
             </td>
             <td valign="top">Log level. Supported: ERROR, INFO, DEBUG<br>
             </td>
           </tr>
           <tr>
             <td valign="top">file<br>
             </td>
             <td valign="top">$(server.root)/logs/jk2.log</td>
             <td valign="top">Log file. <br>
       XXX you may be able to change this at runtime, to implement rolling<br>
             </td>
           </tr>
         <tr>
           <td valign="top" colspan="2"><span style="font-weight: bold;">logger.apache2</span><br>
           </td>
         <td valign="top"><br>
         </td>
                       </tr>
        <tr>
          <td valign="top">level<br>
          </td>
          <td valign="top">INFO<br>
          </td>
          <td valign="top">see logger.file<br>
          </td>
        </tr>
        <tr>
          <td valign="top" colspan="2"><span style="font-weight: bold;">channel.socket</span><br>
          </td>
         <td valign="top">A communication transport to a remote Engine<br>
         <span style="font-weight: bold;">Magic: </span>The local part of the

  name will be the Engine name, to use when defining the uri mappings. For
  example channel.socket.local_9009 will automatically define an engine named
  local_9009, and if no other setting is set ajp13/ajp13 will be used for communication.<br>
        <span style="font-weight: bold;">Magic: </span> If no channel is defined
  in the config, a default channel will be constructed with port=8009, engine=DEFAULT,
  worker=ajp13 - named 'channel.socket.DEFAULT<br>
         </td>
        </tr>
        <tr>
          <td valign="top">port<br>
          </td>
          <td valign="top">8009<br>
          </td>
          <td valign="top">Port where tomcat is listening<br>
          </td>
        </tr>
        <tr>
          <td valign="top">host<br>
          </td>
          <td valign="top">localhost<br>
          </td>
          <td valign="top">Remote host<br>
          </td>
        </tr>
        <tr>
          <td valign="top">protocol<br>
          </td>
          <td valign="top">ajp13<br>
          </td>
          <td valign="top">the protocol to be used to forward the requests.
  No other value is supported at this moment.<br>
          </td>
        </tr>
        <tr>
          <td valign="top">api<br>
          </td>
          <td valign="top">ajp13<br>
          </td>
          <td valign="top">API to be used when forwarding the requests. No
  other value is supported at this moment, ajp14 will be used to indicate that
  the Engine supports additional API methods like autoconfig<br>
          </td>
        </tr>
        <tr>
        <td valign="top">secretkey<br>
        </td>
        <td valign="top">NULL<br>
        </td>
        <td valign="top"><span style="font-weight: bold;">Magic:</span>
the
  secret key will be set automatically on the associated worker<br>
        </td>
      </tr>
      <tr>
        <td valign="top">lbfactor<br>
        </td>
        <td valign="top">1<br>
        </td>
        <td valign="top">Load balancing factor to use. At this moment, it'll
  be set on the worker, but in future it<br>
  should be possible to use lb on a channel level.<br>
        </td>
      </tr>
      <tr>
          <td valign="top" colspan="2"><span style="font-weight: bold;">worker.ajp13</span><br>
          <br>
          </td>
                  <td valign="top">The forwarding worker using the ajp13 RPC
  protocol. It supports the basic ajp13 API and may support additional functions/APIs
  in future like ajp14 API<br>
          </td>
        </tr>
        <tr>
          <td valign="top">secretkey<br>
          </td>
          <td valign="top">NULL<br>
          </td>
          <td valign="top">XXX deprecated - set it on channel ( socket needs
  it, jni doesn't, with unix we can use smarter things ).<br>
  Special attribute to be sent with the first request, used to authenticate.
  Supported by Tomcat3.3 and tomcat4.x if the authentication is configured,
  leave it NULL for tomcat3.2<br>
          </td>
        </tr>
        <tr>
          <td valign="top">lbfactor<br>
          </td>
          <td valign="top">1<br>
          </td>
          <td valign="top">XXX deprecated - set it on channel. <br>
  Load balancing factor to use when <br>
          </td>
        </tr>
        <tr>
          <td valign="top"><br>
          </td>
          <td valign="top"><br>
          </td>
          <td valign="top"><br>
          </td>
        </tr>
                     
    </tbody>     
  </table>
    
  <h3>Example</h3>
  <pre>logger.level=DEBUG<br># That's created by default if no other channel is
defined<br>channel.socket.DEFAULT.port=8009<br>channel.socket.local_9009.port=9009<br><br>#
that defines automatically a worker named<br># 'tomcat1' and an 'engine' named tomcat1<br>channel.socket.tomcat1.host=host1.my.com<br>channel.socket.tomcat1.lbfactor=0.5<br><br>[uri:/examples/*]<br>#
Automatically define the lb worker and sets balanced_workers<br># for this particular
uri.<br>engine=DEFAULT,tomcat1<br><br>[uri:/examples2/*]<br># the
/examples2 is only available on tomcat2<br>engine=tomcat1<br><br></pre>
  <h3>Alternatives</h3>
  <pre>logger.level=DEBUG<br><br>[channel.socket:tomcat1]<br>host=host1.foo.com<br>port=8009<br>lbfactor=0.5<br><br>[channel.socket:DEFAULT]<br>#
no property here, but the channel will be constructed<br># with the default properties<br><br><br><br><br></pre>
                  
  </body>
  </html>
  
  
  
  1.1                  jakarta-tomcat-connectors/jk/doc/jk2/jk2.html
  
  Index: jk2.html
  ===================================================================
  <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  <html>
  <head>
    <title></title>
  </head>
  <body>
  <h2>Jk2 architecture</h2>
  <br>
  <h3>Definitions</h3>
  <ol>
    <li>Engine. This is a tomcat instance, running in a java process. Each
  engine must  have a unique ID, and can be reached by multiple protocols over
  multiple transports</li>
    <li>Worker. A worker is the object serving ( processing ) the request.
  It can either forward it to a servlet Engine, to another worker or generate
  content itself ( status ). The important worker is "ajp13" implementing a
  simple/fast RPC mechanism. </li>
    <li>Channel. A channel represents a transport protocol, connecting 2 sides
  for RPC communication. The most common and standard is the tcp socket. Other
  important  channels are unix socket and jni, which are not yet fully supported. </li>
    <li>Endpoint. An endpoint represents an established connection between
  the web server and the java engine. The connection is reused, and multiple
  endpoints can exist and be active at the same time for one server/engine
  pair. </li>
    <li>Logger. The logger reports jk errors and debug statements. The goal
  is to use the native server logging whenever possible. At this moment there
  is a single logger, in future we may be able to associate loggers with individual
  webapps. </li>
    <li>Config. The config stores and manipulates parameters for each jk object. </li>
    <li>Uri ( XXX is it a good name ? ). A uri stores a pattern that is used
  to match requests, and asociated properties. </li>
    <li>UriMapper. This implements the matching of requests against uri patterns. </li>
    <li>WorkerEnv. The central controller, it controls global properties and 
  provides access to all other objects. </li>
  </ol>
  <h3>Configuration architecture </h3>
  <p>Jk2 is using a mechanism similar with JMX to manage all its configurable
  objects. Each component is controled by a "jk_bean" structure, containing
  pointers  to the setAttribute/getAttribute functions.</p>
  <p>The config object abstracts the persistent repository for config informations.
  Most  components/properties can be configured at runtime. A runtime change
  can be made either directly on the object, affecting the running instance
  only, or to the config object, making it persistent.   <br>
  </p>
  <p>The status worker provids a basic interface for setting/getting runtime
   config information, similar with the manager app in tomcat or the jmx web
  interface. Other workers could provide enhanced functionality ( like the ajp14
  extensions ).  <br>
  </p>
  <h3>Communication protocol</h3>
  <p> Jk2 supports multiple communication protocols ( RPC-style ) and multiple
  transports. In addition, each communication protocol supports multiple "APIs",
  or sets of  functions that are supported.  <br>
  </p>
  <p>The current protocol is called AJP13. It supports marshalling/unmarshalling
  of  strings and ints, with minimal overhead.   <br>
  </p>
  <p>The current API is also called ajp13. It consist of 5 methods:<br>
  </p>
  <ul>
    <li> (oneway) forwardRequest (2): the marshaled request is encoded as parameter. </li>
    <li> (oneway) sendBodyChunk (3): sends the output of a request </li>
    <li> (oneway) sendHeaders  (4): sends the marshaled headers </li>
    <li>(oneway) endResponse (5): marks the end of the response </li>
    <li> (req/resp) getBodyChunk (6): get the POST body.</li>
  </ul>
  <p> It is desirable to migrate to a standard protocol for encoding and RPC
  ( CDR, XDR, etc ), and to support additional protcols ( like WARP ). However
  the AJP13 protocol is stable and shouldn't change in future.  <br>
  </p>
  <p>The ajp13 API is also stable and frozen. In future, what will be called
  'ajp14'  may provide additional functions.  ( using the same name for API
  and protocol is very confusing, but that's what we have. We should at least
  call them consistently "ajp13 protocol" and "ajp13 api"  )  <br>
  </p>
  <h3>Low level components </h3>
  <p>Jk2 uses a object oriented style, allowing multiple implementations for
  each  object. The model is based on the style used in JNI ( and a bit Corba
  C bindings). Each function takes as parameter a pointer to an execution context
  ( jk_env ), a pointer to its own object structure, and the normal parameters. 
   <br>
  </p>
  <p>Jk_env is not completed, but it'll support basic exception handling (
  JNI style ), a local pool, etc.  <br>
  </p>
  <p>In addition, each configurable component has as the first member a jk_bean
  pointer, pointing to the JMX-like dynamic configurator.  The jk_env stores
  a table with all the known 'types', and a constructor for each.<br>
  </p>
  <p> Each object has a name, either specified explicitely or generated from
  it's type. The object name has the type as prefix.  Jk_env also stores a
  table with all existing 'instances', by name. <br>
  </p>
  <p>It is assumed that all 'top level' objects will be long-lived ( including
  endpoints ).  <br>
  </p>
  <h3>Default configuration</h3>
  <p>Jk2 uses a config file ( jk2.conf ) in the style of a .properties or ini
  file. It can be configured to use any other backed that provides similar
  capabilities.<br>
  </p>
  <p>  The config file is user editable, but mod_jk will persist the changes
  requested by protocol. If you manually change the file while jk is working,
  your changes will be lost.   The config file supports no comments at this
  moment. We'll allow a limited  form of comments that can be persisted.   <br>
  </p>
  <p>The configuration defines properties for each configurable component.
  A simple form of substitution is used, where $(property) will be replaced
  with a  previously defined setting.  Each setting consists of an object name
  and a property, with the associated value. The property name is a simple
  string, with no '.' in it. The name can be anything, but it must have a known
  'type' as prefix.  <br>
  </p>
  <p>2 formats are supported:   <br>
  </p>
  <pre>NAME.PROPERTY=VALUE <br>and<br>[NAME]
  PROPERTY=VALUE
  <br></pre>
  <p>In addition to the configuration file, properties can be set from the
  main server config file - but those will not be modifiable.   <br>
  </p>
  <p>Properties with no type prefix will be stored as 'global' properties.
  <br>
  </p>
  <p>The first time a name is found, the object will be created using the type
   prefix ( by looking for the longest match on all known types ).  <br>
  </p>
  <h3>Default values / guessing</h3>
  <p>Each component will do the best effort to detect it's environment and
  set  default values, to minimze the user effort.  <br>
  </p>
  <p>On startup, jk2 will set few global settings:     <br>
  </p>
  <ul>
    <li>fs = file separator, / on unix, \ on windows</li>
    <li>ps = path separator, : on unix, ; on windows</li>
    <li>so = plaftorm extension for libraries ( .so, .dll, .nlm )</li>
    <li>(TODO) arch = system architecture</li>
    <li>(TODO) server.root = base directory for the server ( same as ServerRoot
  for apache )</li>
  </ul>
  <p>All those are either compile time or extracted from the running server,
  and  can be used to construct other settings.  A separate document defines
  all the supported properties and 'magic' that is used to automatically configure
  the object and simplify the config.<br>
  </p>
  <h3>  Source code structure </h3>
  <p>Each interface "foo" is defined in a file include/jk_foo.h. If the interface
  has a single ( or base ) implementation, it'll be called common/jk_foo.c.
  If it has multiple implementations, the files  will be named jk_foo_bar.c.
    All server-specific files are in server/[SERVER] ( server/apache2, etc
  ). The apache13 objects should be used as a basis for new servers, apache2 
  has a number of extra fancy features to be used as model for 'deeper'  integration. 
   The default set of types is defined in common/jk_registry.c, common/jk_registry.h. 
  Additional types can be defined at runtime in the server adapter or various 
  other components.   </p>
  </body>
  </html>
  
  
  

--
To unsubscribe, e-mail:   <mailto:tomcat-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:tomcat-dev-help@jakarta.apache.org>


Mime
View raw message