Provided by: siege_2.61-3_i386 bug

NAME

       siege - An HTTP/HTTPS stress tester

INTRODUCTION

       Siege  is  a multi-threaded http load testing and benchmarking utility.
       It was designed to let web developers measure the performance of  their
       code  under  duress.   It  allows  one  to  hit  a  web  server  with a
       configurable number of concurrent simulated users.  Those  users  place
       the  webserver  "under  siege."   Performance  measures include elapsed
       time, total data transferred, server  response  time,  its  transaction
       rate,  its  throughput,  its  concurrency  and  the  number of times it
       returned OK.  These measures are quantified and reported at the end  of
       each  run.   Their  meaning and significance is discussed below.  Siege
       has essentially three modes of operation: regression (when  invoked  by
       bombardment), internet simulation and brute force.

INVOCATION

       The format for invoking siege is:   siege [options]
                                           siege [options] [url]
                                           siege -g [url]

       Siege supports the following command line options:

       -V, --version
              VERSION, prints the version number

       -h, --help
              HELP,  prints  the  help section which includes a summary of all
              the command line options.

       -C, --config
              CONFIGURATION,  prints  the   current   configuration   in   the
              $HOME/.siegerc  file.   Edit  that  file  to set flag values for
              EVERY siege run, a feature which eases runtime  invocation.  You
              set  an  alternative  resource file with the SIEGERC environment
              variable: export SIEGERC=/home/jeff/haha

       -v, --verbose
              VERBOSE, prints the HTTP return status and the  GET  request  to
              the   screen.    Useful when reading  a series of  URLs  from  a
              configuration file.  This  flag  allows  you  to   witness   the
              progress  of  the test.

       -g, --get
              GET,  pull  down  headers  from  the  server  and  display  HTTP
              transaction. Great for web application debugging. Requires a URL
              be passed to siege on the command line.

       -c NUM, --concurrent=NUM
              CONCURRENT, allows you to set the concurrent number of simulated
              users to num. The number of simulated users is  limited  to  the
              resources on the computer running siege.

       -i, --internet
              INTERNET, generates user simulation by randomly hitting the URLs
              read from the urls.txt file.  This option is  viable  only  with
              the urls.txt file.

       -d NUM, --delay=NUM
              DELAY,  each  siege simulated users sleeps for a random interval
              in seconds between 0 and NUM.

       -b, --benchmark
              BENCHMARK,  runs  the  test  with  NO   DELAY   for   throughput
              benchmarking.  By default each simulated user is invoked with at
              least a one second delay. This option removes that delay.  It is
              not recommended that you use this option while load testing.

       -r NUM, --reps=NUM
              REPS,  allows  you  to  run the siege for NUM repetitions. NOTE:
              -t/--time takes precedent over -r/--reps. If  you  want  to  use
              this  option,  make  sure  time  =  x  is  commented out in your
              $HOME/.siegerc file.

       -t NUMm, --time=NUMm
              TIME, allows you to run the test for a selected period of  time.
              The  format  is  "NUMm",  where  NUM  is a time unit and the "m"
              modifier is either S, M, or H for seconds,  minutes  and  hours.
              To  run  siege  for  an  hour,  you  could select any one of the
              following combinations: -t3600S, -t60M, -t1H.  The  modifier  is
              not  case  sensitive,  but  it does require no space between the
              number and itself.

       -l, --log
              LOG, log stats to SIEGE_HOME/var/siege.log. If you’ve  installed
              siege     in     /usr/local,     then     the    siege.log    is
              /usr/local/var/siege.log. This option logs the final  statistics
              reported  when  siege  successfully  completes its test. You can
              edit $HOME/.siegerc to change  the  location  of  the  siege.log
              file.

       -m MESSAGE, --mark=MESSAGE
              MARK,  mark  the  log  file  with a separator.  This option will
              allow  you  to  separate  your  log  file  entries  with  header
              information.    This  is  especially  useful  when  testing  two
              different servers.  It is not  necessary  to  use  both  the  -m
              option  and  the  -l option.  -m assumes -l so it marks and logs
              the transaction. If the MESSAGE has spaces in it, make sure that
              you put it in quotes.

       -H HEADER, --header=HEADER
              HEADER,   this  option  allows  you  to  add  additional  header
              information.

       -R SIEGERC, --rc=SIEGERC
              RC, sets the siegerc file for the run. This option overrides the
              environment  variable  SIEGERC  and  the  default resource file,
              $HOME/.siegerc

       -f FILE, --file=FILE
              FILE, the  default  URL  file  is  SIEGE_HOME/etc/urls.txt.   To
              select a different URL file, use this  option,  i.e.,   siege -f
              myurls.txt

       -u URL, --url=URL
              URL, use this option  to  stress  a  single  URL.   This  option
              overrides the URL file and stresses just the URL selected at the
              command line.  This feature has been deprecated. The new  format
              for  invoking  siege  is  siege [options] when using an urls.txt
              file and siege [options] [url]

