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