441 lines
14 KiB
Plaintext
441 lines
14 KiB
Plaintext
=pod
|
|
|
|
=encoding utf8
|
|
|
|
=head1 NAME
|
|
|
|
tinyproxy.conf - Tinyproxy HTTP proxy daemon configuration file
|
|
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<tinyproxy.conf>
|
|
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
L<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. Some string values must be enclosed in double
|
|
quotes (") as noted below.
|
|
|
|
The possible keywords and their descriptions are as follows:
|
|
|
|
=over 4
|
|
|
|
=item B<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.
|
|
|
|
=item B<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.
|
|
|
|
=item B<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.
|
|
|
|
=item B<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.
|
|
|
|
=item B<Bind>
|
|
|
|
This allows you to specify which address Tinyproxy will bind
|
|
to for outgoing connections.
|
|
This parameter may be specified multiple times, then Tinyproxy
|
|
will try all the specified addresses in order.
|
|
|
|
=item B<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.
|
|
|
|
=item B<Timeout>
|
|
|
|
The maximum number of seconds of inactivity a connection is
|
|
allowed to have before it is closed by Tinyproxy.
|
|
|
|
=item B<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. Enclose the file location
|
|
in double quotes.
|
|
|
|
=item B<DefaultErrorFile>
|
|
|
|
The HTML template file returned when an error occurs for which no
|
|
specific error file has been set. Enclose in double quotes.
|
|
|
|
=item B<StatHost>
|
|
|
|
The host name or IP address that is treated as the `stat host`.
|
|
Enclose in double quotes. Whenever Tinyproxy receives a request for
|
|
the `stat host` it returns 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@`.
|
|
|
|
=item B<StatFile>
|
|
|
|
The HTML file that Tinyproxy sends in response to a request for the
|
|
`stat host`. Enclose in double quotes. If this parameter is not set,
|
|
Tinyproxy returns a hard-coded basic statistics page. See the STATHOST
|
|
section in the L<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 L<tinyproxy(8)>
|
|
manual page contains a description of all template variables.
|
|
|
|
=item B<LogFile>
|
|
|
|
The location of the file to which Tinyproxy writes its debug output.
|
|
Enclose in double quotes. Alternatively, Tinyproxy can log to syslog
|
|
-- see the Syslog option.
|
|
|
|
=item B<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.
|
|
|
|
=item B<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:
|
|
|
|
=over 4
|
|
|
|
=item * Critical (least verbose)
|
|
|
|
=item * Error
|
|
|
|
=item * Warning
|
|
|
|
=item * Notice
|
|
|
|
=item * Connect (log connections without Info's noise)
|
|
|
|
=item * Info (most verbose)
|
|
|
|
=back
|
|
|
|
=item B<PidFile>
|
|
|
|
The location of the file where the main Tinyproxy process stores its
|
|
process ID for signaling purposes. Enclose in double quotes.
|
|
|
|
=item B<XTinyproxy>
|
|
|
|
Setting this option to `Yes` tells Tinyproxy to add a header
|
|
`X-Tinyproxy` containing the client's IP address to the request.
|
|
|
|
=item B<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:
|
|
|
|
=over 4
|
|
|
|
=item * I<upstream type host:port> turns proxy upstream support on generally.
|
|
|
|
=item * I<upstream type user:pass@host:port>
|
|
does the same, but uses the supplied credentials for authentication.
|
|
|
|
=item * I<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`.
|
|
|
|
a `site_spec` is either a full domain name, a domain name starting with a
|
|
`.`, in which case it is treated as a suffix, or an ip/mask tuple.
|
|
the `site_spec` needs to be double-quoted.
|
|
|
|
=item * I<upstream none "site_spec">
|
|
turns off upstream support for sites matching `site_spec`, that means the
|
|
connection is done directly.
|
|
|
|
=back
|
|
|
|
It's recommended to use raw IP addresses to specify the upstream host, so
|
|
no costly DNS lookup has to be done everytime it is used.
|
|
IPv6 addresses need to be enclosed in square brackets.
|
|
|
|
The site can be specified in various forms as a hostname, domain
|
|
name or as an IP range:
|
|
|
|
=over 4
|
|
|
|
=item * I<name> matches host exactly
|
|
|
|
=item * I<.name> matches any host in domain "name"
|
|
|
|
=item * I<.> matches any host with no domain (in 'empty' domain)
|
|
|
|
=item * I<IP/bits> matches network/mask
|
|
|
|
=item * I<IP/mask> matches network/mask
|
|
|
|
=back
|
|
|
|
Note that the upstream directive can also be used to null-route
|
|
a specific target domain/host, e.g.:
|
|
`upstream http 0.0.0.0:0 ".adserver.com"`
|
|
|
|
=item B<MaxClients>
|
|
|
|
Tinyproxy creates one thread 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.
|
|
|
|
=item B<Allow>
|
|
|
|
=item B<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`.
|
|
Note that by adding a rule using a host or domain name, a costly name
|
|
lookup has to be done for every new connection, which could slow down
|
|
the service considerably.
|
|
|
|
=item B<BasicAuth>
|
|
|
|
Configure HTTP "Basic Authentication" username and password
|
|
for accessing the proxy. If there are any entries specified,
|
|
access is only granted for authenticated users.
|
|
|
|
BasicAuth user password
|
|
|
|
=item B<BasicAuthRealm>
|
|
|
|
In case "BasicAuth" is configured, the "realm" information.
|
|
"Proxy Authentication Required" status http 407 "error-response" can be
|
|
customized.
|
|
|
|
- defaults in code to "Tinyproxy" (PACKAGE_NAME), if not configured.
|
|
|
|
=item B<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"
|
|
|
|
=item B<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. Enclose in double
|
|
quotes.
|
|
|
|
=item B<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...
|
|
|
|
=item B<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.
|
|
|
|
Rules are specified as POSIX basic regular expressions (BRE), unless
|
|
another FilterType is specified.
|
|
Comment lines start with a `#` character.
|
|
|
|
Example filter file contents:
|
|
|
|
# filter exactly cnn.com
|
|
^cnn\.com$
|
|
|
|
# filter all subdomains of cnn.com, but not cnn.com itself
|
|
.*\.cnn.com$
|
|
|
|
# filter any domain that has cnn.com in it, like xcnn.comfy.org
|
|
cnn\.com
|
|
|
|
# filter any domain that ends in cnn.com
|
|
cnn\.com$
|
|
|
|
# filter any domain that starts with adserver
|
|
^adserver
|
|
|
|
=item B<FilterType>
|
|
|
|
This option can be set to one of `bre`, `ere`, or `fnmatch`.
|
|
If `bre` is set, the rules specified in the filter file are matched
|
|
using POSIX basic regular expressions, when set to `ere`, using
|
|
POSIX extended regular expressions, and when set to `fnmatch` using
|
|
the `fnmatch` function as specified in the manpage `man 3p fnmatch`.
|
|
`fnmatch` matching is identical to what's used in the shell to match
|
|
filenames, so for example `*.google.com` matches everything that
|
|
ends with `.google.com`.
|
|
If you don't know what regular expressions are or you're using filter
|
|
lists from 3rd party sources, `fnmatch` is probably what you want.
|
|
It's also the fastest matching method of the three.
|
|
|
|
=item B<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.
|
|
|
|
Note that filtering for URLs works only in plain HTTP scenarios.
|
|
Since HTTPS has become ubiquitous during the last years, this
|
|
will only work on a tiny fraction of websites, so it is
|
|
recommended not to use this option.
|
|
|
|
=item B<FilterExtended>
|
|
|
|
Deprecated. Use `FilterType ere` instead.
|
|
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.
|
|
|
|
=item B<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, unfortunately.
|
|
If you set this to `Yes`, then your matching will be almost
|
|
twice as fast.
|
|
This setting affects only `bre` and `ere` FilterTypes, fnmatch
|
|
is always case sensitive.
|
|
|
|
=item B<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.
|
|
In other words, if set to `No` the Filter list acts as a
|
|
blacklist, if set to `Yes` as a whitelist.
|
|
|
|
=item B<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 double 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"
|
|
|
|
=item B<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`.
|
|
|
|
=item B<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/"
|
|
|
|
=item B<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`.
|
|
|
|
=item B<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.
|
|
|
|
=item B<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.
|
|
|
|
=back
|
|
|
|
=head1 BUGS
|
|
|
|
To report bugs in Tinyproxy, please visit
|
|
L<https://tinyproxy.github.io/>.
|
|
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<tinyproxy(8)>
|
|
|
|
|
|
=head1 AUTHOR
|
|
|
|
This manpage was written by the Tinyproxy project team.
|
|
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright (c) 1998-2024 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.
|
|
|