adzapper   adzapper Home | About Adzapper | Installing | Zaplets | Zaplet File Format | Zaplet Updates Python Powered  

Installation Instructions for adzapper

For information about adzapper, go here.

Installation is different on Windows and Unix. Please follow the instructions for your platform.


On Unix platforms, you will need a recent version of Python to run adzapper; I have only tested it on version 1.5.2, but any recent version should work. adzapper has only been tested on Linux (RedHat 6.2), but it should run on any Unix variant that can run Python. Please let me know if you have any problems, and if you get adzapper running on a platform not listed here.

Before installing adzapper, you will need to install Python; get it from the Python website download page.

Unpack the adzapper-x.y.z.tgz file into the place you want to keep it, change to that directory, and run the 'install' script. install makes a shell script called 'adzapper' that will run the program, and places it in a directory you specify (default is /usr/local/bin). You can run adzapper from the command line, or run it as a daemon using the 'adzapperd' script (if you ran 'install-adzapperd').



Installation on Windows platforms now uses a self-installing exe file. Launch the installer, it will prompt you for the directory to install adzapper in. The installer will place an icon for adzapper in your Start/Programs menu, and on your desktop.

To use adzapper, double-click the adzapper icon, and then adjust your browser settings so it will use adzapper as a proxy server. The installer does not automatically adjust your browser settings; I hope to add this in a future release.

adzapper has been tested on Windows NT 4.0, Windows 98, and Windows 95.


Running adzapper

adzapper is a filtering proxy server-- it sits between your web browser and the Internet. It doesn't need to be installed on your desktop machine-- it can be installed on another computer or a server, too.

To use adzapper, you need to set your browser's preferences to use it as a proxy server. Set the address to the IP address or DNS name of the machine that you are running adzapper on, and set the port for HTTP protocol to port 51966. adzapper does not yet filter HTTPS or FTP.

If you need more detailed instructions on setting your web browser to use a proxy server, see the hints below.

The default port adzapper runs on is 51966; you can set this to a different port by using the command line options. (type 'adzapper -h' at a command prompt to see what options are available.)

adzapper's UI runs on +1; by default this is port 51967. After you install adzapper, you can access its web-based user interface at this page: http://localhost:51967/ (if you are using the default port).

You can bookmark this page for easy reference. From the GUI, you can make new zaplets, edit existing zaplets, and change adzapper's configuration settings.

If you want adzapper to re-read the zaplets (because you have edited a zaplet file on disk), you will need to stop adzapper, then start it again. You can do this from the GUI's 'Restart adzapper' page. Under Unix you can also send adzapper a SIGHUP, which accomplishes the same thing.

If you edit zaplets using the GUI, you don't have to restart adzapper; the changes take effect immediately.


Setting your browser to use a proxy


Under Netscape 4.x, this is set under Preferences. select "Preferences" from the "Edit" pop-down menu. Proxy configuration is done in "Proxies" under the "Advanced" section. You will need to choose "Manual proxy configuration", then click "View..." to view the configuration. Enter the IP number or DNS name of the machine that adzapper is running on in the "HTTP Proxy:" field (usually this is the same machine you are surfing the web from, in which case you would ""). enter the port adzapper is running on (normally 51966) in the "Port:" field.


Internet Explorer

Under Internet Explorer 4.x, this is set under Internet Options. Select "Internet Options" from the "View" pop-down menu. proxy configuration is done in the "Connection" tab. Make sure the "Access the Internet using a proxy server" checkbox is checked, and fill in the "Address:" field with the IP number or domain name of the computer that adzapper is running on (usually this is the same machine you are surfing the web from, in which case you would enter ""). enter the port adzapper is running on (normally 51966) in the "Port:" field.


Lynx, Opera, or other browsers

If you're using a browser other than the ones listed above, you probably know how to change your proxy server. :-)

If you use a web browser not mentioned here and would like to contribute directions for using a proxy server, please send them to me at the address below!


