filtering HTTP/HTTPS proxy server
is a filtering HTTP/HTTPS 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 optionally
to some directory. Logging to
is supported, as is using another
auxiliary proxy server. An HTTP accelerator feature (acting as a front-end to
an HTTP server) is included. Contacting IPv6 servers as well as binding to
IPv6 is supported and allows transparent IPv6 over IPv4 browsing (and vice
Remind that there is an alternative to command line options by using
configuration files. See ffproxy.conf(5)
for details. It allows options that
are not available on command line.
The following command line options are recognized. They specify general settings
like IP to bind to or place of the db/ and html/ directories. Note that
arguments to options must be separated from the option by spaces, as are such
options from each other.
- Bind to port. Default is 8080.
- Bind to IPv4. Default is any IPv4.
- Bind to IPv6. Default is any IPv6.
- Maximum number of child processes to be forked. That is,
the maximum number of concurrent requests allowed. Default is 10.
- Change UID and GID. Both options must be used. Default is
not changing UID and GID.
- Change root chroot(7) to dir.
Used in conjunction with -u and -g. Because ffproxy drops its privileges
and chroots after reading the configuration files, -D should be set to .
(the current dir). It might need
/etc/resolv.conf copied as etc/resolv.conf in
its working directory. Example: ``# cd /var/ffproxy ;
/usr/local/bin/ffproxy -r /var/ffproxy -D . -d -u proxy -g proxy -f
- Specify IP (or hostname) of an auxiliary proxy server that
the program will forward requests to. Used together with -X.
- Port number of auxiliary proxy.
- Location of the db/ and html/ directories. For example,
specifying -D /var/ffproxy tells the proxy to search for db/ files in
/var/ffproxy/db/ and html/ files in
- Auxiliary forward HTTP server to use (see section HTTP
- Port to use for above. Defaults to 80.
- directory to store file ffproxy.pid with ffproxy pid
inside. Default is /var/run
- User configuration file to load. Please note that command
line options get overwritten by set configuration file options. Default
location is /etc/ffproxy/ffproxy.conf. Read
ffproxy.conf(5) for details. Use -f
"" to disable configuration files.
- Run as daemon.
- Be silent. Don't log to syslog.
- Use IPv4 only. Do not try contacting servers via IPv6.
- Don't bind to IPv4. Might be needed under Linux 2.4, due to
a ``Feature'' IPv6 binds to IPv4, too. Try using this option or bind to
specific IPv6 address via -C.
- Don't bind to IPv6.
- Show usage information.
- Display version number.
The db/ directory contains files that control the behaviour of ffproxy. The
files for filtering are prefixed by `filter'. Access to the proxy server is
controlled by files with prefix `host'.
Requests or header entries to be filtered are matched by extended regular
expressions or case insensitive by strings.
ffproxy is able to filter requests by host, header, remote header, and URL. The
specific files are
Files ending in `drop' specify requests to be completely filtered (dropped).
Files ending in `entry' specify header entries to be removed from the header.
They are matched case insensitive without extended regular expressions. Files
ending in `match' specify extended regular expressions to be matched against
header entries, host, or URL.
Adding custom header entries is also supported. The entries of file
will be added to every outgoing
Access to the proxy is controlled through the files prefixed `host'.
contains host names with dynamic IPv4
addresses. The host names are resolved to IPv4 addresses and compared to the
client's IP. If it matches, access is granted.
contains static IPv4 and IPv6 address.
contains official hostnames (reverse
Except for host.dyndns
, the files contain extended
regular expressions. If any of the entries matches, access is granted.
Every mentioned file above must exist, although it may be empty. Every entry is
exactly one line. Empty lines are ignored, as are lines beginning with a #
The location of the db/ directory may be specified by an argument to the command
line option -D. If this option and configuration file option db_files_path are
not used, ffproxy will search for db/ and html/ in
ffproxy comes with sample db/ files. They also contain needed and suggested
entries, as described next.
The file filter.header.entry
following entries for the program's proper operation
First two lines are needed for browsers that send out Accept*: Headers but don't
understand encoded data coming back from the proxy. Host: has to be removed,
since proxies require absolute URIs (Host: is redundant).
We removed the two entries through
and now implant our own to
force disconnection after each request.
Whatever the server answered, we remove it.
This directory contains files with HTTP header and HTML that are sent to the
user's browser if either an error occured or a request was filtered. In the
files, the variable $u
will be replaced by
the URL, $h
by the host to connect to, and
by the hostname of the client.
Since the files are loaded into memory for faster execution, the size of each
file is limited to about 8 kB (what is more than enough, the default files are
under 1 kB).
The specific files are (every file must exist)
- Connection failed (503)
- Request filtered (200)
- Invalid request (400)
- Unable to post data (400)
- Resolve error (503)
ffproxy may also be used as a HTTP accelerator, that is, connecting to just one
HTTP server and beeing a front-end to that. Use accel_host and accel_port in
configuration file or command line options -a and -A to use this feature.
Default behaviour is *not* sending Host: header to allow insertion of a custom
one via filter.header.add
(see section THE DB/
DIRECTORY) or keeping the original one used by connecting client (`Host:' hast
to be removed from default filter.header.entry
of course). To change this, use `accel_user_host no' in the configuration
file. ``Host: accel_host:accel_port'' will be used then.
It is possible to redirect all HTTP traffic, that is, traffic to port 80, to the
proxy's listening port. It will then transparently act as a HTTP proxy, the
client not even knowing it is connecting to a proxy.
On OpenBSD one could enable this by adding a line like
rdr on rl0 proto tcp from any to any port 80 -> 127.0.0.1 port 8080
. In this example, rl0 is the local
interface. All traffic coming from rl0 directed to port 80 (HTTP standard
port) is sent to 127.0.0.1:8080 where ffproxy is supposed to be listening.
The program supports keep alive on client to proxy connections. This is used
automatically by default and may be disabled by setting `use_keep_alive no' in
the configuration file.
The proxy allows HTTPS proxying via implementation of the CONNECT request
method. By default, only port 443 is allowed for CONNECT. This may be changed
by using `unrestricted_connect yes' in the configuration file. Timeout may
also be tuned by `timeout_connect seconds'.
Send a SIGHUP to the pid of the ffproxy master process to let it reload db/
files, html/ files, *and* configuration file. If no configuration file was
is tried. Of
course, only some changes to the program can be done at runtime. See
for details on options that may
be changed at runtime.
ffproxy write its pid file ffproxy.pid
directory specified by the command line parameter -n or the
setting in config file. Default is
By default, the proxy logs incorrect and filtered requests. To log all requests,
use the configuration file keyword `log_all_requests yes'. Please make sure
that you separate the programs log output from that of other programs by
, since the output is
Behaviour of ffproxy is determined by
- startup options given either on the command line or read
from configuration files --
/etc/ffproxy/ffproxy.conf is loaded by
- the files in db/ which specify filtering options and who
is allowed to connect and use ffproxy
for a sample configuration file
for default configuration
for details on config file
for a short description of how to
set up the proxy
version and patches
Dobrica Pavlinusic <email@example.com> provided patches for http
This manual documents ffproxy 1.6 (2005-01-05).
Send bug reports, comments, suggestions to <firstname.lastname@example.org>
Niklas Olmes <email@example.com>