Description
===========

ffproxy -- full featured, secure HTTP proxy server

ffproxy is a filtering HTTP proxy server.  It is able to filter
by host, url, and header.  Custom header entries can be filtered
and added.  It can even drop its privileges and chroot() to some
directory.  Logging to syslog() is supported, as is using another
auxiliary proxy server.  Contacting servers via IPv6 is supported
as well.

Website:  http://faith.eu.org/programs.html

Compilation
===========

  * Edit Makefile to fit your needs.
    (uncomment OCFLAGS = -DLINUX if you're using Linux)
  * After making your changes, compile ffproxy with make.
    (see section `Bugs' at the very end of the file if
    ffproxy won't compile or crashes)

Installation
============

 * Copy directories db/ and html/ to some other directory,
   like /var/ffproxy.
 * Execute make install
   This will copy ffproxy to /usr/local/bin and the manpage
   ffproxy.8 to /usr/local/man/man8.

Documentation
=============

   o For a quick summary and reference on ffproxy,
     read the manual page.

   o For a longer introduction to configuring with the
     db/ files, read this file.
   

Configuration
=============

ffproxy's basic settings (like the port to bind to) are determined at
program invocation by means of command line options, or by means
of a config file and the command line option `-f'. If no config
file is given, /etc/ffproxy.conf is used.

See file config.sample for a configuration template.

Filtering settings are read from directory db/ in /var/ffproxy
by default (use -D or db_files_path in config file to change).
These files do the following:

The following three files are for filtering User Agent Headers:

 * filter.header.add	Header entries to add

 * filter.header.drop   If the regular expression matches any line of
			the header, the complete request will be dropped

 * filter.header.entry	Header entries to remove (i.e. `User-Agent:')


 * filter.header.match	If regular expression matches any header entry,
			that one will be removed

The files filter.rheader.drop, filter.rheader.entry, filter.rheader.match
do exactly the same on the remote side.

The following files are for filtering hosts and urls:

 * filter.host.match	Don't get anything from these hosts
			(extended regular expression)

 * filter.url.match	Don't get URLs that match any of
                        the extended regular expressions

Access settings are read from db/, too:

 * host.dyndns		Hostnames with dynamic IP addresses that have
			access permission (matched case insensitive
			without regular expressions)

 * host.ip		static IP addresses (regular expressions)

 * host.name		Official hostnames (regular expressions)


All entries are one line each.  Comments are not allowed.

All files ending in `match' or `drop' do pattern matching with extended
regular expressions, see manpage re_format(7) or regex(7), depending
on your system, for more information.

	Examples:
	in db/filter.url.match:
	/\.\./		don't allow to trick us or remote servers.
			(prevent directory traversal, don't remove that)

	WERBUNG		don't get file if URL contains the string `WERBUNG'
			(German for commercial)
	/[Rr]eal[Mm]edia	don't get any URL that contains this string,
				the effect is that directories or files
				starting with `RealMedia' get filtered out
	/ads/		this will prevent from receiving advertisements,
			which quite often lie in directories named like
			this
	
	in db/filter.host.match:
	^ad[0-9]*\.	don't get anything from hosts with names starting
			with `ad' followed by a dot or an abitrary
			number followed by a dot.


Reloading Configuration
=======================

If you altered files in db/ or html/ and want to make the changes
take effect, you don't have to restart ffproxy.

Simply send a SIGHUP to the master process.  It'll reload all files
and report success (by logging to syslog).  Note that fatal errors,
like non existing files, cause ffproxy to terminate.  Non fatal errors,
like broken extended regular expressions are logged while reloading
configuration.

Bugs
====

Before I release a new version of ffproxy,  I eliminate all known bugs.
Though I have only access to a limited number of different systems,
it's possible that ffproxy won't run correctly or won't compile at all.

I would appreciate to hear succes stories or receive error reports
from you.  Send these to my e-mail address, Niklas Olmes <niklas@noxa.de>
