Ubuntu Manpage: tinyproxy.conf - Tinyproxy HTTP proxy daemon configuration file

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. Some string values must be enclosed in double quotes (") as noted below.

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. This
parameter may be specified multiple times, then Tinyproxy will try all the specified addresses in
order.

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. Enclose the file location in
double quotes.

DefaultErrorFile
The HTML template file returned when an error occurs for which no specific error file has been set.
Enclose in double quotes.

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.stats`.

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 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
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.

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
The location of the file where the main Tinyproxy process stores its process ID for signaling
purposes. Enclose in double quotes.

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`, that means
the connection is done directly.

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:

• 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

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"`

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.

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`. 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.

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

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. Enclose in
double quotes.

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.

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

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.

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.

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.

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.

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.

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"

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/>.

AUTHOR

       This manpage was written by the Tinyproxy project team.

COPYRIGHT