****** Wbox TUTORIAL - taken from http://www.hping.org/wbox/ ******

***** HTTP client mode *****

The following is a short tutorial. Wbox is trivial to use but you may want to
read this in order to understand better what wbox is and how to use it.

**** Basic usage ****

The simplest way to use wbox is to call it with just one argument, an url:

% wbox www.google.it
WBOX www.google.it (64.233.183.99) port 80
0. 200 OK    3774 bytes    407 ms
1. 200 OK    (3767) bytes    273 ms
2. 200 OK    3767 bytes    304 ms
3. 200 OK    3767 bytes    260 ms
user terminated

As you can see wbox in this mode of operation resembles the ping_utility. For
every performed HTTP request it shows the sequence number of the request (0.),
the HTTP reply code and reason string (200 OK), the number of bytes received
from the server (3774 bytes), and the time the request took to complete in
milliseconds (407 ms). There are two details to note.

    * The number of received bytes includes the HTTP reply header, so it is not
      equal to the document length.
    * Every time it changes compared to the previous HTTP reply, the number of
      received bytes is put between parens, like in (3767)

**** Limiting the number of requests ****

By default wbox will continue to perform requests forever, until you don't
press Ctrl+C. After the url argument you can pass a number of options to wbox
to alter its behaviour, one of this is an integer number specifying how many
requests to perform.

% wbox www.google.it/notexistingpage.html 1
WBOX www.google.it (64.233.183.103) port 80
0. 404 Not Found    1495 bytes    310 ms

This time wbox terminated after the first request was received.

**** Obtaining splitted timing information ****

Usually web applications don't spend the same time in the generation of every
part of the page. With wbox it's possible to obtain time information for
different parts of the document using the timesplit option.

% wbox digg.com timesplit 1
WBOX digg.com (64.191.203.30) port 80
0. 200 OK    44134 bytes    1326 ms
       [0] 0-4095 -> 728 ms
       [1] 4096-8191 -> 254 ms
       [2] 8192-12287 -> 16 ms
       [3] 12288-16383 -> 17 ms
       [4] 16384-20479 -> 225 ms
       [5] 20480-24575 -> 12 ms
       [6] 24576-28671 -> 16 ms
       [7] 28672-32767 -> 18 ms
       [8] 32768-36863 -> 16 ms
       [9] 36864-40959 -> 16 ms
       [10] 40960-44133 -> 8 ms

**** Dumping data ****

We may like to see what kind of HTTP reply google is emitting on 404 errors,
the option showhdr tells wbox to dump the HTTP reply header.

% wbox www.google.it/notexistingpage.html 1 showhdr
WBOX www.google.it (64.233.183.103) port 80

HTTP/1.1 404 Not Found
Content-Type: text/html
Server: GWS/2.1
Content-Length: 1368
Date: Tue, 05 Jun 2007 16:49:58 GMT

0. 404 Not Found    1495 bytes    540 ms

We may like to use wbox inside a shell script in order to collect different
headers, so the option silent tells wbox to don't show status lines.

% wbox www.google.it/notexistingpage.html 1 showhdr silent
HTTP/1.1 404 Not Found
Content-Type: text/html
Server: GWS/2.1
Content-Length: 1368
Date: Tue, 05 Jun 2007 16:51:52 GMT

It's also possible to dump the whole reply using the dump option.

% wbox www.google.it/notexistingpage.html 1 dump silent
HTTP/1.1 404 Not Found
Content-Type: text/html
Server: GWS/2.1
Content-Length: 1368
Date: Tue, 05 Jun 2007 16:53:44 GMT

<html><head>

404 Not Found
<style><!--
body {font-family: arial,sans-serif}
div.nav {margin-top: 1ex}
(a lot of data omitted)

You can use dump and timesplit at the same time in order to get a dump of the
reply with time annotations, but warning! using this feature the time used in
order to produce the actual output on screen will alter the results, so you
must redirect the output into a file. The right command line to use is the
following:

% wbox http://digg.com dump timesplit 1 > /tmp/dump.txt

Then open the file with an editor to see the HTTP reply splitted in chunks of
data separated by time annotations.

**** Stressing servers and apps ****

Instead to make a single request it's possible to make multiple concurrent
requests using the clients number option. Wbox will spawn the required number
of processes, and every process will perform a query every second.