URL FORMAT

       Siege understands the following URL formats:
       (brackets indicate the directive is optional)

       .br [protocol://] host.domain.xxx [:port] [/path/file]

       .br host.domain.xxx/file POST field=value&field2=value2

       .br Or you can POST the  contents  of  a  file  using  the  line  input
       operator, the "<"  character:

       .br host/file POST </home/jeff/haha.txt

       .br  The  first  example  above  is  an  implicit GET, the next two are
       obviously POSTs. You can pass parameters using GET much like you  would
       in a web browser:

       www.haha.com/form.jsp?first=homer&last=simpson

       .br  If  you invoke the URL on the command line with the -u option, you
       should probably place the URL in quotes.  Currently,  it  supports  two
       protocols,  http and https.  If a protocol is not specified, then siege
       assumes http.  The minimum URL requirement is this: servername.  That’s
       it.   So if you’re in the same domain as a server named shemp and shemp
       is in your host file or it is in  DNS,  then:  "siege  -u  shemp"  will
       stress     http://shemp.yourdomain.net/index.html     (assuming    that
       "index.html" is the server specified index). To stress  the  same  page
       using   https   protocol,   the   minimum   URL  requirement  is  this:
       https://shemp.    That   URL   specification   will   lay   siege    to
       https://shemp.yourdomain.net/index.html

URLS FILE

       To  hit  multiple  URLs, place them in a single file.  The default URLs
       file is $SIEGE_HOME/etc/urls.txt.  [You may change that file  with  the
       -f option, see above.] In that file list the URLs one per line:
       # place all your comments behind hashes
       http://homer.whoohoo.com/index.html
       http://homer.whoohoo.com/howto.jsp
       http://go.whoohoo.com/cgi-bin/q.cgi?scope=a
       http://go.whoohoo.com/cgi-bin/q.cgi POST scope=a
       http://homer.whoohoo.com/my.jsp POST a=1&b=2
       # POST the contents of a file...
       www.haha.com/aha.jsp POST </home/jeff/my.txt
       www.haha.com/parser.jsp POST <./my.txt

       When invoked without a URL on the command line, siege looks for URLs in
       a file.  Normally, it reads them all into memory and runs through  them
       sequentially.  If  you  specify  internet  mode  [-i], then it randomly
       selects URLs to hit.

       You may set and reference variables in URLs file. It  is  necessary  to
       set  them  PRIOR to referencing them. The syntax for defining variables
       is NAME = VALUE with a single assignment  on  a  single  line.  If  you
       define several variables in the file, you must place each assignment on
       a single line. To use the value of the variable, you must reference  it
       inside  $()  or  ${},  i.e.,  $(NAME). If you reference a variable that
       doesn’t exist, siege will evaluate it to the empty string "".
       # Example using variable assignment
       # in the urls.txt file.
       HOST = homer.whoohoo.com
       http://${HOST}/index.html
       http://${HOST}/howto.jsp

