ab.xml revision a8e068a3b4c675dfafbb2bd69b045eefd7fc65dd
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny<!DOCTYPE manualpage SYSTEM "/style/manualpage.dtd">
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny<!-- $LastChangedRevision$ -->
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny Licensed to the Apache Software Foundation (ASF) under one or more
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny contributor license agreements. See the NOTICE file distributed with
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny this work for additional information regarding copyright ownership.
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny The ASF licenses this file to You under the Apache License, Version 2.0
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny (the "License"); you may not use this file except in compliance with
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny the License. You may obtain a copy of the License at
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny Unless required by applicable law or agreed to in writing, software
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny distributed under the License is distributed on an "AS IS" BASIS,
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny See the License for the specific language governing permissions and
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny limitations under the License.
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny<parentdocument href="./">Programs</parentdocument>
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce<title>ab - Apache HTTP server benchmarking tool</title>
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny <p><code>ab</code> is a tool for benchmarking your Apache Hypertext
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny Transfer Protocol (HTTP) server. It is designed to give you an impression
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny of how your current Apache installation performs. This especially shows
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny you how many requests per second your Apache installation is capable of
204cfc89a076fd32bf34f2abb3f809304aaa88abSimo Sorce serving.</p>
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny [ -<strong>A</strong> <var>auth-username</var>:<var>password</var> ]
9822d4d468ec74e4e173f5adf0db12d02974cd18Sumit Bose [ -<strong>C</strong> <var>cookie-name</var>=<var>value</var> ]
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny [ -<strong>P</strong> <var>proxy-auth-username</var>:<var>password</var> ]
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce [ -<strong>x</strong> <var><table>-attributes</var> ]
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce [ -<strong>X</strong> <var>proxy</var>[:<var>port</var>] ]
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce [ -<strong>y</strong> <var><tr>-attributes</var> ]
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce [ -<strong>z</strong> <var><td>-attributes</var> ]
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce [http[s]://]<var>hostname</var>[:<var>port</var>]/<var>path</var></code></p>
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny <dt><code>-A <var>auth-username</var>:<var>password</var></code></dt>
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny <dd>Supply BASIC Authentication credentials to the server. The username and
aab938c5975f0e3b85c7c79a5d718e5fefed7217Simo Sorce password are separated by a single <code>:</code> and sent on the wire
aab938c5975f0e3b85c7c79a5d718e5fefed7217Simo Sorce base64 encoded. The string is sent regardless of whether the server needs
aab938c5975f0e3b85c7c79a5d718e5fefed7217Simo Sorce it (<em>i.e.</em>, has sent an 401 authentication needed).</dd>
7fe69bb6ec70bce439c6b975a9a0044c98ff502bSimo Sorce <dd>Size of TCP send/receive buffer, in bytes.</dd>
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny <dt><code>-B <var>local-address</var></code></dt>
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny <dd>Address to bind to when making outgoing connections.</dd>
aab938c5975f0e3b85c7c79a5d718e5fefed7217Simo Sorce <dd>Number of multiple requests to perform at a time. Default is one
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny request at a time.</dd>
aab938c5975f0e3b85c7c79a5d718e5fefed7217Simo Sorce <dt><code>-C <var>cookie-name</var>=<var>value</var></code></dt>
204cfc89a076fd32bf34f2abb3f809304aaa88abSimo Sorce <dd>Add a <code>Cookie:</code> line to the request. The argument is
aab938c5975f0e3b85c7c79a5d718e5fefed7217Simo Sorce typically in the form of a <code><var>name</var>=<var>value</var></code>
aab938c5975f0e3b85c7c79a5d718e5fefed7217Simo Sorce pair. This field is repeatable.</dd>
9822d4d468ec74e4e173f5adf0db12d02974cd18Sumit Bose <dd>Do not display the "percentage served within XX [ms] table". (legacy
9822d4d468ec74e4e173f5adf0db12d02974cd18Sumit Bose support).</dd>
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce <dd>Write a Comma separated value (CSV) file which contains for each
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce percentage (from 1% to 100%) the time (in milliseconds) it took to serve
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce that percentage of the requests. This is usually more useful than the
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce 'gnuplot' file; as the results are already 'binned'.</dd>
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce <dd>Specify SSL/TLS protocol (SSL2, SSL3, TLS1, or ALL).</dd>
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce <dd>Write all measured values out as a 'gnuplot' or TSV (Tab separate
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce values) file. This file can easily be imported into packages like Gnuplot,
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce IDL, Mathematica, Igor or even Excel. The labels are on the first line of
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce the file. </dd>
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce <dt><code>-H <var>custom-header</var></code></dt>
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce <dd>Append extra headers to the request. The argument is typically in
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce the form of a valid header line, containing a colon-separated field-value
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce pair (<em>i.e.</em>, <code>"Accept-Encoding: zip/zop;8bit"</code>).</dd>
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce <dd>Do <code>HEAD</code> requests instead of <code>GET</code>.</dd>
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce <dd>Enable the HTTP KeepAlive feature, <em>i.e.</em>, perform multiple
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce requests within one HTTP session. Default is no KeepAlive.</dd>
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce <dd>Number of requests to perform for the benchmarking session. The default
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce is to just perform a single request which usually leads to
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce non-representative benchmarking results.</dd>
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce <dd>File containing data to POST. Remember to also set <code>-T</code>.</dd>
9822d4d468ec74e4e173f5adf0db12d02974cd18Sumit Bose <dt><code>-P <var>proxy-auth-username</var>:<var>password</var></code></dt>
9822d4d468ec74e4e173f5adf0db12d02974cd18Sumit Bose <dd>Supply BASIC Authentication credentials to a proxy en-route. The
9822d4d468ec74e4e173f5adf0db12d02974cd18Sumit Bose username and password are separated by a single <code>:</code> and sent on
9822d4d468ec74e4e173f5adf0db12d02974cd18Sumit Bose the wire base64 encoded. The string is sent regardless of whether the
9822d4d468ec74e4e173f5adf0db12d02974cd18Sumit Bose proxy needs it (<em>i.e.</em>, has sent an 407 proxy authentication
9822d4d468ec74e4e173f5adf0db12d02974cd18Sumit Bose needed).</dd>
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce <dd>When processing more than 150 requests, <code>ab</code> outputs a
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce progress count on <code>stderr</code> every 10% or 100 requests or so. The
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce <code>-q</code> flag will suppress these messages.</dd>
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce <dd>Maximum number of seconds to wait before the socket times out.
bba1a5fd62cffcae076d1351df5a83fbc4a6ec17Simo Sorce Default is 30 seconds.</dd>
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny <dd>Do not display the median and standard deviation values, nor display
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny the warning/error messages when the average and median are more than
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny one or two times the standard deviation apart. And default to the
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny <dd>Maximum number of seconds to spend for benchmarking. This implies a
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny <code>-n 50000</code> internally. Use this to benchmark the server within a
e76d78338026fa47dca32eaf7f5c15eabb1b951aJan Zeleny fixed total amount of time. Per default there is no timelimit.</dd>
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny <dd>Content-type header to use for POST/PUT data, eg.
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny <dd>File containing data to PUT. Remember to also set <code>-T</code>.</dd>
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny <dd>Set verbosity level - <code>4</code> and above prints information on
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny headers, <code>3</code> and above prints response codes (404, 200, etc.),
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny <code>2</code> and above prints warnings and info.</dd>
65393a294e635822c1d7a15fe5853dc457ad8a2aSimo Sorce <dd>Print out results in HTML tables. Default table is two columns wide,
65393a294e635822c1d7a15fe5853dc457ad8a2aSimo Sorce with a white background.</dd>
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny <dt><code>-x <var><table>-attributes</var></code></dt>
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny <dd>String to use as attributes for <code><table></code>. Attributes
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny are inserted <code><table <var>here</var> ></code>.</dd>
65393a294e635822c1d7a15fe5853dc457ad8a2aSimo Sorce <dt><code>-X <var>proxy</var>[:<var>port</var>]</code></dt>
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny <dt><code>-y <var><tr>-attributes</var></code></dt>
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny <dd>String to use as attributes for <code><tr></code>.</dd>
cb388d52f49f54963379cc20a25e14d17fe6e9a3Simo Sorce <dt><code>-z <var><td>-attributes</var></code></dt>
cb388d52f49f54963379cc20a25e14d17fe6e9a3Simo Sorce <dd>String to use as attributes for <code><td></code>.</dd>
cb388d52f49f54963379cc20a25e14d17fe6e9a3Simo Sorce <dd>Specify SSL/TLS cipher suite (See openssl ciphers)</dd>
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny <p>The following list describes the values returned by <code>ab</code>:
65393a294e635822c1d7a15fe5853dc457ad8a2aSimo Sorce <dd>The value, if any, returned in the <var>server</var> HTTP header
65393a294e635822c1d7a15fe5853dc457ad8a2aSimo Sorce of the first successful response. This includes all characters in the
65393a294e635822c1d7a15fe5853dc457ad8a2aSimo Sorce header from beginning to the point a character with decimal value of 32
65393a294e635822c1d7a15fe5853dc457ad8a2aSimo Sorce (most notably: a space or CR/LF) is detected.</dd>
204cfc89a076fd32bf34f2abb3f809304aaa88abSimo Sorce <dd>The DNS or IP address given on the command line</dd>
204cfc89a076fd32bf34f2abb3f809304aaa88abSimo Sorce <dd>The port to which ab is connecting. If no port is given on the
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny command line, this will default to 80 for http and 443 for
65393a294e635822c1d7a15fe5853dc457ad8a2aSimo Sorce <dd>The protocol parameters negotiated between the client and server.
65393a294e635822c1d7a15fe5853dc457ad8a2aSimo Sorce This will only be printed if SSL is used.</dd>
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny <dd>The request URI parsed from the command line string.</dd>
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny <dd>This is the size in bytes of the first successfully returned document.
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny If the document length changes during testing, the response is
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny considered an error.</dd>
65393a294e635822c1d7a15fe5853dc457ad8a2aSimo Sorce <dd>The number of concurrent clients used during the test</dd>
65393a294e635822c1d7a15fe5853dc457ad8a2aSimo Sorce <dd>This is the time taken from the moment the first socket connection
65393a294e635822c1d7a15fe5853dc457ad8a2aSimo Sorce is created to the moment the last response is received</dd>
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny <dd>The number of successful responses received</dd>
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny <dd>The number of requests that were considered a failure. If the
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny number is greater than zero, another line will be printed showing the
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny number of requests that failed due to connecting, reading, incorrect
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny content length, or exceptions.</dd>
3912262270a6449ebe1d3e92c27c217b4044f894Simo Sorce <dd>The number of errors that failed during write (broken pipe).</dd>
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny <dd>The number of responses that were not in the 200 series of response
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny codes. If all responses were 200, this field is not printed.</dd>
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny <dd>The number of connections that resulted in Keep-Alive requests</dd>
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny <dd>If configured to send data as part of the test, this is the total
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny number of bytes sent during the tests. This field is omitted if the test
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny did not include a body to send.</dd>
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny <dd>The total number of bytes received from the server. This number
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny is essentially the number of bytes sent over the wire.</dd>
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny <dd>The total number of document bytes received from the server. This
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny number excludes bytes received in HTTP headers</dd>
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny <dd>This is the number of requests per second. This value is the result
3912262270a6449ebe1d3e92c27c217b4044f894Simo Sorce of dividing the number of requests by the total time taken</dd>
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny <dd>The average time spent per request. The first value is calculated
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny with the formula <code>concurrency * timetaken * 1000 / done</code>
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny while the second value is calculated with the formula
204cfc89a076fd32bf34f2abb3f809304aaa88abSimo Sorce <dd>The rate of transfer as calculated by the formula
204cfc89a076fd32bf34f2abb3f809304aaa88abSimo Sorce <p>There are various statically declared buffers of fixed length. Combined
3912262270a6449ebe1d3e92c27c217b4044f894Simo Sorce with the lazy parsing of the command line arguments, the response headers
204cfc89a076fd32bf34f2abb3f809304aaa88abSimo Sorce from the server and other external inputs, this might bite you.</p>
204cfc89a076fd32bf34f2abb3f809304aaa88abSimo Sorce <p>It does not implement HTTP/1.x fully; only accepts some 'expected' forms
204cfc89a076fd32bf34f2abb3f809304aaa88abSimo Sorce of responses. The rather heavy use of <code>strstr(3)</code> shows up top
204cfc89a076fd32bf34f2abb3f809304aaa88abSimo Sorce in profile, which might indicate a performance problem; <em>i.e.</em>, you
204cfc89a076fd32bf34f2abb3f809304aaa88abSimo Sorce would measure the <code>ab</code> performance rather than the server's.</p>
3912262270a6449ebe1d3e92c27c217b4044f894Simo Sorce</manualpage>