Lighttpd

{{{
#!rst

===================
the Proxy Interface ===================

----------------------
Module: mod_proxy_core
----------------------

.. contents:: Table of Contents

Description ===========

FastCGI, SCGI, HTTP, ... are doing the simple job: they forward the HTTP-request to a backend and send the response back to the server. They just use different protocol to encode the data.

• FastCGI was developed by http://www.fastcgi.com/ and is a binary container around HTTP requests which reduces the parsing overhead.
• SCGI similar to HTTP and only adds a length header for the HTTP-header. http://www.mems-exchange.org/software/scgi/ says "The SCGI protocol is a replacement for the Common Gateway Interface (CGI) protocol. It is a standard for applications to interface with HTTP servers. It is similar to FastCGI but is designed to be easier to implement."
• for HTTP we support HTTP/1.0 and HTTP/1.1 on the backend side
• AJP13 is the Apache JServ Protocol version 1.3 (see http://tomcat.apache.org/connectors-doc/common/ajpv13a.html), implemented by mod_jk in the apache world.

A small guide shall help you to choose the right protocol for your needs.

======== ============= =============== ==========
Protocol preferred by binary protocol keep-alive ======== ============= =============== ==========
HTTP mongrel no yes
SCGI WSGI (python) not really no
FastCGI PHP, rails yes yes
AJP13 Tomcat yes yes ======== ============= =============== ==========

Installation
------------

If you want to use mod-proxy-core you have to load it first. Each protocol is a module too and has to be loaded
after the core-module.: ::

server.modules = (
    ..., 
    "mod_proxy_core",
    "mod_proxy_backend_http",
    ... )

Load Balancing
--------------

mod-proxy-core supports 4 different load balancers:

• the static load balancer (static) does no load balancing, only fail-over in case the first listed backend is not available. See http://permalink.gmane.org/gmane.comp.web.lighttpd/4686 for an example (basically local and remote backends).
• in Round Robin (round-robin) the requests are distributed equally over all backends. In our implementation we are not enforcing true round robin, but do a random selection of a backend.
• Shortest Queue First (sqf) is similar to round-robin and prefers the backend with the shortest wait-queue.
• the Cache Array Routing Protocol (carp) is a bit different as it is the only balancing protocol which improves the locality of the backends. It hashes the URL and send the same URL always to the same backend. http://icp.ircache.net/carp.txt explains the full spec.

Currently not implemented:

• sticky-session
• alot of the http://www.ietf.org/proceedings/99mar/I-D/draft-melve-intercache-comproto-00.txt protocols

Fail-Over Handling
------------------

In case a request to the backend fails (connections refused, connection timeout, ...) the request is sent to another backend. If no backend is a available, ``504 Gateway Timeout`` is returned. (see http://forum.lighttpd.net/topic/4993)

Timeouts
--------

If your incoming requests is exceeding the number of backends you have the request is put into a backlog queue. As soon as a backend is available again the first connection from the queue is woken up and is processed.

In case a request is waiting for more than 10 seconds in the queue, the request is terminated and ``504 Gateway timeout`` is returned.

Options =======

proxy-core.balancer
might be one of 'round-robin', 'sqf', 'carp' or 'static'.

See: 

• http://blog.lighttpd.net/articles/2006/11/14/mod-proxy-core-and-sqf

proxy-core.protocol
might be one of 'http', 'fastcgi', 'ajp13' or 'scgi'. Make sure you load the backend
modules (see mod_proxy_backend_<name>)

proxy-core.backends
tell the module where to send Proxy requests to.
It is a list of hostname/ip address/unix-domain socket

Example: ::

proxy-core.backends = ( 
      "10.0.0.1:80",     ## IPv4 address
      "unix:/tmp/php.socket", ## unix domain socket
      "[::1]:80",        ## IPv6 addresss
      "google.com:80"    ## hostname, resolved at startup
    )

proxy-core.max-pool-size
max size for pool of connections to a single backend.

• for mongrel this should be 1
• for PHP this should match the PHP_FCGI_CHILDREN setting
• for WSGI it should match the number of threads of the backend
• for HTTP proxying it is up to you how many parallel requests you want to allow to the same backend

Default: 1

proxy-core.check-local
enable checking for url file in local document-root.

If you want to use ``index-file.names = ( "index.php" )`` you have to enable the ``proxy-core.check-local``

Default: disabled

proxy-core.allow-x-sendfile
enables use of "X-Sendfile/X-LIGHTTPD-Sendfile/X-LIGHTTPD-send-tempfile" headers.

See: 

• http://blog.lighttpd.net/articles/2006/07/22/mod_proxy_core-got-x-sendfile-support
• http://blog.lighttpd.net/articles/2006/11/29/faster-fastcgi

proxy-core.allow-x-rewrite
enables use of "X-Rewrite"

See:
  * http://blog.lighttpd.net/articles/2006/07/22/x-sendfiles-new-friend-x-rewrite

proxy-core.rewrite-request
rewrite request headers or request uri.

proxy-core.rewrite-response
rewrite response headers.

proxy-core.max-keep-alive-requests
number of request before closing a keep-alive connection.

Default: 0

proxy-core.split-hostnames
If the backends uses DNS hostnames each with multiple ip address, split each address into a separate backend.
Disable this option to put the ip addresses into an address pool for that backend.

Default: enabled

Example: ========

Using lighttpd + mod_proxy_core in front of 8 Squids which handle the
caching of dynamic content for you. All requests for the host
www.example.org should be forwarded to the proxy. All proxies
listen on port 80 for requests. ::

server.modules  += ( "mod_proxy_backend_http" )
  $HTTP["host"] == "www.example.org" {
    proxy-core.protocol = "http" 
    proxy-core.balancer = "carp" 
    proxy-core.backends = ( "10.0.0.10",
                            "10.0.0.11",
                            "10.0.0.12",
                            "10.0.0.13",
                            "10.0.0.14",
                            "10.0.0.15",
                            "10.0.0.16",
                            "10.0.0.17" )
  }

If one of the hosts goes down the all requests for this one server are
moved equally to the other servers. If you want to know more about
the algorithm used here google for 'Microsoft CARP'.

for php using unix-domain socket "/tmp/php-fastcgi.sock" ::

server.modules  += ( "mod_proxy_backend_fastcgi" )
  $HTTP["url"] =~ "\.php$" {
    proxy-core.balancer = "round-robin" 
    proxy-core.protocol = "fastcgi" 
    proxy-core.check-local = "enable" 
    proxy-core.allow-x-sendfile = "enable" 
    proxy-core.backends = ( "unix:/tmp/php-fastcgi.sock" )
    proxy-core.max-pool-size = 16
  }

for SCGI ::

server.modules  += ( "mod_proxy_backend_scgi" )
  $HTTP["url"] =~ "\.scgi$" {
    proxy-core.balancer = "round-robin" 
    proxy-core.protocol = "scgi" 
    proxy-core.check-local = "enable" 
    proxy-core.allow-x-sendfile = "enable" 
    proxy-core.backends = ( "127.0.0.1:9090" )
    proxy-core.max-pool-size = 16
  }

for http-proxy with host and file-extension conditionals ::

server.modules  += ( "mod_proxy_backend_http" )
  $HTTP["host"] == "www.example.org" {
    proxy-core.protocol = "http" 
    proxy-core.balancer = "carp" 
    $HTTP["url"] =~ "\.php$" {
      proxy-core.backends = ( "10.0.0.10:80" )
    }
    else $HTTP["url"] =~ "\.scgi$" {
      proxy-core.backends = ( "10.0.0.11:80" )
    }
  }

Reverse-Proxying ::

server.modules  += ( "mod_proxy_backend_http" )
  $HTTP["url"] =~ "^/proxyme(/|$)" {
    proxy-core.balancer = "round-robin" 
    proxy-core.protocol = "http" 
    proxy-core.backends = ( "en.wikipedia.org" )
    proxy-core.rewrite-response = (
      "Location" => ( "^http://en.wikipedia.org/(.*)" => "http://127.0.0.1:1025/proxyme/$1" ),
    )
    proxy-core.rewrite-request = (
      "_uri" => ( "^/proxyme/?(.*)" => "/$1" ),
      "Host" => ( ".*" => "en.wikipedia.org" ),
    )
  }

for proxying to Tomcat using AJP13 protocol ::

server.modules  += ( "mod_proxy_backend_ajp13" )
  $HTTP["url"] =~ "^/tomcat/" {
    proxy-core.balancer = "round-robin" 
    proxy-core.protocol = "ajp13" 
    proxy-core.backends = ( "localhost:8009" )
    proxy-core.max-pool-size = 16
  }

example of allow-x-rewrite config ::

server.modules  += ( "mod_proxy_backend_fastcgi" )
  $HTTP["url"] =~ "\.php$" {
    proxy-core.balancer = "round-robin" 
    proxy-core.protocol = "fastcgi" 
    proxy-core.check-local = "enable" 
    proxy-core.allow-x-rewrite = "enable" 
    proxy-core.backends = ( "unix:/tmp/php-fastcgi.sock" )
    proxy-core.max-pool-size = 16
  }
  server.modules  += ( "mod_proxy_backend_http" )
  $HTTP["host"] == "backend-cluster" {
    proxy-core.balancer = "round-robin" 
    proxy-core.protocol = "http" 
    proxy-core.max-pool-size = 4
  }

example X-Rewrite script ::

<?php
  header("X-Rewrite-URI: /");
  header("X-Rewrite-Host: backend-cluster");
  header("X-Rewrite-Backend: " . $_REQUEST['backend']); // dynamicaly add/select a backend to the "backend-cluster" proxy-core
  ?>

}}}