siege - An HTTP/HTTPS stress tester

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.

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]

Siege understands the following URL formats:

(brackets indicate the directive is optional)



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



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



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



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



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



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

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

Jeffrey Fulmer <jeff@joedog.org>

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

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.

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

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