hammerhead(1)					    hammerhead(1)


NAME
       hammerhead  -  hammer  a	 given machine/port with a set of
       http requests

SYNOPSIS
       hammerhead configFile [ 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 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 all 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.

OPTIONS
       The following options are supported:

       -t	 This option causes the config file and specified
		 scenario  files  to  be  loaded  and proceeds to
		 request  each	scenario  from	each  target  web
		 server. Any failures are reported.

       -T	 This option is the same as -t.

       -c	 This  option  causes the config to be loaded and
		 then exits. This is useful to	check  configura-
		 tion file syntax.

       -C	 This option is the same as -c.

OPERANDS
       The following operand is supported:

       configFile
		 The  name  of	the configuration file to read to
		 determine the behaviour of hammerhead.

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  sce-
       nario  file is any file with the extension .scn (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/

   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	microseconds)  to  sleep  between
       requests.  In  fact,  this  is the average sleep time, and
       hammerhead will sleep  for  a  randomly	selected  period,
       between 0 microseconds, and twice this value.

       default value: 0

   Summary_interval
       The  number of requests a thread should make before print-
       ing a summary line.

       default value: 10

   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 con-
       figuration 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  termi-
       nated  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_Cookies
       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 hammer-
       head 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 dis-
       carded.

   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  speci-
       fied is assumed to be the last in a sequence.

   T
       Think time in milliseconds

       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.


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

       # Print a summary report every 1000 requests
       Summary_interval 1000

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

   Usage
       The following example:
	      example% hammerhead test.conf

       hammers the machine/port specified in the  test.conf  con-
       figuration 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 ter-
       minal settings.


			   15 Feb 2000				9