PERFORMANCE STATISTICS

       Performance measures include elapsed time of the test,  the  amount  of
       data  transferred  (  including  headers  ),  the  response time of the
       server, its transaction rate, its throughput, its concurrency  and  the
       number  of  times  it  returned  OK.  These measures are quantified and
       reported at the end of each run.  The reporting format is modeled after
       Lincoln Stein’s torture.pl script:
       ** Siege 2.60
       ** Preparing 100 concurrent users for battle.
       The server is now under siege...done
       Transactions:                    339 hits
       Availability:                  93.39 %
       Elapsed time:                  67.47 secs
       Data transferred:            4273708 bytes
       Response time:                  8.25 secs
       Transaction rate:               5.02 trans/sec
       Throughput:                 63342.34 bytes/sec
       Concurrency:                   41.47
       Successful transactions:         337
       Failed transactions:              26
       Longest transaction:           17.77 secs
       Shortest transaction:           0.37 secs

       Transactions
              The number of server hits.  In the example, 25 simulated users [
              -c25 ] each hit the server 10 times [ -r10 ],  a  total  of  250
              transactions.  It  is possible for the number of transactions to
              exceed the number of hits  that  were  scheduled.  Siege  counts
              every  server  hit  a  transaction, which means redirections and
              authentication challenges count as two hits, not one. With  this
              regard,  siege  follows  the  HTTP  specification  and it mimics
              browser behavior.

       Availability
              This  is  the  percentage  of  socket  connections  successfully
              handled  by  the  server.  It  is  the result of socket failures
              (including timeouts)  divided  by  the  sum  of  all  connection
              attempts.  This number does not include 400 and 500 level server
              errors which are recorded  in  "Failed  transactions"  described
              below.

       Elapsed time
              The  duration  of  the entire siege test.  This is measured from
              the time the user invokes siege until the  last  simulated  user
              completes  its  transactions.   Shown above, the test took 14.67
              seconds to complete.

       Data transferred
              The sum of data transferred to every siege simulated  user.   It
              includes  the header information as well as content.  Because it
              includes header information, the number reported by  siege  will
              be  larger  then  the number reported by the server. In internet
              mode, which hits random  URLs  in  a  configuration  file,  this
              number is expected to vary from run to run.

       Response time
              The  average  time  it  took to respond to each simulated user’s
              requests.

       Transaction rate
              The average number of transactions the server was able to handle
              per second, in a nutshell: transactions divided by elapsed time.

       Throughput
              The average number of bytes transferred every  second  from  the
              server to all the simulated users.

       Concurrency
              The  average  number of simultaneous connections, a number which
              rises as server performance decreases.

       Successful transactions
              The number of times the server responded with a  return  code  <
              400.

       Failed transactions
              The  number  of times the server responded with a return code >=
              400 plus  the  sum  of  all  failed  socket  transactions  which
              includes socket timeouts.

       Longest transaction
              The  greatest  amount  of time that any single transaction took,
              out of all transactions.

       Shortest transaction
              The smallest amount of time that any  single  transaction  took,
              out of all transactions.

AUTHOR

       Jeffrey Fulmer <jeff@joedog.org>

BUGS

       Report  bugs  to  jeff@joedog.org.   Give a detailed description of the
       problem and report the version of siege that you are using.

COPYRIGHT

       Copyright © 2000 2001 2004 Jeffrey Fulmer

       This program is free software; you can redistribute it and/or modify it
       under  the  terms of the GNU General Public License as published by the
       Free Software Foundation; either version 2 of the License, or (at  your
       option) any later version.

       This  program  is  distributed  in the hope that it will be useful, but
       WITHOUT  ANY  WARRANTY;  without   even   the   implied   warranty   of
       MERCHANTABILITY  or  FITNESS  FOR  A  PARTICULAR  PURPOSE.  See the GNU
       General Public License for more details.

       You should have received a copy of the GNU General Public License along
       with this program; if not, write to the Free Software Foundation, Inc.,
       675 Mass Ave, Cambridge, MA 02139, USA.

AVAILABILITY

       The most recent released version of siege is available by anonymous FTP
       from ftp.joedog.org in the directory pub/siege.

SEE ALSO

       siege.config(1) layingsiege(1)  urls_txt(1)