granicus.if.org Git - apache/blob - docs/man/ab.1

   1 .\" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   2 .\" DO NOT EDIT! Generated from XML source.
   3 .\" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   4 .de Sh \" Subsection
   5 .br
   6 .if t .Sp
   7 .ne 5
   8 .PP
   9 \fB\\$1\fR
  10 .PP
  11 ..
  12 .de Sp \" Vertical space (when we can't use .PP)
  13 .if t .sp .5v
  14 .if n .sp
  15 ..
  16 .de Ip \" List item
  17 .br
  18 .ie \\n(.$>=3 .ne \\$3
  19 .el .ne 3
  20 .IP "\\$1" \\$2
  21 ..
  22 .TH "AB" 1 "2012-01-09" "Apache HTTP Server" "ab"
  23
  24 .SH NAME
  25 ab \- Apache HTTP server benchmarking tool
  26
  27 .SH "SYNOPSIS"
  28
  29 .PP
  30 \fBab\fR [ -\fBA\fR \fIauth-username\fR:\fIpassword\fR ] [ -\fBb\fR \fIwindowsize\fR ] [ -\fBB\fR \fIlocal-address\fR ] [ -\fBc\fR \fIconcurrency\fR ] [ -\fBC\fR \fIcookie-name\fR=\fIvalue\fR ] [ -\fBd\fR ] [ -\fBe\fR \fIcsv-file\fR ] [ -\fBf\fR \fIprotocol\fR ] [ -\fBg\fR \fIgnuplot-file\fR ] [ -\fBh\fR ] [ -\fBH\fR \fIcustom-header\fR ] [ -\fBi\fR ] [ -\fBk\fR ] [ -\fBn\fR \fIrequests\fR ] [ -\fBp\fR \fIPOST-file\fR ] [ -\fBP\fR \fIproxy-auth-username\fR:\fIpassword\fR ] [ -\fBq\fR ] [ -\fBr\fR ] [ -\fBs\fR ] [ -\fBS\fR ] [ -\fBt\fR \fItimelimit\fR ] [ -\fBT\fR \fIcontent-type\fR ] [ -\fBu\fR \fIPUT-file\fR ] [ -\fBv\fR \fIverbosity\fR] [ -\fBV\fR ] [ -\fBw\fR ] [ -\fBx\fR \fI<table>-attributes\fR ] [ -\fBX\fR \fIproxy\fR[:\fIport\fR] ] [ -\fBy\fR \fI<tr>-attributes\fR ] [ -\fBz\fR \fI<td>-attributes\fR ] [ -\fBZ\fR \fIciphersuite\fR ] [http[s]://]\fIhostname\fR[:\fIport\fR]/\fIpath\fR
  31
  32
  33 .SH "SUMMARY"
  34
  35 .PP
  36 ab is a tool for benchmarking your Apache Hypertext Transfer Protocol (HTTP) server\&. It is designed to give you an impression of how your current Apache installation performs\&. This especially shows you how many requests per second your Apache installation is capable of serving\&.
  37
  38
  39 .SH "OPTIONS"
  40
  41
  42 .TP
  43 -A \fIauth-username\fR:\fIpassword\fR
  44 Supply BASIC Authentication credentials to the server\&. The username and password are separated by a single : and sent on the wire base64 encoded\&. The string is sent regardless of whether the server needs it (\fIi\&.e\&.\fR, has sent an 401 authentication needed)\&.
  45 .TP
  46 -b \fIwindowsize\fR
  47 Size of TCP send/receive buffer, in bytes\&.
  48 .TP
  49 -B \fIlocal-address\fR
  50 Address to bind to when making outgoing connections\&.
  51 .TP
  52 -c \fIconcurrency\fR
  53 Number of multiple requests to perform at a time\&. Default is one request at a time\&.
  54 .TP
  55 -C \fIcookie-name\fR=\fIvalue\fR
  56 Add a Cookie: line to the request\&. The argument is typically in the form of a \fIname\fR=\fIvalue\fR pair\&. This field is repeatable\&.
  57 .TP
  58 -d
  59 Do not display the "percentage served within XX [ms] table"\&. (legacy support)\&.
  60 .TP
  61 -e \fIcsv-file\fR
  62 Write a Comma separated value (CSV) file which contains for each percentage (from 1% to 100%) the time (in milliseconds) it took to serve that percentage of the requests\&. This is usually more useful than the 'gnuplot' file; as the results are already 'binned'\&.
  63 .TP
  64 -f \fIprotocol\fR
  65 Specify SSL/TLS protocol (SSL2, SSL3, TLS1, or ALL)\&.
  66 .TP
  67 -g \fIgnuplot-file\fR
  68 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\&.
  69 .TP
  70 -h
  71 Display usage information\&.
  72 .TP
  73 -H \fIcustom-header\fR
  74 Append extra headers to the request\&. The argument is typically in the form of a valid header line, containing a colon-separated field-value pair (\fIi\&.e\&.\fR, "Accept-Encoding: zip/zop;8bit")\&.
  75 .TP
  76 -i
  77 Do HEAD requests instead of GET\&.
  78 .TP
  79 -k
  80 Enable the HTTP KeepAlive feature, \fIi\&.e\&.\fR, perform multiple requests within one HTTP session\&. Default is no KeepAlive\&.
  81 .TP
  82 -n \fIrequests\fR
  83 Number of requests to perform for the benchmarking session\&. The default is to just perform a single request which usually leads to non-representative benchmarking results\&.
  84 .TP
  85 -p \fIPOST-file\fR
  86 File containing data to POST\&. Remember to also set -T\&.
  87 .TP
  88 -P \fIproxy-auth-username\fR:\fIpassword\fR
  89 Supply BASIC Authentication credentials to a proxy en-route\&. The username and password are separated by a single : and sent on the wire base64 encoded\&. The string is sent regardless of whether the proxy needs it (\fIi\&.e\&.\fR, has sent an 407 proxy authentication needed)\&.
  90 .TP
  91 -q
  92 When processing more than 150 requests, ab outputs a progress count on stderr every 10% or 100 requests or so\&. The -q flag will suppress these messages\&.
  93 .TP
  94 -r
  95 Don't exit on socket receive errors\&.
  96 .TP
  97 -s
  98 When compiled in (ab -h will show you) use the SSL protected https rather than the http protocol\&. This feature is experimental and \fIvery\fR rudimentary\&. You probably do not want to use it\&.
  99 .TP
 100 -S
 101 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)\&.
 102 .TP
 103 -t \fItimelimit\fR
 104 Maximum number of seconds to spend for benchmarking\&. This implies a -n 50000 internally\&. Use this to benchmark the server within a fixed total amount of time\&. Per default there is no timelimit\&.
 105 .TP
 106 -T \fIcontent-type\fR
 107 Content-type header to use for POST/PUT data, eg\&. application/x-www-form-urlencoded\&. Default: text/plain\&.
 108 .TP
 109 -u \fIPUT-file\fR
 110 File containing data to PUT\&. Remember to also set -T\&.
 111 .TP
 112 -v \fIverbosity\fR
 113 Set verbosity level - 4 and above prints information on headers, 3 and above prints response codes (404, 200, etc\&.), 2 and above prints warnings and info\&.
 114 .TP
 115 -V
 116 Display version number and exit\&.
 117 .TP
 118 -w
 119 Print out results in HTML tables\&. Default table is two columns wide, with a white background\&.
 120 .TP
 121 -x \fI<table>-attributes\fR
 122 String to use as attributes for <table>\&. Attributes are inserted <table \fIhere\fR >\&.
 123 .TP
 124 -X \fIproxy\fR[:\fIport\fR]
 125 Use a proxy server for the requests\&.
 126 .TP
 127 -y \fI<tr>-attributes\fR
 128 String to use as attributes for <tr>\&.
 129 .TP
 130 -z \fI<td>-attributes\fR
 131 String to use as attributes for <td>\&.
 132 .TP
 133 -Z \fIciphersuite\fR
 134 Specify SSL/TLS cipher suite (See openssl ciphers)
 135
 136 .SH "BUGS"
 137
 138 .PP
 139 There are various statically declared buffers of fixed length\&. Combined with the lazy parsing of the command line arguments, the response headers from the server and other external inputs, this might bite you\&.
 140
 141 .PP
 142 It does not implement HTTP/1\&.x fully; only accepts some 'expected' forms of responses\&. The rather heavy use of strstr(3) shows up top in profile, which might indicate a performance problem; \fIi\&.e\&.\fR, you would measure the ab performance rather than the server's\&.
 143