HTTP testing tool

Wbox aims to help you having fun while testing HTTP related stuff. You can use it to perform many tasks, including the following.

Wbox is free software under the BSD license and was written in ANSI C (POSIX runtime required) by Salvatore 'antirez' Sanfilippo.


Like wbox? Please consider donating few bucks ($1 is ok) using this button

10 Dec 2009 - wbox version 5 is out. Changes: Switched to BSD license and other non-coding changes before to enter Debian.
10 Jun 2007 - wbox version 4 is out. Changes: stats with min/avg/max times on exit, no more defunct childs, the new close option (see doc below), in server mode Index of ... no longer reveals the real filesystem path, source code cleanup and many fixes.
8 Jun 2007 - wbox version 3 is out, ability to set referer and cookies inside! Along with many bug fixes (and many new bugs I guess).
7 Jun 2007 - wbox version 2 is out, server mode inside!.
5 Jun 2007 - wbox version 1 is out.

Don't miss the next release, use the Wbox RSS feed

In order to compile wbox you need a working ANSI C compiler and a POSIX system like Linux. Windows systems are supported by compiling Wbox on Cygwin. Wbox compiles under MacOS X without problems.

Windows binaries

If you want to use WBox under Windows but don't know how to compile it you can download this precompiled binary of Wbox version 3 for Windows (Thanks to Zaim Bakar).

Wbox tutorial

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 ( 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.

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

<meta http-equiv="content-type" content="text/html;charset=utf-8">
<title>404 Not Found</title>
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 ( 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 host www.google.it dump
WBOX www.google.it ( 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

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

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