1AB(1)                                 ab                                 AB(1)
2
3
4

NAME

6       ab - Apache HTTP server benchmarking tool
7
8

SYNOPSIS

10       ab [ -A auth-username:password ] [ -b windowsize ] [ -B local-address ]
11       [ -c concurrency ] [ -C cookie-name=value ] [ -d ] [ -e csv-file ] [ -E
12       client-certificate  file ] [ -f protocol ] [ -g gnuplot-file ] [ -h ] [
13       -H custom-header ] [ -i ] [ -k ] [  -l  ]  [  -m  HTTP-method  ]  [  -n
14       requests  ] [ -p POST-file ] [ -P proxy-auth-username:password ] [ -q ]
15       [ -r ] [ -s timeout ] [ -S ] [ -t timelimit ] [ -T content-type ] [  -u
16       PUT-file ] [ -v verbosity] [ -V ] [ -w ] [ -x <table>-attributes ] [ -X
17       proxy[:port] ] [ -y <tr>-attributes ]  [  -z  <td>-attributes  ]  [  -Z
18       ciphersuite ] [http[s]://]hostname[:port]/path
19
20
21

SUMMARY

23       ab  is  a tool for benchmarking your Apache Hypertext Transfer Protocol
24       (HTTP) server. It is designed to give you an  impression  of  how  your
25       current  Apache  installation  performs.  This especially shows you how
26       many requests per second your Apache installation is capable  of  serv‐
27       ing.
28
29
30

OPTIONS

32       -A auth-username:password
33              Supply BASIC Authentication credentials to the server. The user‐
34              name and password are separated by a single : and  sent  on  the
35              wire  base64  encoded.  The string is sent regardless of whether
36              the server needs  it  (i.e.,  has  sent  an  401  authentication
37              needed).
38
39       -b windowsize
40              Size of TCP send/receive buffer, in bytes.
41
42       -B local-address
43              Address to bind to when making outgoing connections.
44
45       -c concurrency
46              Number of multiple requests to perform at a time. Default is one
47              request at a time.
48
49       -C cookie-name=value
50              Add a Cookie: line to the request. The argument is typically  in
51              the form of a name=value pair. This field is repeatable.
52
53       -d     Do  not  display  the  "percentage served within XX [ms] table".
54              (legacy support).
55
56       -e csv-file
57              Write a Comma separated value (CSV) file which contains for each
58              percentage  (from 1% to 100%) the time (in milliseconds) it took
59              to serve that percentage of the requests. This is  usually  more
60              useful  than  the  'gnuplot'  file;  as  the results are already
61              'binned'.
62
63       -E client-certificate-file
64              When connecting to an SSL website, use the provided client  cer‐
65              tificate in PEM format to authenticate with the server. The file
66              is expected to  contain  the  client  certificate,  followed  by
67              intermediate  certificates,  followed by the private key. Avail‐
68              able in 2.4.36 and later.
69
70       -f protocol
71              Specify SSL/TLS protocol (SSL2, SSL3, TLS1, TLS1.1,  TLS1.2,  or
72              ALL). TLS1.1 and TLS1.2 support available in 2.4.4 and later.
73
74       -g gnuplot-file
75              Write  all  measured values out as a 'gnuplot' or TSV (Tab sepa‐
76              rate values) file. This file can easily be imported  into  pack‐
77              ages  like  Gnuplot,  IDL,  Mathematica, Igor or even Excel. The
78              labels are on the first line of the file.
79
80       -h     Display usage information.
81
82       -H custom-header
83              Append extra headers to the request. The argument  is  typically
84              in the form of a valid header line, containing a colon-separated
85              field-value pair (i.e., "Accept-Encoding: zip/zop;8bit").
86
87       -i     Do HEAD requests instead of GET.
88
89       -k     Enable  the  HTTP  KeepAlive  feature,  i.e.,  perform  multiple
90              requests within one HTTP session. Default is no KeepAlive.
91
92       -l     Do  not report errors if the length of the responses is not con‐
93              stant. This can be useful for dynamic pages. Available in  2.4.7
94              and later.
95
96       -m HTTP-method
97              Custom  HTTP  method  for  the requests. Available in 2.4.10 and
98              later.
99
100       -n requests
101              Number of requests to perform for the benchmarking session.  The
102              default  is to just perform a single request which usually leads
103              to non-representative benchmarking results.
104
105       -p POST-file
106              File containing data to POST. Remember to also set -T.
107
108       -P proxy-auth-username:password
109              Supply BASIC Authentication credentials to a proxy en-route. The
110              username  and  password  are separated by a single : and sent on
111              the wire base64  encoded.  The  string  is  sent  regardless  of
112              whether  the proxy needs it (i.e., has sent an 407 proxy authen‐
113              tication needed).
114
115       -q     When processing more than 150 requests, ab  outputs  a  progress
116              count  on  stderr  every  10% or 100 requests or so. The -q flag
117              will suppress these messages.
118
119       -r     Don't exit on socket receive errors.
120
121       -s timeout
122              Maximum number of seconds to wait before the socket  times  out.
123              Default is 30 seconds. Available in 2.4.4 and later.
124
125       -S     Do  not  display  the  median and standard deviation values, nor
126              display the warning/error messages when the average  and  median
127              are more than one or two times the standard deviation apart. And
128              default to the min/avg/max values. (legacy support).
129
130       -t timelimit
131              Maximum number  of  seconds  to  spend  for  benchmarking.  This
132              implies  a -n 50000 internally. Use this to benchmark the server
133              within a fixed total amount of time. Per  default  there  is  no
134              timelimit.
135
136       -T content-type
137              Content-type header to use for POST/PUT data, eg. application/x-
138              www-form-urlencoded. Default is text/plain.
139
140       -u PUT-file
141              File containing data to PUT. Remember to also set -T.
142
143       -v verbosity
144              Set verbosity level - 4 and above prints information on headers,
145              3  and above prints response codes (404, 200, etc.), 2 and above
146              prints warnings and info.
147
148       -V     Display version number and exit.
149
150       -w     Print out results in HTML tables. Default table is  two  columns
151              wide, with a white background.
152
153       -x <table>-attributes
154              String to use as attributes for <table>. Attributes are inserted
155              <table here >.
156
157       -X proxy[:port]
158              Use a proxy server for the requests.
159
160       -y <tr>-attributes
161              String to use as attributes for <tr>.
162
163       -z <td>-attributes
164              String to use as attributes for <td>.
165
166       -Z ciphersuite
167              Specify SSL/TLS cipher suite (See openssl ciphers)
168
169

OUTPUT

171       The following list describes the values returned by ab:
172
173
174
175       Server Software
176              The value, if any, returned in the server  HTTP  header  of  the
177              first  successful  response. This includes all characters in the
178              header from beginning to the  point  a  character  with  decimal
179              value of 32 (most notably: a space or CR/LF) is detected.
180
181       Server Hostname
182              The DNS or IP address given on the command line
183
184       Server Port
185              The  port  to which ab is connecting. If no port is given on the
186              command line, this will default to  80  for  http  and  443  for
187              https.
188
189       SSL/TLS Protocol
190              The  protocol  parameters  negotiated  between  the  client  and
191              server. This will only be printed if SSL is used.
192
193       Document Path
194              The request URI parsed from the command line string.
195
196       Document Length
197              This is the size in bytes of  the  first  successfully  returned
198              document.  If  the  document  length changes during testing, the
199              response is considered an error.
200
201       Concurrency Level
202              The number of concurrent clients used during the test
203
204       Time taken for tests
205              This is the time taken from the moment the first socket  connec‐
206              tion is created to the moment the last response is received
207
208       Complete requests
209              The number of successful responses received
210
211       Failed requests
212              The  number  of  requests that were considered a failure. If the
213              number is greater than zero, another line will be printed  show‐
214              ing  the number of requests that failed due to connecting, read‐
215              ing, incorrect content length, or exceptions.
216
217       Write errors
218              The number of errors that failed during write (broken pipe).
219
220       Non-2xx responses
221              The number of responses that were  not  in  the  200  series  of
222              response  codes.  If  all  responses were 200, this field is not
223              printed.
224
225       Keep-Alive requests
226              The number of connections that resulted in Keep-Alive requests
227
228       Total body sent
229              If configured to send data as part of  the  test,  this  is  the
230              total number of bytes sent during the tests. This field is omit‐
231              ted if the test did not include a body to send.
232
233       Total transferred
234              The total number of bytes received from the server. This  number
235              is essentially the number of bytes sent over the wire.
236
237       HTML transferred
238              The  total  number  of  document bytes received from the server.
239              This number excludes bytes received in HTTP headers
240
241       Requests per second
242              This is the number of requests per second.  This  value  is  the
243              result  of  dividing  the  number  of requests by the total time
244              taken
245
246       Time per request
247              The average time spent per request. The first  value  is  calcu‐
248              lated  with  the  formula  concurrency * timetaken * 1000 / done
249              while the second value is calculated with the formula  timetaken
250              * 1000 / done
251
252       Transfer rate
253              The  rate  of  transfer as calculated by the formula totalread /
254              1024 / timetaken
255
256

BUGS

258       There are various statically declared buffers of fixed length. Combined
259       with the lazy parsing of the command line arguments, the response head‐
260       ers from the server and other external inputs, this might bite you.
261
262
263       It does not implement HTTP/1.x  fully;  only  accepts  some  'expected'
264       forms  of  responses. The rather heavy use of strstr(3) shows up top in
265       profile, which might indicate a performance problem;  i.e.,  you  would
266       measure the ab performance rather than the server's.
267
268
269
270
271Apache HTTP Server                2018-10-10                             AB(1)
Impressum