Commit a4cbcf82 authored by Mladen Turk's avatar Mladen Turk
Browse files

Explain new proxy parameters.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@122771 13f79535-47bb-0310-9956-ffa450edef68
parent f84da0e7
Loading
Loading
Loading
Loading
+133 −4
Original line number Diff line number Diff line
@@ -546,6 +546,137 @@ directly</td></tr>
      &lt;/Proxy&gt;
    </code></p></div>

    <p>New in Apache 2.1, is the ability to set the various connection
    parameters to a backend server. The connection parameters are in
    the form <code>key=value</code>.
    </p>
    <table>
    <tr><th>Parameter</th>
        <th>Default</th>
        <th>Description</th></tr>
    <tr><td>min</td>
        <td>0</td>
        <td>Minumum number of connections that will always
            be open to the backend server.</td></tr>
    <tr><td>max</td>
        <td>1...n</td>
        <td>Hard Maximum number of connections that will be
    allowed to the backend server. The default for a Hard Maximum
    for the number of connections is the number of threads per process in the 
    active MPM. In the Prefork MPM, this is always 1, while with the Worker MPM
    it is controlled by the <code class="directive">ThreadsPerChild</code>.
    Apache will never create more than the Hard Maximum connections
    to the backend server.</td></tr>
    <tr><td>smax</td>
        <td>max</td>
        <td>Upto the Soft Maximum
    number of connections will be created on demand. Any connections above 
    <code>smax</code> are subject to a time to live or <code>ttl</code>.
    </td></tr>
    <tr><td>ttl</td>
        <td>-</td>
        <td>Time To Live for the inactive connections above the
        <code>smax</code> connections in seconds. Apache will close all
        connections that has not been used inside that time period.
        If not set the Apache will wait until the free connection
        is available. This directive is used for limiting the number
        of connections to the backend server together with <code>max</code>
        parameter.
    </td></tr>
    <tr><td>timeout</td>
        <td><code class="directive">Timeout</code></td>
        <td>Connection timeout in seconds.
    </td></tr>
    <tr><td>acquire</td>
        <td>-</td>
        <td>If set this will be the maximum time to wait for a free
    connection in the connection pool. If there is no free connections
    in the pool the Apache will return <code>SERVER_BUSY</code> status to
    the client.
    </td></tr>
    <tr><td>keepalive</td>
        <td>Off</td>
        <td>This parameter should be used when you have a firewall between your
    Apache and the backend server, who tend to drop inactive connections.
    This flag will told Operating System to send <code>KEEP_ALIVE</code> message
    on inactive connections (interval depend on global OS settings,
    generally 120ms), and thus prevent the firewall to cut the connection.
    To enable keepalive set this property value to the <code>On</code>. 
    </td></tr>
    <tr><td>retry</td>
        <td>60</td>
        <td>Connection pool worker retry timeout in seconds.
    If the connection pool worker to the backend server is in the error state,
    the Apache will not forward any request to that servers untill that timeout
    expires. This enables to shut down the backend server for maintenance,
    and bring it back online.
    </td></tr>
    <tr><td>loadfactor</td>
        <td>1</td>
        <td>Worker load factor. Used with BalancerMamber.
         It is a number between 1 and 100 and defined the load aplied to
         the worker.
    </td></tr>
    <tr><td>route</td>
        <td>-</td>
        <td>Route of the worker when used inside load balancer.
        The route is a value appended to seesion id.
    </td></tr>
    <tr><td>redirect</td>
        <td>-</td>
        <td>Redirection Route of the worker. This value is usually
        set dynamically to enable safe removal of the node from
        the cluster. If set all requests without session id will be
        redirected to the BalancerMember that has route parametar
        equal as this value.
    </td></tr>

    </table>

    <p>If the Proxy directive scheme starts with the
    <code>balancer://</code> then a virtual worker that does not really
    communicate with the backend server will be created. Instead it is responsible
    for the management of several "real" workers. In that case the special set of
    parameters can be add to this virtual worker.
    </p>
    <table>
    <tr><th>Parameter</th>
        <th>Default</th>
        <th>Description</th></tr>
    <tr><td>stickysession</td>
        <td>-</td>
        <td>Balancer sticky session name. The value is usually set to something
        like <code>JSESSIONID</code> or <code>PHPSESSIONID</code>,
        and it depends on the backend application server that support sessions.
    </td></tr>
    <tr><td>nofailover</td>
        <td>Off</td>
        <td>If set to <code>On</code> the session will break if the worker is in
        error state or disabled. Set this value to On if backend servers do not
        support session replication.
    </td></tr>
    <tr><td>timeout</td>
        <td>0</td>
        <td>Balancer timeout in seconds. If set this will be the maximum time
        to wait for a free worker. Default is not to wait. 
    </td></tr>
    <tr><td>maxattempts</td>
        <td>1</td>
        <td>Maximum number of failover attempts before giving up. 
    </td></tr>
    
    </table>
    <div class="example"><p><code>
      &lt;Proxy balancer://mycluster stickysession=jsessionid nofailover=On&gt;<br />
      <span class="indent">
        BalancerMember http://1.2.3.4:8009<br />
        BalancerMember http://1.2.3.5:8009<br />
        BalancerMember http://1.2.3.6:8009<br />
      </span>
      &lt;/Proxy&gt;
    </code></p></div>
    

