1.\" $Id: ffproxy.conf.5.s,v 2.3 2005/01/05 15:54:39 niklas Exp niklas $
2.\" Copyright (c) 2002-2005 Niklas Olmes <niklas@noxa.de>
3.\" See COPYING for license (GNU GPL)
4.\" http://faith.eu.org
5.Dd Jan 5, 2005
6.Dt ffproxy.conf 5
7.Sh NAME
8.Nm ffproxy.conf
9.Nd filtering HTTP/HTTPS proxy server configuration file
10.Sh DESCRIPTION
11.Nm ffproxy
12is a filtering HTTP/HTTPS proxy server.  It is able to filter
13by host, URL, and header.  Custom header entries can be filtered
14and added.  It can even drop its privileges and optionally
15.Xr chroot 2
16to some directory.  Logging to
17.Xr syslog 3
18is supported, as is using another auxiliary proxy server.
19An HTTP accelerator feature (acting as a front-end to an HTTP server)
20is included.  Contacting IPv6 servers as well as binding to IPv6 is
21supported and allows transparent IPv6 over IPv4 browsing (and vice versa).
22.Pp
23This manual describes how to use configuration files with the program
24and documents the options.
25.Sh USING CONFIGURATION FILES
26.Ss Default ffproxy.conf
27If the command line parameters -f or -F are not used, the proxy
28tries to open
29.Pa _CFGFILE_ .
30If this file does not exist, the program continues execution.
31.Ss User Configuration File
32Use command line parameter -f to load a non-default configuration
33file.  You will notice the warning at the program's startup.  This
34is due to the programs implementation that allows to reload
35all configuration files.  To disable the warning, use -F instead.
36.Ss Deactivating
37To use command line options only, use -f "".
38.Ss Reloading Configuration
39To let the proxy reload its configuration files, that is, besides
40the configuration file specified, the contents of db/ and html/,
41send the signal HUP to the program's master process.  If
42ffproxy runs daemonized, the PID can be found in
43.Pa db_files_path/ffproxy.conf .
44Otherwise look into your system's syslog log files or process table.
45.Pp
46Options that can be successfully altered at runtime are
47.Bd -literal -offset indent
48child_processes
49use_ipv6
50use_syslog
51log_all_requests
52forward_proxy
53forward_proxy_port
54forward_proxy_ipv6
55accel_host
56accel_port
57accel_user_host
58use_keep_alive
59unrestricted_connect
60timeout_connect
61backlog_size
62.Ed
63.Pp
64Set `accel_port 0' or `forward_proxy_port 0' to explicitly disable
65acceleration or auxiliary proxy.  Commenting out options is not
66sufficient, since configuration options may only overwritten.
67.Pp
68Changes to other options not mentioned above get silently ignored.
69.Sh CONFIGURATION OPTIONS
70.Bd -literal
71#
72# lines starting with '#' are comments
73#
74
75# run as daemon?
76# (default: no)
77#daemonize yes
78#daemonize no
79
80# number of child processes,
81# that is, the maximum number of concurrent requests
82# (default: 10)
83#child_processes 10
84
85# ffproxy binds to any IPv4 address
86# and any IPv6 address by default
87#
88# bind to IPv4?  (default: yes)
89#bind_ipv4 no
90#bind_ipv4 yes
91# bind to IPv6?  (default: yes)
92#bind_ipv6 no
93#bind_ipv6 yes
94#
95# Hostname or IP to bind to
96# (default is any IP)
97#
98#bind_ipv4_host 192.168.10.1
99#bind_ipv4_host martyr.burden.eu.org
100#bind_ipv6_host ::1
101#bind_ipv6_host oz.burden.eu.org
102
103# listen on port
104# (default: 8080)
105#port 1111
106#port 8080
107
108# use IPv6 when contacting servers?
109# (default: yes)
110#use_ipv6 no
111#use_ipv6 yes
112
113# use syslog?
114# (default: yes)
115#use_syslog no
116#use_syslog yes
117
118# log all requests?
119# (default: no)
120# to use, set also use_syslog to yes
121#log_all_requests yes
122#log_all_requests no
123
124# change UID and GID
125#
126# to use, both uid and gid must be set
127# (disabled by default)
128#uid proxy
129#gid proxy
130#uid 37
131#gid 38
132
133# change root to (only in connection with uid and gid change)
134#   /etc/resolv.conf might need to be copied
135#   to chroot_dir/etc/resolv.conf
136# (disabled by default)
137#chroot_dir _BASE_
138
139# forward to proxy (auxiliary proxy)
140# (set `forward_proxy_port 0' to explicitly disable feature
141#  (i.e, when reloading configuration file via SIGHUP))
142# (disabled by default)
143#forward_proxy blackness.burden.eu.org
144#forward_proxy 192.168.10.5
145#forward_proxy ::1
146#forward_proxy_port 8082
147#forward_proxy_port 0
148
149# try IPv6 for auxiliary proxy?
150# use_ipv6 must be set to yes, too
151# (default: yes)
152#forward_proxy_ipv6 no
153#forward_proxy_ipv6 yes
154
155# path to db/ and html/ directories
156# (default: _BASE_)
157# (Note: if ffproxy runs chrooted,
158#  give a path name relative to new root, or,
159#  if db_files_path is the same as root, use db_files_path ./
160#  You have to start ffproxy in the new root directory,
161#  otherwise it won't find the database files.
162#  Please keep in mind that ffproxy's config file has to
163#  be within chroot directory, otherwise it will not find
164#  its config file on reload)
165#db_files_path ./
166#db_files_path _BASE_
167
168# http accelerator
169# (disabled by default)
170#
171# if you want to use ffproxy as http accelerator (that is, connecting
172# to just one http server and beeing used as front-end to that, e.g.
173# in DMZ) uncomments options below (port is optional, defaults to 80)
174# (set `accel_port 0' to explicitly disable feature
175#  (i.e, when reloading configuration file via SIGHUP))
176#accel_host 10.254.1.2
177#accel_host revelation.martyr.eu.org
178#accel_port 80
179#accel_port 0
180#
181# Omit Host: accel_host:accel_port in Header
182# to provide own Host: header via db/filter.header.add?
183# (default: yes)
184#accel_user_host no
185#accel_user_host yes
186
187# keep alive on client to proxy connections
188# (enabled by default)
189#use_keep_alive no
190#use_keep_alive yes
191
192# allow CONNECT request to other than port 443 (HTTPS)
193# (CONNECT enables HTTPS proxying)
194# (disabled by default for security)
195#unrestricted_connect yes
196#unrestricted_connect no
197
198# timeout for CONNECT requests in seconds
199# (default: 5)
200#timeout_connect 20
201#timeout_connect 5
202
203# backlog size for accept()
204# (default: 4)
205#backlog_size 16
206#backlog_size 4
207.Ed
208.Sh VERSION
209This manual documents ffproxy 1.6 (2005-01-05).
210.Sh FILES
211.Pa _CFGFILE_
212default configuration file
213.Pp
214.Pa sample.config
215sample configuration file
216.Sh SEE ALSO
217.Xr ffproxy 8 ,
218.Xr ffproxy.quick 7 ,
219.Xr regex 7 ,
220.Xr re_format 7 ,
221.Xr syslogd 8 ,
222.Xr chroot 2 ,
223.Xr kill 1
224