1SIEGE(1)                       Siege Load Tester                      SIEGE(1)
2
3
4

NAME

6       siege is a HTTP/FTP load tester and benchmarking utility.
7

SYNOPSIS

9         siege [options]
10         siege [options] <URL>
11         siege [options] -g <URL>
12         siege [options] -f urls.txt
13

DESCRIPTION

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

OPTIONS

27   Option Syntax
28       siege supports long and short options. Short options look like this:
29           -c 25
30           -c25
31
32       Long options look like this:
33           --concurrent=25
34
35   Option Values
36       -V, --version
37           Displays the siege release version and copyright information.
38
39       -h, --help
40           Prints a help message describing siege's command-line options.
41
42       -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
46       -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
52           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
60           NOTE: You can turn off color in siege.conf like this: 'color = off'
61
62       -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
67             siege --quiet -g www.joedog.org
68             if [ $? -eq 0 ] ; then
69               echo "Success"
70             else
71               echo "Failure"
72             fi
73
74       -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
80             $ 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
87             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
98           NOTE: It's a best practice to quote the URL when it's passed to
99           siege from the the command-line.
100
101       -p URL, --print=URL
102           This option is similar to -g / --get but it PRINTS the page it
103           received from the server.
104
105             $ 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
112             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
119
120             <!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
130       -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
135           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
140           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
144       -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
149           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
153           For more information about the urls.txt file, see option -f <file>,
154           --file=<file>
155
156       -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
161           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
168       -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
174           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
180           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
184       -b, --benchmark
185           This directive tells siege to go into benchmark mode. This means
186           there is no delay between iterations.
187
188       -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
193       -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
199           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
203             https://$(HOST)/siege/jsoner.php POST {"price": "\$10 per mile"}
204
205       -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
211       -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
215       -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
222       -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
228       -A "string", --agent="string"
229           This option allows you to override the default user-agent with a
230           custom one.
231
232             siege --agent="JoeDog Jr. in da hizzle"
233
234           Will set this header:
235
236             User-agent: JoeDog Jr. in da hizzle
237
238           Alternatively, you could set the User-agent with the -H/--header
239           option above.
240
241       -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
245       --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
252       --no-follow
253           This directive instructs siege not to follow 3xx redirects.
254

URL FORMAT

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
261       An RFC 1738 URL looks like this:
262         <scheme>://<username>:<password>@<hostname>:<port>/<path>;<params>?<query>#<frag>
263
264       A siege URL with a method indicator looks like this:
265         <scheme>://<username>:<password>@<hostname>:<port>/<path> POST
266       <query>
267
268       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
273       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
277       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
282       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
288       When siege receives a host name it builds the URL with default
289       assumptions.  www.joedog.org becomes http://www.joedog.org:80/
290

URLS.txt FILE

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
298       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
303       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
309       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
313         SCHEME=https
314         HOST=bart.joedog.org
315         $(SCHEME)://$(HOST)/
316         $(SCHEME)://$(HOST)/haha/
317         $(SCHEME)://$(HOST)/haha/ POST homer=simpson&marge=doestoo
318
319       You can tell siege about this file with the -f/--file option:
320         siege -c1 -r50 -f /home/jeff/urls.txt
321

PERFORMANCE STATISTICS

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
328         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
341         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
349         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
356         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
362         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
370         Response time
371             The average time it took to respond to each simulated user's requests.
372
373         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
378         Throughput
379             The average number of bytes transferred every second from the
380             server to all the simulated users.
381
382         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
387         Successful transactions
388             The number of times the server responded with a return code < 400.
389
390         Failed transactions
391             The number of times the socket transactions failed which includes
392             socket timeouts.
393
394         Longest transaction
395             The greatest amount of time that any single transaction took, out
396             of all transactions.
397
398         Shortest transaction
399             The smallest amount of time that any single transaction took, out
400             of all transactions.
401

AUTHOR

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
410       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
415       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
420       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

AVAILABILITY

425       The most recent released version of siege is available by HTTP
426       download:
427         http://download.joedog.org/pub/siege
428

SEE ALSO

430       siege.config(1) bombardment(1) siege2csv(1)
431
432
433
434JoeDog                            2023-01-05                          SIEGE(1)
Impressum