Under Unix, if adzapper doesn't start, you might want to check that you have python in your path. If you don't have it in your path, or don't want to put it in your path, edit the install or install-daemon script and change the PYTHON='python' line so that PYTHON points to your python executable:


If you get the error 'Address already in use', either adzapper is already running, or the port is in use by another server. To use adzapper with a different port, type "adzapper <port>". For example:

% adzapper 9999

adzapper has it's own DNS resolver, since the one inside adzapper is a lot faster than just using the built-in resolver. Because it has its own resolver, adzapper needs to know your local DNS server. It tries to guess this on its own (under Unix by looking in /etc/resolv.conf, and under Windows by looking in the Registry), and if it fails, it uses localhost ( as a default.

Using localhost as a DNS resolver sometimes works under Unix, but doesn't under Windows, so if you are having problems, this might be it. The symptom: you can only contact web sites that you specify using their IP address instead of their DNS name. (i.e.,

If you encounter problems, try setting the DNS server manually. For example:

% adzapper -n

zaplets usually live in the zaplets/ directory in the directory where you installed adzapper. If you want to put the zaplets somewhere else, use the -z option to specify another directory. The adzapper configuration file lives in the zaplet directory; to specify a filename other than the default "adzapper.conf", use the -f option.

For information on other options, type "adzapper -h" for help.


Most of adzapper's options can be configured in the GUI control panel, or in the adzapper.conf file, which usually lives in the zaplets/ directory of your installation. It is easy to configure adzapper using the GUI, but you can edit the adzapper.conf file directly; it is a self-explanatory XML document. The DTD for this document is included in the doc/ directory.


Specifying the DNS Server

By default, adzapper tries to guess your DNS server. This usually works well on most Unix systems, and on Windows NT systems that use a permanent (LAN) internet connection. However, if you need to, you can specify the DNS server in the configuration file:


Using Another Proxy Server

adzapper can access the internet through another proxy server. If you already use a proxy server, enter the URL here. (Note that the format is different from Netscape's!) For example:


If you don't include the port, it will default to 8080.


Using A Different Replacement GIF

You can specify a different replacement GIF instead of the default transparent GIF. You can specify an absolute file name or one that is relative to the zaplets directory. For example:



adzapper PID file

If you want to run adzapper as a daemon, you may want adzapper to write its PID to a file so that utility scripts can start, stop, or restart adzapper. For example,



Access control

adzapper has access control, which means you can restrict who uses adzapper by the IP number the requests come from. By default adzapper has access control turned off-- adzapper will server requests from any IP address.

To turn accesscontrol on, set this to 'on'; for off, set this to 'off':


The syntax for the accesscontrol commands is similar to apache's access control syntax. For instance, to block all requests except from your own machine, use these statements in the control panel:

Access Control on/off: on
Access Control Order: deny,allow
Access Control deny-from list: all
Access Control allow-from list:

use partial IP addresses to denote network numbers:

Access Control on/off: on
Access Control Order: deny,allow
Access Control deny-from list: all
Access Control allow-from list: 127. 192.168. 10.

You can change the way that adzapper will check addresses-- by default it is "all that is not expressly permitted is denied". To allow just from some networks, but deny some specific hosts from those networks, use something like this:

Access Control on/off: on
Access Control Order: allow,deny
Access Control deny-from list: 192.168.
Access Control allow-from list: 192.168.7.

This would allow access only from any computer in the 192.168.x.y group of addresses, except the host and all computers on the 192.168.7 network.


Running adzapper as a daemon

On Unix, adzapper can run as a background process, and log errors to a file. Use the 'install-daemon' script to make the 'adzapperd' script, then start adzapper by typing 'adzapperd' at the command prompt.

There is a System-V-style startup script in the 'scripts' directory; you can move this to your /etc/rc.d/init.d directory and use it to add adzapperd to your startup scripts. Note: this script was written for RedHat 6.0, and hasn't been thoroughly tested.


adzapper Home | About Adzapper | Installing | Zaplets | Zaplet File Format | Zaplet Updates

Adam Feuer
adamf at (replace the 'at' with '@' to contact me via email) | sitemap