FFPROXY(8)

🌸 NAME 🌸

okay so you opened the manual for ffproxy(8) and bestie, it's a filtering HTTP/HTTPS proxy server. that's the whole vibe. it filters, it proxies, it slays 💅

---

✨ SYNOPSIS ✨

ffproxy [-p port] [-c ip|hostname] [-C ip|hostname] [-l children]
        [-u uid|user -g gid|group] [-r dir] [-D datadir]
        [-x proxyip|proxyhost -X proxyport] [-a ip|hostname] [-A port]
        [-n piddir] [-f configfile] [-ds4bBhv]

---

🦋 DESCRIPTION 🦋

okay so ffproxy is a filtering HTTP/HTTPS proxy server, and she does a lot. she can filter by host, by URL, and by header. custom header entries can be filtered and added, which is giving full control honestly 👑

she can even drop her privileges and optionally chroot(2) to some directory. logging to syslog(3) is supported, and so is using another auxiliary proxy server. there's also an HTTP accelerator feature (acting as a front-end to an HTTP server) included. contacting IPv6 servers as well as binding to IPv6 is supported, and it allows transparent IPv6 over IPv4 browsing (and vice versa). no cap.

remind that there is an alternative to command line options by using configuration files. see ffproxy.conf(5) and sample.config for details. it allows options that are not available on command line — so yeah, config files stay winning.

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. no squishing them together bestie, it's not that kind of party 🙈

• -p port — bind to port. default is 8080.
• -c ip|hostname — bind to IPv4. default is any IPv4.
• -C ip|hostname — bind to IPv6. default is any IPv6.
• -l children — maximum number of child processes to be forked. that is, the maximum number of concurrent requests allowed. default is 10.
• -u uid|user -g gid|group — change UID and GID. both options must be used (they're a package deal fr fr). default is not changing UID and GID.
• -r dir — 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 ""
• -x ip|hostname — specify IP (or hostname) of an auxiliary proxy server that the program will forward requests to. used together with -X.
• -X port — port number of auxiliary proxy.
• -D dir — 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 /var/ffproxy/html/.
• -a ip|hostname — auxiliary forward HTTP server to use (see section HTTP ACCELERATOR).
• -A port — port to use for above. defaults to 80.
• -n piddir — directory to store file ffproxy.pid with ffproxy pid inside. default is /var/run
• -f configfile — 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.
• -d — run as daemon.
• -s — be silent. don't log to syslog.
• -4 — use IPv4 only. do not try contacting servers via IPv6.
• -b — 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.
• -B — don't bind to IPv6.
• -h — show usage information.
• -v — display version number.

---

🎀 THE DB/ DIRECTORY 🎀

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.

💜 Filtering

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

filter.host.match
filter.header.drop
filter.header.entry
filter.header.match
filter.rheader.drop
filter.rheader.entry
filter.rheader.match
filter.url.match

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 filter.header.add will be added to every outgoing request.

🔐 Access Control

access to the proxy is controlled through the files prefixed host.

host.dyndns 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.

host.ip contains static IPv4 and IPv6 address.

host.name contains official hostnames (reverse lookup).

except for host.dyndns, the files contain extended regular expressions. if any of the entries matches, access is granted 💖

📂 Layout of db/ Files

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 # (comments).

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 /usr/share/ffproxy.

ffproxy comes with sample db/ files. they also contain needed and suggested entries, as described next.

🌟 Suggested db/ file entries

the file filter.header.entry should contain following entries for the program's proper operation

Accept-Encoding:
Accept:
Connection:
Proxy-Connection:
Host:

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).

filter.header.add should contain

Connection: close
Proxy-Connection: close

we removed the two entries through filter.header.entry and now implant our own to force disconnection after each request. main character energy honestly 👑

filter.rheader.entry should contain

Connection:
Proxy-Connection:

whatever the server answered, we remove it. periodt.

---

🌈 THE HTML/ DIRECTORY 🌈

this directory contains files with HTTP header and HTML that are sent to the user's browser if either an error occurred 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 $c 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)

connect      Connection failed (503)
filtered     Request filtered (200)
invalid      Invalid request (400)
post         Unable to post data (400)
resolve      Resolve error (503)

---

🚀 HTTP ACCELERATOR 🚀

ffproxy may also be used as a HTTP accelerator, that is, connecting to just one HTTP server and being 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.

---

🕶️ TRANSPARENT OPERATION 🕶️

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. sneaky, iconic, we love her 💅

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

to /etc/pf.conf. 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.

---

💞 KEEP ALIVE 💞

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.

---

🔒 HTTPS OPERATION 🔒

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.

---

🔄 RELOADING CONFIGURATION 🔄

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 specified, /etc/ffproxy/ffproxy.conf is tried. of course, only some changes to the program can be done at runtime. see ffproxy.conf(5) for details on options that may be changed at runtime.

ffproxy write its pid file ffproxy.pid in the directory specified by the command line parameter -n or the pid_dir setting in config file. default is /var/run.

---

📝 LOGGING 📝

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 modifying syslog.conf(5), since the output is very noisy. bestie she's a yapper when you let her log everything 😭

---

📁 FILES 📁

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 default.
• the files in db/ which specify filtering options and who is allowed to connect and use ffproxy

---

👀 SEE ALSO 👀

sample.config for a sample configuration file

/etc/ffproxy/ffproxy.conf for default configuration file

ffproxy.conf(5) for details on config file

ffproxy.quick(7) for a short description of how to set up the proxy

http://faith.eu.org/programs.html for latest version and patches

regex(7), re_format(7), syslogd(8), chroot(2), kill(1)

---

🫶 CONTRIBUTORS 🫶

Dobrica Pavlinusic <dpavlin@rot13.org> provided patches for http accelerator feature

---

⭐ VERSION ⭐

this manual documents ffproxy 1.6 (2005-01-05).

send bug reports, comments, suggestions to <niklas@noxa.de>

👑 AUTHOR 👑

Okay bestie, one (1) absolute legend made this whole thing happen, and you have to give them their flowers 💐

• Niklas Olmes <niklas@noxa.de> — yeah, that's the icon, the moment, the main character. If ffproxy ever came in clutch for you, this is the name you're thanking. Respect where respect is due, fr fr 🫶

---

And that's a wrap on the whole page, bestie! You just read through ffproxy(8) — this version landed on Jan 5, 2005, so it's giving vintage, it's giving old-school Unix royalty, and honestly? It ate. 💅✨

Go forth, proxy responsibly, and remember: read the whole man page before you touch the config file. No cap. 🌈💖