Adding upstream version 2.4.56.upstream/2.4.56

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 216 insertions, 0 deletions

diff --git a/docs/man/ab.1 b/docs/man/ab.1
new file mode 100644
index 0000000..bf38b9b
--- /dev/null
+++ b/docs/man/ab.1
@@ -0,0 +1,216 @@
+.\" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+.\" DO NOT EDIT! Generated from XML source.
+.\" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+.de Sh \" Subsection
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Ip \" List item
+.br
+.ie \\n(.$>=3 .ne \\$3
+.el .ne 3
+.IP "\\$1" \\$2
+..
+.TH "AB" 1 "2018-10-10" "Apache HTTP Server" "ab"
+
+.SH NAME
+ab \- Apache HTTP server benchmarking tool
+
+.SH "SYNOPSIS"
+ 
+.PP
+\fB\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 ] [ -\fBE\fR \fIclient-certificate file\fR ] [ -\fBf\fR \fIprotocol\fR ] [ -\fBg\fR \fIgnuplot-file\fR ] [ -\fBh\fR ] [ -\fBH\fR \fIcustom-header\fR ] [ -\fBi\fR ] [ -\fBk\fR ] [ -\fBl\fR ] [ -\fBm\fR \fIHTTP-method\fR ] [ -\fBn\fR \fIrequests\fR ] [ -\fBp\fR \fIPOST-file\fR ] [ -\fBP\fR \fIproxy-auth-username\fR:\fIpassword\fR ] [ -\fBq\fR ] [ -\fBr\fR ] [ -\fBs\fR \fItimeout\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\fR
+ 
+
+.SH "SUMMARY"
+ 
+.PP
+\fBab\fR 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\&.
+ 
+
+.SH "OPTIONS"
+ 
+ 
+.TP
+\fB-A \fIauth-username\fR:\fIpassword\fR\fR
+Supply BASIC Authentication credentials to the server\&. The username and password are separated by a single \fB:\fR 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)\&.  
+.TP
+\fB-b \fIwindowsize\fR\fR
+Size of TCP send/receive buffer, in bytes\&.  
+.TP
+\fB-B \fIlocal-address\fR\fR
+Address to bind to when making outgoing connections\&.  
+.TP
+\fB-c \fIconcurrency\fR\fR
+Number of multiple requests to perform at a time\&. Default is one request at a time\&.  
+.TP
+\fB-C \fIcookie-name\fR=\fIvalue\fR\fR
+Add a \fBCookie:\fR line to the request\&. The argument is typically in the form of a \fB\fIname\fR=\fIvalue\fR\fR pair\&. This field is repeatable\&.  
+.TP
+\fB-d\fR
+Do not display the "percentage served within XX [ms] table"\&. (legacy support)\&.  
+.TP
+\fB-e \fIcsv-file\fR\fR
+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'\&.  
+.TP
+\fB-E \fIclient-certificate-file\fR\fR
+When connecting to an SSL website, use the provided client certificate in PEM format to authenticate with the server\&. The file is expected to contain the client certificate, followed by intermediate certificates, followed by the private key\&. Available in 2\&.4\&.36 and later\&.  
+.TP
+\fB-f \fIprotocol\fR\fR
+Specify SSL/TLS protocol (SSL2, SSL3, TLS1, TLS1\&.1, TLS1\&.2, or ALL)\&. TLS1\&.1 and TLS1\&.2 support available in 2\&.4\&.4 and later\&.  
+.TP
+\fB-g \fIgnuplot-file\fR\fR
+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\&.  
+.TP
+\fB-h\fR
+Display usage information\&.  
+.TP
+\fB-H \fIcustom-header\fR\fR
+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, \fB"Accept-Encoding: zip/zop;8bit"\fR)\&.  
+.TP
+\fB-i\fR
+Do \fBHEAD\fR requests instead of \fBGET\fR\&.  
+.TP
+\fB-k\fR
+Enable the HTTP KeepAlive feature, \fIi\&.e\&.\fR, perform multiple requests within one HTTP session\&. Default is no KeepAlive\&.  
+.TP
+\fB-l\fR
+Do not report errors if the length of the responses is not constant\&. This can be useful for dynamic pages\&. Available in 2\&.4\&.7 and later\&.  
+.TP
+\fB-m \fIHTTP-method\fR\fR
+Custom HTTP method for the requests\&. Available in 2\&.4\&.10 and later\&.  
+.TP
+\fB-n \fIrequests\fR\fR
+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\&.  
+.TP
+\fB-p \fIPOST-file\fR\fR
+File containing data to POST\&. Remember to also set \fB-T\fR\&.  
+.TP
+\fB-P \fIproxy-auth-username\fR:\fIpassword\fR\fR
+Supply BASIC Authentication credentials to a proxy en-route\&. The username and password are separated by a single \fB:\fR 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)\&.  
+.TP
+\fB-q\fR
+When processing more than 150 requests, \fBab\fR outputs a progress count on \fBstderr\fR every 10% or 100 requests or so\&. The \fB-q\fR flag will suppress these messages\&.  
+.TP
+\fB-r\fR
+Don't exit on socket receive errors\&.  
+.TP
+\fB-s \fItimeout\fR\fR
+Maximum number of seconds to wait before the socket times out\&. Default is 30 seconds\&. Available in 2\&.4\&.4 and later\&.  
+.TP
+\fB-S\fR
+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)\&.  
+.TP
+\fB-t \fItimelimit\fR\fR
+Maximum number of seconds to spend for benchmarking\&. This implies a \fB-n 50000\fR internally\&. Use this to benchmark the server within a fixed total amount of time\&. Per default there is no timelimit\&.  
+.TP
+\fB-T \fIcontent-type\fR\fR
+Content-type header to use for POST/PUT data, eg\&. \fBapplication/x-www-form-urlencoded\fR\&. Default is \fBtext/plain\fR\&.  
+.TP
+\fB-u \fIPUT-file\fR\fR
+File containing data to PUT\&. Remember to also set \fB-T\fR\&.  
+.TP
+\fB-v \fIverbosity\fR\fR
+Set verbosity level - \fB4\fR and above prints information on headers, \fB3\fR and above prints response codes (404, 200, etc\&.), \fB2\fR and above prints warnings and info\&.  
+.TP
+\fB-V\fR
+Display version number and exit\&.  
+.TP
+\fB-w\fR
+Print out results in HTML tables\&. Default table is two columns wide, with a white background\&.  
+.TP
+\fB-x \fI<table>-attributes\fR\fR
+String to use as attributes for \fB<table>\fR\&. Attributes are inserted \fB<table \fIhere\fR >\fR\&.  
+.TP
+\fB-X \fIproxy\fR[:\fIport\fR]\fR
+Use a proxy server for the requests\&.  
+.TP
+\fB-y \fI<tr>-attributes\fR\fR
+String to use as attributes for \fB<tr>\fR\&.  
+.TP
+\fB-z \fI<td>-attributes\fR\fR
+String to use as attributes for \fB<td>\fR\&.  
+.TP
+\fB-Z \fIciphersuite\fR\fR
+Specify SSL/TLS cipher suite (See openssl ciphers)  
+ 
+.SH "OUTPUT"
+ 
+.PP
+The following list describes the values returned by \fBab\fR:
+ 
+ 
+.TP
+Server Software
+The value, if any, returned in the \fIserver\fR HTTP header of the first successful response\&. This includes all characters in the header from beginning to the point a character with decimal value of 32 (most notably: a space or CR/LF) is detected\&.  
+.TP
+Server Hostname
+The DNS or IP address given on the command line  
+.TP
+Server Port
+The port to which ab is connecting\&. If no port is given on the command line, this will default to 80 for http and 443 for https\&.  
+.TP
+SSL/TLS Protocol
+The protocol parameters negotiated between the client and server\&. This will only be printed if SSL is used\&.  
+.TP
+Document Path
+The request URI parsed from the command line string\&.  
+.TP
+Document Length
+This is the size in bytes of the first successfully returned document\&. If the document length changes during testing, the response is considered an error\&.  
+.TP
+Concurrency Level
+The number of concurrent clients used during the test  
+.TP
+Time taken for tests
+This is the time taken from the moment the first socket connection is created to the moment the last response is received  
+.TP
+Complete requests
+The number of successful responses received  
+.TP
+Failed requests
+The number of requests that were considered a failure\&. If the number is greater than zero, another line will be printed showing the number of requests that failed due to connecting, reading, incorrect content length, or exceptions\&.  
+.TP
+Write errors
+The number of errors that failed during write (broken pipe)\&.  
+.TP
+Non-2xx responses
+The number of responses that were not in the 200 series of response codes\&. If all responses were 200, this field is not printed\&.  
+.TP
+Keep-Alive requests
+The number of connections that resulted in Keep-Alive requests  
+.TP
+Total body sent
+If configured to send data as part of the test, this is the total number of bytes sent during the tests\&. This field is omitted if the test did not include a body to send\&.  
+.TP
+Total transferred
+The total number of bytes received from the server\&. This number is essentially the number of bytes sent over the wire\&.  
+.TP
+HTML transferred
+The total number of document bytes received from the server\&. This number excludes bytes received in HTTP headers  
+.TP
+Requests per second
+This is the number of requests per second\&. This value is the result of dividing the number of requests by the total time taken  
+.TP
+Time per request
+The average time spent per request\&. The first value is calculated with the formula \fBconcurrency * timetaken * 1000 / done\fR while the second value is calculated with the formula \fBtimetaken * 1000 / done\fR  
+.TP
+Transfer rate
+The rate of transfer as calculated by the formula \fBtotalread / 1024 / timetaken\fR  
+ 
+.SH "BUGS"
+ 
+.PP
+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\&.
+ 
+.PP
+It does not implement HTTP/1\&.x fully; only accepts some 'expected' forms of responses\&. The rather heavy use of \fBstrstr(3)\fR shows up top in profile, which might indicate a performance problem; \fIi\&.e\&.\fR, you would measure the \fBab\fR performance rather than the server's\&.
+