Permalink
Browse files

Initial documentation import

  • Loading branch information...
1 parent 1c94b9d commit b7258b45435e6eec9c9adc752089571a724ece8f @cog cog committed with dormando Dec 20, 2010
View
305 README
@@ -0,0 +1,305 @@
+ Perlbal
+
+ Version 1.76
+
+ 18th June 2010
+
+ Copyright 2004, Danga Interactive, Inc.
+ Copyright 2005-2010, Six Apart, Ltd.
+
+ You can use and redistribute Perlbal under the same terms as Perl itself.
+
+ http://www.danga.com/perlbal/
+
+
+INSTALLATION
+------------
+
+If you have CPAN installed you can install Perlbal from the command line:
+
+ $ cpan Perlbal
+
+See Perlbal::Manual::Install for further information on installing Perlbal,
+including instructions for specific operating systems and some
+troubleshooting (the file lives under lib/Perlbal/Manual/Install.pod, it is
+recommended that you read it using perldoc).
+
+
+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.
+
+Perlbal is a single-threaded event-based server supporting HTTP load
+balancing, web serving, and a mix of the two (see below).
+
+Almost everything in Perlbal can be configured or reconfigured on the fly
+without needing to restart the software (see Perlbal::Manual::Management).
+
+In this file you'll find:
+
+ * GENERAL FEATURES
+ * PERFORMANCE
+ * STATISTICS AND MONITORING
+ * PLUGINS (EXTENSIBILITY)
+ * FURTHER DOCUMENTATION
+ * SUPPORT
+ * CONTRIBUTING
+
+
+GENERAL FEATURES
+----------------
+
+Perlbal has many features; this is just a short list of some of them:
+
+
+Role: Reverse Proxy
+
+ * Maintains pool of connected backend connections to reduce turnover
+
+ * Gets list of nodes either from asynchronously monitored node file, or
+ from in-server pool objects which you can add/remove nodes from
+ using the management interface
+
+ * Intelligent load balancing based on what backend connections are free
+ for a new request. No unreliable "weighting" numbers required
+
+ * Can verify (using a quick OPTIONS request) that a backend connection is
+ talking to a webserver and not just the kernel's listen queue before
+ sending client requests at it. Lower latency for the client
+
+ * Has a high priority queue for sending requests through to backends quickly
+
+ o Uses cookies to determine if a request should go to fast queue
+ (configurable)
+
+ o Highpri (high priority) plugin supports making requests high
+ priority by URI or Host
+
+ o Can specify a relief level to let low priority requests through to
+ prevent starvation
+
+ * Can allow X-Forwarded-For (and similar) headers from client based on
+ client IP
+
+ * Configurable header management before sending request to backend
+
+ * Internal redirection to file or URL(s)
+
+ o Big one for us; a backend can instruct Perlbal to fetch the user's
+ data from a completely separate server and port and URL, 100%
+ transparent to the user
+
+ 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
+
+ * Persistent client connections (configurable)
+
+ * Persistent backend connections (shared by multiple clients;
+ no "backend waste")
+
+
+Role: Web Server
+
+ * Listen on a port, share from a directory
+
+ * Directory indexing
+
+ * Byte range support (clients can resume downloads)
+
+ * Can have directory index requests fall back to index file list
+
+ o I.e., requests for /foo/ go to /foo/index.html instead
+
+ o Multiple index files supported, tries one at a time until it finds
+ one
+
+ * Persistent client connections (configurable)
+
+ * Almost all disk operations are done asynchronously as to not stall the
+ event loop
+
+ * Configurable support for storing files (PUT, DELETE support)
+
+
+PERFORMANCE
+-------------
+
+ * Great performance "out-of-the-box" (for both small and large sites)
+
+ * 100% asynchronous in all the recommended use cases
+
+ * Lightweight
+
+ * HTTP Header processing (optionally) done in C with
+ Perlbal::XS::HTTPHeaders for maximum performance
+
+ * Event-based using epoll or kqueue to avoid the scalability problems of
+ not-so-modern systems
+
+
+STATISTICS AND MONITORING
+-------------------------
+
+Perlbal's management interface provides extremely detailed and powerful
+statistics in addition to runtime configuration. For example:
+
+ * CPU usage (user, system)
+
+ * Total requests served across all services
+
+ * Requests service by individual backends
+
+ * Perlbal's uptime
+
+ * All connected sockets (and tons of info about each)
+
+ * Outstanding connections to backends
+
+ * Backends that have recently failed verification
+
+ * Pending backend connections by service
+
+ * Total of all socket states by socket type
+
+ * Size (in seconds and number of connections) of all queues
+
+ * State of reproxy engine (queued requests, outstanding requests,
+ backends)
+
+ * Loaded plugins per service
+
+(All statistics are in machine readable form, easy to parse and write scripts
+that check on the status of Perlbal)
+
+
+PLUGINS (EXTENSIBILITY)
+-----------------------
+
+Perlbal supports the concept of having per-service (and global) plugins that
+can add functionality or override many parts of request handling and behavior.
+There are many custom plugins that send new headers to the backends, promote
+requests to the fast queue, maintain more detailed statistics, do image
+header manipulation, and more.
+
+The following is a list of known plugins. Most of these are shipped with Perlbal
+itself; the others can be easily attained through CPAN.
+
+ * Perlbal::Plugin::AccessControl
+
+ * Perlbal::Plugin::Addheader
+
+ * Perlbal::Plugin::AutoRemoveLeadingDir
+
+ * Perlbal::Plugin::BackendHeaders
+
+ * Perlbal::Plugin::Cgilike
+
+ * Perlbal::Plugin::EchoService
+
+ * Perlbal::Plugin::ExpandSSL
+
+ * Perlbal::Plugin::ForwardedFor
+
+ * Perlbal::Plugin::Highpri
+
+ * Perlbal::Plugin::Include
+
+ * Perlbal::Plugin::LazyCDN
+
+ * Perlbal::Plugin::MaxContentLength
+
+ * Perlbal::Plugin::NotModified
+
+ * Perlbal::Plugin::PSGI
+
+ * Perlbal::Plugin::Palimg
+
+ * Perlbal::Plugin::Queues
+
+ * Perlbal::Plugin::Redirect
+
+ * Perlbal::Plugin::Stats
+
+ * Perlbal::Plugin::StickySessions
+
+ * Perlbal::Plugin::TrustHeader
+
+ * Perlbal::Plugin::UrlGroup
+
+ * Perlbal::Plugin::Vhosts
+
+ * Perlbal::Plugin::Vpaths
+
+Writing your own plugins is also easy.
+
+For more information on how plugins work, see Perlbal::Manual::Plugins.
+
+
+FURTHER DOCUMENTATION
+---------------------
+
+Perlbal's documentation is split into several sections under
+Perlbal::Manual::*.
+
+Perlbal::Manual provides the index for the manual:
+
+ perldoc Perlbal::Manual
+
+Individual sections can be viewed in the same manner:
+
+ perldoc Perlbal::Manual::Configuration
+ perldoc Perlbal::Manual::LoadBalancer
+ perldoc Perlbal::Manual::Plugins
+
+If you're interested in the internals of the Perlbal:
+
+ perldoc Perlbal::Manual::Internals
+
+The documentation is relatively new (December 2010) and was mostly written
+or gathered by Bruno Martins and José Castro under a TPF grant. You can read
+more about it at http://7eip.sl.pt and http://4hw3.sl.pt.
+
+
+SUPPORT
+-------------
+
+Feel free to ask us questions on the mailing list:
+
+ http://groups.google.com/group/perlbal
+
+There are also the old Perlbal List Archives for postings until June 2008:
+
+ http://lists.danga.com/pipermail/perlbal/
+
+
+CONTRIBUTING
+-------------
+
+You may find information on how to contribute under
+Perlbal::Manual::Contributing.
+
+The source code currently resides in https://github.com/perlbal/Perlbal
+
+
+AUTHOR
+-------------
+
+Perlbal was originally written by Brad Fitzpatrick and counts with the help
+and contributions from many other people.
+
+See Perlbal::Manual::Credits for details.
+
+
+COPYRIGHT
+-------------
+
+Copyright 2004, Danga Interactive, Inc. Copyright 2005-2010, Six Apart, Ltd.
+
+You can use and redistribute Perlbal under the same terms as Perl itself.
View
@@ -0,0 +1,91 @@
+=head1 NAME
+
+Perlbal::FAQ - Frequently Asked Questions about Perlbal
+
+
+=head2 VERSION
+
+Perlbal 1.76.
+
+
+=head2 DESCRIPTION
+
+This document aims at listing several Frequently Asked Questions regarding Perlbal.
+
+
+=head2 Configuring Perlbal
+
+=head3 Is there a sample C<perlbal.*> I can use for my C<init.d>?
+
+Yes, you can find one under C<debian/perlbal.init>. It implements C<start>, C<stop> and C<restart/force-reload>. Make sure you adjust it to your particular taste and/or needs.
+
+
+=head3 Is there a way to make perlbal re-read the config file without shuting it down?
+
+No, there is not. But typically, if you're making changes, you can just make them on the management console, which doesn't require any restart whatsoever.
+
+Still, restarting is probably easy. The trick to it is to simulate a graceful restart.
+
+
+=head3 How can I implement a graceful restart?
+
+Here's a sample script that will allow you to perform a graceful restart:
+
+ $ cat restart-perlbal.sh
+ echo "shutdown graceful" | nc localhost 60000
+ /usr/local/bin/perlbal --conf=/etc/perlbal.conf
+
+The idea is that you tell the old Perlbal to do a graceful shutdown; that immediately closes all of the listening sockets, so new connections are not accepted. As soon as that's done (which is instant) you can start up a new Perlbal.
+
+This gives you a minimum of downtime that can be measured on the order of milliseconds (the time it takes for the new Perlbal to start up).
+
+Remember that you need to have a C<management> service listening on port 60000 for this example to work. See L<Perlbal::Manual::Management>.
+
+
+=head2 Load Balancing
+
+=head3 What balancing algorithm does Perlbal use?
+
+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.
+
+
+=head2 Plugins
+
+=head3 Can I influence the order plugins are used?
+
+Yes. When you set the plugins for your service they get to register their hooks in order.
+
+ SET plugins = AccessControl HighPri
+
+These hooks are pushed into an array, which means that they preserve the order of the plugins.
+
+
+=head2 HTTP, SSL
+
+=head3 Does perlbal support HTTP 1.1?
+
+Perlbal for the most part only speaks HTTP/1.0 both to clients and to backend webservers. It happily takes requests advertising HTTP/1.1 and downgrading them to HTTP/1.0 when speaking to backend serves.
+
+It knows all about persistent connections (in both 1.0 and 1.1) and will reply with HTTP/1.0 Connection: keep-alive the request was only implicitly keep-alive with HTTP/1.1. etc.
+
+Perlbal is now also starting to speak more of 1.1. For instance, Perlbal does support receiving transfer-encoding "chunked" requests from clients (a feature of HTTP/1.1), will send a C<100 Continue> in response to C<Expect: 100-continue>, and will parse the chunked requests, writing the request-of-unknown-length to disk (only if C<buffered_uploads> is enabled), and then will send an HTTP/1.0 request to the backends, with the actual C<Content-Length> (now known) filled in.
+
+When more of 1.1 is supported, it will become an option, and later become the default. However, after several years of usage, there just hasn't been that much of a reason. The chunked requests (common from mobile phones uploading large images) has been the most annoying shortcoming but now that it's solved, it's questionable whether or not more of HTTP/1.1 will be supported.
+
+
+=head3 Does perlbal support SSL?
+
+Yes. To use SSL mode you'll need L<IO::Socket::SSL> C<v0.97+> installed.
+
+You can do SSL either on C<web_server>, C<reverse_proxy> or C<selector> modes, but not on a vhost-based C<selector> service, because SSL and vhosts aren't compatible.
+
+See the configuration file F<ssl.conf> under F<conf/> for an example.
+
+
+=head2 SEE ALSO
+
+L<Perlbal::Manual>.
Oops, something went wrong.

0 comments on commit b7258b4

Please sign in to comment.