Permalink
Browse files

first round of edits.

did a whole bunch, and added some content. didn't want to split it into 20
commits, sorry :(
  • Loading branch information...
1 parent b7258b4 commit ca0636247d5f2c3b5799c300ddf6c3d836114c3f @dormando dormando committed Dec 20, 2010
View
6 README
@@ -31,7 +31,7 @@ DESCRIPTION
Perlbal is a Perl-based reverse proxy load balancer and web server.
It processes hundreds of millions of requests a day just for LiveJournal,
-Vox and TypePad and dozens of other high-traffic websites.
+TypePad and dozens of other high-traffic websites.
Perlbal is a single-threaded event-based server supporting HTTP load
balancing, web serving, and a mix of the two (see below).
@@ -96,8 +96,8 @@ Role: Reverse Proxy
o Can actually give Perlbal a list of URLs to try. Perlbal will find
one that's alive. Again, the end user sees no redirects happening
- o Can also redirect to a file, which Perlbal will serve
- non-blocking. See webserver mode above
+ o Can also redirect to a local file, which Perlbal will serve
+ non-blocking. See webserver mode below
* Persistent client connections (configurable)
View
2 lib/Perlbal/FAQ.pod
@@ -50,7 +50,7 @@ Currently, Perlbal supports only one balancing method: C<random>.
SET pool balance_method = 'random'
-With this mode, Perlbal selects one of the nodes within the pool randomly for each request received.
+With this mode, Perlbal selects one of the nodes within the pool randomly for each request received. It prefers reusing existing idle backend connections if backend_persist is enabled, which is faster than waiting for a new connection to open each time.
=head2 Plugins
View
5 lib/Perlbal/Manual.pod
@@ -95,11 +95,6 @@ Brief description of existing roles.
Setting up a Perlbal C<selector> service.
-=item L<Perlbal::Manual::ToDo>
-
-Perlbal's To-Do list.
-
-
=item L<Perlbal::Manual::WebServer>
Setting up a Perlbal C<web_server> service.
View
2 lib/Perlbal/Manual/Configuration.pod
@@ -78,6 +78,8 @@ Note that:
...unsets the nodefile, but does not remove current members.
+Also note: If you set a nodefile, then modify the pool via POOL ADD or POOL REMOVE, Perlbal will stop checking the nodefile for updates!
+
Check F<conf/load-balancer.conf> and F<conf/nodelist.dat> for an example.
View
5 lib/Perlbal/Manual/Contributing.pod
@@ -17,7 +17,7 @@ This document aims at providing useful pointers for people wanting to contribute
There's a description of Perlbal's internals in L<Perlbal::Manual::Internals>.
-There's a list of to-do items at L<Perlbal::Manual::ToDo>.
+There's a list of to-do items at http://code.google.com/p/perlbal/issues/list
Also, join the mailing list at http://groups.google.com/group/perlbal.
@@ -52,7 +52,7 @@ Be sure to follow local style conventions.
http://groups.google.com/group/perlbal
-=item Bug Tracker
+=item Bug Tracker and ToDo
http://code.google.com/p/perlbal/issues/list
@@ -63,4 +63,3 @@ Be sure to follow local style conventions.
L<Perlbal::Manual::Credits>,
L<Perlbal::Manual::Internals>,
-L<Perlbal::Manual::ToDo>.
View
4 lib/Perlbal/Manual/Credits.pod
@@ -14,12 +14,11 @@ Lots of incredible people have contributed to make Perlbal the amazing tool that
We are all very grateful for their help.
-Please let us know if you think someone is missing from this list.
+Please let us know if you think someone is missing from this list. The primary git repo may also be more up to date.
=head2 CONTRIBUTORS
-Alan Kasindorf,
Andreas J Koenig,
Andrew McClain,
Andy Armstrong,
@@ -31,6 +30,7 @@ Brad Fitzpatrick,
Chuck Remes,
Chris Hondl,
Dan Conlon,
+dormando,
Eamon Daly,
Fred Moyer,
Giao Phan,
View
2 lib/Perlbal/Manual/Debugging.pod
@@ -19,7 +19,7 @@ One of them is through a management console; the other is through debugging mess
You'll need to set up a management service and use it to dump all the information you require.
-The comprehensive documentation on this process can be found at L<Perlbal::Manual::Management.
+The comprehensive documentation on this process can be found at L<Perlbal::Manual::Management>.
=head2 Debugging messages
View
15 lib/Perlbal/Manual/Install.pod
@@ -19,6 +19,11 @@ How to install Perlbal.
cpan> install Perlbal
+L<App::cpanminus> is also good at quickly installing Perlbal and all of its dependencies
+
+ $ cpanm Perlbal IO::AIO Perlbal::XS::HTTPHeaders
+
+... will give you an ideal Perlbal environment.
=head2 Installing Perlbal (with a little more detail)
@@ -77,6 +82,16 @@ You can clone Perlbal's repository from github and install it by hand by followi
=head2 Optional Dependencies and Asynchronous IO
+It is very highly recommended that L<Perlbal::XS::HTTPHeaders> is installed and enabled. If you have poor performance, the first thing to do is install L<Perlbal::XS::HTTPHeaders>.
+
+ $ perl -MCPAN -e shell
+
+ cpan> install Perlbal::XS::HTTPHeaders
+
+Enable it in your configuration:
+
+ XS enable headers
+
Perlbal checks for L<IO::AIO> availability and uses it to perform asynchronous IO operations. If you're performing disk operations (e.g., using Perlbal as a web server), having L<IO::AIO> will improve your response times.
The only thing required in order to benefit from this feature is to install L<IO::AIO>:
View
5 lib/Perlbal/Manual/Internals.pod
@@ -10,7 +10,7 @@ Perlbal 1.76.
=head2 DESCRIPTION
-Perlbal listens for UDP broadcasts from the web nodes describing how many available children they have. This information is then used to pick an endpoint for a backend connection to be made to in order to handle a user's incoming request.
+Connections come in from wherever and get to the TCPListener. It uses Service objects to determine what kind of Client* to spawn. The Client classes then handle crafting the response for the user.
{{ INTERNET }}
|
@@ -24,8 +24,9 @@ Perlbal listens for UDP broadcasts from the web nodes describing how many availa
v
[BackendHTTP]
-So connections come in from wherever and get to the TCPListener. It uses Service objects to determine what kind of Client* to spawn. The Client classes then handle crafting the response for the user.
+Perlbal decides what backend to send a request to randomly (only presently supported method). If that service has idle backend connections available, configured by C<backend_persist> and C<connect_ahead>, it will reuse those connections and greatly reduce latency. See more detail in L<Perlbal::Manual::LoadBalancer>.
+Perlbal also specializes in "spoonfeeding" data to slow clients. This allows backends to continue serving requests while Perlbal transfers responses back as fast as the client can read.
=head2 Classes
View
22 lib/Perlbal/Manual/LoadBalancer.pod
@@ -65,6 +65,28 @@ After that you define a service called C<service_mywebsite> with the role C<reve
The last line is what allows you have several services configured in a file even if they are not currently active (a common scenario is to configure everything on the file and then enable/disable services on-the-fly as required; see L<Perlbal::Manual::Management> for more information on this process).
+=head3 The Load Balancing algorithm
+
+Perlbal uses a highly efficient load balancing algorithm. It is very effective for distributing dynamic web requests among potentially heterogeneous hardware.
+
+First, backend servers must have their MaxClients (for apache, or equivalent) setting tuned to a reasonable limit. If your hardware can run 20 requests in parallel before running out of CPU, set MaxClients to 20.
+
+Next, by default Perlbal will distribute requests randomly. Opening a new connection to any available backend, and issuing the request.
+
+The proper algorithm is able to be used if C<verify_backend>, C<backend_persist>, C<backend_persist_cache>, and C<connect_ahead> are enabled.
+
+ SET persist_backend = on
+ SET verify_backend = on
+ SET backend_persist_cache = 5
+ SET connect_ahead = 2
+
+In this configuration, Perlbal will only route client requests to backends that it knows are real processes, instead of the OS listen queue. It will attempt to reuse pre-verified backends, and will attempt to create slightly more idle connections than it needs in preparation of future requests.
+
+When you put all this together, it becomes less likely that a client will wait for Perlbal to find an available backend. By setting your MaxClients properly, backends are able to serve traffic without getting overwhelmed. If no backends are available, Perlbal will queue them internally, rather than overload backends.
+
+You would want to disable C<verify_backend> if you are balancing across image servers, or other extremely lightweight requests.
+
+
=head2 SEE ALSO
L<Perlbal::Manual::Configuration>,
View
2 lib/Perlbal/Manual/Management.pod
@@ -200,6 +200,8 @@ Unsetting the file to autoload nodes from (note that this does not remove curren
C<undef>, C<null>, "" and '' are interpreted just like C<none>.
+Note that manually modifying the pool (via POOL ADD or POOL REMOVE) will disable the periodic checking of the nodefile.
+
Setting the load balancing method:
SET pool balance_method = 'random'
View
3 lib/Perlbal/Manual/Plugins.pod
@@ -62,6 +62,7 @@ A Perlbal plugin consists in a package under the C<Perlbal::Plugin> namespace th
These steps and functions (plus some helper functions you can define or use) are described below.
+PLEASE KEEP IN MIND: Perlbal is a single-process, asynchronous web server. You must not do things in plugins which will cause it to block, or no other requests can be served at the same time.
=head3 Creating a package
@@ -238,7 +239,7 @@ C<check_type> can also contain a code reference that will be used to validate th
...
},
-This code reference should return a true of false value. If returning false, the contents of C<$emesg> (which is passed as a reference to the function) will be used as the error message.
+This code reference should return a true or false value. If returning false, the contents of C<$emesg> (which is passed as a reference to the function) will be used as the error message.
Here's a better explanation of the acceptable values for C<check_type>:
View
6 lib/Perlbal/Manual/ReverseProxy.pod
@@ -65,7 +65,7 @@ Default is 100k.
=item B<buffer_size> = size
-How much ahead of a client we'll get while copying from a backend to a client. If a client gets behind this much, we stop reading from the backend for a bit.
+How much ahead of a client we'll get while copying from a backend to a client. If a client gets behind this much, we stop reading from the backend for a bit. Once all remaining data fits in the buffer, the backend is released and may be reused.
Default is 256k.
@@ -170,7 +170,7 @@ See L<Perlbal::Manual::HighPriority> for more information.
=item B<idle_timeout> = int
-Timeout in seconds for idle connections to the end user.
+Timeout in seconds for idle connections to the end user. It's also the limit for how long a backend may take to respond or transfer data.
Default is 30.
@@ -330,7 +330,7 @@ Let's assume, for simplification purposes, that your service only has one server
=item * Perlbal starts
-1 connection is opened (because of C<connect_ahead>'s value).
+No connections open until the very first request comes in (this may change in the future).
=item * one requests arrives
View
184 lib/Perlbal/Manual/ToDo.pod
@@ -1,184 +0,0 @@
-=head1 NAME
-
-Perlbal::Manual::ToDo - Perlbal's To-Do list
-
-
-=head2 VERSION
-
-Perlbal 1.76.
-
-
-=head2 DESCRIPTION
-
-A wish-list/roadmap/to-do-list for Perlbal.
-
-
-=head2 To do items
-
-The following are possible to-do items for Perlbal:
-
-
-=over 4
-
-=item Re: TCP resets in response to HEAD requests
-
- http://rt.livejournal.org/Ticket/Display.html?id=261
-
-=item perlbal idea: X-Pick-Backend header (fwd)
-
- http://rt.livejournal.org/Ticket/Display.html?id=326
-
-=item Perlbal rate limiting patch (fwd)
-
- http://rt.livejournal.org/Ticket/Display.html?id=342
-
-=item Perlbal hook to modify response headers before getting sent to client
-
- http://rt.livejournal.org/Ticket/Display.html?id=589
-
-=item sendmail from perlbal?
-
- http://rt.livejournal.org/Ticket/Display.html?id=686
-
-=item Perlbal's SSL blocks during connect?
-
- http://rt.livejournal.org/Ticket/Display.html?id=729
-
-=item window sizes, so_recvbuf
-
- http://rt.livejournal.org/Ticket/Display.html?id=1225
-
-=item perlbal memory leaks --- need to add watches
-
- http://rt.livejournal.org/Ticket/Display.html?id=1693
-
-=item Perlbal memory leak / spin on no servers in pool
-
- http://rt.livejournal.org/Ticket/Display.html?id=1698
-
-=item non-blocking SSL from DJabberd
-
- http://rt.livejournal.org/Ticket/Display.html?id=1995
-
-=item Perlbal with Danga::Socket and IO::KQueue
-
- http://rt.livejournal.org/Ticket/Display.html?id=2761
-
-=item Track disconnects from backends
-
- http://rt.livejournal.org/Ticket/Display.html?id=2769
-
-=item Allow option to say O_EXCL for PUTs
-
- http://rt.livejournal.org/Ticket/Display.html?id=2772
-
-=item reduce system calls (epoll_ctl, socket creation, corking)
-
- http://rt.livejournal.org/Ticket/Display.html?id=2773
-
-=item Allow configurable response code that means 'backend dead; replay request'
-
- http://rt.livejournal.org/Ticket/Display.html?id=2774
-
-=item Proxying TCP (non-HTTP) services
-
- http://rt.livejournal.org/Ticket/Display.html?id=2775
-
-=item more global & per node/service/pool bytes in/out
-
- http://rt.livejournal.org/Ticket/Display.html?id=2776
-
-=item make the response-code-tracking-per-ipport a plugin, not on by default
-
- http://rt.livejournal.org/Ticket/Display.html?id=2777
-
-=item pidfile writing
-
- http://rt.livejournal.org/Ticket/Display.html?id=2778
-
-=item acl stuff
-
- http://rt.livejournal.org/Ticket/Display.html?id=2779
-
-=item CREATE SERVICE foo LIKE webserver
-
- http://rt.livejournal.org/Ticket/Display.html?id=2780
-
-=item HTTP::Request (and other LWP/etc stuff) is required for make test but not the rest of the app. fix that one way or another.
-
- http://rt.livejournal.org/Ticket/Display.html?id=2781
-
-=item ProxyPassReverse-like system
-
- http://rt.livejournal.org/Ticket/Display.html?id=2782
-
-=item getter commands to retrieve the running config (GET?) or DUMP/SHOW/LIST
-
- http://rt.livejournal.org/Ticket/Display.html?id=2783
-
-=item add tests for 'trusted_upstream_proxies' and 'always_trusted'
-
- http://rt.livejournal.org/Ticket/Display.html?id=2784
-
-=item get rid of httpres vs. res distinction in HTTPHeaders
-
- http://rt.livejournal.org/Ticket/Display.html?id=2785
-
-=item verify that we support all the HTTP methods that subversion needs
-
- http://rt.livejournal.org/Ticket/Display.html?id=2786
-
-=item secure downloads
-
- http://rt.livejournal.org/Ticket/Display.html?id=2787
-
-=item perlbal needs "SERVER" command to drop root and change to another user
-
- http://rt.livejournal.org/Ticket/Display.html?id=2827
-
-=item in SSL mode, when role is web_server, you can't sendfile()!
-
- http://rt.livejournal.org/Ticket/Display.html?id=3666
-
-=item cacheable header perlbal plugin
-
- http://rt.livejournal.org/Ticket/Display.html?id=4045
-
-=item content caching perlbal plugin
-
- http://rt.livejournal.org/Ticket/Display.html?id=4046
-
-=item IP scoring to assist throttling IPs
-
- http://rt.livejournal.org/Ticket/Display.html?id=4047
-
-=item header counting and display perlbal plugin
-
- http://rt.livejournal.org/Ticket/Display.html?id=4048
-
-=item max conns to backend limit
-
- http://rt.livejournal.org/Ticket/Display.html?id=4052
-
-=item make AccessControl plugin efficient with tons of rules
-
- http://rt.livejournal.org/Ticket/Display.html?id=4134
-
-=item perlbal: fix Undef client_ip errors
-
- http://rt.livejournal.org/Ticket/Display.html?id=4345
-
-=item perlbal: fix "Use of uninitialized value in (split|bitwise|string)"
-
- http://rt.livejournal.org/Ticket/Display.html?id=4346
-
-=item Perlbal closes connection on some AJAX requests
-
- http://rt.livejournal.org/Ticket/Display.html?id=4429
-
-=back
-
-
-=head2 SEE ALSO
-
-L<Perlbal::Manual::Contributing>.

0 comments on commit ca06362

Please sign in to comment.