httperf.man

一个WEB服务器的性能测试工具

.TH httperf 1 "30 Oct 2000"
.IX httperf
.SH NAME
httperf \- HTTP performance measurement tool
.SH SYNOPSIS
.B httperf
.RB [ --add-header
.IR S ]
.RB [ --burst-length
.IR N ]
.RB [ --client
.IR I / N ]
.RB [ --close-with-reset ]
.RB [ -d | --debug
.IR N ]
.RB [ --failure-status
.IR N ]
.RB [ -h | --help ]
.RB [ --hog ]
.RB [ --http-version
.IR S ]
.RB [ --max-connections
.IR N ]
.RB [ --max-piped-calls
.IR N ]
.RB [ --method
.IR S ]
.RB [ --no-host-hdr ]
.RB [ --num-calls 
.IR N ]
.RB [ --num-conns
.IR N ]
.RB [ --period " [" d | u | e ] \fIT1\fR [ ,\fIT2\fR ]]
.RB [ --port
.IR N ]
.RB [ --print-reply " [" header | body ] ]
.RB [ --print-request " [" header | body ] ]
.RB [ --rate
.IR X ]
.RB [ --recv-buffer
.IR N ]
.RB [ --retry-on-failure ]
.RB [ --send-buffer
.IR N ]
.RB [ --server
.IR S ]
.RB [ --server-name
.IR S ]
.RB [ --session-cookie ]
.RB [ --ssl ]
.RB [ --ssl-ciphers
.IR L ]
.RB [ --ssl-no-reuse ]
.RB [ --think-timeout
.IR X ]
.RB [ --timeout
.IR X ]
.RB [ --uri
.IR S ]
.RB [ -v | --verbose ]
.RB [ -V | --version ]
.RB [ "--wlog y" | n, \fIF\fR]
.RB [ --wsess
.IR N , N , X ]
.RB [ --wsesslog
.IR N , X , F ]
.RB [ --wset
.IR N , X ]
.SH DESCRIPTION
.B httperf
is a tool to measure web server performance.  It speaks the HTTP
protocol both in its HTTP/1.0 and HTTP/1.1 flavors and offers a
variety of workload generators. While running, it keeps track of a
number of performance metrics that are summarized in the form of
statistics that are printed at the end of a test run.  The most basic
operation of
.B httperf
is to generate a fixed number of HTTP GET requests and to measure how
many replies (responses) came back from the server and at what rate
the responses arrived.

.B IMPORTANT:
To obtain correct results, it is necessary to run at most one
.B httperf
process per client machine.  Also, there should be as few background
processes as possible both on the client and server machines.

