1SIEGE(1) General Commands Manual SIEGE(1)
2
6 siege - An HTTP/HTTPS stress tester
7
9 Siege is a multi-threaded http load testing and benchmarking utility.
10 It was designed to let web developers measure the performance of their
11 code under duress. It allows one to hit a web server with a config‐
12 urable number of concurrent simulated users. Those users place the
13 webserver "under siege." Performance measures include elapsed time,
14 total data transferred, server response time, its transaction rate, its
15 throughput, its concurrency and the number of times it returned OK.
16 These measures are quantified and reported at the end of each run.
17 Their meaning and significance is discussed below. Siege has essen‐
18 tially three modes of operation: regression (when invoked by bombard‐
19 ment), internet simulation and brute force.
20
22 The format for invoking siege is: siege [options]
23 siege [options] [url]
24 siege -g [url]
25 Siege supports the following command line options:
27 -V, --version
29 VERSION, prints the version number
30 -h, --help
32 HELP, prints the help section which includes a summary of all
33 the command line options.
34 -C, --config
36 CONFIGURATION, prints the current configuration in the
37 $HOME/.siegerc file. Edit that file to set flag values for
38 EVERY siege run, a feature which eases runtime invocation. You
39 set an alternative resource file with the SIEGERC environment
40 variable: export SIEGERC=/home/jeff/haha
41 -v, --verbose
43 VERBOSE, prints the HTTP return status and the GET request to
44 the screen. Useful when reading a series of URLs from a
45 configuration file. This flag allows you to witness the
46 progress of the test.
47 -g, --get
49 GET, pull down HTTP headers and display the transaction. Great
50 for web server configuration debugging. Requires a URL be passed
51 to siege on the command line.
52 -c NUM, --concurrent=NUM
54 CONCURRENT, allows you to set the concurrent number of simulated
55 users to num. The number of simulated users is limited to the
56 resources on the computer running siege.
57 -i, --internet
59 INTERNET, generates user simulation by randomly hitting the URLs
60 read from the urls.txt file. This option is viable only with
61 the urls.txt file.
62 -d NUM, --delay=NUM
64 DELAY, each siege simulated users sleeps for a random interval
65 in seconds between 0 and NUM.
66 -b, --benchmark
68 BENCHMARK, runs the test with NO DELAY for throughput benchmark‐
69 ing. By default each simulated user is invoked with at least a
70 one second delay. This option removes that delay. It is not
71 recommended that you use this option while load testing.
72 -r NUM, --reps=NUM, --reps=once
74 REPS, allows you to run the siege for NUM repetitions. If
75 --reps=once, then siege will run through the urls.txt file one
76 time and stop when it reaches the end. NOTE: -t/--time takes
77 precedent over -r/--reps. If you want to use this option, make
78 sure time = x is commented out in your $HOME/.siegerc file.
79 -t NUMm, --time=NUMm
81 TIME, allows you to run the test for a selected period of time.
82 The format is "NUMm", where NUM is a time unit and the "m" modi‐
83 fier is either S, M, or H for seconds, minutes and hours. To
84 run siege for an hour, you could select any one of the following
85 combinations: -t3600S, -t60M, -t1H. The modifier is not case
86 sensitive, but it does require no space between the number and
87 itself.
88 -l [FILE], --log[=FILE]
90 LOG transaction stats to FILE. The argument is optional. If FILE
91 is not specified, then siege logs the transaction to
92 SIEGE_HOME/var/siege.log. If siege is installed in /usr/local,
93 then the default siege.log is /usr/local/var/siege.log. This
94 option logs the final statistics reported when siege success‐
95 fully completes its test. You can edit $HOME/.siegerc to change
96 the location of the siege.log file.
97 -m MESSAGE, --mark=MESSAGE
99 MARK, mark the log file with a separator. This option will
100 allow you to separate your log file entries with header informa‐
101 tion. This is especially useful when testing two different
102 servers. It is not necessary to use both the -m option and the
103 -l option. -m assumes -l so it marks and logs the transaction.
104 If the MESSAGE has spaces in it, make sure that you put it in
105 quotes.
106 -H HEADER, --header=HEADER
108 HEADER, this option allows you to add additional header informa‐
109 tion.
110 -R SIEGERC, --rc=SIEGERC
112 RC, sets the siegerc file for the run. This option overrides the
113 environment variable SIEGERC and the default resource file,
114 $HOME/.siegerc
115 -f FILE, --file=FILE
117 FILE, the default URL file is SIEGE_HOME/etc/urls.txt. To
118 select a different URL file, use this option, i.e., siege -f
119 myurls.txt
120 -A "User Agent", --user-agent="User Agent"
122 AGENT, use this option to set the User-Agent in the request.
123
125 Siege understands the following URL formats:
126 (brackets indicate the directive is optional)
127 [protocol://] host.domain.xxx [:port] [/path/file]
129 host.domain.xxx/file POST field=value&field2=value2
131 Or you can POST the contents of a file using the line input operator,
133 the "<" character:
134 host/file POST </home/jeff/haha.txt
136 The first example above is an implicit GET, the next two are obviously
138 POSTs. You can pass parameters using GET much like you would in a web
139 browser:
140 www.haha.com/form.jsp?first=homer&last=simpson
142 If you invoke the URL as a command line argument, you should probably
144 place it in quotes. Currently, it supports two protocols, http and
145 https. If a protocol is not specified, then siege assumes http. The
146 minimum URL requirement is this: servername. That's it. So if you're
147 in the same domain as a server named shemp and shemp is in your host
148 file or it is in DNS, then: "siege shemp" will stress
149 http://shemp.yourdomain.net/index.html (assuming that "index.html" is
150 the server specified index). To stress the same page using https proto‐
151 col, the minimum URL requirement is this: https://shemp. That URL
152 specification will lay siege to https://shemp.yourdomain.net/index.html
153
155 To hit multiple URLs, place them in a single file. The default URLs
156 file is $SIEGE_HOME/etc/urls.txt. [You may change that file with the
157 -f option, see above.] In that file list the URLs one per line:
158 # place all your comments behind hashes
159 http://homer.whoohoo.com/index.html
160 http://homer.whoohoo.com/howto.jsp
161 http://go.whoohoo.com/cgi-bin/q.cgi?scope=a
162 http://go.whoohoo.com/cgi-bin/q.cgi POST scope=a
163 http://homer.whoohoo.com/my.jsp POST a=1&b=2
164 # POST the contents of a file...
165 www.haha.com/aha.jsp POST </home/jeff/my.txt
166 www.haha.com/parser.jsp POST <./my.txt
167 When invoked without a URL on the command line, siege looks for URLs in
169 a file. Normally, it reads them all into memory and runs through them
170 sequentially. If you specify internet mode [-i], then it randomly
171 selects URLs to hit.
172 You may set and reference variables in URLs file. It is necessary to
174 set them PRIOR to referencing them. The syntax for defining variables
175 is NAME = VALUE with a single assignment on a single line. If you
176 define several variables in the file, you must place each assignment on
177 a single line. To use the value of the variable, you must reference it
178 inside $() or ${}, i.e., $(NAME). If you reference a variable that
179 doesn't exist, siege will evaluate it to the empty string "".
180 # Example using variable assignment
181 # in the urls.txt file.
182 HOST = homer.whoohoo.com
183 http://${HOST}/index.html
184 http://${HOST}/howto.jsp
185
187 Performance measures include elapsed time of the test, the amount of
188 data transferred ( including headers ), the response time of the
189 server, its transaction rate, its throughput, its concurrency and the
190 number of times it returned OK. These measures are quantified and
191 reported at the end of each run. The reporting format is modeled after
192 Lincoln Stein's torture.pl script:
193 ** Siege 2.60
194 ** Preparing 100 concurrent users for battle.
195 The server is now under siege...done
196 Transactions: 339 hits
197 Availability: 93.39 %
198 Elapsed time: 67.47 secs
199 Data transferred: 4273708 bytes
200 Response time: 8.25 secs
201 Transaction rate: 5.02 trans/sec
202 Throughput: 63342.34 bytes/sec
203 Concurrency: 41.47
204 Successful transactions: 337
205 Failed transactions: 26
206 Longest transaction: 17.77 secs
207 Shortest transaction: 0.37 secs
208 Transactions
210 The number of server hits. In the example, 25 simulated users [
211 -c25 ] each hit the server 10 times [ -r10 ], a total of 250
212 transactions. It is possible for the number of transactions to
213 exceed the number of hits that were scheduled. Siege counts
214 every server hit a transaction, which means redirections and
215 authentication challenges count as two hits, not one. With this
216 regard, siege follows the HTTP specification and it mimics
217 browser behavior.
218 Availability
220 This is the percentage of socket connections successfully han‐
221 dled by the server. It is the result of socket failures (includ‐
222 ing timeouts) divided by the sum of all connection attempts.
223 This number does not include 400 and 500 level server errors
224 which are recorded in "Failed transactions" described below.
225 Elapsed time
227 The duration of the entire siege test. This is measured from
228 the time the user invokes siege until the last simulated user
229 completes its transactions. Shown above, the test took 14.67
230 seconds to complete.
231 Data transferred
233 The sum of data transferred to every siege simulated user. It
234 includes the header information as well as content. Because it
235 includes header information, the number reported by siege will
236 be larger then the number reported by the server. In internet
237 mode, which hits random URLs in a configuration file, this num‐
238 ber is expected to vary from run to run.
239 Response time
241 The average time it took to respond to each simulated user's
242 requests.
243 Transaction rate
245 The average number of transactions the server was able to handle
246 per second, in a nutshell: transactions divided by elapsed time.
247 Throughput
249 The average number of bytes transferred every second from the
250 server to all the simulated users.
251 Concurrency
253 The average number of simultaneous connections, a number which
254 rises as server performance decreases.
255 Successful transactions
257 The number of times the server responded with a return code <
258 400.
259 Failed transactions
261 The number of times the server responded with a return code >=
262 400 plus the sum of all failed socket transactions which
263 includes socket timeouts.
264 Longest transaction
266 The greatest amount of time that any single transaction took,
267 out of all transactions.
268 Shortest transaction
270 The smallest amount of time that any single transaction took,
271 out of all transactions.
272
275 Jeffrey Fulmer, et al. <jeff@joedog.org>
276
278 Report bugs to jeff@joedog.org. Give a detailed description of the
279 problem and report the version of siege that you are using.
280
282 Copyright © 2000 2001 2004 Jeffrey Fulmer, et al.
283 This program is free software; you can redistribute it and/or modify it
285 under the terms of the GNU General Public License as published by the
286 Free Software Foundation; either version 2 of the License, or (at your
287 option) any later version.
288 This program is distributed in the hope that it will be useful, but
290 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
291 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
292 Public License for more details.
293 You should have received a copy of the GNU General Public License along
295 with this program; if not, write to the Free Software Foundation, Inc.,
296 675 Mass Ave, Cambridge, MA 02139, USA.
297
299 The most recent released version of siege is available by anonymous FTP
300 from ftp.joedog.org in the directory pub/siege.
301
303 siege.config(1) urls_txt(5) layingsiege(7)
304Siege v2.70 July-17-2010 SIEGE(1)