1TINYPROXY.CONF(5) Tinyproxy manual TINYPROXY.CONF(5)
2
3
4
6 tinyproxy.conf - Tinyproxy HTTP proxy daemon configuration file
7
9 tinyproxy.conf
10
12 tinyproxy(8) reads its configuration file, typically stored in
13 /etc/tinyproxy/tinyproxy.conf (or passed to Tinyproxy with -c on the
14 command line). This manpage describes the syntax and contents of the
15 configuration file.
16
17 The Tinyproxy configuration file contains key-value pairs, one per
18 line. Lines starting with # and empty lines are comments and are
19 ignored. Keywords are case-insensitive, whereas values are
20 case-sensitive. Values may be enclosed in double-quotes (") if they
21 contain spaces.
22
23 The possible keywords and their descriptions are as follows:
24
25 User
26 The user which the Tinyproxy process should run as, after the
27 initial port-binding has been done as the root user. Either the
28 user name or the UID may be specified.
29
30 Group
31 The group which the Tinyproxy process should run as, after the
32 initial port-binding has been done as the root user. Either the
33 group name or the GID may be specified.
34
35 Port
36 The port which the Tinyproxy service will listen on. If the port is
37 less than 1024, you will need to start the Tinyproxy process as the
38 root user.
39
40 Listen
41 By default, Tinyproxy listens for connections on all available
42 interfaces (i.e. it listens on the wildcard address 0.0.0.0). With
43 this configuration parameter, Tinyproxy can be told to listen only
44 on one specific address.
45
46 Bind
47 This allows you to specify which address Tinyproxy will bind to for
48 outgoing connections to web servers or upstream proxies.
49
50 BindSame
51 If this boolean parameter is set to yes, then Tinyproxy will bind
52 the outgoing connection to the IP address of the incoming
53 connection that triggered the outgoing request.
54
55 Timeout
56 The maximum number of seconds of inactivity a connection is allowed
57 to have before it is closed by Tinyproxy.
58
59 ErrorFile
60 This parameter controls which HTML file Tinyproxy returns when a
61 given HTTP error occurs. It takes two arguments, the error number
62 and the location of the HTML error file.
63
64 DefaultErrorFile
65 This parameter controls the HTML template file returned when an
66 error occurs for which no specific error file has been set.
67
68 StatHost
69 This configures the host name or IP address that is treated as the
70 stat host: Whenever a request for this host is received, Tinyproxy
71 will return an internal statistics page instead of forwarding the
72 request to that host. The template for this page can be configured
73 with the StatFile configuration option. The default value of
74 StatHost is tinyproxy.stats.
75
76 StatFile
77 This configures the HTML file that Tinyproxy sends when a request
78 for the stathost is received. If this parameter is not set,
79 Tinyproxy returns a hard-coded basic statistics page. See the
80 STATHOST section in the tinyproxy(8) manual page for details.
81
82 Note that the StatFile and the error files configured with
83 ErrorFile and DefaultErrorFile are template files that can contain
84 a few template variables that Tinyproxy expands prior to delivery.
85 Examples are "{cause}" for an abbreviated error description and
86 "{detail}" for a detailed error message. The tinyproxy(8) manual
87 page contains a description of all template variables.
88
89 LogFile
90 This controls the location of the file to which Tinyproxy writes
91 its debug output. Alternatively, Tinyproxy can log to syslog — see
92 the Syslog option.
93
94 Syslog
95 When set to On, this option tells Tinyproxy to write its debug
96 messages to syslog instead of to a log file configured with
97 LogFile. These two options are mutually exclusive.
98
99 LogLevel
100 Sets the log level. Messages from the set level and above are
101 logged. For example, if the LogLevel was set to Warning, then all
102 log messages from Warning to Critical would be output, but Notice
103 and below would be suppressed. Allowed values are:
104
105 • Critical (least verbose)
106
107 • Error
108
109 • Warning
110
111 • Notice
112
113 • Connect (log connections without Info’s noise)
114
115 • Info (most verbose)
116
117 PidFile
118 This option controls the location of the file where the main
119 Tinyproxy process stores its process ID for signaling purposes.
120
121 XTinyproxy
122 Setting this option to Yes tells Tinyproxy to add a header
123 X-Tinyproxy containing the client’s IP address to the request.
124
125 Upstream
126 This option allows you to set up a set of rules for deciding
127 whether an upstream proxy server is to be used, based on the host
128 or domain of the site being accessed. The rules are stored in the
129 order encountered in the configuration file and the LAST matching
130 rule wins. The following forms for specifying upstream rules exist:
131
132 • upstream type host:port turns proxy upstream support on
133 generally.
134
135 • upstream type user:pass@host:port does the same, but uses the
136 supplied credentials for authentication.
137
138 • upstream type host:port "site_spec" turns on the upstream proxy
139 for the sites matching site_spec.
140
141 `type` can be one of `http`, `socks4`, `socks5`, `none`.
142
143 • upstream none "site_spec" turns off upstream support for sites
144 matching site_spec.
145
146 The site can be specified in various forms as a hostname, domain
147 name or as an IP range:
148
149 • name matches host exactly
150
151 • .name matches any host in domain "name"
152
153 • . matches any host with no domain (in empty domain)
154
155 • IP/bits matches network/mask
156
157 • IP/mask matches network/mask
158
159 MaxClients
160 Tinyproxy creates one child process for each connected client. This
161 options specifies the absolute highest number processes that will
162 be created. With other words, only MaxClients clients can be
163 connected to Tinyproxy simultaneously.
164
165 MinSpareServers, MaxSpareServers
166 Tinyproxy always keeps a certain number of idle child processes so
167 that it can handle new incoming client requests quickly.
168 MinSpareServer and MaxSpareServers control the lower and upper
169 limits for the number of spare processes. I.e. when the number of
170 spare servers drops below MinSpareServers then Tinyproxy will start
171 forking new spare processes in the background and when the number
172 of spare processes exceeds MaxSpareServers then Tinyproxy will kill
173 off extra processes.
174
175 StartServers
176 The number of servers to start initially. This should usually be
177 set to a value between MinSpareServers and MaxSpareServers.
178
179 MaxRequestsPerChild
180 This limits the number of connections that a child process will
181 handle before it is killed. The default value is 0 which disables
182 this feature. This option is meant as an emergency measure in the
183 case of problems with memory leakage. In that case, setting
184 MaxRequestsPerChild to a value of e.g. 1000, or 10000 can be
185 useful.
186
187 Allow, Deny
188 The Allow and Deny options provide a means to customize which
189 clients are allowed to access Tinyproxy. Allow and Deny lines can
190 be specified multiple times to build the access control list for
191 Tinyproxy. The order in the config file is important. If there are
192 no Allow or Deny lines, then all clients are allowed. Otherwise,
193 the default action is to deny access. The argument to Allow or Deny
194 can be a single IP address of a client host, like 127.0.0.1, an IP
195 address range, like 192.168.0.1/24 or a string that will be matched
196 against the end of the client host name, i.e, this can be a full
197 host name like host.example.com or a domain name like .example.com
198 or even a top level domain name like .com.
199
200 AddHeader
201 Configure one or more HTTP request headers to be added to outgoing
202 HTTP requests that Tinyproxy makes. Note that this option will not
203 work for HTTPS traffic, as Tinyproxy has no control over what
204 headers are exchanged.
205
206 AddHeader "X-My-Header" "Powered by Tinyproxy"
207
208 ViaProxyName
209 RFC 2616 requires proxies to add a Via header to the HTTP requests,
210 but using the real host name can be a security concern. If the
211 ViaProxyname option is present, then its string value will be used
212 as the host name in the Via header. Otherwise, the server’s host
213 name will be used.
214
215 DisableViaHeader
216 When this is set to yes, Tinyproxy does NOT add the Via header to
217 the requests. This virtually puts Tinyproxy into stealth mode. Note
218 that RFC 2616 requires proxies to set the Via header, so by
219 enabling this option, you break compliance. Don’t disable the Via
220 header unless you know what you are doing...
221
222 Filter
223 Tinyproxy supports filtering of web sites based on URLs or domains.
224 This option specifies the location of the file containing the
225 filter rules, one rule per line.
226
227 FilterURLs
228 If this boolean option is set to Yes or On, filtering is performed
229 for URLs rather than for domains. The default is to filter based on
230 domains.
231
232 FilterExtended
233 If this boolean option is set to Yes, then extended POSIX regular
234 expressions are used for matching the filter rules. The default is
235 to use basic POSIX regular expressions.
236
237 FilterCaseSensitive
238 If this boolean option is set to Yes, then the filter rules are
239 matched in a case sensitive manner. The default is to match
240 case-insensitively.
241
242 FilterDefaultDeny
243 The default filtering policy is to allow everything that is not
244 matched by a filtering rule. Setting FilterDefaultDeny to Yes
245 changes the policy do deny everything but the domains or URLs
246 matched by the filtering rules.
247
248 Anonymous
249 If an Anonymous keyword is present, then anonymous proxying is
250 enabled. The headers listed with Anonymous are allowed through,
251 while all others are denied. If no Anonymous keyword is present,
252 then all headers are allowed through. You must include quotes
253 around the headers.
254
255 Most sites require cookies to be enabled for them to work
256 correctly, so you will need to allow cookies through if you access
257 those sites.
258
259 Example:
260
261 Anonymous "Host"
262 Anonymous "Authorization"
263 Anonymous "Cookie"
264
265 ConnectPort
266 This option can be used to specify the ports allowed for the
267 CONNECT method. If no ConnectPort line is found, then all ports are
268 allowed. To disable CONNECT altogether, include a single
269 ConnectPort line with a value of 0.
270
271 ReversePath
272 Configure one or more ReversePath directives to enable reverse
273 proxy support. With reverse proxying it’s possible to make a number
274 of sites appear as if they were part of a single site.
275
276 If you uncomment the following two directives and run Tinyproxy on
277 your own computer at port 8888, you can access example.com, using
278 http://localhost:8888/example/.
279
280 ReversePath "/example/" "http://www.example.com/"
281
282 ReverseOnly
283 When using Tinyproxy as a reverse proxy, it is STRONGLY recommended
284 that the normal proxy is turned off by setting this boolean option
285 to Yes.
286
287 ReverseMagic
288 Setting this option to Yes, makes Tinyproxy use a cookie to track
289 reverse proxy mappings. If you need to reverse proxy sites which
290 have absolute links you must use this option.
291
292 ReverseBaseURL
293 The URL that is used to access this reverse proxy. The URL is used
294 to rewrite HTTP redirects so that they won’t escape the proxy. If
295 you have a chain of reverse proxies, you’ll need to put the
296 outermost URL here (the address which the end user types into
297 his/her browser). If this option is not set then no rewriting of
298 redirects occurs.
299
301 To report bugs in Tinyproxy, please visit
302 <https://tinyproxy.github.io/>.
303
305 tinyproxy(8)
306
308 This manpage was written by the Tinyproxy project team.
309
311 Copyright (c) 1998-2018 the Tinyproxy authors.
312
313 This program is distributed under the terms of the GNU General Public
314 License version 2 or above. See the COPYING file for additional
315 information.
316
317
318
319Version 1.10.0 07/23/2021 TINYPROXY.CONF(5)