% wbox http://localhost clients 4
WBOX localhost (127.0.0.1) port 80
0. 200 OK    9939 bytes    14 ms
0. 200 OK    9939 bytes    22 ms
0. 200 OK    9939 bytes    26 ms
0. 200 OK    9939 bytes    31 ms
1. 200 OK    9939 bytes    4 ms
1. 200 OK    9939 bytes    7 ms
1. 200 OK    9939 bytes    7 ms
1. 200 OK    9939 bytes    4 ms
2. 200 OK    9939 bytes    4 ms
2. 200 OK    9939 bytes    6 ms
2. 200 OK    9939 bytes    10 ms
2. 200 OK    9939 bytes    3 ms
3. 200 OK    9939 bytes    3 ms
3. 200 OK    9939 bytes    4 ms
3. 200 OK    9939 bytes    7 ms
3. 200 OK    9939 bytes    7 ms
user terminated

Every client will print a status line, so you can get an idea about delays
under load. Note that's much better to perform this tests on localhost or over
LAN in order to filter bandwidth limits that may otherwise alter the numbers.

**** Modifing requests period ****

By default wbox will perform a request per second, you can change this using
the option wait seconds (for every process). Set it to zero in order to perform
continuous requests without delay between them using wait 0.

**** Setting cookies and referer ****

Many web applications perform different tasks for the same url if some cookie
is set to the right value. One obvious example is a login cookie. Wbox is able
to perform requests containing cookies using the option cookie name value like
in the following example.

% wbox hping.org cookie secret ff8a45a7

It is possible to use the cookie option multiple times to set more than a
cookie. Another parameter that sometimes may change the target site behaviour
is the Referer header. It is possbile to set it using the referer url option.

**** Testing virtual domains ****

Sometimes after you configured a new virtual domain in your web server it's
handly to check if everything is working as it should before DNS propagation
and without the need to alter by hand your /etc/hosts. You can use the host
name wbox option in order to do this.

% wbox 64.233.183.99 host www.google.it dump
WBOX www.google.it (64.233.183.99) port 80
HTTP/1.1 200 OK
Cache-Control: private
Content-Type: text/html; charset=UTF-8
Set-Cookie: PREF=ID=81ccf41f3364e7fa:TM=1181063780:LM=1181063780:S=yd7lfPo-
SBZTngH_; expires=Sun, 17-Jan-2038 19:14:07 GMT; path=/; domain=.google.it
Server: GWS/2.1
Transfer-Encoding: chunked
Date: Tue, 05 Jun 2007 17:16:20 GMT

d6f
<html>... (data omitted)

**** Testing HTTP compression ****

Using the compr option wbox will include the right headers to accept the gzip/
deflate data encoding. If the web server supports compression it will reply
with compressed data, and wbox will show this fact in the reply status lines.

% wbox antirez.com compr
WBOX antirez.com (62.149.233.114) port 80 [compr]
0. 200 OK    6553 bytes    837 ms    compr
1. 200 OK    6553 bytes    301 ms    compr
user terminated

It is sometimes interesting to check the time required to complete the request
with and without the HTTP compression just including/excluding the compr option
from the command line.

**** A few more options ****

    * http10 tells wbox to use HTTP/1.0 in the request, avoiding chunked data
      output.
    * head forces wbox to use the HEAD method instead of GET.
    * close close the connection after few bytes received. Handy to check just
      latency against big pages/files, to check what happens on end of file
      from client conditions, ...
    * Use wbox -h in order to list all the available options.

***** HTTP server mode *****

Wbox implements a minimal configuration-less HTTP server. It is useful as a
quick way to share files in a LAN or via Internet, so it implements directory
listing by default. In order to start this mode just use the following command
line (assuming documents you want to share are in /tmp/mydocs):

% wbox servermode webroot /tmp/mydocs

Than play with it conneting to http://127.0.0.1:8081 since Wbox for default
uses the 8081 TCP port. You can change this default using the serverport port
option.

**** Limiting number of clients in server mode ****

The default in wbox server mode is to handle up to 20 concurrent clients. It is
possible to tune this parameter using maxclients number. When a clinet connects
but there are already the maximum number of clients connected the connection is
closed before to spawn a child. This allows for an easy DOS attack so the
behaviour should be changed in two ways: a timeout should be implemented in
order to avoid that a client can hang forever, also on a new connection that
can't be server because too many clients are already connected a random old
connection should be killed.

****** Have fun ******
Copyright(C) 2007 Salvatore antirez Sanfilippo - All Rights Reserved
