c4dc3ba007
the file docs/filter-howto.txt was removed, as it contained misleading information since it was first checked in. it suggests the syntax for filter rules is fnmatch()-like, when in fact they need to be specified as posix regular expressions. additionally it contained a lot of utterly unrelated and irrelevant/ outdated text. a few examples with the correct syntax have now been added to tinyproxy.conf.5 manpage. closes #212
388 lines
12 KiB
Plaintext
388 lines
12 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. Values may be enclosed in double-quotes (") if they
|
|
contain spaces.
|
|
|
|
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 to web servers or upstream proxies.
|
|
|
|
=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.
|
|
|
|
=item B<DefaultErrorFile>
|
|
|
|
This parameter controls the HTML template file returned when an
|
|
error occurs for which no specific error file has been set.
|
|
|
|
=item B<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@`.
|
|
|
|
=item B<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 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>
|
|
|
|
This controls the location of the file to which Tinyproxy
|
|
writes its debug output. 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>
|
|
|
|
This option controls the location of the file where the main
|
|
Tinyproxy process stores its process ID for signaling purposes.
|
|
|
|
=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`.
|
|
|
|
=item * I<upstream none "site_spec">
|
|
turns off upstream support for sites matching `site_spec`, that means the
|
|
connection is done directly.
|
|
|
|
=back
|
|
|
|
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<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.
|
|
|
|
=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
|
|
FilterExtended is activated.
|
|
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<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.
|
|
|
|
=item B<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.
|
|
|
|
=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.
|
|
|
|
=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.
|
|
|
|
=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 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-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.
|
|
|