</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="ProxyBadHeader" id="ProxyBadHeader">ProxyBadHeader</a> <a name="proxybadheader" id="proxybadheader">Directive</a></h2>
@@ -769,15 +900,13 @@ through</td></tr>
    be open to the backend server. Upto the Soft Maximum or <code>smax</code> 
    number of connections will be created on demand. Any connections above 
    <code>smax</code> are subject to a time to live or <code>ttl</code>.  Apache
    will never create more than the Hard Maximum or <code>hmax</code> connections
    will never create more than the Hard Maximum or <code>max</code> connections
    to the backend server.</p>

    <div class="example"><p><code>
        ProxyPass /example http://backend.example.com min=0 smax=5 hmax=20 ttl=60
        ProxyPass /example http://backend.example.com smax=5 max=20 ttl=120 retry=300
    </code></p></div>

    

    <p>When used inside a <code class="directive"><a href="../mod/core.html#location">&lt;Location&gt;</a></code> section, the first argument is omitted and the local
    directory is obtained from the <code class="directive"><a href="../mod/core.html#location">&lt;Location&gt;</a></code>.</p>

+133 −8
Original line number Diff line number Diff line
@@ -373,6 +373,137 @@
      </indent>
      &lt;/Proxy&gt;
    </example>

    <p>New in Apache 2.1, is the ability to set the various connection
    parameters to a backend server. The connection parameters are in
    the form <code>key=value</code>.
    </p>
    <table>
    <tr><th>Parameter</th>
        <th>Default</th>
        <th>Description</th></tr>
    <tr><td>min</td>
        <td>0</td>
        <td>Minumum number of connections that will always
            be open to the backend server.</td></tr>
    <tr><td>max</td>
        <td>1...n</td>
        <td>Hard Maximum number of connections that will be
    allowed to the backend server. The default for a Hard Maximum
    for the number of connections is the number of threads per process in the 
    active MPM. In the Prefork MPM, this is always 1, while with the Worker MPM
    it is controlled by the <directive>ThreadsPerChild</directive>.
    Apache will never create more than the Hard Maximum connections
    to the backend server.</td></tr>
    <tr><td>smax</td>
        <td>max</td>
        <td>Upto the Soft Maximum
    number of connections will be created on demand. Any connections above 
    <code>smax</code> are subject to a time to live or <code>ttl</code>.
    </td></tr>
    <tr><td>ttl</td>
        <td>-</td>
        <td>Time To Live for the inactive connections above the
        <code>smax</code> connections in seconds. Apache will close all
        connections that has not been used inside that time period.
        If not set the Apache will wait until the free connection
        is available. This directive is used for limiting the number
        of connections to the backend server together with <code>max</code>
        parameter.
    </td></tr>
    <tr><td>timeout</td>
        <td><directive>Timeout</directive></td>
        <td>Connection timeout in seconds.
    </td></tr>
    <tr><td>acquire</td>
        <td>-</td>
        <td>If set this will be the maximum time to wait for a free
    connection in the connection pool. If there is no free connections
    in the pool the Apache will return <code>SERVER_BUSY</code> status to
    the client.
    </td></tr>
    <tr><td>keepalive</td>
        <td>Off</td>
        <td>This parameter should be used when you have a firewall between your
    Apache and the backend server, who tend to drop inactive connections.
    This flag will told Operating System to send <code>KEEP_ALIVE</code> message
    on inactive connections (interval depend on global OS settings,
    generally 120ms), and thus prevent the firewall to cut the connection.
    To enable keepalive set this property value to the <code>On</code>. 
    </td></tr>
    <tr><td>retry</td>
        <td>60</td>
        <td>Connection pool worker retry timeout in seconds.
    If the connection pool worker to the backend server is in the error state,
    the Apache will not forward any request to that servers untill that timeout
    expires. This enables to shut down the backend server for maintenance,
    and bring it back online.
    </td></tr>
    <tr><td>loadfactor</td>
        <td>1</td>
        <td>Worker load factor. Used with BalancerMamber.
         It is a number between 1 and 100 and defined the load aplied to
         the worker.
    </td></tr>
    <tr><td>route</td>
        <td>-</td>
        <td>Route of the worker when used inside load balancer.
        The route is a value appended to seesion id.
    </td></tr>
    <tr><td>redirect</td>
        <td>-</td>
        <td>Redirection Route of the worker. This value is usually
        set dynamically to enable safe removal of the node from
        the cluster. If set all requests without session id will be
        redirected to the BalancerMember that has route parametar
        equal as this value.
    </td></tr>

    </table>

    <p>If the Proxy directive scheme starts with the
    <code>balancer://</code> then a virtual worker that does not really
    communicate with the backend server will be created. Instead it is responsible
    for the management of several "real" workers. In that case the special set of
    parameters can be add to this virtual worker.
    </p>
    <table>
    <tr><th>Parameter</th>
        <th>Default</th>
        <th>Description</th></tr>
    <tr><td>stickysession</td>
        <td>-</td>
        <td>Balancer sticky session name. The value is usually set to something
        like <code>JSESSIONID</code> or <code>PHPSESSIONID</code>,
        and it depends on the backend application server that support sessions.
    </td></tr>
    <tr><td>nofailover</td>
        <td>Off</td>
        <td>If set to <code>On</code> the session will break if the worker is in
        error state or disabled. Set this value to On if backend servers do not
        support session replication.
    </td></tr>
    <tr><td>timeout</td>
        <td>0</td>
        <td>Balancer timeout in seconds. If set this will be the maximum time
        to wait for a free worker. Default is not to wait. 
    </td></tr>
    <tr><td>maxattempts</td>
        <td>1</td>
        <td>Maximum number of failover attempts before giving up. 
    </td></tr>
    
    </table>
    <example>
      &lt;Proxy balancer://mycluster stickysession=jsessionid nofailover=On&gt;<br />
      <indent>
        BalancerMember http://1.2.3.4:8009<br />
        BalancerMember http://1.2.3.5:8009<br />
        BalancerMember http://1.2.3.6:8009<br />
      </indent>
      &lt;/Proxy&gt;
    </example>
    
</usage>
</directivesynopsis>

@@ -584,19 +715,13 @@ expressions</description>
    be open to the backend server. Upto the Soft Maximum or <code>smax</code> 
    number of connections will be created on demand. Any connections above 
    <code>smax</code> are subject to a time to live or <code>ttl</code>.  Apache
    will never create more than the Hard Maximum or <code>hmax</code> connections
    will never create more than the Hard Maximum or <code>max</code> connections
    to the backend server.</p>

    <example>
        ProxyPass /example http://backend.example.com min=0 smax=5 hmax=20 ttl=60
        ProxyPass /example http://backend.example.com smax=5 max=20 ttl=120 retry=300
    </example>

    <!-- Still to be documented:
             retry acquire timeout 
             iobuffersize receivebuffersize 
             keepalive route redirect 
         See modules/proxy/mod_proxy.c set_worker_param() for details.  -->

    <p>When used inside a <directive type="section" module="core"
    >Location</directive> section, the first argument is omitted and the local
    directory is obtained from the <directive type="section" module="core"