File: hammerhead.html

package info (click to toggle)
hammerhead 2.1.3-7
links: PTS
area: main
in suites: etch, etch-m68k
size: 704 kB
ctags: 588
sloc: cpp: 4,782; sh: 2,794; makefile: 240; perl: 41; csh: 11
file content (806 lines) | stat: -rw-r--r-- 19,118 bytes
parent folder | download | duplicates (4)
Content-type: text/html

<HTML><HEAD><TITLE>Manpage of hammerhead</TITLE>
</HEAD><BODY>
<H1>hammerhead</H1>
Section: User Commands  (1)<BR>Updated: 03 Jul 2002<BR><A HREF="#index">Index</A>
<A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR>

<A NAME="lbAB">&nbsp;</A>
<H2>NAME</H2>

hammerhead - perform load testing on a given machine/port with a set of http requests
<A NAME="lbAC">&nbsp;</A>
<H2>SYNOPSIS</H2>

<B>hammerhead</B>

[
<I>options</I>

]
[
<I>resultsFile</I>

]
<A NAME="lbAD">&nbsp;</A>
<H2>DESCRIPTION</H2>

<A NAME="ixAAB"></A>
<A NAME="ixAAC"></A>
<B>Hammerhead </B>

is a web site coverage and stress testing
tool. It's also useful for benchmarking your web servers. It's been designed
to emulate multiple users from multiple IP addresses and designed for
maximum speed unlike it's interpreted counterparts.  It's highly
configurable and supports scenario based requests.
The
<B>hammerhead</B>

command is sends HTTP requests to a nominated machine/port (as
specified in the 
<B>configFile)</B>

to simulate load on that port. It can be used to test the behaviour of
the port under load, or the ability of the port to service a set of
requests.
<P>

The behaviour of
<B>hammerhead</B>

is defined (almost) entirely by the 
<B>configfile. </B>

See the description of this file below for an explanation of all of
the configuration options.
<P>

<B>hammerhead </B>

loads a set of requests from a number of files, each of which may
contain a number of scenarios (one request per scenario). Scenarios
may be linked into sequences, in order to simulate real users
actions. 
<P>

Once the scenarios are loaded,
<B>hammerhead </B>

starts up a number of threads and sends requests to the port.  The
expected result of a request may be specified in a scenario, and any
result from the port which does not match with the expected result
will be reported as an error. If no expected results are specified,
then any result from the port will be accepted as valid. Specifying an
expected result for any scenario has the effect of specifying the
same result for
<B>all</B>

scenarios which have the same request.
<P>
<P>

Any failure to get a connection to the port, or any failure to receive
a reply to a request will also be reported.
<A NAME="lbAE">&nbsp;</A>
<H2>OPTIONS</H2>

The following options are supported:
<DL COMPACT>
<DT><B>-s or --seconds</B>

<DD>
Seconds to run tests for
<DT><B>-o or --outfile</B>

<DD>
Output result file
<DT><B>-t or --test</B>

<DD>
Test the scenarios in the conf file.
<DT><B>-C or --checkconf</B>

<DD>
Check config file
<DT><B>-c or --conffile</B>

<DD>
Config file path 
<DT><B>-h or --help</B>

<DD>
Display help information
<DT><B>-v or --version</B>

<DD>
Output version
</DL>
<A NAME="lbAF">&nbsp;</A>
<H2>OPERANDS</H2>

The following operand is supported:
<DL COMPACT>
<DT><I>resultsFile:</I>

<DD>
Create an optimized scenario file to make
<B>hammerhead</B>

load faster.
</DL>
<A NAME="lbAG">&nbsp;</A>
<H2>CONFIGURATION FILE</H2>

The configuration file is a plain text file, containing a set of
attribute/value pairs. Attribute names are matched without regard to case.
<P>

