| .TH ab 1 "March 2000" |
| .\" The Apache Software License, Version 1.1 |
| .\" |
| .\" Copyright (c) 2000-2001 The Apache Software Foundation. All rights |
| .\" reserved. |
| .\" |
| .\" Redistribution and use in source and binary forms, with or without |
| .\" modification, are permitted provided that the following conditions |
| .\" are met: |
| .\" |
| .\" 1. Redistributions of source code must retain the above copyright |
| .\" notice, this list of conditions and the following disclaimer. |
| .\" |
| .\" 2. Redistributions in binary form must reproduce the above copyright |
| .\" notice, this list of conditions and the following disclaimer in |
| .\" the documentation and/or other materials provided with the |
| .\" distribution. |
| .\" |
| .\" 3. The end-user documentation included with the redistribution, |
| .\" if any, must include the following acknowledgment: |
| .\" "This product includes software developed by the |
| .\" Apache Software Foundation (http://www.apache.org/)." |
| .\" Alternately, this acknowledgment may appear in the software itself, |
| .\" if and wherever such third-party acknowledgments normally appear. |
| .\" |
| .\" 4. The names "Apache" and "Apache Software Foundation" must |
| .\" not be used to endorse or promote products derived from this |
| .\" software without prior written permission. For written |
| .\" permission, please contact apache@apache.org. |
| .\" |
| .\" 5. Products derived from this software may not be called "Apache", |
| .\" nor may "Apache" appear in their name, without prior written |
| .\" permission of the Apache Software Foundation. |
| .\" |
| .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED |
| .\" WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
| .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE |
| .\" DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR |
| .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
| .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF |
| .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND |
| .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, |
| .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT |
| .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| .\" SUCH DAMAGE. |
| .\" |
| .\" This software consists of voluntary contributions made by many |
| .\" individuals on behalf of the Apache Software Foundation. For more |
| .\" information on the Apache Software Foundation, please see |
| .\" <http://www.apache.org/>. |
| .\" |
| .SH NAME |
| ab \- Apache HTTP server benchmarking tool |
| .SH SYNOPSIS |
| .B ab |
| [ |
| .B \-k |
| ] [ |
| .B \-e |
| ] [ |
| .B \-q |
| ] [ |
| .B \-S |
| ] [ |
| .B \-i |
| ] [ |
| + .B \-s |
| ] [ |
| .BI \-n " requests" |
| ] [ |
| .BI \-t " timelimit" |
| ] [ |
| .BI \-c " concurrency" |
| ] [ |
| .BI \-p " POST file" |
| ] [ |
| .BI \-A " Authentication username:password" |
| ] [ |
| .BI \-P " Proxy Authentication username:password" |
| ] [ |
| .BI \-H " Custom header" |
| ] [ |
| .BI \-C " Cookie name=value" |
| ] [ |
| .BI \-T " content-type" |
| ] [ |
| .BI \-X " proxy [ :port ]" |
| ] [ |
| .BI \-v " verbosity" |
| ] |
| ] [ |
| .BI \-w " output HTML" |
| ] |
| ] [ |
| .BI \-g " output GNUPLOT" |
| ] |
| ] [ |
| .BI \-e " output CSV" |
| ] |
| ] [ |
| .BI \-x " <table> attributes" |
| ] |
| ] [ |
| .BI \-y " <tr> attributes" |
| ] |
| ] [ |
| .BI \-z " <td> attributes" |
| ] |
| .I [http[s]://]hostname[:port]/path |
| |
| .B ab |
| [ |
| .B \-V |
| ] [ |
| .B \-h |
| ] |
| .PP |
| .SH DESCRIPTION |
| .B ab |
| is a tool for benchmarking your Apache HyperText Transfer Protocol (HTTP) |
| server. It is designed to give you an impression of how your current |
| Apache installation performs. This especially shows you how many |
| requests per second your Apache installation is capable of serving. |
| .PP |
| .SH OPTIONS |
| .TP 12 |
| .B \-k |
| Enable the HTTP KeepAlive feature, i.e., perform multiple requests within one |
| HTTP session. Default is no KeepAlive. |
| .TP 12 |
| .BI \-n " requests" |
| Number of requests to perform for the benchmarking session. The default is to |
| just perform a single request which usually leads to non-representative |
| benchmarking results. |
| .TP 12 |
| .BI \-t " timelimit" |
| Maximum number of seconds to spend for benchmarking. This implies |
| .B \-d |
| Do not display the "percentage served within XX [ms] table". (legacy |
| support). |
| .TP 12 |
| .B \-S |
| Do not display the median and standard deviation values, nor display |
| the warning/error messages when the average and median are more than |
| one or two times the standard deviation apart. And default to the |
| min/avg/max values. (legacy support). |
| .TP 12 |
| .B \-s |
| When compiled in (bb -h will show you) use the SSL protected |
| .B https |
| rather than the |
| .B http |
| protocol. This feature is experimental and |
| .B very |
| rudimentary. You propably do not want to use it. |
| .TP 12 |
| .B \-k |
| Enable the HTTP KeepAlive feature; that is, perform multiple requests |
| within one HTTP session. Default is no KeepAlive. |
| a |
| .B \-n |
| .B 50000 |
| internally. Use this to benchmark the server within a fixed total amount of |
| time. Per default there is no timelimit. |
| .TP 12 |
| .BI \-c " concurrency" |
| Number of multiple requests to perform at a time. |
| Default is one request at a time. |
| |
| .TP 12 |
| .BI \-p " POST file" |
| File containing data to POST. |
| |
| .TP 12 |
| .BI \-A " Authentication username:password" |
| Supply BASIC Authentication credentials to the server. The username |
| and password are separated by a single ':' and sent on the wire uuencoded. |
| The string is sent regardless of whether the server needs it; (i.e., has |
| sent an 401 authentication needed). |
| |
| .TP 12 |
| .BI \-X " proxy[:port]" |
| Route all requests through the proxy (at optional port). |
| |
| .TP 12 |
| .BI \-P " Proxy-Authentication username:password" |
| Supply BASIC Authentication credentials to a proxy en-route. The username |
| and password are separated by a single ':' and sent on the wire uuencoded. |
| The string is sent regardless of whether the proxy needs it; (i.e., has |
| sent an 407 proxy authentication needed). |
| |
| .TP 12 |
| .BI \-C " Cookie name=value" |
| Add a 'Cookie:' line to the request. The argument is typically in the form |
| of a 'name=value' pair. This field is repeatable. |
| |
| .TP 12 |
| .BI \-p " Header string" |
| Append extra headers to the request. The argument is typically in the form |
| of a valid header line, containing a colon-separated field-value pair. |
| (i.e., 'Accept-Encoding: zip/zop;8bit'). |
| |
| .TP 12 |
| .BI \-T " content-type" |
| Content-type header to use for POST data. |
| |
| .TP 12 |
| .BI \-g " gnuplot file" |
| Write all measured values out as a 'gnuplot' or TSV (Tab separate values) |
| file. This file can easily be imported into packages like Gnuplot, IDL, Mathematica, |
| Igor or even Excell. The labels are on the first line of the file. |
| |
| .TP 12 |
| .BI \-q |
| When processing more than 150 requsts; |
| .B ab |
| outputs a progress count on |
| .B stderr |
| every 10% or 100 requests or so. The |
| .B -q |
| flag qill suppress these messages. |
| |
| .TP 12 |
| .BI \-e " CSV file" |
| Write a Comma separated value (CSV) file which contains for each |
| percentage (from 1% to 100%) the time (in milli seconds) it took |
| to serve that percentage of the requests. This is usually more |
| usefull than the 'gnuplot' file; as the results are already |
| 'binned'. |
| |
| .TP 12 |
| .B \-v |
| Set verbosity level - 4 and above prints information on headers, 3 and |
| above prints response codes (404, 200, etc.), 2 and above prints |
| warnings and info. |
| |
| .TP 12 |
| .BI \-w |
| Print out results in HTML tables. Default table is two columns wide, |
| with a white background. |
| .TP 12 |
| .BI \-x " attributes" |
| String to use as attributes for <table>. Attributes are inserted |
| <table |
| .B here |
| > |
| .TP 12 |
| .BI \-y " attributes" |
| String to use as attributes for <tr>. |
| .TP 12 |
| .BI \-z " attributes" |
| String to use as attributes for <td>. |
| .TP 12 |
| .B \-V |
| Display version number and exit. |
| .TP 12 |
| .B \-h |
| Display usage information. |
| .PD |
| .SH BUGS |
| There are various statically declared buffers of fixed length. Combined |
| with the lazy parsing of the command line arguments, the response headers |
| from the server and other external inputs, this might bite you. |
| .P |
| It does not implement HTTP/1.x fully; only accepts some 'expected' forms |
| of responses. The rather heavy use of |
| .BR strstr(3) |
| shows up top in profile, |
| which might indicate a performance problem; i.e., you would measure the |
| .BR ab |
| performance rather than the server's. |
| |
| .SH SEE ALSO |
| .BR httpd(8) |
| .P |
| The HTML output is not as complete as the text output. |
| .P |
| Up to version 1.3d |
| .B ab |
| has propably reported values way to low for most measurements; |
| as a single timeout (which is usually in the order of seconds) |
| will shift several thousands of milli-second responses by a |
| considerable factor. This was further componded by a serious |
| interger overrun which would for realistic run's (i.e. those |
| longer than a few minutes) produce believable but totally |
| bogus results. Thanks to Sander Temme <sander@covalent.net> |
| for solving this riddle. |
| . |