hammerhead(1)                                       hammerhead(1)



NNAAMMEE
       hammerhead  - perform load testing on a given machine/port
       with a set of http requests

SSYYNNOOPPSSIISS
       hhaammmmeerrhheeaadd [ _o_p_t_i_o_n_s ] [ _r_e_s_u_l_t_s_F_i_l_e ]

DDEESSCCRRIIPPTTIIOONN
       HHaammmmeerrhheeaadd 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 hhaammmmeerrhheeaadd command
       is sends HTTP requests to  a  nominated  machine/port  (as
       specified  in  the  ccoonnffiiggFFiillee))  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 hhaammmmeerrhheeaadd is defined  (almost)  entirely
       by the ccoonnffiiggffiillee..  See the description of this file below
       for an explanation of all of the configuration options.

       hhaammmmeerrhheeaadd 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, hhaammmmeerrhheeaadd starts up a num-
       ber of threads  and  sends  requests  to  the  port.   The
       expected  result  of  a request may be specified in a sce-
       nario, 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 aallll scenarios which have the same request.


       Any failure to get a connection to the port, or any  fail-
       ure to receive a reply to a request will also be reported.

OOPPTTIIOONNSS
       The following options are supported:

       --ss oorr ----sseeccoonnddss
              Seconds to run tests for

       --oo oorr ----oouuttffiillee
            Output result file

       --tt oorr ----tteesstt
            Test the scenarios in the conf file.

       --CC oorr ----cchheecckkccoonnff
            Check config file

       --cc oorr ----ccoonnffffiillee
            Config file path

       --hh oorr ----hheellpp
            Display help information

       --vv oorr ----vveerrssiioonn
            Output version

OOPPEERRAANNDDSS
       The following operand is supported:

       _r_e_s_u_l_t_s_F_i_l_e_:
       Create an optimized scenario file to make hhaammmmeerrhheeaadd  load
       faster.

CCOONNFFIIGGUURRAATTIIOONN FFIILLEE
       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:

   SScceennaarriioo__ddiirreeccttoorryy
       The directory in which to find the Scenario  file(s).  All
       scenario  files  in  this directory will be loaded. A sce-
       nario file is any file with the extension ..ssccnn (case  sen-
       sitive). There may be more than one directive on a config-
       uration file. Each directory shall be  examined  for  sce-
       nario files.

       default value: /var/tmp/scenarios/

   SScceennaarriioo__ffiillee
       A specific file from which to read scenarios. There may be
       more than one directive on a configuration file.

   LLoogg__ffiilleennaammee
       The file in which all log messages  will  be  written.  If
       this  file  cannot  be created, hhaammmmeerrhheeaadd will default to
       using standard error.

       default value: /var/tmp/hammerhead/hh.log

   LLooaadd__iimmaaggeess
       A flag indicating whether  to  automatically  load  images
       which are referenced in the result of a request.

       posible values: on, off

       default value: off

   SSeessssiioonnss
       The number of threads to start up.

       default value: 1000

   SSeeeedd
       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

   SSeeqquueennccee__pprroobbaabbiilliittyy
       The percentage of the time that hhaammmmeerrhheeaadd 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

   SSlleeeepp__ttiimmee
       The  amount  of  time  (in  milliseconds) to sleep between
       requests. In fact, this is the  average  sleep  time,  and
       hhaammmmeerrhheeaadd  will  sleep  for  a  randomly selected period,
       between 0 milliseconds, and twice this value.

       default value: 0

   RRuunn__ttiimmee
       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

   MMaacchhiinnee__IIPP
       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  mmaann  iinneett__aaddddrr
       and <port_number> is optional.

       This  is the oonnllyy attribute that must be defined in a con-
       figuration file

       default value: no default for <machine_number>,  8080  for
       <port_number>

   IIpp__AAlliiaass
       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

   PPrreemmaattuurree__CClloossee
       The percentage of requests that will be improperly  termi-
       nated  before  sending/receiving is completed properly (to
       test problems such as FIN_WAIT1).

       default value: 0

   BBaadd__RReeqquueesstt
       The percentage of requests the will be scrambled  requests
       (outside the properly defined scenarios).

       default value: 0

   RReeppoorrtt__TTiimmee
       The  time  interval upon which to written report summaries
       to the report log.

       default value: 0 (report only once at test end.)

   RReeppoorrtt__LLoogg
       The log file which is to contain the report summaries.

       default value: /var/tmp/report.log

   RRoobboott__IIDD
       The robot id to be passed to the servers being hammered.

       Currently not implemented.

   SSeenndd__CCooookkiiee
       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

   PPrreemmaattuurree__CClloossee
       The percentage of connections which will close permaturely
       before the request reply has been fully read back from the
       server.

       default value: 0

   LLoogg__LLeevveell
       Log  levels defined to work with the crawl functionality -
       somewhat mystical and not confirmed to be working.

       default value: 0

   BBaannddwwiiddtthh__LLiimmiitt
       Turn on bandwidth limiting.

       Not implemented yet.

   CCrraawwll
       Crawl though the URLs contained in the reply to a request.
       Scope is somewhat unclear. Use with caution.

       default value: off

   SSeelleeccttOOnn
       When  choosing a new sequence to commence, select from all
       the scenarios [ _s_c_e_n_a_r_i_o ] or select from those  scenarios
       which  are  at  the beginning of a sequence of scenarios [
       _s_e_q_u_e_n_c_e ].

       default value: scenario

   SSttaarrtt__LLaagg
       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

   DDNNSS__SSeerrvveerr
       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
       _/_e_t_c_/_r_e_s_o_l_v_._c_o_n_f

   DDNNSS__TTTTLL
       The Time To Live for the self cached DNS queries.

       default value: 120 seconds

   MMaacchhiinnee__NNaammee
       The name of the machine/s to hammer. Names are resolved to
       addresses using the DNS resolver.

   UUssee__SSSSLL
       Should SSL be used during each request?

       default value: no

   HHTTTTPP__RReeqquueesstt__TTyyppee
       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

   BBoottttlleeNNeecckk
       Use  connection  bottlenecking to extend connecton holding
       time

       Not implemented yet.

   MMaaxx__FFaaiilluurreess
       The maximum number of request  failures  to  be  tolerated
       before we abandon the test. The value 0 means that hammer-
       head will never stop because of  an  excessive  number  of
       request failures.

       default value: 0