Any line in the file beginning with a hash (#) is treated as a
comment, and ignored.
<P>

The attributes which may be defined in this file are:
<A NAME="lbAH">&nbsp;</A>
<H3>Scenario_directory</H3>

The directory in which to find the Scenario file(s). All scenario
files in this directory will be loaded. A scenario file is any file
with the extension
<B>.scn </B>

(case sensitive). There may be more than one 

directive on a configuration file. Each directory shall be 
examined for scenario files.
<P>

default value: /var/tmp/scenarios/
<A NAME="lbAI">&nbsp;</A>
<H3>Scenario_file</H3>

A specific file from which to read scenarios. There may be more than one

directive on a configuration file.
<A NAME="lbAJ">&nbsp;</A>
<H3>Log_filename</H3>

The file in which all log messages will be written. If this file
cannot be created, 
<B>hammerhead</B>

will default to using standard error.
<P>

default value: /var/tmp/hammerhead/hh.log
<A NAME="lbAK">&nbsp;</A>
<H3>Load_images</H3>

A flag indicating whether to automatically load images which are
referenced in the result of a request.
<P>

posible values: on, off
<P>

default value: off
<A NAME="lbAL">&nbsp;</A>
<H3>Sessions</H3>

The number of threads to start up.
<P>

default value: 1000
<A NAME="lbAM">&nbsp;</A>
<H3>Seed</H3>

The random number seed used for the random selection of
requests. Setting this number to any non-zero value will give
deterministic behaviour (i.e. the same sequence of requests will be
selected)
<P>

default value: 0
<A NAME="lbAN">&nbsp;</A>
<H3>Sequence_probability</H3>

The percentage of the time that 
<B>hammerhead</B>

will follow the sequence that the current request is in. Setting this
to 100 will force hammerhead to follow any sequence it encounters to
its completion.
<P>

default value: 75
<A NAME="lbAO">&nbsp;</A>
<H3>Sleep_time</H3>

The amount of time (in milliseconds) to sleep between requests. In
fact, this is the average sleep time, and 
<B>hammerhead</B>

will sleep for a randomly selected period, between 0 milliseconds, and
twice this value.
<P>

default value: 0
<A NAME="lbAP">&nbsp;</A>
<H3>Run_time</H3>

The number of seconds to run each thread. If this value is 0, the
threads run for-ever. This can be used to set up tests which run for a
particular length of time.
<P>

default value: 0
<A NAME="lbAQ">&nbsp;</A>
<H3>Machine_IP</H3>

The IP number (and possibly port) of the machine/port to hammer. The
format is &lt;machine_number&gt;[:&lt;port_number&gt;], where &lt;machine_number&gt; is
as described in 
<B>man inet_addr</B>

and &lt;port_number&gt; is optional. 
<P>

This is the
<B>only</B>

attribute that must be defined in a configuration file

default value: no default for &lt;machine_number&gt;, 8080 for &lt;port_number&gt;
<A NAME="lbAR">&nbsp;</A>
<H3>Ip_Alias</H3>

The outgoing IP numbers; allows Hammerhead to simulate multiple
machines (upto 1 machine / session).  May be any of the following forms:
10.0.0.1, 10.0.0.*, 10.0.*.*, 10.0.1-5.*, 10.0.0.1-5.

default value: the hammering machines normal IP address
<A NAME="lbAS">&nbsp;</A>
<H3>Premature_Close</H3>

The percentage of requests that will be improperly terminated before
sending/receiving is completed properly (to test problems
such as FIN_WAIT1).

default value: 0
<A NAME="lbAT">&nbsp;</A>
<H3>Bad_Request</H3>

The percentage of requests the will be scrambled requests
(outside the properly defined scenarios).

default value: 0
<A NAME="lbAU">&nbsp;</A>
<H3>Report_Time</H3>

The time interval upon which to written report summaries to the report
log.

default value: 0 (report only once at test end.)
<A NAME="lbAV">&nbsp;</A>
<H3>Report_Log</H3>

The log file which is to contain the report summaries.

default value: /var/tmp/report.log
<A NAME="lbAW">&nbsp;</A>
<H3>Robot_ID</H3>

The robot id to be passed to the servers being hammered.

Currently not implemented.
<A NAME="lbAX">&nbsp;</A>
<H3>Send_Cookie</H3>

Turn on to allow the sending of cookies with requests. Incoming
cookies are buffered with each session when a Set-Cookie 
header is found. They're sent back with further requests 
to that session. Cookies are capped at 4K.

default value: off
<A NAME="lbAY">&nbsp;</A>
<H3>Premature_Close</H3>

The percentage of connections which will close permaturely before the
request reply has been fully read back from the server.

default value: 0
<A NAME="lbAZ">&nbsp;</A>
<H3>Log_Level</H3>

Log levels defined to work with the 

crawl
functionality - somewhat mystical and not confirmed to be working.

default value: 0
<A NAME="lbBA">&nbsp;</A>
<H3>Bandwidth_Limit</H3>

Turn on bandwidth limiting.

Not implemented yet.
<A NAME="lbBB">&nbsp;</A>
<H3>Crawl</H3>

Crawl though the URLs contained in the reply to a request. Scope is 
somewhat unclear. Use with caution.

default value: off
<A NAME="lbBC">&nbsp;</A>
<H3>SelectOn</H3>

When choosing a new sequence to commence, select from all the scenarios [
<I>scenario</I>

] or select from those scenarios which are at the beginning of a sequence 
of scenarios [
<I>sequence</I>

].

default value: scenario
<A NAME="lbBD">&nbsp;</A>
<H3>Start_Lag</H3>

Start lag is a delay at thread startup before the first request is issued. The delay can be used to control the size of any startup spikes during the commencement of the test. The threads (processes) pause for a time between 0 and (Start_Lag * Sessions) milliseconds before issuing their first request.

default value: 1 millisecond
<A NAME="lbBE">&nbsp;</A>
<H3>DNS_Server</H3>

Allow the specification of an alternate DNS server to use to resolve the machinenames. This resolution is completed once server DNS_TTL seconds.

default value: use the server nominated in 
<I>/etc/resolv.conf</I>

<A NAME="lbBF">&nbsp;</A>
<H3>DNS_TTL</H3>

The Time To Live for the self cached DNS queries.

default value: 120 seconds
<A NAME="lbBG">&nbsp;</A>
<H3>Machine_Name</H3>

The name of the machine/s to hammer. Names are resolved to addresses using
the DNS resolver.
<A NAME="lbBH">&nbsp;</A>
<H3>Use_SSL</H3>

Should SSL be used during each request?

default value: no
<A NAME="lbBI">&nbsp;</A>
<H3>HTTP_Request_Type</H3>

Specify the HTTP request version, the default value is recommended as
Hammerhead maybe not handle all 1.1 return packets correctly.

default value: HTTP/1.0
<A NAME="lbBJ">&nbsp;</A>
<H3>BottleNeck</H3>

Use connection bottlenecking to extend connecton holding time

Not implemented yet.
<A NAME="lbBK">&nbsp;</A>
<H3>Max_Failures</H3>

The maximum number of request failures to be tolerated before we abandon the
test. The value 0 means that hammerhead will never stop because of an excessive
number of request failures.

default value: 0
<A NAME="lbBL">&nbsp;</A>
<H2>SCENARIO FILE</H2>

A scenario file is a plain text file, containing a set of tagged value
lines. The first character of each line is the tag, and the rest of the
line is the value. Tags are matched case-sensitively.
<P>

Any line in the file beginning with a hash (#) is treated as a
comment, and ignored.
<P>

The tag types which are legal in this file are:
<A NAME="lbBM">&nbsp;</A>
<H3>N</H3>

The name of the scenario. A free-format string
<P>

default value: the name of the scenario file
<A NAME="lbBN">&nbsp;</A>
<H3>D</H3>

Any dependencies to be met.
<P>

Unused at present.
<A NAME="lbBO">&nbsp;</A>
<H3>R</H3>

The request to make. A valid HTTP request.
<P>

No default value. Scenarios without a Request are discarded.
<A NAME="lbBP">&nbsp;</A>
<H3>H</H3>

A header (beyond the basic GET request).
<P>

No default value. 
<A NAME="lbBQ">&nbsp;</A>
<H3>B</H3>

The body of a POST request 
<P>

No default value. 
<A NAME="lbBR">&nbsp;</A>
<H3>E </H3>

Expected results. Note that 
<B>hammerhead</B>

will strip off all HTTP header lines from the response (i.e. all lines
up to the first blank line in the response).
<P>

No default value. 
<A NAME="lbBS">&nbsp;</A>
<H3>L</H3>

Expected Log result. 
<P>

Not implemented yet.
<A NAME="lbBT">&nbsp;</A>
<H3>S</H3>

Name of the next scenario in a sequence
<P>

No default value. A scenario without a
<B>S</B>

scenario specified is assumed to be the last in a sequence.
<A NAME="lbBU">&nbsp;</A>
<H3>T</H3>

This option has 3 possible types of value:
A number is the &quot;think&quot; (or wait) time in milliseconds. 
If a '+' proceeds the number then this specifies a fixed time from
when Hammerhead begin to wait until (in milliseconds).
If the 3rd special value '_exit' is given,
then the thread running this scenario witll terminate after completing it.
<P>

default value: 0
<A NAME="lbBV">&nbsp;</A>
<H3>X</H3>

The number of times this scenario may be cross-referenced by other
scenarios (i.e. may be used in a sequence). A value of -1 is used to
represent unlimited use, while 0 and positive numbers have the obvious
meaning.
<P>

default value: -1
<A NAME="lbBW">&nbsp;</A>
<H3>O</H3>

A number of options relating to a scenario are available.
For example,
<DL COMPACT><DT><DD>
<DL COMPACT>
<DT><DD>
<B>SSL</B>

= 
[
<I>on</I>|<I>off</I>

] 
</DL>
<P>

This option turns SSL on or off for this request, overriding the
use of SSL in the configuration file.
<DL COMPACT>
<DT><DD>
<B>PORT</B>

= 
[
<I>port</I>

]
</DL>
<P>

This option allows for an alternative port number to be specificed for
this scenario, overriding the port specified in the configuration file.
</DL>

<A NAME="lbBX">&nbsp;</A>
<H3>.</H3>

End of scenario definition.
<P>
<A NAME="lbBY">&nbsp;</A>
<H2>RESULTS FILE</H2>

<P>
<P>

The results file contains a log of all requests. Each log line
contains a time stamp, the process id of the session, the name of the 
scenario used, three times, the size of the response, the return code 
from the server and the server description.
<P>

The three recorded times are an offset from the initial start time, the
time it took to get the first response from the server and the
total time it took to get the complete response and process it.
Typically these two times are similar, although network issues can
cause the total time to be somewhat greater than the response time.
Each time value is recorded in milliseconds.
<P>

<P>
<A NAME="lbBZ">&nbsp;</A>
<H2>EXAMPLES</H2>

<A NAME="lbCA">&nbsp;</A>
<H3>Configuration File</H3>

# example configuration file - test.conf
<P>

# find all scenarios in this directory
<DL COMPACT><DT><DD>
Scenario_directory /u01/hammerhead/test1
<P>

# put all log messages in this file
<DL COMPACT><DT><DD>
Log_filename /u01/hammerhead/test1/test1.log
<P>

# Load all embedded images in each page returned by the port
<DL COMPACT><DT><DD>
Load_images on
<P>

# Simulate 50 users
<DL COMPACT><DT><DD>
Sessions 50
<P>

# Force all sequences to be completed
<DL COMPACT><DT><DD>
Sequence_probability 100
<P>

# Sleep 100ms between each request
<DL COMPACT><DT><DD>
Sleep_time 100
<P>

# Run the test for 10 minutes
<DL COMPACT><DT><DD>
Run_time 600
<P>

# Hammer goanna, on port 8080
<DL COMPACT><DT><DD>
10.456.789.012:8080
</DL>
</DL>
</DL>
</DL>
</DL>
</DL>
</DL>
</DL>
<A NAME="lbCB">&nbsp;</A>
<H3>Scenario File</H3>

<BR>&nbsp;#&nbsp;Example&nbsp;Scenario&nbsp;file&nbsp;-&nbsp;test.scn
<P>

<BR>&nbsp;#&nbsp;Get&nbsp;the&nbsp;main&nbsp;page,&nbsp;then&nbsp;think&nbsp;for&nbsp;one&nbsp;second,&nbsp;then&nbsp;go&nbsp;to
<DL COMPACT><DT><DD>
<BR>&nbsp;#&nbsp;the&nbsp;next&nbsp;scenario
<DL COMPACT><DT><DD>
<BR>&nbsp;NTest&nbsp;Scenario&nbsp;1
<DL COMPACT><DT><DD>
<BR>&nbsp;RGET&nbsp;/&nbsp;HTTP/1.0
<DL COMPACT><DT><DD>
<BR>&nbsp;STest&nbsp;Scenario&nbsp;2
<DL COMPACT><DT><DD>
<BR>&nbsp;T1000000
<DL COMPACT><DT><DD>
<BR>&nbsp;E&lt;html&gt;
<DL COMPACT><DT><DD>
<BR>&nbsp;E&lt;head&gt;
<DL COMPACT><DT><DD>
<BR>&nbsp;E&lt;title&gt;Hammerhead&nbsp;-&nbsp;exploring&nbsp;Hammerland&lt;/title&gt;
<DL COMPACT><DT><DD>
<BR>&nbsp;E&lt;link&nbsp;rev=made&nbsp;href=&quot;mailto:<A HREF="mailto:feedback@hammerhead.sourceforge.net">feedback@hammerhead.sourceforge.net</A>&quot;&gt;
<DL COMPACT><DT><DD>
<BR>&nbsp;E&lt;/head&gt;
<DL COMPACT><DT><DD>
<BR>&nbsp;.
<DL COMPACT><DT><DD>
<BR>&nbsp;#&nbsp;Get&nbsp;some&nbsp;random&nbsp;page,&nbsp;don't&nbsp;think,&nbsp;and&nbsp;go&nbsp;nowhere&nbsp;else
<DL COMPACT><DT><DD>
<BR>&nbsp;#&nbsp;NOTE:&nbsp;.&nbsp;at&nbsp;end&nbsp;of&nbsp;scenario&nbsp;not&nbsp;required&nbsp;at&nbsp;end&nbsp;of&nbsp;file
<DL COMPACT><DT><DD>
<BR>&nbsp;NTest&nbsp;Scenario&nbsp;2
<DL COMPACT><DT><DD>
<BR>&nbsp;RGET&nbsp;/coma&nbsp;HTTP/1.0
</DL>
</DL>
</DL>
</DL>
</DL>
</DL>
</DL>
</DL>
</DL>
</DL>
</DL>
</DL>
</DL>
</DL>
</DL>
<A NAME="lbCC">&nbsp;</A>
<H3>Usage</H3>

<P>

The following example:
<DL COMPACT><DT><DD>
<B>example% hammerhead -c test.conf results.log</B>

</DL>

<P>

hammers the machine/port specified in the
<B>test.conf</B>

configuration file.
<A NAME="lbCD">&nbsp;</A>
<H2>EXIT STATUS</H2>

The following exit values are returned:

<DL COMPACT>
<DT><B>0</B>

<DD>
<P>
<B>hammerhead</B>

ran successfully to completion.
<DT><B>&gt;0</B>

<DD>
An error occurred.

</DL>
<A NAME="lbCE">&nbsp;</A>
<H2>SEE ALSO</H2>

<B><A HREF="http://localhost/cgi-bin/man/man2html?3N+inet_addr">inet_addr</A></B>(3N)

<A NAME="lbCF">&nbsp;</A>
<H2>NOTES</H2>

The scenario file created by
<B>hammerhead</B>

when using the 
<B>resultsFile</B>

operand is optimised to make it quicker for

to load. All scenario names will be lost. Since 
<B>hammerhead</B>

only ever reports errors in terms of the request being made, this is
no great loss.
<P>

The results generated when using the
<B>resultsFile</B>

operand may contain non-printing characters which may corrupt terminal
settings.
<P>

<HR>
<A NAME="index">&nbsp;</A><H2>Index</H2>
<DL>
<DT><A HREF="#lbAB">NAME</A><DD>
<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
<DT><A HREF="#lbAE">OPTIONS</A><DD>
<DT><A HREF="#lbAF">OPERANDS</A><DD>
<DT><A HREF="#lbAG">CONFIGURATION FILE</A><DD>
<DL>
<DT><A HREF="#lbAH">Scenario_directory</A><DD>
<DT><A HREF="#lbAI">Scenario_file</A><DD>
<DT><A HREF="#lbAJ">Log_filename</A><DD>
<DT><A HREF="#lbAK">Load_images</A><DD>
<DT><A HREF="#lbAL">Sessions</A><DD>
<DT><A HREF="#lbAM">Seed</A><DD>
<DT><A HREF="#lbAN">Sequence_probability</A><DD>
<DT><A HREF="#lbAO">Sleep_time</A><DD>
<DT><A HREF="#lbAP">Run_time</A><DD>
<DT><A HREF="#lbAQ">Machine_IP</A><DD>
<DT><A HREF="#lbAR">Ip_Alias</A><DD>
<DT><A HREF="#lbAS">Premature_Close</A><DD>
<DT><A HREF="#lbAT">Bad_Request</A><DD>
<DT><A HREF="#lbAU">Report_Time</A><DD>
<DT><A HREF="#lbAV">Report_Log</A><DD>
<DT><A HREF="#lbAW">Robot_ID</A><DD>
<DT><A HREF="#lbAX">Send_Cookie</A><DD>
<DT><A HREF="#lbAY">Premature_Close</A><DD>
<DT><A HREF="#lbAZ">Log_Level</A><DD>
<DT><A HREF="#lbBA">Bandwidth_Limit</A><DD>
<DT><A HREF="#lbBB">Crawl</A><DD>
<DT><A HREF="#lbBC">SelectOn</A><DD>
<DT><A HREF="#lbBD">Start_Lag</A><DD>
<DT><A HREF="#lbBE">DNS_Server</A><DD>
<DT><A HREF="#lbBF">DNS_TTL</A><DD>
<DT><A HREF="#lbBG">Machine_Name</A><DD>
<DT><A HREF="#lbBH">Use_SSL</A><DD>
<DT><A HREF="#lbBI">HTTP_Request_Type</A><DD>
<DT><A HREF="#lbBJ">BottleNeck</A><DD>
<DT><A HREF="#lbBK">Max_Failures</A><DD>
</DL>
<DT><A HREF="#lbBL">SCENARIO FILE</A><DD>
<DL>
<DT><A HREF="#lbBM">N</A><DD>
<DT><A HREF="#lbBN">D</A><DD>
<DT><A HREF="#lbBO">R</A><DD>
<DT><A HREF="#lbBP">H</A><DD>
<DT><A HREF="#lbBQ">B</A><DD>
<DT><A HREF="#lbBR">E </A><DD>
<DT><A HREF="#lbBS">L</A><DD>
<DT><A HREF="#lbBT">S</A><DD>
<DT><A HREF="#lbBU">T</A><DD>
<DT><A HREF="#lbBV">X</A><DD>
<DT><A HREF="#lbBW">O</A><DD>
<DT><A HREF="#lbBX">.</A><DD>
</DL>
<DT><A HREF="#lbBY">RESULTS FILE</A><DD>
<DT><A HREF="#lbBZ">EXAMPLES</A><DD>
<DL>
<DT><A HREF="#lbCA">Configuration File</A><DD>
<DT><A HREF="#lbCB">Scenario File</A><DD>
<DT><A HREF="#lbCC">Usage</A><DD>
</DL>
<DT><A HREF="#lbCD">EXIT STATUS</A><DD>
<DT><A HREF="#lbCE">SEE ALSO</A><DD>
<DT><A HREF="#lbCF">NOTES</A><DD>
</DL>
<HR>
This document was created by
<A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
using the manual pages.<BR>
Time: 02:59:23 GMT, November 13, 2002
</BODY>
</HTML>