Man Linux: Main Page and Category List

NAME

       hammerhead - perform load testing on a given machine/port with a set of
       http requests

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
       configFile) 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.

       The behaviour  of  hammerhead  is  defined  (almost)  entirely  by  the
       configfile.   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

       -c or --conffile
            Config file path

       -h or --help
            Display help information

       -v or --version
            Output version

OPERANDS

       The following operand is supported:

       resultsFile:
       Create an optimized scenario file to make hammerhead load faster.

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
       referenced 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.
       Setting this number to  any  non-zero  value  will  give  deterministic
       behaviour (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
       that the current  request  is  in.  Setting  this  to  100  will  force
       hammerhead to follow any sequence it encounters to its completion.

       default value: 75

   Sleep_time
       The  amount  of  time  (in  milliseconds) to sleep between requests. In
       fact, this is the average sleep time, and hammerhead will sleep  for  a
       randomly selected period, between 0 milliseconds, and twice this value.

       default value: 0

   Run_time
       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.

       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
       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

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

       default value: 0

   Log_Level
       Log  levels  defined  to  work  with the crawl functionality - somewhat
       mystical 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
       seconds.

       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

   HTTP_Request_Type
       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

   BottleNeck
       Use connection bottlenecking to extend connecton holding time

       Not implemented yet.

   Max_Failures
       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

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
       Name of the next scenario in a sequence

       No default value. A scenario without a S scenario specified is  assumed
       to be the last in a sequence.

   T
       This  option has 3 possible types of value: A number is the "think" (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.

       default value: 0

   X
       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.

       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
              specificed  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
       Load_images on

       # Simulate 50 users
       Sessions 50

       # Force all sequences to be completed
       Sequence_probability 100

       # Sleep 100ms between each request
       Sleep_time 100

       # Run the test for 10 minutes
       Run_time 600

       # 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
       operand 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)