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 headers from the server and display HTTP transac‐
50 tion. Great for web application debugging. Requires a URL be
51 passed 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
74 REPS, allows you to run the siege for NUM repetitions. NOTE:
75 -t/--time takes precedent over -r/--reps. If you want to use
76 this option, make sure time = x is commented out in your
77 $HOME/.siegerc file.
78 -t NUMm, --time=NUMm
80 TIME, allows you to run the test for a selected period of time.
81 The format is "NUMm", where NUM is a time unit and the "m" modi‐
82 fier is either S, M, or H for seconds, minutes and hours. To
83 run siege for an hour, you could select any one of the following
84 combinations: -t3600S, -t60M, -t1H. The modifier is not case
85 sensitive, but it does require no space between the number and
86 itself.
87 -l, --log
89 LOG, log stats to SIEGE_HOME/var/siege.log. If you've installed
90 siege in /usr/local, then the siege.log is
91 /usr/local/var/siege.log. This option logs the final statistics
92 reported when siege successfully completes its test. You can
93 edit $HOME/.siegerc to change the location of the siege.log
94 file.
95 -m MESSAGE, --mark=MESSAGE
97 MARK, mark the log file with a separator. This option will
98 allow you to separate your log file entries with header informa‐
99 tion. This is especially useful when testing two different
100 servers. It is not necessary to use both the -m option and the
101 -l option. -m assumes -l so it marks and logs the transaction.
102 If the MESSAGE has spaces in it, make sure that you put it in
103 quotes.
104 -H HEADER, --header=HEADER
106 HEADER, this option allows you to add additional header informa‐
107 tion.
108 -R SIEGERC, --rc=SIEGERC
110 RC, sets the siegerc file for the run. This option overrides the
111 environment variable SIEGERC and the default resource file,
112 $HOME/.siegerc
113 -f FILE, --file=FILE
115 FILE, the default URL file is SIEGE_HOME/etc/urls.txt. To
116 select a different URL file, use this option, i.e., siege -f
117 myurls.txt
118 -A "User Agent", --user-agent="User Agent"
120 AGENT, use this option to set the User-Agent in the request.
121
123 Siege understands the following URL formats:
124 (brackets indicate the directive is optional)
125 [protocol://] host.domain.xxx [:port] [/path/file]
127 host.domain.xxx/file POST field=value&field2=value2
129 Or you can POST the contents of a file using the line input operator,
131 the "<" character:
132 host/file POST </home/jeff/haha.txt
134 The first example above is an implicit GET, the next two are obviously
136 POSTs. You can pass parameters using GET much like you would in a web
137 browser:
138 www.haha.com/form.jsp?first=homer&last=simpson
140 If you invoke the URL as a command line argument, you should probably
142 place it in quotes. Currently, it supports two protocols, http and
143 https. If a protocol is not specified, then siege assumes http. The
144 minimum URL requirement is this: servername. That's it. So if you're
145 in the same domain as a server named shemp and shemp is in your host
146 file or it is in DNS, then: "siege shemp" will stress
147 http://shemp.yourdomain.net/index.html (assuming that "index.html" is
148 the server specified index). To stress the same page using https proto‐
149 col, the minimum URL requirement is this: https://shemp. That URL
150 specification will lay siege to https://shemp.yourdomain.net/index.html
151
153 To hit multiple URLs, place them in a single file. The default URLs
154 file is $SIEGE_HOME/etc/urls.txt. [You may change that file with the
155 -f option, see above.] In that file list the URLs one per line:
156 # place all your comments behind hashes
157 http://homer.whoohoo.com/index.html
158 http://homer.whoohoo.com/howto.jsp
159 http://go.whoohoo.com/cgi-bin/q.cgi?scope=a
160 http://go.whoohoo.com/cgi-bin/q.cgi POST scope=a
161 http://homer.whoohoo.com/my.jsp POST a=1&b=2
162 # POST the contents of a file...
163 www.haha.com/aha.jsp POST </home/jeff/my.txt
164 www.haha.com/parser.jsp POST <./my.txt
165 When invoked without a URL on the command line, siege looks for URLs in
167 a file. Normally, it reads them all into memory and runs through them
168 sequentially. If you specify internet mode [-i], then it randomly
169 selects URLs to hit.
170 You may set and reference variables in URLs file. It is necessary to
172 set them PRIOR to referencing them. The syntax for defining variables
173 is NAME = VALUE with a single assignment on a single line. If you
174 define several variables in the file, you must place each assignment on
175 a single line. To use the value of the variable, you must reference it
176 inside $() or ${}, i.e., $(NAME). If you reference a variable that
177 doesn't exist, siege will evaluate it to the empty string "".
178 # Example using variable assignment
179 # in the urls.txt file.
180 HOST = homer.whoohoo.com
181 http://${HOST}/index.html
182 http://${HOST}/howto.jsp
183
185 Performance measures include elapsed time of the test, the amount of
186 data transferred ( including headers ), the response time of the
187 server, its transaction rate, its throughput, its concurrency and the
188 number of times it returned OK. These measures are quantified and
189 reported at the end of each run. The reporting format is modeled after
190 Lincoln Stein's torture.pl script:
191 ** Siege 2.60
192 ** Preparing 100 concurrent users for battle.
193 The server is now under siege...done
194 Transactions: 339 hits
195 Availability: 93.39 %
196 Elapsed time: 67.47 secs
197 Data transferred: 4273708 bytes
198 Response time: 8.25 secs
199 Transaction rate: 5.02 trans/sec
200 Throughput: 63342.34 bytes/sec
201 Concurrency: 41.47
202 Successful transactions: 337
203 Failed transactions: 26
204 Longest transaction: 17.77 secs
205 Shortest transaction: 0.37 secs
206 Transactions
208 The number of server hits. In the example, 25 simulated users [
209 -c25 ] each hit the server 10 times [ -r10 ], a total of 250
210 transactions. It is possible for the number of transactions to
211 exceed the number of hits that were scheduled. Siege counts
212 every server hit a transaction, which means redirections and
213 authentication challenges count as two hits, not one. With this
214 regard, siege follows the HTTP specification and it mimics
215 browser behavior.
216 Availability
218 This is the percentage of socket connections successfully han‐
219 dled by the server. It is the result of socket failures (includ‐
220 ing timeouts) divided by the sum of all connection attempts.
221 This number does not include 400 and 500 level server errors
222 which are recorded in "Failed transactions" described below.
223 Elapsed time
225 The duration of the entire siege test. This is measured from
226 the time the user invokes siege until the last simulated user
227 completes its transactions. Shown above, the test took 14.67
228 seconds to complete.
229 Data transferred
231 The sum of data transferred to every siege simulated user. It
232 includes the header information as well as content. Because it
233 includes header information, the number reported by siege will
234 be larger then the number reported by the server. In internet
235 mode, which hits random URLs in a configuration file, this num‐
236 ber is expected to vary from run to run.
237 Response time
239 The average time it took to respond to each simulated user's
240 requests.
241 Transaction rate
243 The average number of transactions the server was able to handle
244 per second, in a nutshell: transactions divided by elapsed time.
245 Throughput
247 The average number of bytes transferred every second from the
248 server to all the simulated users.
249 Concurrency
251 The average number of simultaneous connections, a number which
252 rises as server performance decreases.
253 Successful transactions
255 The number of times the server responded with a return code <
256 400.
257 Failed transactions
259 The number of times the server responded with a return code >=
260 400 plus the sum of all failed socket transactions which
261 includes socket timeouts.
262 Longest transaction
264 The greatest amount of time that any single transaction took,
265 out of all transactions.
266 Shortest transaction
268 The smallest amount of time that any single transaction took,
269 out of all transactions.
270
273 Jeffrey Fulmer, et al. <jeff@joedog.org>
274
276 Report bugs to jeff@joedog.org. Give a detailed description of the
277 problem and report the version of siege that you are using.
278
280 Copyright © 2000 2001 2004 Jeffrey Fulmer, et al.
281 This program is free software; you can redistribute it and/or modify it
283 under the terms of the GNU General Public License as published by the
284 Free Software Foundation; either version 2 of the License, or (at your
285 option) any later version.
286 This program is distributed in the hope that it will be useful, but
288 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
289 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
290 Public License for more details.
291 You should have received a copy of the GNU General Public License along
293 with this program; if not, write to the Free Software Foundation, Inc.,
294 675 Mass Ave, Cambridge, MA 02139, USA.
295
297 The most recent released version of siege is available by anonymous FTP
298 from ftp.joedog.org in the directory pub/siege.
299
301 siege.config(1) urls_txt(5) layingsiege(7)
302Siege v2.66 April-10-2007 SIEGE(1)