| .TH ab 8 "February 2004" |
| .\" Licensed to the Apache Software Foundation (ASF) under one or more |
| .\" contributor license agreements. See the NOTICE file distributed with |
| .\" this work for additional information regarding copyright ownership. |
| .\" The ASF licenses this file to You under the Apache License, Version 2.0 |
| .\" (the "License"); you may not use this file except in compliance with |
| .\" the License. You may obtain a copy of the License at |
| .\" |
| .\" http://www.apache.org/licenses/LICENSE-2.0 |
| .\" |
| .\" Unless required by applicable law or agreed to in writing, software |
| .\" distributed under the License is distributed on an "AS IS" BASIS, |
| .\" WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| .\" See the License for the specific language governing permissions and |
| .\" limitations under the License. |
| .\" |
| .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 " Authenticate username:password" |
| ] [ |
| .BI \-X " proxy [ :port ]" |
| ] [ |
| .BI \-P " Proxy Authenticate username:password" |
| ] [ |
| .BI \-H " Custom header" |
| ] [ |
| .BI \-C " Cookie name=value" |
| ] [ |
| .BI \-T " content-type" |
| ] [ |
| .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 the performance of your Apache HyperText Transfer |
| Protocol (HTTP) server. It does this by giving you an indication of how |
| many requests per second your Apache installation can serve. |
| .PP |
| .SH OPTIONS |
| .TP 12 |
| .B \-k |
| Enable the HTTP KeepAlive feature; that is, perform multiple requests |
| within one HTTP session. Default is no KeepAlive. |
| .TP 12 |
| .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 (ab -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. |
| .B \-i |
| Use an HTTP 'HEAD' instead of the GET method. Cannot be mixed with POST. |
| .TP 12 |
| .BI \-n " requests" |
| The number of requests to perform for the benchmarking session. The |
| default is to perform just one single request, which will not give |
| representative benchmarking results. |
| .TP 12 |
| .BI \-t " timelimit" |
| The number of seconds to spend benchmarking. Using this option automatically |
| set the number of requests for the benchmarking session to 50000. |
| Use this to benchmark the server for a fixed period of time. By |
| default, there is no timelimit. |
| .TP 12 |
| .BI \-c " concurrency" |
| The number of simultaneous requests to perform. The default is to |
| perform one HTTP request at at time, that is, no concurrency. |
| |
| .TP 12 |
| .BI \-p " POST file" |
| A file containing data that the program will send to the Apache server in |
| any HTTP POST requests. |
| |
| .TP 12 |
| .BI \-A " Authorization username:password" |
| Supply Basic Authentication credentials to the server. The username |
| and password are separated by a single ':', and sent as uuencoded data. |
| The string is sent regardless of whether the server needs it; that is, |
| has sent a 401 Authentication needed. |
| |
| .TP 12 |
| .BI \-X " proxy[:port]" |
| Route all requests through the proxy (at optional port). |
| |
| .TP 12 |
| .BI \-P " Proxy-Authorization username:password" |
| Supply Basic Authentication credentials to a proxy en-route. The username |
| and password are separated by a single ':', and sent as uuencoded data. |
| The string is sent regardless of whether the proxy needs it; that is, |
| has sent a 407 Proxy authentication needed. |
| |
| .TP 12 |
| .BI \-C " Cookie name=value" |
| Add a 'Cookie:' line to the request. The argument is typically |
| a 'name=value' pair. This option may be repeated. |
| |
| .TP 12 |
| .BI \-p " Header string" |
| Append extra headers to the request. The argument is typically in the form |
| of a valid header line, usually a colon separated field value pair, for |
| example, 'Accept-Encoding: zip/zop;8bit'. |
| |
| .TP 12 |
| .BI \-T " content-type" |
| The 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 Excel. 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 |
| Sets the verbosity level. Level 4 and above prints information on headers, |
| level 3 and above prints response codes (for example, 404, 200), and level 2 |
| and above prints warnings and informational messages. |
| |
| .TP 12 |
| .BI \-w |
| Print out results in HTML tables. The default table is two columns wide, |
| with a white background. |
| .TP 12 |
| .BI \-x " attributes" |
| The string to use as attributes for <table>. Attributes are inserted |
| <table |
| .B here |
| > |
| .TP 12 |
| .BI \-y " attributes" |
| The string to use as attributes for <tr>. |
| .TP 12 |
| .BI \-z " attributes" |
| The string to use as attributes for <td>. |
| .TP 12 |
| .B \-V |
| Display the 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 inefficient parsing of the command line arguments, the response headers |
| from the server, and other external inputs, these buffers might overflow. |
| .P |
| .B Ab |
| does not implement HTTP/1.x fully; instead, it only accepts |
| some 'expected' forms of responses. |
| .P |
| The rather heavy use of |
| .BR strstr(3) |
| by the program may skew performance results, since it uses significant |
| CPU resources. Make sure that performance limits are not hit by |
| .B ab |
| before your server's limit is reached. |
| .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 too low for most measurements; |
| as a single timeout (which is usually in the order of seconds) |
| will shift several thousands of millisecond responses by a |
| considerable factor. This was further componded by a serious |
| integer 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 for solving this riddle. |
| |
| .SH SEE ALSO |
| .BR httpd(8) |
| . |