SSCCEENNAARRIIOO FFIILLEE
       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N
       The name of the scenario. A free-format string

       default value: the name of the scenario file

   DD
       Any dependencies to be met.

       Unused at present.

   RR
       The request to make. A valid HTTP request.

       No  default  value.  Scenarios  without a Request are dis-
       carded.

   HH
       A header (beyond the basic GET request).

       No default value.

   BB
       The body of a POST request

       No default value.

   EE
       Expected results. Note that hhaammmmeerrhheeaadd 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L
       Expected Log result.

       Not implemented yet.

   SS
       Name of the next scenario in a sequence

       No default value. A scenario without a SS  scenario  speci-
       fied is assumed to be the last in a sequence.

   T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 Ham-
       merhead 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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O
       A  number of options relating to a scenario are available.
       For example,

                     SSSSLL = [ _o_n|_o_f_f ]

              This option turns SSL on or off for  this  request,
              overriding  the  use  of  SSL  in the configuration
              file.

                     PPOORRTT = [ _p_o_r_t ]

              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.


RREESSUULLTTSS FFIILLEE
       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 com-
       plete  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.



EEXXAAMMPPLLEESS
   CCoonnffiigguurraattiioonn FFiillee
       # 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

   SScceennaarriioo FFiillee
        # 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.source-
       forge.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

   UUssaaggee
       The following example:
              eexxaammppllee%% hhaammmmeerrhheeaadd --cc tteesstt..ccoonnff rreessuullttss..lloogg

       hammers  the  machine/port specified in the tteesstt..ccoonnff con-
       figuration file.

EEXXIITT SSTTAATTUUSS
       The following exit values are returned:
       00          hhaammmmeerrhheeaadd ran successfully to completion.
       >>00        An error occurred.

SSEEEE AALLSSOO
       iinneett__aaddddrr(3N)

NNOOTTEESS
       The scenario file created by  hhaammmmeerrhheeaadd  when  using  the
       rreessuullttssFFiillee operand is optimised to make it quicker for to
       load. All scenario names will be  lost.  Since  hhaammmmeerrhheeaadd
       only  ever  reports  errors  in terms of the request being
       made, this is no great loss.

       The results generated when using the  rreessuullttssFFiillee  operand
       may contain non-printing characters which may corrupt ter-
       minal settings.



                           03 Jul 2002              hammerhead(1)
