README

   1                                  Perlbal
   2
   3                   Copyright 2004, Danga Interactive, Inc.
   4                    Copyright 2005-2010, Six Apart, Ltd.
   5
   6   You can use and redistribute Perlbal under the same terms as Perl itself.
   7
   8                       http://www.danga.com/perlbal/
   9
  10
  11 INSTALLATION
  12 ------------
  13
  14 If you have CPAN installed you can install Perlbal from the command line:
  15
  16     $ cpan Perlbal
  17
  18 See Perlbal::Manual::Install for further information on installing Perlbal,
  19 including instructions for specific operating systems and some
  20 troubleshooting (the file lives under lib/Perlbal/Manual/Install.pod, it is
  21 recommended that you read it using perldoc).
  22
  23
  24 DESCRIPTION
  25 -----------
  26
  27 Perlbal is a Perl-based reverse proxy load balancer and web server.
  28
  29 It processes hundreds of millions of requests a day just for LiveJournal,
  30 TypePad and dozens of other high-traffic websites.
  31
  32 Perlbal is a single-threaded event-based server supporting HTTP load
  33 balancing, web serving, and a mix of the two (see below).
  34
  35 Almost everything in Perlbal can be configured or reconfigured on the fly
  36 without needing to restart the software (see Perlbal::Manual::Management).
  37
  38 In this file you'll find:
  39
  40     * GENERAL FEATURES
  41     * PERFORMANCE
  42     * STATISTICS AND MONITORING
  43     * PLUGINS (EXTENSIBILITY)
  44     * FURTHER DOCUMENTATION
  45     * SUPPORT
  46     * CONTRIBUTING
  47
  48
  49 GENERAL FEATURES
  50 ----------------
  51
  52 Perlbal has many features; this is just a short list of some of them:
  53
  54
  55 Role: Reverse Proxy
  56
  57     * Maintains pool of connected backend connections to reduce turnover
  58
  59     * Gets list of nodes either from asynchronously monitored node file, or
  60         from in-server pool objects which you can add/remove nodes from
  61         using the management interface
  62
  63     * Intelligent load balancing based on what backend connections are free
  64         for a new request. No unreliable "weighting" numbers required
  65
  66     * Can verify (using a quick OPTIONS request) that a backend connection is
  67         talking to a webserver and not just the kernel's listen queue before
  68         sending client requests at it. Lower latency for the client
  69
  70     * Has a high priority queue for sending requests through to backends quickly
  71
  72           o Uses cookies to determine if a request should go to fast queue
  73             (configurable)
  74
  75           o Highpri (high priority) plugin supports making requests high
  76             priority by URI or Host
  77
  78           o Can specify a relief level to let low priority requests through to
  79             prevent starvation
  80
  81     * Can allow X-Forwarded-For (and similar) headers from client based on
  82         client IP
  83
  84     * Configurable header management before sending request to backend
  85
  86     * Internal redirection to file or URL(s)
  87
  88           o Big one for us; a backend can instruct Perlbal to fetch the user's
  89             data from a completely separate server and port and URL, 100%
  90             transparent to the user
  91
  92           o Can actually give Perlbal a list of URLs to try. Perlbal will find
  93             one that's alive. Again, the end user sees no redirects happening
  94
  95           o Can also redirect to a local file, which Perlbal will serve
  96             non-blocking. See webserver mode below
  97
  98     * Persistent client connections (configurable)
  99
 100     * Persistent backend connections (shared by multiple clients;
 101         no "backend waste")
 102
 103
 104 Role: Web Server
 105
 106     * Listen on a port, share from a directory
 107
 108     * Directory indexing
 109
 110     * Byte range support (clients can resume downloads)
 111
 112     * Can have directory index requests fall back to index file list
 113
 114           o I.e., requests for /foo/ go to /foo/index.html instead
 115
 116           o Multiple index files supported, tries one at a time until it finds
 117             one
 118
 119     * Persistent client connections (configurable)
 120
 121     * Almost all disk operations are done asynchronously as to not stall the
 122     event loop
 123
 124     * Configurable support for storing files (PUT, DELETE support)
 125
 126
 127 PERFORMANCE
 128 -------------
 129
 130     * Great performance "out-of-the-box" (for both small and large sites)
 131
 132     * 100% asynchronous in all the recommended use cases
 133
 134     * Lightweight
 135
 136     * HTTP Header processing (optionally) done in C with
 137         Perlbal::XS::HTTPHeaders for maximum performance
 138
 139     * Event-based using epoll or kqueue to avoid the scalability problems of
 140         not-so-modern systems
 141
 142
 143 STATISTICS AND MONITORING
 144 -------------------------
 145
 146 Perlbal's management interface provides extremely detailed and powerful
 147 statistics in addition to runtime configuration. For example:
 148
 149     * CPU usage (user, system)
 150
 151     * Total requests served across all services
 152
 153     * Requests service by individual backends
 154
 155     * Perlbal's uptime
 156
 157     * All connected sockets (and tons of info about each)
 158
 159     * Outstanding connections to backends
 160
 161     * Backends that have recently failed verification
 162
 163     * Pending backend connections by service
 164
 165     * Total of all socket states by socket type
 166
 167     * Size (in seconds and number of connections) of all queues
 168
 169     * State of reproxy engine (queued requests, outstanding requests,
 170         backends)
 171
 172     * Loaded plugins per service
 173
 174 (All statistics are in machine readable form, easy to parse and write scripts
 175 that check on the status of Perlbal)
 176
 177
 178 PLUGINS (EXTENSIBILITY)
 179 -----------------------
 180
 181 Perlbal supports the concept of having per-service (and global) plugins that
 182 can add functionality or override many parts of request handling and behavior.
 183 There are many custom plugins that send new headers to the backends, promote
 184 requests to the fast queue, maintain more detailed statistics, do image
 185 header manipulation, and more.
 186
 187 Writing your own plugins is also easy.
 188
 189 For more information on how plugins work, and a list of known plugins see Perlbal::Manual::Plugins. You may also find them easily on CPAN.
 190
 191
 192 FURTHER DOCUMENTATION
 193 ---------------------
 194
 195 Perlbal's documentation is split into several sections under
 196 Perlbal::Manual::*.
 197
 198 Perlbal::Manual provides the index for the manual:
 199
 200     perldoc Perlbal::Manual
 201
 202 Individual sections can be viewed in the same manner:
 203
 204     perldoc Perlbal::Manual::Configuration
 205     perldoc Perlbal::Manual::LoadBalancer
 206     perldoc Perlbal::Manual::Plugins
 207
 208 If you're interested in the internals of the Perlbal:
 209
 210     perldoc Perlbal::Manual::Internals
 211
 212 The documentation is relatively new (December 2010) and was mostly written
 213 or gathered by Bruno Martins and José Castro under a TPF grant. You can read
 214 more about it at http://7eip.sl.pt and http://4hw3.sl.pt.
 215
 216
 217 SUPPORT
 218 -------------
 219
 220 Feel free to ask us questions on the mailing list:
 221
 222     http://groups.google.com/group/perlbal
 223
 224 There are also the old Perlbal List Archives for postings until June 2008:
 225
 226     http://lists.danga.com/pipermail/perlbal/
 227
 228
 229 CONTRIBUTING
 230 -------------
 231
 232 You may find information on how to contribute under
 233 Perlbal::Manual::Contributing.
 234
 235 The source code currently resides in https://github.com/perlbal/Perlbal
 236
 237
 238 AUTHOR
 239 -------------
 240
 241 Perlbal was originally written by Brad Fitzpatrick and counts with the help
 242 and contributions from many other people.
 243
 244 See Perlbal::Manual::Credits for details.
 245
 246
 247 COPYRIGHT
 248 -------------
 249
 250 Copyright 2004, Danga Interactive, Inc. Copyright 2005-2010, Six Apart, Ltd.
 251
 252 You can use and redistribute Perlbal under the same terms as Perl itself.