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