.SH EXAMPLES
.TP
httperf --hog --server www
This command causes
.B httperf
to create a connection to host www, send a request for the root
document (http://www/), receive the reply, close the connection, and
then print some performance statistics.
.TP
httperf --hog --server www --num-conn 100 --ra 10 --timeout 5
Like above, except that a total of 100 connections are created and
that connections are created at a fixed rate of 10 per second.  Note
that option ``--rate'' has been abbreviated to ``--ra''.
.TP
httperf --hog --server=www --wsess=10,5,2 --rate 1 --timeout 5
Causes
.B httperf
to generate a total of 10 sessions at a rate of 1 session per second.
Each session consists of 5 calls that are spaced out by 2 seconds.
.TP
httperf --hog --server=www --wsess=10,5,2 --rate=1 --timeout=5 --ssl
Like above, except that
.B httperf
contacts server www via SSL at port 443 (the default port for SSL
connections).
.TP
httperf --hog --server www --wsess=10,5,2 --rate=1 --timeout=5 --ssl --ssl-ciphers=EXP-RC4-MD5:EXP-RC2-CBC-MD5 --ssl-no-reuse --http-version=1.0
Like above, except that
.B httperf
will inform the server that it can only select from two cipher suites
(EXP-RC4-MD5 or EXP-RC2-CBC-MD5); furthermore,
.B httperf
will use HTTP version 1.0 which requires a new TCP connection for each
request.  Also, SSL session ids are not reused, so the entire SSL
connection establishment process (known as the SSL handshake) occurs
for each connection.
.SH OPTIONS
The operation of
.B httperf
can be controlled through a number of options.  The tool supports both
short (one-character) and long (arbitrary-length) option names.  Short
options are prefixed with a single leading dash (-), long
options with a double-dash (--).  Multiple short options can be
grouped together (e.g.,
.RB `` -vV ''
is equivalent to
.RB `` "-v -V" '')
and long options can be abbreviated so long as they remain unique.
Parameters to options can be specified either by following the long
option name with an equal sign and the parameter value (e.g.,
.BR --burst=10 )
or by separating the option name and value with whitespace (e.g.,
.BR "--burst 10" ).
.TP
.BI --add-header= S
Specifies to include string
.I S
as an additional request header.  It is necessary to specify the
terminating carriage-return/line-feed sequence explicitly.  This can
be done by using the escape sequence ``\\n''.  This makes it possible
to include multiple request headers.  For example, ``--add-header
"Referer: foo\\nAuth: secret\\n"'' would add two request headers
(``Referer'' and ``Auth'') to each request.  Other supported escape
sequences are ``\\r'' (carriage-return), ``\\a'' (line-feed), ``\\\\''
(backslash), and ``\\N'' where N is the code the character to be
inserted (in octal).
.TP
.BI --burst-length= N
Specifies the length of bursts.  Each burst consists of
.I N
calls to the server.  The exact meaning of this parameter depends on
the workload generator.  For regular request-oriented workloads, see the
description of option
.TP
.BR --no-host-hdr
Specifies that the "Host:" header should not be included when issuing
an HTTP request.
.TP
.BR --num-calls .
For session-oriented workloads, see the description of option
.BR --wsess .
.TP
.BI --client= I / N
Specifies that the machine
.B httperf
is running on is client
.I I
out of a total of
.I N
clients.
.I I
should be in the range from 0 to
.IR N "-1."
Some of the workload generators (e.g.,
.BR --wset)
use the client identity as a bias value to ensure that not all clients
generate perfectly identical workloads.  When performing a test that
involves several client machines, it is generally a good idea to
specify this option.
.TP
.BI --close-with-reset
Requests that
.B httperf
closes TCP connections by sending a RESET instead of going through the
normal TCP connection shutdown handshake.  Turning on this option can
have ill effects such as data corruption, stuck TCP control blocks, or
wrong results.  For this reason, the option should not be used unless
absolutely necessary and even then it should not be used unless its
implications are fully understood.
.TP
.BI -d= N
.TP
.BI --debug= N
Set debug level to
.IR N .
Larger values of
.I N
will result in more output.
.TP
.BI --failure-status= N
Specifies that an HTTP response status code of
.I N
should be treated as a failure (i.e., treated as if the request had
timed out, for example).  For example, with
.RB `` --failure-status=504 ''
responses with an HTTP status of ``504 Gateway Time-out'' would be
considered failures.  Caveat: this option is currently supported
for session workloads only (see the
.B --wsess
and
.B --wsesslog
options).
.TP
.B -h
.TP
.B --help
Prints a summary of available options and their parameters.
.TP
.BI --hog
This option requests to use up as many TCP ports as necessary.
Without this option,
.B httperf
is typically limited to using ephemeral ports (in the range from 1024
to 5000).  This limited port range can quickly become a bottleneck so
it is generally a good idea to specify this option for serious
testing.  Also, this option must be specified when measuring NT
servers since it avoids a TCP incompatibility between NT and UNIX
machines.
.TP
.BI --http-version= S
Specifies the version string that should be included in the requests
sent to the server.  By default, version string ``1.1'' is used.  This
option can be set to ``1.0'' to force the generation of HTTP/1.0
requests.  Setting this option to any value other than ``1.0'' or ``1.1''
may result in undefined behavior.
.TP
.BI --max-connections= N
Specifies that at most
.I N
connections are opened for each session.  This option is meaningful in
conjunction with options
.B --wsess
and
.B --wsesslog
only.
.TP
.BI --max-piped-calls= N
Specifies that at most
.I N
pipelined calls are issued on each connection.  This option is
meaningful in conjunction with options
.B --wsess
and
.B --wsesslog
only.
.TP
.BI --method= S
Specifies the method that should be used when issuing an HTTP request.
If this option is not specified, the GET method is used.  The method
.I S
can be an arbitrary string but is usually one of GET, HEAD, PUT, POST,
etc.
.TP
.BI --num-calls= N
This option is meaningful for request-oriented workloads only.  It
specifies the total number of calls to issue on each connection before
closing it.  If
.I N
is greater than 1, the server must support persistent connections.
The default value for this option is 1.  If
.BR --burst-length
is set to
.IR B ,
then the
.I N
calls are issued in bursts of
.I B
pipelined calls each.  Thus, the total number of such bursts will
be
.I N/B
(per connection).
.TP
.BI --num-conns= N
This option is meaningful for request-oriented workloads only.  It
specifies the total number of connections to create.  On each
connection, calls are issued as specified by options
.B --num-calls
and
.BR --burst-length .
A test stops as soon as the
.I N
connections have either completed or failed.  A connection is
considered to have failed if any activity on the connection fails to
make forward progress for more than the time specified by the timeout
options
.B --timeout
and
.BR --think-timeout .
The default value for this option is 1.
.TP
.BI --period= [D]T1[,T2]
Specifies the time interval between the creation of connections or sessions.
Connections are created by default, sessions if option
.B --wsess
or
.B --wsesslog
has been specified.
This connection/session ``interarrival time'' can alternatively be specified by
the 
.B --rate
option, although more flexibility is available with
.B --period.
The
.I D
parameter specifies the interarrival time distribution.
If omitted or set to
.RB `` d '',
a deterministic (i.e., fixed) period is used as specified
by parameter
.IR T1
in units of seconds.
If
.I D
is set to 
.RB `` e '',
an exponential (i.e., Poisson) distribution is used with
a mean interarrival time of
.IR T1 .
Finally, if
.I D
is set to 
.RB `` u '',
a uniform distribution over the interval
.RI [ T1 , T2 )
is used for the interarrival time.
In all cases, a period of 0 results in connections
or sessions being generated sequentially (a new connection/session is
initiated as soon as the previous one completes).  The default value
for this option is 0.  Note that specifying, for example,
.B --rate=5
is equivalent to specifying
.B --period=d0.2
or
.BR --period=0.2 .
By specifying
.BR --period=u1,3 ,
the interarrival times will be randomly chosen from the interval
between 1 and 3 seconds.  The specific sequence of (pseudo-)random
interarrival times are identical from one
.B httperf
run to another as long as the values for the
.B --period
and
.B --client
options are identical.
.TP
.BI --port= N
This option specifies the port number
.I N
on which the web server is listening for HTTP requests.  By default,
.B httperf
uses port number 80.
.TP
.BR --print-reply [ = [ header | body ]]
Requests the printing of the reply headers, body, and summary.  The
output is directed to standard output.  Reply header lines are
prefixed by "RH", reply body lines are prefixed by "RB", and the
reply-size summary is prefixed by "RS".  The prefix is followed by a
serial number that uniquely identifies the call that the reply line is
for and a colon (":") character that marks the beginning of the actual
reply line.  To print only reply headers, pass argument
.B header
to this option.  To print only the reply body, pass argument
.B body
to this option.
.TP
.BR --print-request [ = [ header | body ]]
Requests the printing of the request headers, body (if one is
present), and summary.  The output is directed to standard output.
Request header lines are prefixed by "SH", request body lines are
prefixed by "SB", and the request summary is prefixed by "SS".  The