WHAT IS LINGERD?

Lingerd is a daemon (service) designed to take over the job of
properly closing network connections from an http server like
Apache.

Because of some technical complications in TCP/IP, at the end of
each client connection, it is not enough for Apache to close the
socket and forget about it; instead, it needs to spend about one
second "lingering" on the client.  (More details in the file
htdocs/manual/misc/fin_wait_2.html in the Apache distribution).

Now, Apache is a fairly heavy program in itself, and it gets much
heavier when you link it with a scripting language interpreter like
mod_perl, and then preload thousands of lines of website code.  

So, when traffic gets high, the end result is that each heavy Apache
process ends up spending much of its time doing lingering_close(),
which is a time-consuming but extremely simple and dull operation.

Lingerd, then, is a daemon specialized in doing lingering_closes.
Unlike Apache, which uses one process per connection, lingerd can do
thousands of lingers in parallel, from a single process.  This makes
lingerd extremely light on resources (both CPU and memory), which is
reasonable, considering that its job amounts to doing nothing to
sockets in an orderly way.

To use lingerd, you need to compile and run it.  You also need to
set up Apache so that it hands over its network connections to
lingerd.  Handing over an open connection from one process to
another is done using a rather esoteric feature called "file
descriptor passing on Unix-domain sockets", and, as the name
implies, is not very portable outside of Unix systems.


ARE THERE ANY ALTERNATIVES TO LINGERD?

Yes.  The "classical" solution to the lingering_close problem, and more
generally, to the problem of having a big Apache/mod_{perl,php} process
spoonfeed data to a slow client on a congested link, is to run a
front-end proxy server.  This can be done with of squid, or with a
light-weight Apache configured with mod_proxy and without any scripting.

Lingerd has a number of advantages, and also some disadvantages,
compared to this approach.

Advantages:

  - lingerd is easier to set up: no URL rewriting, no multiple webservers,
    no reverse rewriting rules.

  - lingerd only takes control when Apache is done with the connection, so
    there is no extra latency for the client.

  - lingerd is easier on system resources: the sent data doesn't get
    copied around any extra times between userspace and kernel memory,
    the way it does with a proxy.  lingerd itself takes very few
    resources of its own.

Disadvantages:

  - a proxy front-end can double as a cache, as a load balancer and as
    a light-weight image server, which lingerd obviously can't.  
    
    for an image server, I recommend using a standalone copy of
    thttpd (http://www.acme.com/software/thttpd/) or boa
    (http://www.boa.org).

    for load balancing, this is better done at the IP level, with a
    package like Piranha
    (http://people.redhat.com/kbarrett/HA/index.html)

  - both approaches can still stall the heavy Apache process if the data
    to send doesn't fit in the buffers.  with lingerd, the maximum data
    size that can be handled without slowing Apache down is the kernel's
    maximum write() buffer for tcp/ip sockets.  since a front-end proxy
    goes through two network sockets and a userspace buffer, the maximum
    data size that it can handle without blocking is twice the kernel's
    tcp/ip write buffer size plus the size of the userspace buffer
    (usually 8k or so).  see `TUNING HINTS' below on how to increase
    the tcp/ip write buffer size with lingerd.

  - lingerd is less portable.  it should run on any modern Unix, but it
    would probably be hard to port to non-POSIX systems.  but feel free
    to prove me wrong.


HOW DO I COMPILE AND RUN LINGERD?

See the file `INSTALL'.


TUNING HINTS

See the file `TUNING'.


COMMON PROBLEMS

If you get connect() errors, make sure that lingerd and Apache are
running under the same user name, and that this user can write to the
directory that holds the Unix-domain socket.  Some Unix kernels honor
the permission flags on Unix-domain sockets (Linux does at least), so if
you really want to run lingerd as a different user than Apache's, you
might have to do a "umask 000" from the script that starts lingerd, or
manually chmod the socket.


TESTING AND BENCHMARKING

See the file `testing/TESTING'.


STATUS

Lingerd has been used in production for months, and has handled a
millions of lingers without any reported errors, so it is now
considered production quality.

Lingerd was originally developped under Linux.  From version 0.94
on, it has also been ported and tested under FreeBSD and Solaris,
but more real-world testing is needed to be sure it works well on
these systems.  It should also work without any problems on NetBSD
and OpenBSD.  

If you have any problems with lingerd, or if you port it to a
different platform, please tell me about it and/or send me any
patches, at <espel@iagora.net>.


AUTHOR & LICENSE

Lingerd was written by Roger Espel Llima <espel@iagora.net> for iAgora,
LLC.  

The code and documentation are Copyright (C) 2000, iAgora LLC,

Lingerd is Free Software.  You can redistribute and/or modify it under
the terms specified in the file ``LICENSE'', which is part of the
lingerd distribution.  

(For the impatient: it's an Apache-style license, without the
advertising clause.)