SYNOPSIS
hammerhead [ options ] [ resultsFile ]
DESCRIPTION
Hammerhead 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 hammerhead command is sends
HTTP requests to a nominated machine/port (as specified in the config-
File) to simulate load on that port. It can be used to test the behav-
iour of the port under load, or the ability of the port to service a
set of requests.
The behaviour of hammerhead is defined (almost) entirely by the config-
file. See the description of this file below for an explanation of all
of the configuration options.
hammerhead 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.
Once the scenarios are loaded, hammerhead 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 all scenarios which have
the same request.
Any failure to get a connection to the port, or any failure to receive
a reply to a request will also be reported.
OPTIONS
The following options are supported:
-s or --seconds
Seconds to run tests for
-o or --outfile
Output result file
-t or --test
Test the scenarios in the conf file.
-C or --checkconf
Check config file
CONFIGURATION FILE
The configuration file is a plain text file, containing a set of
attribute/value pairs. Attribute names are matched without regard to
case.
Any line in the file beginning with a hash (#) is treated as a comment,
and ignored.
The attributes which may be defined in this file are:
Scenario_directory
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 .scn (case sensitive). There may be more than one directive
on a configuration file. Each directory shall be examined for scenario
files.
default value: /var/tmp/scenarios/
Scenario_file
A specific file from which to read scenarios. There may be more than
one directive on a configuration file.
Log_filename
The file in which all log messages will be written. If this file cannot
be created, hammerhead will default to using standard error.
default value: /var/tmp/hammerhead/hh.log
Load_images
A flag indicating whether to automatically load images which are refer-
enced in the result of a request.
posible values: on, off
default value: off
Sessions
The number of threads to start up.
default value: 1000
Seed
The random number seed used for the random selection of requests. Set-
ting this number to any non-zero value will give deterministic behav-
iour (i.e. the same sequence of requests will be selected)
default value: 0
Sequence_probability
The percentage of the time that hammerhead will follow the sequence
threads run for-ever. This can be used to set up tests which run for a
particular length of time.
default value: 0
Machine_IP
The IP number (and possibly port) of the machine/port to hammer. The
format is <machine_number>[:<port_number>], where <machine_number> is
as described in man inet_addr and <port_number> is optional.
This is the only attribute that must be defined in a configuration file
default value: no default for <machine_number>, 8080 for <port_number>
Ip_Alias
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
Premature_Close
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
Bad_Request
The percentage of requests the will be scrambled requests (outside the
properly defined scenarios).
default value: 0
Report_Time
The time interval upon which to written report summaries to the report
log.
default value: 0 (report only once at test end.)
Report_Log
The log file which is to contain the report summaries.
default value: /var/tmp/report.log
Robot_ID
The robot id to be passed to the servers being hammered.
Currently not implemented.
Send_Cookie
Turn on to allow the sending of cookies with requests. Incoming cookies
tical and not confirmed to be working.
default value: 0
Bandwidth_Limit
Turn on bandwidth limiting.
Not implemented yet.
Crawl
Crawl though the URLs contained in the reply to a request. Scope is
somewhat unclear. Use with caution.
default value: off
SelectOn
When choosing a new sequence to commence, select from all the scenarios
[ scenario ] or select from those scenarios which are at the beginning
of a sequence of scenarios [ sequence ].
default value: scenario
Start_Lag
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
DNS_Server
Allow the specification of an alternate DNS server to use to resolve
the machinenames. This resolution is completed once server DNS_TTL sec-
onds.
default value: use the server nominated in /etc/resolv.conf
DNS_TTL
The Time To Live for the self cached DNS queries.
default value: 120 seconds
Machine_Name
The name of the machine/s to hammer. Names are resolved to addresses
using the DNS resolver.
Use_SSL
Should SSL be used during each request?
default value: no
of an excessive number of request failures.
default value: 0
SCENARIO FILE
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.
Any line in the file beginning with a hash (#) is treated as a comment,
and ignored.
The tag types which are legal in this file are:
N
The name of the scenario. A free-format string
default value: the name of the scenario file
D
Any dependencies to be met.
Unused at present.
R
The request to make. A valid HTTP request.
No default value. Scenarios without a Request are discarded.
H
A header (beyond the basic GET request).
No default value.
B
The body of a POST request
No default value.
E
Expected results. Note that hammerhead will strip off all HTTP header
lines from the response (i.e. all lines up to the first blank line in
the response).
No default value.
L
Expected Log result.
Not implemented yet.
S
X
The number of times this scenario may be cross-referenced by other sce-
narios (i.e. may be used in a sequence). A value of -1 is used to rep-
resent unlimited use, while 0 and positive numbers have the obvious
meaning.
default value: -1
O
A number of options relating to a scenario are available. For example,
SSL = [ on|off ]
This option turns SSL on or off for this request, overriding the
use of SSL in the configuration file.
PORT = [ port ]
This option allows for an alternative port number to be speci-
ficed for this scenario, overriding the port specified in the
configuration file.
.
End of scenario definition.
RESULTS FILE
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.
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.
EXAMPLES
Configuration File
# example configuration file - test.conf
# find all scenarios in this directory
Scenario_directory /u01/hammerhead/test1
# put all log messages in this file
Log_filename /u01/hammerhead/test1/test1.log
# Load all embedded images in each page returned by the port
# Hammer goanna, on port 8080
10.456.789.012:8080
Scenario File
# Example Scenario file - test.scn
# Get the main page, then think for one second, then go to
# the next scenario
NTest Scenario 1
RGET / HTTP/1.0
STest Scenario 2
T1000000
E<html>
E<head>
E<title>Hammerhead - exploring Hammerland</title>
E<link rev=made href="mailto:feedback@hammerhead.sourceforge.net">
E</head>
.
# Get some random page, don't think, and go nowhere else
# NOTE: . at end of scenario not required at end of file
NTest Scenario 2
RGET /coma HTTP/1.0
Usage
The following example:
example% hammerhead -c test.conf results.log
hammers the machine/port specified in the test.conf configuration file.
EXIT STATUS
The following exit values are returned:
0 hammerhead ran successfully to completion.
>0 An error occurred.
SEE ALSO
inet_addr(3N)
NOTES
The scenario file created by hammerhead when using the resultsFile op-
erand is optimised to make it quicker for to load. All scenario names
will be lost. Since hammerhead only ever reports errors in terms of the
request being made, this is no great loss.
The results generated when using the resultsFile operand may contain
non-printing characters which may corrupt terminal settings.
03 Jul 2002 hammerhead(1)
Man(1) output converted with
man2html