.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SIEGE 1"
.TH SIEGE 1 "2016-05-20" "JoeDog" "Siege Load Tester"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
siege \- An HTTP/FTP load tester and benchmarking utility.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&  siege [options]
\&  siege [options] <URL>
\&  siege [options] \-g <URL>
\&  siege [options] \-f urls.txt
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CWsiege\fR is a multi-threaded \s-1HTTP/FTP\s0 load tester and benchmarking 
utility. It supports most of the features detailed in RFCs 2616 (\s-1HTTP\s0)
and 959 (\s-1FTP\s0). Properties can be set at both from the command line and
in a configuration file. When the same propertie is set in both 
locations, the command line takes precedent.
.PP
The default configuration file is \f(CW$HOME\fR/.siege/siege.conf If you don't 
have a \f(CW$HOME\fR/.siege directory and a siege.conf and cookies.txt file, 
siege will generate a new config directory when it runs. You can 
generate your configu directory with the following command: siege.config
.SH "OPTIONS"
.IX Header "OPTIONS"
.SS "Option Syntax"
.IX Subsection "Option Syntax"
\&\f(CWsiege\fR supports long and short options. Short options look like this:
    \-c 25
    \-c25
.PP
Long options look like this:
    \-\-concurrent=25
.SS "Option Values"
.IX Subsection "Option Values"
.IP "\fB\-V\fR, \fB\-\-version\fR" 4
.IX Item "-V, --version"
Displays the \f(CWsiege\fR release version and copyright information.
.IP "\fB\-h\fR, \fB\-\-help\fR" 4
.IX Item "-h, --help"
Prints a help message describing \f(CWsiege\fR's command-line options.
.IP "\fB\-C\fR, \fB\-\-config\fR" 4
.IX Item "-C, --config"
Prints a detailed summary of all the currently configured options, most
of which are sent in \f(CW$HOME\fR/.siege/siege.conf
.IP "\fB\-v\fR, \fB\-\-vebose\fR" 4
.IX Item "-v, --vebose"
This directive puts \f(CWsiege\fR into verbose mode which is actually a 
default setting. This command-line option is useful when the config 
file is set to 'verbose = false' since it will allow you to override 
that.
.Sp
By default \f(CWsiege\fR's verbose output is displayed in a color-coded 
style.
  * \s-1HTTP\s0 2xx is coded blue
  * \s-1HTTP\s0 3xx is coded cyan
  * \s-1HTTP\s0 4xx is coded magenta
  * \s-1HTTP\s0 5xx is coded red
  * \s-1HTTP\s0 cached is coded black
.Sp
\&\s-1NOTE:\s0 You can turn off color in siege.conf like this: 'color = off'
.IP "\fB\-q\fR, \fB\-\-quiet\fR" 4
.IX Item "-q, --quiet"
This directive silences \f(CWsiege\fR. It is mostly used for scripting and 
is often used in conjunction with \-g/\-\-get. You can detect the success 
or failure of the run with its exit code.
.Sp
.Vb 6
\&  siege \-\-quiet \-g www.joedog.org
\&  if [ $? \-eq 0 ] ; then
\&    echo "Success"
\&  else
\&    echo "Failure"
\&  fi
.Ve
.IP "\fB\-g \s-1URL\s0\fR, \fB\-\-get=URL\fR" 4
.IX Item "-g URL, --get=URL"
This option allows you to request a \s-1URL\s0 and watch the header 
transaction.  There is a corresponding config file directive that 
allows you to set the request method for these requests: 
gmethod = HEAD|GET
.Sp
.Vb 6
\&  $ siege \-g "https://www.joedog.org/"
\&  HEAD / HTTP/1.0
\&  Host: www.joedog.org
\&  Accept: */*
\&  User\-Agent: Mozilla/5.0 (unknown\-x86_64\-linux\-gnu) Siege/4.0.0\-beta5
\&  Connection: close
\&
\&  HTTP/1.1 200 OK
\&  Server: cloudflare\-nginx
\&  Date: Tue, 09 Feb 2016 18:18:41 GMT
\&  Content\-Type: text/html; charset=UTF\-8
\&  Connection: close
\&  Last\-Modified: Wed, 25 Nov 2015 18:46:08 GMT
\&  Cache\-Control: max\-age=3, must\-revalidate
\&  Expires: Tue, 09 Feb 2016 18:18:44 GMT
\&  Vary: Accept\-Encoding,Cookie
\&  CF\-RAY: 27219407eeff084a\-IAD
.Ve
.Sp
\&\s-1NOTE:\s0 It's best practice to quote the \s-1URL\s0 when it's passed to \f(CWsiege\fR 
from the the command-line.
.IP "\fB\-c \s-1NUM\s0\fR, \fB\-\-concurrent=NUM\fR" 4
.IX Item "-c NUM, --concurrent=NUM"
This option allows you to set the concurrent number of users. The total 
number of users is technically limited to your computer's resources.
.Sp
You should not configure more users than your web server is configured 
to handle. For example, the default apache configuration is capped at 
255 threads. If you run siege with \-c 1024, then 769 siege users are 
left waiting for an apache handler.
.Sp
For this reason, the default siege configuration is capped at 255 users.
You can increase that number inside siege.conf but if you make a mess, 
then please don't complain to us.
.IP "\fB\-r \s-1NUM\s0\fR, \fB\-\-reps=NUM|once\fR" 4
.IX Item "-r NUM, --reps=NUM|once"
This option tells each siege user how times it should run. The value 
should generally be a number greater than zero but it may be the keyword
\&'once'.
.Sp
If \-\-reps=3 then each siege user will run three times before it exits. 
However, if \-\-reps=once, then each user will run through the urls.txt 
file exactly one time.
.Sp
For more information about the urls.txt file, see option \-f <file>, 
\&\-\-file=<file>
.IP "\fB\-t NUMm\fR, \fB\-\-time=NUMm\fR" 4
.IX Item "-t NUMm, --time=NUMm"
This option is similar to \-\-reps but instead of specifying the number 
of times each user should run, it specifies the amount of time each 
should run.
.Sp
The value format is \*(L"NUMm\*(R", where \*(L"\s-1NUM\s0\*(R" is an amount of time and the \*(L"m\*(R"
modifier is either S, M, or H for seconds, minutes and hours. To run 
\&\f(CWsiege\fR 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.
.IP "\fB\-d \s-1NUM\s0\fR, \fB\-\-delay=NUM\fR" 4
.IX Item "-d NUM, --delay=NUM"
This option instructs \f(CWsiege\fR how long to delay between each page 
request.  The value \s-1NUM\s0 represents the number of seconds between each
one. This number can be a decimal value. In fact the default is half a
second (\-\-delay=0.5).
.Sp
The time between delay requests is \s-1NOT\s0 applied toward the transaction 
time. If two 0.1 second transactions have a 2 second delay between them,
their average transaction time is run is 0.1 seconds. It is applied 
toward the total elapsed time. In this scenario, the elapsed time would 
be 2.2 seconds.
.Sp
\&\s-1NOTE:\s0 when the parser is enabled (see: \-p/\-\-parser), there is no delay
between the page and its elements, i.e., style sheets, javascripts, etc. 
The delay is only between page requests.
.IP "\fB\-b\fR, \fB\-\-benchmark\fR" 4
.IX Item "-b, --benchmark"
This directive tells siege to go into benchmark mode. This means there 
is no delay between iterations.
.IP "\fB\-i\fR, \fB\-\-internet\fR" 4
.IX Item "-i, --internet"
This option sets siege into what we call internet mode. It makes 
requests from the urls.txt file (see: \-f <file> / \-\-file=<file>) in 
random order.
.IP "\fB\-f \s-1FILE\s0\fR, \fB\-\-file=FILE\fR" 4
.IX Item "-f FILE, --file=FILE"
This option tells siege to work with a list of urls inside a text 
file. The URLs are listed one per line. Unlike URLs that are passed as
a command-line argument, the URLs in this file should not be quoted.
.Sp
\&\f(CWsiege\fR's urls.txt parser supports comments and variables.
.IP "\fB\-R \s-1FILE\s0\fR, \fB\-\-rc=FILE\fR" 4
.IX Item "-R FILE, --rc=FILE"
This directive allows you to set an alternative resource file. By 
default, the siegerc file is \f(CW$HOME\fR/.siege/siege.conf With this 
directive, you can override the default and use an alternative file.
.IP "\fB\-L \s-1FILE\s0\fR, \fB\-\-log=FILE\fR" 4
.IX Item "-L FILE, --log=FILE"
The default log file is \f(CW$prefix\fR/var/log/siege.log. This directive 
allows you to specify and alternative file for logging.
.ie n .IP "\fB\-m ""string""\fR, \fB\-\-mark=""string""\fR" 4
.el .IP "\fB\-m ``string''\fR, \fB\-\-mark=``string''\fR" 4
.IX Item "-m string, --mark=string"
This option allows you to log a message to the log file before your 
stats are written there. It is generally used to identify the 
proceeding run. You could, for example, mark the file with your
command-line parameters so it's understood what configuration 
generated the following data.
.ie n .IP "\fB\-H ""header: value""\fR, \fB\-\-header=""Header: value""\fR" 4
.el .IP "\fB\-H ``header: value''\fR, \fB\-\-header=``Header: value''\fR" 4
.IX Item "-H header: value, --header=Header: value"
This options allows you to set a custom header in the request. 
Generally speaking, this request will override an existing header. The
Cookie header is a special case.  If you set \-H \*(L"Cookie: value\*(R" then 
siege will send that cookie in addition to the other ones.
.ie n .IP "\fB\-A ""string""\fR, \fB\-\-agent=""string""\fR" 4
.el .IP "\fB\-A ``string''\fR, \fB\-\-agent=``string''\fR" 4
.IX Item "-A string, --agent=string"
This option allows you to override the default user-agent with a custom 
one.
.Sp
.Vb 1
\&  siege \-\-agent="JoeDog Jr. in da hizzle"
.Ve
.Sp
Will set this header:
.Sp
.Vb 1
\&  User\-agent: JoeDog Jr. in da hizzle
.Ve
.Sp
Alternatively, you could set the User-agent with the \-H/\-\-header option 
above.
.ie n .IP "\fB\-T ""text""\fR, \fB\-\-content\-type=""text""\fR" 4
.el .IP "\fB\-T ``text''\fR, \fB\-\-content\-type=``text''\fR" 4
.IX Item "-T text, --content-type=text"
This is another set header shortcut. You use this option to override 
the default Content-type request header.
.SH "URL FORMAT"
.IX Header "URL FORMAT"
\&\f(CWsiege\fR supports \s-1RFC\s0 1738 \s-1URL\s0 formats but it takes pains to implement
commonly used shortcuts for your convenience. In addition to \s-1RFC\s0 1738 
formats, siege introduces its own \s-1URL\s0 format to indicate protocol method.
.PP
An \s-1RFC\s0 1738 \s-1URL\s0 looks like this:
  <scheme>://<username>:<password>@<hostname>\::<port>/<path>;<params>?<query>#<frag>
.PP
A \f(CWsiege\fR \s-1URL\s0 with a method idicator looks like this:
  <scheme>://<username>:<password>@<hostname>:<port>/<path> \s-1POST\s0 <query>
.PP
You can also post the contents of a file using the redirect character
like this:
  <scheme>://<username>:<password>@<hostname>:<port>/<path> \s-1POST\s0 </home/jeff/haha.txt
.PP
Here's two examples with the \f(CWsiege\fR method indicator:
  http://www.joedog.org/ \s-1POST\s0 haha=papa&dada=mama
  ftp://ftp.armstrong.com/ \s-1PUT\s0 </home/jdfulmer/etc/tests/bbc.jpg
.PP
\&\s-1NOTE:\s0 If you set URLs with method indicators at the command-line, then 
you \s-1MUST\s0 quote the thing or your shell will treat it like three separate
arguments. If the \s-1URL\s0 is in a urls.txt file, then you shouldn't quote it.
.PP
As mentioned above, \f(CWsiege\fR goes to great lengths to allow commonly 
used shortcuts that you're used to from most browser implementations. 
It treats many parts of the 1738 \s-1URL\s0 as optional. In this example, the 
parts in brackets are optional:
  [scheme://] host.domain.xxx [:port] [/path/file]
.PP
When \f(CWsiege\fR receives a host name it builds the \s-1URL\s0 with default 
assumptions.  www.joedog.org becomes http://www.joedog.org:80/
.SH "URLS.txt FILE"
.IX Header "URLS.txt FILE"
From the section called Option Syntax above we learn that \f(CWsiege\fR 
can take a \s-1URL\s0 as an argument. \f(CWsiege\fR \-c \-r2 www.joedog.org will 
request the JoeDog index page twice.  But what if you want to hit
large portions of the site? \f(CWsiege\fR will allow you to fill a file 
with URLs so that it can run through list.
.PP
The format for the file is one \s-1URL\s0 per line:
  https://www.joedog.org/
  https://www.joedog.org/haha/
  https://www.joedog.org/haha/ \s-1POST\s0 homer=simpson&marge=doestoo
.PP
The file also supports UNIX-style commenting:
  # Comment looks like this
  https://www.joedog.org/
  https://www.joedog.org/haha/
  https://www.joedog.org/haha/ \s-1POST\s0 homer=simpson&marge=doestoo
.PP
It supports shell-style variable declaration and references. This is 
convenient if you want to run the same test on two different tiers or
two different shemes:
.PP
.Vb 5
\&  SCHEME=https
\&  HOST=bart.joedog.org
\&  $(SCHEME)://$(HOST)/
\&  $(SCHEME)://$(HOST)/haha/
\&  $(SCHEME)://$(HOST)/haha/ POST homer=simpson&marge=doestoo
.Ve
.PP
You can tell siege about this file with the \-f/\-\-file option:
  siege \-c1 \-r50 \-f /home/jeff/urls.txt
.SH "PERFORMANCE STATISTICS"
.IX Header "PERFORMANCE STATISTICS"
When its run is complete, siege will gather performance data from all
its clients and summarize them after the run. (You can also choose to
log these numbers). The command-line output is modeled after Lincoln 
Stein's torture.pl script:
.PP
.Vb 12
\&  Transactions:                   2000 hits
\&  Availability:                 100.00 %
\&  Elapsed time:                  58.57 secs
\&  Data transferred:               5.75 MB
\&  Response time:                  0.25 secs
\&  Transaction rate:              34.15 trans/sec
\&  Throughput:                     0.10 MB/sec
\&  Concurrency:                    8.45
\&  Successful transactions:        2000
\&  Failed transactions:               0
\&  Longest transaction:            4.62
\&  Shortest transaction:           0.00
\&
\&  Transactions
\&      This number represents the total number of HTTP requests. In this
\&      example, we ran 25 simulated users [\-c25] and each ran ten times
\&      [\-r10]. Twenty\-five times ten equals 250 so why is the transaction 
\&      total 2000? That\*(Aqs because siege counts every request. This run 
\&      included a META redirect, a 301 redirect and the page it requested 
\&      contained several elements that were also downloaded.
\&
\&  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\*(Aqs requests.
\&
\&  Transaction rate
\&      The average number of transactions the server was able to handle
\&      per second, in a nutshell: it is the count of all transactions 
\&      divided by elapsed time.
\&
\&  Throughput
\&      The average number of bytes transferred every second from the 
\&      server to all the simulated users.
\&
\&  Concurrency
\&      This is the average number of simultaneous connections. The metric
\&      is calculated like this: the sum of all transaction times divided
\&      by elapsed time (how long siege ran) 
\&
\&  Successful transactions
\&      The number of times the server responded with a return code < 400.
\&
\&  Failed transactions
\&      The number of times the socket transactions failed 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.
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
\&\f(CWJeffrey Fulmer, et al.\fR <jeff@joedog.org> is the primary author of \f(CWsiege\fR. Numerous people 
throughout the globe also contributed to this program. Their 
contributions are noted in the source code ChangeLog
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright \f(CW\fR by \f(CWJeffrey Fulmer, et al.\fR <jeff@joedog.org>
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of the \s-1GNU\s0 General Public License as published by the 
Free Software Foundation; either version 2 of the License, or (at your 
option) any later version.
.PP
This program is distributed in the hope that it will be useful, but 
\&\s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of 
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the \s-1GNU\s0 
General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License along 
with this program; if not, write to the Free Software Foundation, Inc., 
675 Mass Ave, Cambridge, \s-1MA\s0 02139, \s-1USA\s0.
.SH "AVAILABILITY"
.IX Header "AVAILABILITY"
The most recent released version of \f(CWsiege\fR is available by \s-1HTTP\s0 
download:
  http://download.joedog.org/pub/siege
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIsiege.config\fR\|(1) \fIbombardment\fR\|(1) \fIsiege2csv\fR\|(1)