granicus.if.org Git - apache/blob - docs/manual/programs/ab.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>ab - Apache HTTP server benchmarking tool - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
  12 <script src="../style/scripts/prettify.js" type="text/javascript">
  13 </script>
  14
  15 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  16 <body id="manual-page"><div id="page-header">
  17 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  18 <p class="apache">Apache HTTP Server Version 2.5</p>
  19 <img alt="" src="../images/feather.gif" /></div>
  20 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  21 <div id="path">
  22 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Programs</a></div><div id="page-content"><div id="preamble"><h1>ab - Apache HTTP server benchmarking tool</h1>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="../en/programs/ab.html" title="English">&nbsp;en&nbsp;</a> |
  25 <a href="../ko/programs/ab.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a> |
  26 <a href="../tr/programs/ab.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
  27 </div>
  28
  29     <p><code>ab</code> is a tool for benchmarking your Apache Hypertext
  30     Transfer Protocol (HTTP) server. It is designed to give you an impression
  31     of how your current Apache installation performs. This especially shows
  32     you how many requests per second your Apache installation is capable of
  33     serving.</p>
  34 </div>
  35 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#synopsis">Synopsis</a></li>
  36 <li><img alt="" src="../images/down.gif" /> <a href="#options">Options</a></li>
  37 <li><img alt="" src="../images/down.gif" /> <a href="#output">Output</a></li>
  38 <li><img alt="" src="../images/down.gif" /> <a href="#bugs">Bugs</a></li>
  39 </ul><h3>See also</h3><ul class="seealso"><li><code class="program"><a href="../programs/httpd.html">httpd</a></code></li></ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
  40 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  41 <div class="section">
  42 <h2><a name="synopsis" id="synopsis">Synopsis</a></h2>
  43     <p><code><strong>ab</strong>
  44     [ -<strong>A</strong> <var>auth-username</var>:<var>password</var> ]
  45     [ -<strong>b</strong> <var>windowsize</var> ]
  46     [ -<strong>B</strong> <var>local-address</var> ]
  47     [ -<strong>c</strong> <var>concurrency</var> ]
  48     [ -<strong>C</strong> <var>cookie-name</var>=<var>value</var> ]
  49     [ -<strong>d</strong> ]
  50     [ -<strong>e</strong> <var>csv-file</var> ]
  51     [ -<strong>f</strong> <var>protocol</var> ]
  52     [ -<strong>g</strong> <var>gnuplot-file</var> ]
  53     [ -<strong>h</strong> ]
  54     [ -<strong>H</strong> <var>custom-header</var> ]
  55     [ -<strong>i</strong> ]
  56     [ -<strong>k</strong> ]
  57     [ -<strong>n</strong> <var>requests</var> ]
  58     [ -<strong>p</strong> <var>POST-file</var> ]
  59     [ -<strong>P</strong> <var>proxy-auth-username</var>:<var>password</var> ]
  60     [ -<strong>q</strong> ]
  61     [ -<strong>r</strong> ]
  62     [ -<strong>s</strong> ]
  63     [ -<strong>S</strong> ]
  64     [ -<strong>t</strong> <var>timelimit</var> ]
  65     [ -<strong>T</strong> <var>content-type</var> ]
  66     [ -<strong>u</strong> <var>PUT-file</var> ]
  67     [ -<strong>v</strong> <var>verbosity</var>]
  68     [ -<strong>V</strong> ]
  69     [ -<strong>w</strong> ]
  70     [ -<strong>x</strong> <var>&lt;table&gt;-attributes</var> ]
  71     [ -<strong>X</strong> <var>proxy</var>[:<var>port</var>] ]
  72     [ -<strong>y</strong> <var>&lt;tr&gt;-attributes</var> ]
  73     [ -<strong>z</strong> <var>&lt;td&gt;-attributes</var> ]
  74     [ -<strong>Z</strong> <var>ciphersuite</var> ]
  75     [http[s]://]<var>hostname</var>[:<var>port</var>]/<var>path</var></code></p>
  76 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  77 <div class="section">
  78 <h2><a name="options" id="options">Options</a></h2>
  79     <dl>
  80     <dt><code>-A <var>auth-username</var>:<var>password</var></code></dt>
  81     <dd>Supply BASIC Authentication credentials to the server. The username and
  82     password are separated by a single <code>:</code> and sent on the wire
  83     base64 encoded. The string is sent regardless of whether the server needs
  84     it (<em>i.e.</em>, has sent an 401  authentication needed).</dd>
  85
  86     <dt><code>-b <var>windowsize</var></code></dt>
  87     <dd>Size of TCP send/receive buffer, in bytes.</dd>
  88
  89     <dt><code>-B <var>local-address</var></code></dt>
  90     <dd>Address to bind to when making outgoing connections.</dd>
  91
  92     <dt><code>-c <var>concurrency</var></code></dt>
  93     <dd>Number of multiple requests to perform at a time. Default is one
  94     request at a time.</dd>
  95
  96     <dt><code>-C <var>cookie-name</var>=<var>value</var></code></dt>
  97     <dd>Add a <code>Cookie:</code> line to the request. The  argument  is
  98     typically in the form of a <code><var>name</var>=<var>value</var></code>
  99     pair. This field is repeatable.</dd>
 100
 101     <dt><code>-d</code></dt>
 102     <dd>Do not display the "percentage served within XX [ms] table". (legacy
 103     support).</dd>
 104
 105     <dt><code>-e <var>csv-file</var></code></dt>
 106     <dd>Write a Comma separated value (CSV) file which contains for each
 107     percentage (from 1% to 100%) the time (in milliseconds) it took to serve
 108     that percentage of the requests. This is usually more useful than the
 109     'gnuplot' file; as the results are already 'binned'.</dd>
 110
 111     <dt><code>-f <var>protocol</var></code></dt>
 112     <dd>Specify SSL/TLS protocol (SSL2, SSL3, TLS1, or ALL).</dd>
 113
 114     <dt><code>-g <var>gnuplot-file</var></code></dt>
 115     <dd>Write all measured values out as a 'gnuplot' or TSV (Tab separate
 116     values) file. This file can easily be imported into packages like Gnuplot,
 117     IDL, Mathematica, Igor or even Excel. The labels are on the first line of
 118     the file. </dd>
 119
 120     <dt><code>-h</code></dt>
 121     <dd>Display usage information.</dd>
 122
 123     <dt><code>-H <var>custom-header</var></code></dt>
 124     <dd>Append extra headers to the request.  The  argument  is typically in
 125     the form of a valid header line, containing a colon-separated field-value
 126     pair (<em>i.e.</em>, <code>"Accept-Encoding: zip/zop;8bit"</code>).</dd>
 127
 128     <dt><code>-i</code></dt>
 129     <dd>Do <code>HEAD</code> requests instead of <code>GET</code>.</dd>
 130
 131     <dt><code>-k</code></dt>
 132     <dd>Enable the HTTP KeepAlive feature, <em>i.e.</em>, perform multiple
 133     requests within one HTTP session. Default is no KeepAlive.</dd>
 134
 135     <dt><code>-n <var>requests</var></code></dt>
 136     <dd>Number of requests to perform for the benchmarking session. The default
 137     is to just perform a single request which usually leads to
 138     non-representative benchmarking results.</dd>
 139
 140     <dt><code>-p <var>POST-file</var></code></dt>
 141     <dd>File containing data to POST.  Remember to also set <code>-T</code>.</dd>
 142
 143     <dt><code>-P <var>proxy-auth-username</var>:<var>password</var></code></dt>
 144     <dd>Supply BASIC Authentication credentials to a proxy en-route. The
 145     username and password are separated by a single <code>:</code> and sent on
 146     the  wire base64 encoded. The string is sent regardless of whether the
 147     proxy needs it (<em>i.e.</em>, has  sent an 407 proxy authentication
 148     needed).</dd>
 149
 150     <dt><code>-q</code></dt>
 151     <dd>When processing more than 150 requests, <code>ab</code> outputs a
 152     progress count on <code>stderr</code> every 10% or 100 requests or so. The
 153     <code>-q</code> flag will suppress these messages.</dd>
 154
 155     <dt><code>-r</code></dt>
 156     <dd>Don't exit on socket receive errors.</dd>
 157
 158    <dt><code>-s</code></dt>
 159     <dd>When compiled in (<code>ab -h</code> will show you) use the SSL
 160     protected <code>https</code> rather than the <code>http</code> protocol.
 161     This feature is experimental and <em>very</em> rudimentary. You probably
 162     do not want to use it.</dd>
 163
 164     <dt><code>-S</code></dt>
 165     <dd>Do not display the median and standard deviation values, nor display
 166     the warning/error messages when the average and median are more than
 167     one or two times the standard deviation apart. And default to the
 168     min/avg/max values. (legacy support).</dd>
 169
 170     <dt><code>-t <var>timelimit</var></code></dt>
 171     <dd>Maximum number of seconds to  spend  for  benchmarking. This implies a
 172     <code>-n 50000</code> internally. Use this to benchmark the server within a
 173     fixed total amount of time. Per default there is no timelimit.</dd>
 174
 175     <dt><code>-T <var>content-type</var></code></dt>
 176     <dd>Content-type header to use for POST/PUT data, eg.
 177     <code>application/x-www-form-urlencoded</code>.
 178     Default: <code>text/plain</code>.</dd>
 179
 180     <dt><code>-u <var>PUT-file</var></code></dt>
 181     <dd>File containing data to PUT.  Remember to also set <code>-T</code>.</dd>
 182
 183     <dt><code>-v <var>verbosity</var></code></dt>
 184     <dd>Set verbosity level - <code>4</code> and above prints information on
 185     headers, <code>3</code> and above prints response codes (404, 200, etc.),
 186     <code>2</code> and above prints warnings and info.</dd>
 187
 188     <dt><code>-V</code></dt>
 189     <dd>Display version number and exit.</dd>
 190
 191     <dt><code>-w</code></dt>
 192     <dd>Print out results in HTML tables. Default table is two columns wide,
 193     with a white background.</dd>
 194
 195     <dt><code>-x <var>&lt;table&gt;-attributes</var></code></dt>
 196     <dd>String to use as attributes for <code>&lt;table&gt;</code>. Attributes
 197     are inserted <code>&lt;table <var>here</var> &gt;</code>.</dd>
 198
 199     <dt><code>-X <var>proxy</var>[:<var>port</var>]</code></dt>
 200     <dd>Use a proxy server for the requests.</dd>
 201
 202     <dt><code>-y <var>&lt;tr&gt;-attributes</var></code></dt>
 203     <dd>String to use as attributes for <code>&lt;tr&gt;</code>.</dd>
 204
 205     <dt><code>-z <var>&lt;td&gt;-attributes</var></code></dt>
 206     <dd>String to use as attributes for <code>&lt;td&gt;</code>.</dd>
 207
 208     <dt><code>-Z <var>ciphersuite</var></code></dt>
 209     <dd>Specify SSL/TLS cipher suite (See openssl ciphers)</dd>
 210     </dl>
 211 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 212 <div class="section">
 213 <h2><a name="output" id="output">Output</a></h2>
 214     <p>The following list describes the values returned by <code>ab</code>:
 215     </p>
 216
 217     <dl>
 218         <dt>Server Software</dt>
 219         <dd>The value, if any, returned in the <var>server</var> HTTP header
 220         of the first successful response. This includes all characters in the
 221         header from beginning to the point a character with decimal value of 32
 222         (most notably: a space or CR/LF) is detected.</dd>
 223
 224         <dt>Server Hostname</dt>
 225         <dd>The DNS or IP address given on the command line</dd>
 226
 227         <dt>Server Port</dt>
 228         <dd>The port to which ab is connecting. If no port is given on the
 229         command line, this will default to 80 for http and 443 for
 230         https.</dd>
 231
 232         <dt>SSL/TLS Protocol</dt>
 233         <dd>The protocol parameters negotiated between the client and server.
 234         This will only be printed if SSL is used.</dd>
 235
 236         <dt>Document Path</dt>
 237         <dd>The request URI parsed from the command line string.</dd>
 238
 239         <dt>Document Length</dt>
 240         <dd>This is the size in bytes of the first successfully returned document.
 241         If the document length changes during testing, the response is
 242         considered an error.</dd>
 243
 244         <dt>Concurrency Level</dt>
 245         <dd>The number of concurrent clients used during the test</dd>
 246
 247         <dt>Time taken for tests</dt>
 248         <dd>This is the time taken from the moment the first socket connection
 249         is created to the moment the last response is received</dd>
 250
 251         <dt>Complete requests</dt>
 252         <dd>The number of successful responses received</dd>
 253
 254         <dt>Failed requests</dt>
 255         <dd>The number of requests that were considered a failure. If the
 256         number is greater than zero, another line will be printed showing the
 257         number of requests that failed due to connecting, reading, incorrect
 258         content length, or exceptions.</dd>
 259
 260         <dt>Write errors</dt>
 261         <dd>The number of errors that failed during write (broken pipe).</dd>
 262
 263         <dt>Non-2xx responses</dt>
 264         <dd>The number of responses that were not in the 200 series of response
 265         codes. If all responses were 200, this field is not printed.</dd>
 266
 267         <dt>Keep-Alive requests</dt>
 268         <dd>The number of connections that resulted in Keep-Alive requests</dd>
 269
 270         <dt>Total body sent</dt>
 271         <dd>If configured to send data as part of the test, this is the total
 272         number of bytes sent during the tests. This field is omitted if the test
 273         did not include a body to send.</dd>
 274
 275         <dt>Total transferred</dt>
 276         <dd>The total number of bytes received from the server. This number
 277         is essentially the number of bytes sent over the wire.</dd>
 278
 279         <dt>HTML transferred</dt>
 280         <dd>The total number of document bytes received from the server. This
 281         number excludes bytes received in HTTP headers</dd>
 282
 283         <dt>Requests per second</dt>
 284         <dd>This is the number of requests per second. This value is the result
 285         of dividing the number of requests by the total time taken</dd>
 286
 287         <dt>Time per request</dt>
 288         <dd>The average time spent per request. The first value is calculated
 289         with the formula <code>concurrency * timetaken * 1000 / done</code>
 290         while the second value is calculated with the formula
 291         <code>timetaken * 1000 / done</code></dd>
 292
 293         <dt>Transfer rate</dt>
 294         <dd>The rate of transfer as calculated by the formula
 295         <code>totalread / 1024 / timetaken</code></dd>
 296     </dl>
 297 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 298 <div class="section">
 299 <h2><a name="bugs" id="bugs">Bugs</a></h2>
 300     <p>There are various statically declared buffers of fixed length. Combined
 301     with the lazy parsing of the command line arguments, the response headers
 302     from the server and other external inputs, this might bite you.</p>
 303
 304     <p>It does not implement HTTP/1.x fully; only accepts some 'expected' forms
 305     of responses. The rather heavy use of <code>strstr(3)</code> shows up top
 306     in profile, which might indicate a performance problem; <em>i.e.</em>, you
 307     would measure the <code>ab</code> performance rather than the server's.</p>
 308 </div></div>
 309 <div class="bottomlang">
 310 <p><span>Available Languages: </span><a href="../en/programs/ab.html" title="English">&nbsp;en&nbsp;</a> |
 311 <a href="../ko/programs/ab.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a> |
 312 <a href="../tr/programs/ab.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
 313 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>This section is experimental!</strong><br />Comments placed here should not be expected
 314 to last beyond the testing phase of this system, nor do we in any way guarantee that we'll read them.</div>
 315 <script type="text/javascript"><!--//--><![CDATA[//><!--
 316 var disqus_shortname = 'httpd';
 317 var disqus_identifier = 'http://httpd.apache.org/docs/2.4/programs/ab.html.en';
 318 (function(w, d) {
 319     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 320         d.write('<div id="disqus_thread"><\/div>');
 321         var s = d.createElement('script');
 322         s.type = 'text/javascript';
 323         s.async = true;
 324         s.src = 'http' + '://' + disqus_shortname + '.disqus.com/embed.js';
 325         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 326     }
 327     else {
 328         d.write('<div id="disqus_thread">Comments have been disabled for offline viewing.<\/div>');
 329     }
 330 })(window, document);
 331 //--><!]]></script></div><div id="footer">
 332 <p class="apache">Copyright 2012 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 333 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
 334 if (typeof(prettyPrint) !== 'undefined') {
 335     prettyPrint();
 336 }
 337 //--><!]]></script>
 338 </body></html>