About HttpTea
============================
What is this Program doing?
---------------------------
As you known, HTTP (Hyper Text Transfer Protocol) is an ASCII
protocol used to transfer data between a your browser and the
WEB servers (the other site of the Internet).
This program allows you to
* watch this exchange of data.
* change the protocol data.
When do I need this Program?
-----------------------------
This program is made for people who are constructing and debugging
WEB applications. However, if your application just conststs of
a number of HTML pages, you properly still not need this program.
If your are doing more complex dynamic WEB application using PHP or
J2EE, you'll see problems like:
* Cookies are not send to your server
* A session is lost
* Request parameters are not passed to your application
* HTTP-Redirects do not work as expected
HttpTea can help to track down this kind of problems.
I'm working with complex WEB application since some years and during
this time I've teched HttpTea all that I ever needed to
see are alter in the HTTP protocol. This may or may not fit your needs.
If it does not - feel free to improve the program!
How this the Program Working?
-----------------------------
The program sits between the client (your WEB browser) and the
server much like a proxy. What ever the browser of the server are
sending, is displayed on the console.
Simple Configuration
--------------------
On the client site HttpTea is wired in between the
client browser and the server like a proxy server.
..............................
. local PC . +------+
. +-------+ +-------+ : /--->|Server|
. |Browser|------>o|HttpTea|-----/ +------+
. +-------+ ^+-------+ :
. | .
. | .
. Listener Port .
..............................
Required settings:
1 - Browser: set the proxy server to
localhost:Listener-Port
2 - HttpTea -l Listener-Port
Example:
java -jar HttpTea.jar -l 9000
Configuration with Proxy Server
-------------------------------
On the client site HttpTea is wired in between the
client browser and the proxy server.
..............................
. local PC . +------+
. +-------+ +-------+ : /-->o|Proxy-|-\ +----------+
. |Browser|------>o|HttpTea|-----/ ^| Host | \--o|App.Server|
. +-------+ ^+-------+ : |+------+ +----------+
. | . |
. | . Proxy-Port
. Listener Port .
..............................
Required settings:
1 - Browser: set the proxy server to
localhost:Listener-Port
2 - HttpTea -l Listener-Port
-p Proxy-Host:Proxy-Port
Configuration Example 1
-----------------------
HttpTea -l 9001
-p 138.222.190.40:1001
-x "138.221.*;www.heute.de"
HttpTea will listen at port 9001 and send all requests to the proxy server 138.222.190.40:1001. Requests for IP addresses beginning with 138.221. are not send to the proxy server but directly to their target. The same is true for any requests for the host www.heute.de
Configuration Example 2
-----------------------
HttpTea -l 9001
-h www.heute.de=138.222.190.1
-h www.yahoo.com=138.222.190.1
-h www.yahoo.com:8080=www.google.com:80
HttpTea will listen a port 9001. All requests for the hosts www.heute.de and www.yahoo.com will be deferred to 138.222.190.1.
Any request for host www.yahoo.com on port 8080 will be deferred to www.google.com on port 80.
Configuration Example 3
-----------------------
HttpTea -l 9001
-H www.heute.de=138.222.190.1
-H www.yahoo.com=138.222.190.1
HttpTea will listen a port 9001. Any HTTP Redirect that the server sends to the client browser which point to a location on the hosts www.heute.de or www.yahoo.com will be modified to point to the host 138.222.190.1 instead. HttpTea will change the content of the LOCATION attribute in the HTTP header.
Program Options
================
General Options:
-? [1..n] Display help.
-? [a..z] Display information about an options.
+/-i Toggle display of HttpTea configuration.
-l port Listener port.
+/-n Toggle display of thread number.
-p host[:port] Proxy host and port.
-r [Format] Raw Mode. The HTTP protocol is not analyzed.
-s 0..n Client socket timeout.
-S 0..n Server socket timeout in ms.
-v 0..5 Verbose level. 0=none;1=error;2=warning;3=info;>3=debug
-y 0..n Buffer size.
HTTP Options:
-a <URL-pattern>;attribute Attribute deleted from request
+a <URL-pattern>;attribute:value Attribute added to request
-A <URL-pattern>;attribute Attribute deleted from response
+A <URL-pattern>;attribute:value Attribute added to response
-b Disable display of the HTTP content.
+b [Format] Enable display of the HTTP content.
-c <cookie data> Change cookies in COOKIE (HTTP request).
-C <cookie data> Change cookies in SET-COOKIE (HTTP response).
-d host Host excluded from the output.
+d host Host included in the output.
-e host=IP-Adr Overwrite default hostname resolution.
-h host_org=host_new Host replacement in requests.
-H host_org=host_new Host replacement in response.
-R <URL-pattern>;200..505 Alter the HTTP result for given URL.
+/-t Toggle display of the raw HTTP header.
+/-T Toggle display of the processed HTTP header.
-x host Dont send via proxy.
The 'a' Option - Add or Remove Http Request Header Attributes
==============================================================
With this option you can add/modify/remove
attributes in the HTTP request.
Attribute names are case-insensitive.
-a <URL pattern>;<attribute>
...removes the attribute
from each request that matches the given URL pattern.
+a <URL pattern>;<attribute>:<value>
...adds the attribute
to each request that matches the given URL patten.
If the attribute exists in the request, the original
value is replaced.
URL pattern
-----------
The URL pattern is a regular expression.
Note: the regular expression http://localhost:8080
will NOT match the request for: http://localhost:8080/test
...but http://localhost:8080.+ ...will do the trick!
The URLs are case-insensitive.
Example: -a "http://www\.heute\.de/.+;Content-Type:text/plain"
..will replace the value of the Content-Type attribute
for all HTTP responses send from the www.heute.de domain.
Note: the dot (.) character has a special function in a regular expression
and must therefor be escaped.
Note: use the +T option to see the modified HTTP header.
use the +t option to see the original HTTP header.
See also: -A and -C
The 'A' Option - Add or Remove Http Response Header Attributes
==============================================================
With this option you can add/modify/remove attributes in the HTTP response.
Attribute names are case-insensitive.
-A <URL pattern>;<attribute>
...removes the attribute from each response where the requested URL matches
the given URL pattern.
-A <URL pattern>;<attribute>:<value>
...adds the attribute to each response where the requested URL matches the
given URL pattern.
If the attribute exists in the response, the original value is replaced.
URL pattern
-----------
HttpTea checks the URL of the request which
causes this response to see whether the HTTP attributes shall be modified.
The URL pattern is a regular expression.
Note: the regular expression http://localhost:8080
will NOT match the request for: http://localhost:8080/test
...but http://localhost:8080.+ ...will do the trick!
The URLs are case-insensitive.
Example: -A "http://www\.heute\.de/.+;Content-Type:text/plain"
...will replace the value of the Content-Type attribute
for all HTTP responses send from the www.heute.de domain.
Note: the dot (.) character has a special function in a regular expression
and must therefor be escaped.
Note: use the +T option to see the modified HTTP header.
use the +t option to see the original HTTP header.
See also: -a and -C
The 'c' Option - Cookies
==============================================================
Use the -c option to modify cookies that in the HTTP request.
Syntax: -c <url pattern>;<mode>;<cookie data>
where : <url pattern> is a regular expression describing the name of a host.
<mode> is i[nsert] to add a cookie.
u[pdate] to modify the cookie data that the client sends.
d[elete] to delete the cookie from the request.
<cookie data>
is a string containing key=value pair to describe the cookie.
The following keys are used:
name = the name of the cookie
value = the value of the cookie
rename = the new name of the cookie
In update mode, missing elements are not modified.
In insert mode, missing elements are omitted from the cookie.
Example: HttpTea -c ".+yahoo.+;delete;name=JSESSIONID"
...will delete the cookie named JSESSIONID from all request send to
yahoo hosts.
Example: HttpTea -c ".+yahoo.+;i;name=USERID;value=KALLE"
...will add a cookie with the name USERID and the value KALLE to all
responses send to yahoo hosts.
Example: HttpTea -C ".+yahoo.+;u;name=USERID;value=PELLE"
...will set the value of the cookie USERID that is send to yahoo hosts to PELLE.
The 'C' Option - Cookies
==============================================================
Use the -C option to modify cookies that in the HTTP response.
Syntax: -C <url pattern>;<mode>;<cookie data>
where : <url pattern> is a regular expression describing the name of a host.
<mode> is i[nsert] to add a cookie.
u[pdate] to modify the cookie data that the server sends.
d[elete] to delete the cookie from the response.
<cookie data>
is a string containing key=value pair to describe the cookie.
The following keys are used:
name = the name of the cookie
value = the value of the cookie
path = the path value of the cookie
rename = the new name of the cookie
domain = the domain value of the cookie
expires= the time when the cookie will expire.
In update mode, missing elements are not modified.
In insert mode, missing elements are omitted from the cookie.
Example: HttpTea -C ".+yahoo.+;delete;name=JSESSIONID"
...will delete the cookie named JSESSIONID from all responses coming
from yahoo host.
Example: HttpTea -C ".+yahoo.+;i;name=USERID;value=KALLE;path=/"
...will add a cookie with the name USERID and the value KALLE to all
responses coming from yahoo host.
Example: HttpTea -C ".+yahoo.+;u;name=USERID;path=/test"
...will set the path value of any cookie send from yahoo host and
named USERID to /tests
The 'd' Option - Display List
==============================================================
With this option you can include (+d) or exclude (-d)
dedicated hosts from protocol.
Syntax: -d <host pattern>
where : <host pattern> is a regular expression describing the name of a host.
Example: HttpTea +d "www\.yahoo.+" -l 9001
...tell HttpTea to log only data of request from yahoo hosts.
(like www.yahoo.com or www.yahoo.de)
Example: HttpTea -d "localhost" -l 9001
...tell HttpTea to log all request but the once from the host "localhost".
The 'e' Option - Hostname Resolution
==============================================================
By default, HttpTea uses host functions (like DNS or /etc/hosts)
to convert a hostname into an IP address.
With the -e option you can tell the program to use the given IP address
for a host.
This options can be specified multiple times.
Example: HttpTea -l 9001 -e www.heute.de=127.222.190.63
See also: -x
The 'h' Option - Host Replacement
==============================================================
This option allows you to replace the name of a host in the HTTP request.
The option effects the "Host" attribute and the target value of the
GET and POST parameter.
Example: Assume that your browser is sending the following request:
GET http://www.heute.de/test.html
Host: www.heute.de
User-Agent: ...
....
...and you add the following option:
-h "www\.heute.+=localhost"
then the HTTP request is modified to look like this:
GET http://localhost/test.html
Host: localhost
User-Agent: ...
....
Note: the dot (.) character has a special function in a regular expression
and must therefor be escaped.
It is possible to include a port number in the host name.
Example: www\.heute\.de:80=localhost:8080
See also: -H and -e
The 'H' Option - Host Replacement
==============================================================
This option also you to replace the name of a host in the HTTP response.
The option effects the "Location" attribute.
Example: Assume that a server is sending the following response:
GET http://www.heute.de/test.html
Host: www.heute.de
User-Agent: ...
....
...and you add the following option:
-h "www\.heute.+=localhost"
then the HTTP request is modified to look like this:
GET http://localhost/test.html
Host: localhost
User-Agent: ...
....
Note: the dot (.) character has a special function in a regular expression
and must therefor be escaped.
It is possible to include a port number in the host name.
Example: www\.heute\.de:80=localhost:8080
See also: -h and -e
The 'i' Option - Information Mode
==============================================================
This flag surpresses the information
that is displayed when HttpTea
starts.
This information contains among others things the
version number of this program.
The 'l' Option - Define the Listener Port
==============================================================
This parameter defines the SERVER PORT.
This program is listening at this port
for client requests.
This port must not be used by any other program.
Only one program is able to open a server port
for a given port number.
If this port is in use by an other program, HttpTea
will display the following error message:
Address already in use: JVM_Bind
Example: HttpTea -l 9001
...tells HttpTea to listen at port 9001.
The 'n' Option - Thread Number
==============================================================
Use this option to tell HttpTea that information about
the thread that is handling the request shall be included in the output.
Background
..........
Todays HTML pages are complicated. They not only contain the HTML text
but also many additional elements like pictures, style sheets, scripts
and sounds.
To load such a page in an effective way, modern browsers are working
like this:
- they are starting separate thread to load the different parts of
a page in parallel
- they keep the connection to the server open after the requests has
been processed. The connection is then re-used to load other objects.
This makes the loading a bit faster. On the other hand, it makes it hard to
find out which server response belongs to which request.
With the -n option, the output of HttpTea looks like this:
0 Client>>>
0 GET http://localhost:8080/ HTTP/1.1
0 Host: localhost:8080
0 Keep-Alive: 300
0 Proxy-Connection: keep-alive
0
0<
0< Server>>>
0< HTTP/1.1 200 OK
0< Content-Type: text/html
0< Transfer-Encoding: chunked
0< Date: Sun, 09 Apr 2006 13:31:08 GMT
0< Server: Apache-Coyote/1.1
0<
0< <... here comes the HTML text>
1
1 Client>>>
1 GET http://localhost:8080/tomcat-power.gif HTTP/1.1
1 Host: localhost:8080
1 Keep-Alive: 300
1 Proxy-Connection: keep-alive
1 Referer: http://localhost:8080/
1
2 Client>>>
2 GET http://localhost:8080/jakarta-banner.gif HTTP/1.1
2 Host: localhost:8080
2 Keep-Alive: 300
2 Proxy-Connection: keep-alive
2 Referer: http://localhost:8080/
2 Cache-Control: max-age=0
2
The number in the first column indicates the ID of the client <--> server
connection. The following character "<" indicates that the text belongs
to data that the server sends to the client.
So, in the example above, the lines starting with "0<" are the server
response to the request for the URL "http://localhost:8080/"
The 'p' Option - Proxy
==============================================================
This options tells HttpTea which host should act as proxy server.
This parameter is required for the raw mode. For the HTTP mode, the
parameter is optional.
Example: HttpTea -p localhost:8080 -l 9001
...uses localhost, port 8080 as proxy.
See also: -r
The 'r' Option - Raw Mode
==============================================================
Set the operation mode to RAW. In this mode,
HttpTea does not interpret the HTTP protocol.
The incoming data is send to the proxy without any
investigation or modification.
For this mode, you need to specify a proxy using the -p option.
The following output formats are supported:
A - ASCII format
H - Hex format
Example: -r H
...will display the HTTP traffic in hex.
Why do I need a proxy for this?
HttpTea is not looking into the request in this mode.
So it has not way to find out to which host the data shall be send.
If the WEB application you are working with is only communicating
with a single server, you can enter this server as the proxy unsing
the -p option.
Example: HttpTea -r -p 129.222.190.10:8080
...tells HttpTea to work in raw mode and to send all
requests to the host 129.222.190.10 at port 8080
See also: -p
The 'r' Option - Raw Mode
==============================================================
Set the operation mode to RAW. In this mode,
HttpTea does not interpret the HTTP protocol.
The incoming data is send to the proxy without any
investigation or modification.
For this mode, you need to specify a proxy using the -p option.
The following output formats are supported:
A - ASCII format
H - Hex format
Example: -r H
...will display the HTTP traffic in hex.
Why do I need a proxy for this?
HttpTea is not looking into the request in this mode.
So it has not way to find out to which host the data shall be send.
If the WEB application you are working with is only communicating
with a single server, you can enter this server as the proxy unsing
the -p option.
Example: HttpTea -r -p 129.222.190.10:8080
...tells HttpTea to work in raw mode and to send all
requests to the host 129.222.190.10 at port 8080
See also: -p
The 's' Option - Client Socket Timeout
==============================================================
This parameter defines the timeout for
the client socket. The client socket is the
socket that the browser opens towards the HttpTea.
If the browser does not send any data during
the specified time, the socket is closed.
Example: HttpTea -s 1000
...tells HttpTea to wait for 1 second on HTTP requests from the browser.
See also: -S option
The 'S' Option - Server Socket Timeout
==============================================================
Set the server socket timeout.
This is the timeout of the socktes that HttpTea opens to the server.
The server is the proxy or the final destination of the request.
Example: HttpTea -S 5000
...will set this timeout to 5 seconds.
The 't' Option - Display Raw Header
==============================================================
This option enables or disables the display of the
HTTP header in the output.
HttpTea modifies the HTTP header depending on different
options (+A for example)
With the +t option you can tell HttpTea to include the HTTP header
as it was originally send into the output.
Example: HttpTea +T +t -l 9001
...display the HTTP header of each request two times:
- before HttpTea has processed it (raw header)
- after HttpTea has processed it (processed header)
Example: HttpTea +T -t -l 9001
...display only the HTTP header after it has been processed.
Example: HttpTea -T +t -l 9001
...display only the HTTP header before it has been processed.
See also: -T
The 'T' Option - Display Processed Header
==============================================================
This option enables or disables the display of the
HTTP header in the output.
HttpTea modifies the HTTP header depending on different
options (+A for example)
With the +t option you can tell HttpTea to include the HTTP header
as it was originally send into the output.
Example: HttpTea +T +t -l 9001
...display the HTTP header of each request two times:
- before HttpTea has processed it (raw header)
- after HttpTea has processed it (processed header)
Example: HttpTea +T -t -l 9001
...display only the HTTP header after it has been processed.
Example: HttpTea -T +t -l 9001
...display only the HTTP header before it has been processed.
See also: -T
The 'v' Option - Verbose Level
==============================================================
Sets the log-level for the application.
Level:
0 = none
1 = error
2 = warning
3 = info
>3 = debug
Example: HttpTea -v 4
...will set log level to DEBUG.
The 'y' Option - Define the Receive Buffer Size
==============================================================
This option sets the buffer size. This is the size of the
Input buffer when reading data from the client or from the server.
Exampele: HttpTea -y 8192
...sets the buffer to 8kB.
