[ Requirements | Installation | Browser Configuration | Starting Muffin | Using Muffin | Access Control | Using Filters | Writing your own filters | BUGS | TODO ]

Muffin

version 0.2

What is Muffin?

Muffin is an HTTP proxy filter that sits between your web browser and your HTTP proxy server. All HTTP transactions are passed through Muffin which uses filter modules written in Java to process and possibly modify each transaction. Several example filters are included with Muffin, but users are encouraged to write their own. Muffin is not an applet, it is a stand-alone Java application.

Requirements

Muffin requires an HTTP proxy server. If you do not use a proxy (check your Network Preferences) then Muffin will not work. If you wish to setup a proxy server I recommend the free proxy server called Squid.

Muffin is written in Java which means it requires the Java run-time environment to be installed your system. One place to obtain Java is from www.javasoft.com.

I've tested Muffin with the JavaSoft JDK 1.0.2 on Solaris 2.5 and Windows 95. Java works on the Macintosh, but the JDK 1.0.2 version of java.net.ServerSocket doesn't seem to work.


Installation

First read the license information and be sure you understand that:
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
With that in mind, download Muffin. Click download to obtain a ZIP file that contains the Java source and class files for Muffin. (A gzip tar archive is also available) Next, you'll need to unpack the ZIP archive which will create a muffin directory. Inside this directory will be another directory called muffin that contains all the Java source and class files for Muffin.

Browser Configuration

Muffin listens for requests from the web browser on a specific network port. By default, port 51966 will be used. Instead of your browser sending requests to your proxy server, the browser needs to be configured to send its requests to the Muffin port instead. In Netscape this port is specified in the Options/Network Preferences/Proxies/View... window. This window should currently include your HTTP proxy host and port. Remember the current settings and change them to talk to Muffin instead. For example, if your default proxy is proxy.yourdomain.com at port 3128, change the hostname to the host where Muffin will be running and change the port to the port that you wish Muffin to use or simply use 51966.

Starting Muffin

Muffin supports a few command-line options that you may need to start Muffin correctly:
$ java muffin.Main -help
Muffin Options:

-help                 This useful message.
-httpProxyHost HOST   Use HOST as the HTTP proxy.
-httpProxyPort PORT   Use PORT as the HTTP proxy port.
-port PORT            Listen on PORT for browser requests.
Go into the directory that contains the COPYING file and the muffin directory and start Muffin like this:
Unix or Windows 95/NT:
java muffin.Main
or
java muffin.Main -port 1234
Unix users can also use the muffin shell script provided in the bin directory.

Once muffin is running it will be ready to receive requests from your web browser. However, you still need to tell Muffin about your real HTTP proxy server. You can do this by entering the information in the Options... window or use the -httpProxyHost and -httpProxyPort options when you start Muffin. By default a host named proxy at port 3128 is used.


Using Muffin

The main Muffin has a few buttons and a graphic display of the current HTTP transactions. Filters... will popup the filters window, Options... will popup the options window, Suspend will cause Muffin to not accept HTTP requests from the browser, and Stop will stop all HTTP transactions, similar to the Stop button in a web browser.

Access Control

The Options... window allows you to restrict which hosts can connect to your Muffin. HostsAllow and HostsDeny are lists of IP address where access is allowed and denied, respectively. Multiple address are separated by commas and spaces. A range of IP addresses can be specified by only including part of an IP address. For example, 130.191.13. is the same as all addresses in the range 130.191.13.1 ... 130.191.13.254. The string ALL can be used to match all IP addresses.

The default access privileges are to allow access to the IP address of the host Muffin is running on and to deny access to all others hosts.


Using Filters

A filter is started by selecting it from the Known Filters list and pressing the Run button. Now the filter should be listed in the Running Filters list. All filters in this list will sequentially process the HTTP requests and responses. The order can be changed by using the Move Up and Move Down buttons. The current status of the filter can be obtained using the View... button. A filter can be stopped an any time by pressing the Stop button.

New filters can be added to the Known Filters list by pressing the New... button. You will need to enter a valid Java class path to specify the filter name. Examples would be java.lang.String, muffin.filters.SecretAgent, and test.TestFilter. You might need to modify the CLASSPATH environment variable to help java find classes that are not included in the system java classes or the current directory.

The following filters are included with Muffin:
  • CookieMonster - Removes `Cookie' and/or `Set-Cookie' headers. [source]
  • Logger - Keeps a log of all requested URLs. [source]
  • SecretAgent - Changes `User-Agent' header that's sent by the browser. [source]
  • SecretServer - Change `Server' header that's sent to the browser. [source]
  • Snoop - Keep a log of all HTTP headers. [source]
  • Stats - Maintain various stats about your HTTP session. [source]

Writing your own filters

In order to write your own filter you need to know how to program in Java, or perhaps you can ask a friend. Each filter must implement the Filter interface. Currently the interface includes the following functions:

filterRequest

public void filterRequest (Request r)
Filter the Request object.
filterReply
public void filterReply (Reply r)
Filter the Reply object.
view
public void view ()
Display information about the filter. Most filters used this to create a Frame to display filter specific information and/or allow the user to set configuration options.

Note that Request and Reply are sub-classes of Message which contains the interface to HTTP headers. Request adds several functions like getRequest, getCommand, and getURL.

Look at the source code for the included filters for more information.


BUGS


TODO


by Mark Boyns
Muffin logo by Rebecca Smith
Last modified: Mon Nov 25 15:13:41 PST 1996
Accesses: