1SIEGE(1) Siege Load Tester SIEGE(1)
2
6 siege is a HTTP/FTP load tester and benchmarking utility.
7
9 siege [options]
10 siege [options] <URL>
11 siege [options] -g <URL>
12 siege [options] -f urls.txt
13
15 siege is a multi-threaded HTTP/FTP load tester and benchmarking
16 utility. It supports most of the features detailed in RFCs 2616 (HTTP)
17 and 959 (FTP). Properties can be set both from the command line and in
18 a configuration file. When the same property is set in both locations,
19 the command line takes precedence.
20 The default configuration file is $HOME/.siege/siege.conf If you don't
22 have a $HOME/.siege directory and a siege.conf and cookies.txt file,
23 siege will generate a new config directory when it runs. You can
24 generate your config directory with the following command: siege.config
25
27 Option Syntax
28 siege supports long and short options. Short options look like this:
29 -c 25
30 -c25
31 Long options look like this:
33 --concurrent=25
34 Option Values
36 -V, --version
37 Displays the siege release version and copyright information.
38 -h, --help
40 Prints a help message describing siege's command-line options.
41 -C, --config
43 Prints a detailed summary of all the currently configured options,
44 most of which are sent in $HOME/.siege/siege.conf
45 -v, --verbose
47 This directive puts siege into verbose mode which is actually a
48 default setting. This command-line option is useful when the config
49 file is set to 'verbose = false' since it will allow you to
50 override that.
51 By default siege's verbose output is displayed in a color-coded
53 style.
54 * HTTP 2xx is coded blue
55 * HTTP 3xx is coded cyan
56 * HTTP 4xx is coded magenta
57 * HTTP 5xx is coded red
58 * HTTP cached is coded black
59 NOTE: You can turn off color in siege.conf like this: 'color = off'
61 -q, --quiet
63 This directive silences siege. It is mostly used for scripting and
64 is often used in conjunction with -g/--get. You can detect the
65 success or failure of the run with its exit code.
66 siege --quiet -g www.joedog.org
68 if [ $? -eq 0 ] ; then
69 echo "Success"
70 else
71 echo "Failure"
72 fi
73 -g URL, --get=URL
75 This option allows you to request a URL and watch the header
76 transaction. There is a corresponding config file directive that
77 allows you to set the request method for these requests: gmethod =
78 HEAD|GET
79 $ siege -g "https://www.joedog.org/"
81 HEAD / HTTP/1.0
82 Host: www.joedog.org
83 Accept: */*
84 User-Agent: Mozilla/5.0 (unknown-x86_64-linux-gnu) Siege/4.0.0-beta5
85 Connection: close
86 HTTP/1.1 200 OK
88 Server: cloudflare-nginx
89 Date: Tue, 09 Feb 2016 18:18:41 GMT
90 Content-Type: text/html; charset=UTF-8
91 Connection: close
92 Last-Modified: Wed, 25 Nov 2015 18:46:08 GMT
93 Cache-Control: max-age=3, must-revalidate
94 Expires: Tue, 09 Feb 2016 18:18:44 GMT
95 Vary: Accept-Encoding,Cookie
96 CF-RAY: 27219407eeff084a-IAD
97 NOTE: It's a best practice to quote the URL when it's passed to
99 siege from the the command-line.
100 -p URL, --print=URL
102 This option is similar to -g / --get but it PRINTS the page it
103 received from the server.
104 $ siege -p http://www.joedog.org/
106 GET / HTTP/1.0
107 Host: www.joedog.org
108 Accept: */*
109 User-Agent: Mozilla/5.0 (unknown-x86_64-linux-gnu) Siege/4.0.3rc1
110 Connection: close
111 HTTP/1.1 301 Moved Permanently
113 Date: Wed, 19 Oct 2016 16:58:13 GMT
114 Content-Type: text/html; charset=iso-8859-1
115 Location: https://www.joedog.org/
116 Server: cloudflare-nginx
117 Connection: close
118 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
121 <html><head>
122 <title>301 Moved Permanently</title>
123 </head><body>
124 <h1>Moved Permanently</h1>
125 <p>The document has moved <a href="https://www.joedog.org/">here</a>.</p>
126 <hr>
127 <address>Apache/2.2.31 (Amazon) Server at www.joedog.org Port 80</address>
128 </body></html>
129 -c NUM, --concurrent=NUM
131 This option allows you to set the concurrent number of users. The
132 total number of users is technically limited to your computer's
133 resources.
134 You should not configure more users than your web server is
136 configured to handle. For example, the default apache configuration
137 is capped at 255 threads. If you run siege with -c 1024, then 769
138 siege users are left waiting for an apache handler.
139 For this reason, the default siege configuration is capped at 255
141 users. You can increase that number inside siege.conf but if you
142 make a mess, then please don't complain to us.
143 -r NUM, --reps=NUM|once
145 This option tells each siege user how many times it should run. The
146 value should generally be a number greater than zero but it may be
147 the keyword 'once'.
148 If --reps=3 then each siege user will run three times before it
150 exits. However, if --reps=once, then each user will run through
151 the urls.txt file exactly one time.
152 For more information about the urls.txt file, see option -f <file>,
154 --file=<file>
155 -t NUMm, --time=NUMm
157 This option is similar to --reps but instead of specifying the
158 number of times each user should run, it specifies the amount of
159 time each should run.
160 The value format is "NUMm", where "NUM" is an amount of time and
162 the "m" modifier is either S, M, or H for seconds, minutes and
163 hours. To run siege for an hour, you could select any one of the
164 following combinations: -t3600S, -t60M, -t1H. The modifier is not
165 case sensitive, but it does require no space between the number and
166 itself.
167 -d NUM, --delay=NUM
169 This option instructs siege how long to delay between each page
170 request. The value NUM represents the number of seconds between
171 each one. This number can be a decimal value. In fact the default
172 is half a second (--delay=0.5).
173 The time between delay requests is NOT applied toward the
175 transaction time. If two 0.1 second transactions have a 2 second
176 delay between them, their average transaction time is 0.1 seconds.
177 It is applied toward the total elapsed time. In this scenario, the
178 elapsed time would be 2.2 seconds.
179 NOTE: when the parser is enabled (see: -p/--parser), there is no
181 delay between the page and its elements, i.e., style sheets,
182 javascripts, etc. The delay is only between page requests.
183 -b, --benchmark
185 This directive tells siege to go into benchmark mode. This means
186 there is no delay between iterations.
187 -i, --internet
189 This option sets siege into what we call internet mode. It makes
190 requests from the urls.txt file (see: -f <file> / --file=<file>) in
191 random order.
192 -f FILE, --file=FILE
194 This option tells siege to work with a list of urls inside a text
195 file. The URLs are listed one per line. Unlike URLs that are passed
196 as a command-line argument, the URLs in this file should not be
197 quoted.
198 siege's urls.txt parser supports comments and variables. Since
200 siege uses the dollar sign ($) as a prefix for scalar variables,
201 you should escape any variable you want to send to the server:
202 https://$(HOST)/siege/jsoner.php POST {"price": "\$10 per mile"}
204 -R FILE, --rc=FILE
206 This directive allows you to set an alternative resource file. By
207 default, the siegerc file is $HOME/.siege/siege.conf With this
208 directive, you can override the default and use an alternative
209 file.
210 -L FILE, --log=FILE
212 The default log file is $prefix/var/log/siege.log. This directive
213 allows you to specify an alternative file for logging.
214 -m "string", --mark="string"
216 This option allows you to log a message to the log file before your
217 stats are written there. It is generally used to identify the
218 proceeding run. You could, for example, mark the file with your
219 command-line parameters so it's understood what configuration
220 generated the following data.
221 -H "header: value", --header="Header: value"
223 This options allows you to set a custom header in the request.
224 Generally speaking, this header will override an existing header.
225 The Cookie header is a special case. If you set -H "Cookie: value"
226 then siege will send that cookie in addition to the other ones.
227 -A "string", --agent="string"
229 This option allows you to override the default user-agent with a
230 custom one.
231 siege --agent="JoeDog Jr. in da hizzle"
233 Will set this header:
235 User-agent: JoeDog Jr. in da hizzle
237 Alternatively, you could set the User-agent with the -H/--header
239 option above.
240 -T "text", --content-type="text"
242 This is another set header shortcut. You use this option to
243 override the default Content-type request header.
244 --no-parser
246 Turn off the HTML parser. When siege downloads a page, it parses it
247 for additional page elements such as style-sheets, javascript and
248 images. It will make additional requests for any elements it finds.
249 With this option enabled, siege will stop after it pulls down the
250 main page.
251 --no-follow
253 This directive instructs siege not to follow 3xx redirects.
254
256 siege supports RFC 1738 URL formats but it takes pains to implement
257 commonly used shortcuts for your convenience. In addition to RFC 1738
258 formats, siege introduces its own URL format to indicate protocol
259 method.
260 An RFC 1738 URL looks like this:
262 <scheme>://<username>:<password>@<hostname>:<port>/<path>;<params>?<query>#<frag>
263 A siege URL with a method indicator looks like this:
265 <scheme>://<username>:<password>@<hostname>:<port>/<path> POST
266 <query>
267 You can also post the contents of a file using the redirect character
269 like this:
270 <scheme>://<username>:<password>@<hostname>:<port>/<path> POST
271 </home/jeff/haha.txt
272 Here are two examples with the siege method indicator:
274 http://www.joedog.org/ POST haha=papa&dada=mama
275 ftp://ftp.armstrong.com/ PUT </home/jdfulmer/etc/tests/bbc.jpg
276 NOTE: If you set URLs with method indicators at the command-line, then
278 you MUST quote the thing or your shell will treat it like three
279 separate arguments. If the URL is in a urls.txt file, then you
280 shouldn't quote it.
281 As mentioned above, siege goes to great lengths to allow commonly used
283 shortcuts that you're used to from most browser implementations. It
284 treats many parts of the 1738 URL as optional. In this example, the
285 parts in brackets are optional:
286 [scheme://] host.domain.xxx [:port] [/path/file]
287 When siege receives a host name it builds the URL with default
289 assumptions. www.joedog.org becomes http://www.joedog.org:80/
290
292 From the section called Option Syntax above we learn that siege can
293 take a URL as an argument. siege -c -r2 www.joedog.org will request the
294 JoeDog index page twice. But what if you want to hit large portions of
295 the site? siege will allow you to fill a file with URLs so that it can
296 run through list.
297 The format for the file is one URL per line:
299 https://www.joedog.org/
300 https://www.joedog.org/haha/
301 https://www.joedog.org/haha/ POST homer=simpson&marge=doestoo
302 The file also supports UNIX-style commenting:
304 # Comment looks like this
305 https://www.joedog.org/
306 https://www.joedog.org/haha/
307 https://www.joedog.org/haha/ POST homer=simpson&marge=doestoo
308 It supports shell-style variable declaration and references. This is
310 convenient if you want to run the same test on two different tiers or
311 two different schemes:
312 SCHEME=https
314 HOST=bart.joedog.org
315 $(SCHEME)://$(HOST)/
316 $(SCHEME)://$(HOST)/haha/
317 $(SCHEME)://$(HOST)/haha/ POST homer=simpson&marge=doestoo
318 You can tell siege about this file with the -f/--file option:
320 siege -c1 -r50 -f /home/jeff/urls.txt
321
323 When its run is complete, siege will gather performance data from all
324 its clients and summarize them after the run. (You can also choose to
325 log these numbers). The command-line output is modeled after Lincoln
326 Stein's torture.pl script:
327 Transactions: 2000 hits
329 Availability: 100.00 %
330 Elapsed time: 58.57 secs
331 Data transferred: 5.75 MB
332 Response time: 0.25 secs
333 Transaction rate: 34.15 trans/sec
334 Throughput: 0.10 MB/sec
335 Concurrency: 8.45
336 Successful transactions: 2000
337 Failed transactions: 0
338 Longest transaction: 4.62
339 Shortest transaction: 0.00
340 Transactions
342 This number represents the total number of HTTP requests. In this
343 example, we ran 25 simulated users [-c25] and each ran ten times
344 [-r10]. Twenty-five times ten equals 250 so why is the transaction
345 total 2000? That's because siege counts every request. This run
346 included a META redirect, a 301 redirect and the page it requested
347 contained several elements that were also downloaded.
348 Availability
350 This is the percentage of socket connections successfully handled
351 by the server. It is the result of socket failures (including
352 timeouts) divided by the sum of all connection attempts. This
353 number does not include 400 and 500 level server errors which are
354 recorded in "Failed transactions" described below.
355 Elapsed time
357 The duration of the entire siege test. This is measured from the
358 time the user invokes siege until the last simulated user
359 completes its transactions. Shown above, the test took 58.57
360 seconds to complete.
361 Data transferred
363 The sum of data transferred to every siege simulated user. It
364 includes the header information as well as content. Because it
365 includes header information, the number reported by siege will
366 be larger then the number reported by the server. In internet
367 mode, which hits random URLs in a configuration file, this
368 number is expected to vary from run to run.
369 Response time
371 The average time it took to respond to each simulated user's requests.
372 Transaction rate
374 The average number of transactions the server was able to handle
375 per second, in a nutshell: it is the count of all transactions
376 divided by elapsed time.
377 Throughput
379 The average number of bytes transferred every second from the
380 server to all the simulated users.
381 Concurrency
383 This is the average number of simultaneous connections. The metric
384 is calculated like this: the sum of all transaction times divided
385 by elapsed time (how long siege ran)
386 Successful transactions
388 The number of times the server responded with a return code < 400.
389 Failed transactions
391 The number of times the socket transactions failed which includes
392 socket timeouts.
393 Longest transaction
395 The greatest amount of time that any single transaction took, out
396 of all transactions.
397 Shortest transaction
399 The smallest amount of time that any single transaction took, out
400 of all transactions.
401
403 Jeffrey Fulmer, et al. <jeff@joedog.org> is the primary author of
404 siege. Numerous people throughout the globe also contributed to this
405 program. Their contributions are noted in the source code ChangeLog
406
408 Copyright by Jeffrey Fulmer, et al. <jeff@joedog.org>
409 This program is free software; you can redistribute it and/or modify it
411 under the terms of the GNU General Public License as published by the
412 Free Software Foundation; either version 2 of the License, or (at your
413 option) any later version.
414 This program is distributed in the hope that it will be useful, but
416 WITHOUT ANY WARRANTY; without even the implied warranty of
417 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
418 General Public License for more details.
419 You should have received a copy of the GNU General Public License along
421 with this program; if not, write to the Free Software Foundation, Inc.,
422 675 Mass Ave, Cambridge, MA 02139, USA.
423
425 The most recent released version of siege is available by HTTP
426 download:
427 http://download.joedog.org/pub/siege
428
430 siege.config(1) bombardment(1) siege2csv(1)
431JoeDog 2023-01-05 SIEGE(1)