372 lines
12 KiB
Plaintext
372 lines
12 KiB
Plaintext
TINYPROXY.CONF(5)
|
|
=================
|
|
:man source: Version @VERSION@
|
|
:man manual: Tinyproxy manual
|
|
|
|
NAME
|
|
----
|
|
|
|
tinyproxy.conf - Tinyproxy HTTP proxy daemon configuration file
|
|
|
|
|
|
SYNOPSIS
|
|
--------
|
|
|
|
*tinyproxy.conf*
|
|
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
|
|
`tinyproxy(8)` reads its configuration file, typically stored in
|
|
`/etc/tinyproxy/tinyproxy.conf` (or passed to Tinyproxy with -c on the
|
|
command line). This manpage describes the syntax and contents of the
|
|
configuration file.
|
|
|
|
The Tinyproxy configuration file contains key-value pairs, one per
|
|
line. Lines starting with `#` and empty lines are comments and are
|
|
ignored. Keywords are case-insensitive, whereas values are
|
|
case-sensitive. Values may be enclosed in double-quotes (") if they
|
|
contain spaces.
|
|
|
|
The possible keywords and their descriptions are as follows:
|
|
|
|
*User*::
|
|
|
|
The user which the Tinyproxy process should run as, after the
|
|
initial port-binding has been done as the `root` user. Either the
|
|
user name or the UID may be specified.
|
|
|
|
*Group*::
|
|
|
|
The group which the Tinyproxy process should run as, after the
|
|
initial port-binding has been done as the `root` user. Either the
|
|
group name or the GID may be specified.
|
|
|
|
*Port*::
|
|
|
|
The port which the Tinyproxy service will listen on. If the port is
|
|
less than 1024, you will need to start the Tinyproxy process as the
|
|
`root` user.
|
|
|
|
*Listen*::
|
|
|
|
By default, Tinyproxy listens for connections on all available
|
|
interfaces (i.e. it listens on the wildcard address `0.0.0.0`).
|
|
With this configuration parameter, Tinyproxy can be told to listen
|
|
only on one specific address.
|
|
|
|
*Bind*::
|
|
|
|
This allows you to specify which address Tinyproxy will bind
|
|
to for outgoing connections to web servers or upstream proxies.
|
|
|
|
*BindSame*::
|
|
|
|
If this boolean parameter is set to `yes`, then Tinyproxy will
|
|
bind the outgoing connection to the IP address of the incoming
|
|
connection that triggered the outgoing request.
|
|
|
|
*Timeout*::
|
|
|
|
The maximum number of seconds of inactivity a connection is
|
|
allowed to have before it is closed by Tinyproxy.
|
|
|
|
*ErrorFile*::
|
|
|
|
This parameter controls which HTML file Tinyproxy returns when a
|
|
given HTTP error occurs. It takes two arguments, the error number
|
|
and the location of the HTML error file.
|
|
|
|
*DefaultErrorFile*::
|
|
|
|
This parameter controls the HTML template file returned when an
|
|
error occurs for which no specific error file has been set.
|
|
|
|
*StatHost*::
|
|
|
|
This configures the host name or IP address that is treated
|
|
as the `stat host`: Whenever a request for this host is received,
|
|
Tinyproxy will return an internal statistics page instead of
|
|
forwarding the request to that host. The template for this
|
|
page can be configured with the `StatFile` configuration option.
|
|
The default value of `StatHost` is `@TINYPROXY_STATHOST@`.
|
|
|
|
*StatFile*::
|
|
|
|
This configures the HTML file that Tinyproxy sends when
|
|
a request for the stathost is received. If this parameter is
|
|
not set, Tinyproxy returns a hard-coded basic statistics page.
|
|
See the STATHOST section in the `tinyproxy(8)` manual page
|
|
for details.
|
|
+
|
|
Note that the StatFile and the error files configured with ErrorFile
|
|
and DefaultErrorFile are template files that can contain a few
|
|
template variables that Tinyproxy expands prior to delivery.
|
|
Examples are "\{cause}" for an abbreviated error description and
|
|
"\{detail}" for a detailed error message. The `tinyproxy(8)`
|
|
manual page contains a description of all template variables.
|
|
|
|
*LogFile*::
|
|
|
|
This controls the location of the file to which Tinyproxy
|
|
writes its debug output. Alternatively, Tinyproxy can log
|
|
to syslog -- see the Syslog option.
|
|
|
|
*Syslog*::
|
|
|
|
When set to `On`, this option tells Tinyproxy to write its
|
|
debug messages to syslog instead of to a log file configured
|
|
with `LogFile`. These two options are mutually exclusive.
|
|
|
|
*LogLevel*::
|
|
|
|
Sets the log level. Messages from the set level and above are
|
|
logged. For example, if the LogLevel was set to Warning, then all
|
|
log messages from Warning to Critical would be output, but Notice
|
|
and below would be suppressed. Allowed values are:
|
|
|
|
* Critical (least verbose)
|
|
* Error
|
|
* Warning
|
|
* Notice
|
|
* Connect (log connections without Info's noise)
|
|
* Info (most verbose)
|
|
|
|
*PidFile*::
|
|
|
|
This option controls the location of the file where the main
|
|
Tinyproxy process stores its process ID for signaling purposes.
|
|
|
|
*XTinyproxy*::
|
|
|
|
Setting this option to `Yes` tells Tinyproxy to add a header
|
|
`X-Tinyproxy` containing the client's IP address to the request.
|
|
|
|
*Upstream*::
|
|
|
|
This option allows you to set up a set of rules for deciding
|
|
whether an upstream proxy server is to be used, based on the
|
|
host or domain of the site being accessed. The rules are stored
|
|
in the order encountered in the configuration file and the
|
|
LAST matching rule wins. The following forms for specifying upstream
|
|
rules exist:
|
|
|
|
* 'upstream type host:port' turns proxy upstream support on generally.
|
|
|
|
* 'upstream type user:pass@host:port' does the same, but uses the
|
|
supplied credentials for authentication.
|
|
|
|
* 'upstream type host:port "site_spec"' turns on the upstream proxy
|
|
for the sites matching `site_spec`.
|
|
|
|
`type` can be one of `http`, `socks4`, `socks5`, `none`.
|
|
|
|
* 'upstream none "site_spec"' turns off upstream support for sites
|
|
matching `site_spec`.
|
|
|
|
The site can be specified in various forms as a hostname, domain
|
|
name or as an IP range:
|
|
|
|
* 'name' matches host exactly
|
|
* '.name' matches any host in domain "name"
|
|
* '.' matches any host with no domain (in 'empty' domain)
|
|
* 'IP/bits' matches network/mask
|
|
* 'IP/mask' matches network/mask
|
|
|
|
*MaxClients*::
|
|
|
|
Tinyproxy creates one child process for each connected client.
|
|
This options specifies the absolute highest number processes that
|
|
will be created. With other words, only MaxClients clients can be
|
|
connected to Tinyproxy simultaneously.
|
|
|
|
*MinSpareServers*::
|
|
*MaxSpareServers*::
|
|
|
|
Tinyproxy always keeps a certain number of idle child processes
|
|
so that it can handle new incoming client requests quickly.
|
|
`MinSpareServer` and `MaxSpareServers` control the lower and upper
|
|
limits for the number of spare processes. I.e. when the number of
|
|
spare servers drops below `MinSpareServers` then Tinyproxy will
|
|
start forking new spare processes in the background and when the
|
|
number of spare processes exceeds `MaxSpareServers` then Tinyproxy
|
|
will kill off extra processes.
|
|
|
|
*StartServers*::
|
|
|
|
The number of servers to start initially. This should usually be
|
|
set to a value between MinSpareServers and MaxSpareServers.
|
|
|
|
*MaxRequestsPerChild*::
|
|
|
|
This limits the number of connections that a child process
|
|
will handle before it is killed. The default value is `0`
|
|
which disables this feature. This option is meant as an
|
|
emergency measure in the case of problems with memory leakage.
|
|
In that case, setting `MaxRequestsPerChild` to a value of e.g.
|
|
1000, or 10000 can be useful.
|
|
|
|
*Allow*::
|
|
*Deny*::
|
|
|
|
The `Allow` and `Deny` options provide a means to customize
|
|
which clients are allowed to access Tinyproxy. `Allow` and `Deny`
|
|
lines can be specified multiple times to build the access control
|
|
list for Tinyproxy. The order in the config file is important.
|
|
If there are no `Allow` or `Deny` lines, then all clients are
|
|
allowed. Otherwise, the default action is to deny access.
|
|
The argument to `Allow` or `Deny` can be a single IP address
|
|
of a client host, like `127.0.0.1`, an IP address range, like
|
|
`192.168.0.1/24` or a string that will be matched against the
|
|
end of the client host name, i.e, this can be a full host name
|
|
like `host.example.com` or a domain name like `.example.com` or
|
|
even a top level domain name like `.com`.
|
|
|
|
*AddHeader*::
|
|
|
|
Configure one or more HTTP request headers to be added to outgoing
|
|
HTTP requests that Tinyproxy makes. Note that this option will not
|
|
work for HTTPS traffic, as Tinyproxy has no control over what
|
|
headers are exchanged.
|
|
+
|
|
----
|
|
AddHeader "X-My-Header" "Powered by Tinyproxy"
|
|
----
|
|
|
|
*ViaProxyName*::
|
|
|
|
RFC 2616 requires proxies to add a `Via` header to the HTTP
|
|
requests, but using the real host name can be a security
|
|
concern. If the `ViaProxyname` option is present, then its
|
|
string value will be used as the host name in the Via header.
|
|
Otherwise, the server's host name will be used.
|
|
|
|
*DisableViaHeader*::
|
|
|
|
When this is set to yes, Tinyproxy does NOT add the `Via` header
|
|
to the requests. This virtually puts Tinyproxy into stealth mode.
|
|
Note that RFC 2616 requires proxies to set the `Via` header, so by
|
|
enabling this option, you break compliance.
|
|
Don't disable the `Via` header unless you know what you are doing...
|
|
|
|
*Filter*::
|
|
|
|
Tinyproxy supports filtering of web sites based on URLs or
|
|
domains. This option specifies the location of the file
|
|
containing the filter rules, one rule per line.
|
|
|
|
*FilterURLs*::
|
|
|
|
If this boolean option is set to `Yes` or `On`, filtering is
|
|
performed for URLs rather than for domains. The default is to
|
|
filter based on domains.
|
|
|
|
*FilterExtended*::
|
|
|
|
If this boolean option is set to `Yes`, then extended POSIX
|
|
regular expressions are used for matching the filter rules.
|
|
The default is to use basic POSIX regular expressions.
|
|
|
|
*FilterCaseSensitive*::
|
|
|
|
If this boolean option is set to `Yes`, then the filter rules
|
|
are matched in a case sensitive manner. The default is to
|
|
match case-insensitively.
|
|
|
|
*FilterDefaultDeny*::
|
|
|
|
The default filtering policy is to allow everything that is
|
|
not matched by a filtering rule. Setting `FilterDefaultDeny`
|
|
to `Yes` changes the policy do deny everything but the domains
|
|
or URLs matched by the filtering rules.
|
|
|
|
*Anonymous*::
|
|
|
|
If an `Anonymous` keyword is present, then anonymous proxying
|
|
is enabled. The headers listed with `Anonymous` are allowed
|
|
through, while all others are denied. If no Anonymous keyword
|
|
is present, then all headers are allowed through. You must
|
|
include quotes around the headers.
|
|
+
|
|
Most sites require cookies to be enabled for them to work correctly, so
|
|
you will need to allow cookies through if you access those sites.
|
|
+
|
|
Example:
|
|
+
|
|
----
|
|
Anonymous "Host"
|
|
Anonymous "Authorization"
|
|
Anonymous "Cookie"
|
|
----
|
|
|
|
*ConnectPort*::
|
|
|
|
This option can be used to specify the ports allowed for the
|
|
CONNECT method. If no `ConnectPort` line is found, then all
|
|
ports are allowed. To disable CONNECT altogether, include a
|
|
single ConnectPort line with a value of `0`.
|
|
|
|
*ReversePath*::
|
|
|
|
Configure one or more ReversePath directives to enable reverse proxy
|
|
support. With reverse proxying it's possible to make a number of
|
|
sites appear as if they were part of a single site.
|
|
+
|
|
If you uncomment the following two directives and run Tinyproxy
|
|
on your own computer at port 8888, you can access example.com,
|
|
using http://localhost:8888/example/.
|
|
+
|
|
----
|
|
ReversePath "/example/" "http://www.example.com/"
|
|
----
|
|
|
|
*ReverseOnly*::
|
|
|
|
When using Tinyproxy as a reverse proxy, it is STRONGLY
|
|
recommended that the normal proxy is turned off by setting
|
|
this boolean option to `Yes`.
|
|
|
|
*ReverseMagic*::
|
|
|
|
Setting this option to `Yes`, makes Tinyproxy use a cookie to
|
|
track reverse proxy mappings. If you need to reverse proxy
|
|
sites which have absolute links you must use this option.
|
|
|
|
*ReverseBaseURL*::
|
|
|
|
The URL that is used to access this reverse proxy. The URL is
|
|
used to rewrite HTTP redirects so that they won't escape the
|
|
proxy. If you have a chain of reverse proxies, you'll need to
|
|
put the outermost URL here (the address which the end user
|
|
types into his/her browser). If this option is not set then
|
|
no rewriting of redirects occurs.
|
|
|
|
|
|
BUGS
|
|
----
|
|
|
|
To report bugs in Tinyproxy, please visit
|
|
<https://tinyproxy.github.io/[https://tinyproxy.github.io/]>.
|
|
|
|
|
|
SEE ALSO
|
|
--------
|
|
tinyproxy(8)
|
|
|
|
|
|
AUTHOR
|
|
------
|
|
|
|
This manpage was written by the Tinyproxy project team.
|
|
|
|
|
|
COPYRIGHT
|
|
---------
|
|
|
|
Copyright (c) 1998-2018 the Tinyproxy authors.
|
|
|
|
This program is distributed under the terms of the GNU General Public
|
|
License version 2 or above. See the COPYING file for additional
|
|
information.
|