adzapper Home | About Adzapper | Zaplets | Installing

Installation Instructions for adzapper

for information about adzapper, go here.

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.0), and Windows NT 4.0 (SP3), but it should run on Windows 95/98 and also 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.

Unix

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 adzapper.py program, and places it in a directory you specify (default is /usr/local/bin).

Windows

unzip the adzapper-x.y.z.tgz file into the place you want to keep it, usually C:\Program Files\adzapper. that's all. if you have python installed correctly, you should be able to double-click the "adzapper.py" file to run adzapper.

Running adzapper

adzapper is a filtering proxy server-- it sits between your web browser and the Internet. to use adzapper, you need to run it, then configure your browser to access the Internet through a proxy server (adzapper).

to start adzapper, simply type 'adzapper' at a command prompt. 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' to see what options are available.)

now set your browser's preferences to use a proxy server to connect to the Internet. 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.

if you want adzapper to re-read the zaplets (because you have edited them), you will need to stop it, then start it again. under unix you can also send adzapper a SIGHUP, which accomplishes the same thing.

Setting your browser to use a proxy

Netscape

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 "localhost" or "127.0.0.1"). 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 "localhost" or "127.0.0.1"). 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. :-)

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!

Troubleshooting

if adzapper doesn't start, you might want to check that you have python in your path. under unix, 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:
PYTHON='/path/to/your/python'

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 (127.0.0.1) as a default.

this sometimes works under Unix, but doesn't under Windows, so if you are having problems, this might it. the symptom: you can only contact web sites that you specify using their IP address instead of their DNS name. (i.e., http://10.10.2.3/)

if you encounter problems, try setting the DNS server manually. for example:

% adzapper -n 216.39.128.6
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.

Configuration

most of adzapper's options can be configured in the adzapper.conf file, which usually lives in the zaplets/ directory of your installation. the following commands can be used in this file:

Using Another Proxy Server

adzapper can access the internet through another proxy server. if you already use a proxy server, use the http_proxy command:
http_proxy http://my_proxy_server:9999/
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. the file needs to be placed in the zaplets/ directory:
replacement_gif blue.gif

adzapper PID file

if you 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:
pid_file /var/run/adzapperd.pid

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.

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

order deny,allow
deny from all
allow from 127.0.0.1

use partial IP addresses to denote network numbers:

order deny, allow
deny from all
allow from 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:

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

Running adzapper as a daemon

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

Adam Feuer
adamf at pobox.com (replace the 'at' with '@' to contact me via email)
http://www.pobox.com/~adamf/

Last Modified: Sun Aug 15 01:09:46 1999