path: root/docs/man5/tinyproxy.conf.txt.in

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*::
*No Upstream*::

    This option allows you to set up a set of rules for deciding
    whether an upstream a 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. There are three possible forms for
    specifying upstream rules:

    * 'upstream host:port' turns proxy upstream support on generally.

    * 'upstream host:port "site_spec"' turns on the upstream proxy for
    the sites matching `site_spec`.

    * 'no upstream "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://www.banu.com/tinyproxy/support/[https://www.banu.com/tinyproxy/support/]>.


SEE ALSO
--------
tinyproxy(8)


AUTHOR
------

Written by the Tinyproxy project team.


COPYRIGHT
---------

Copyright (c) 1998-2000 Steven Young;
Copyright (c) 2000-2001 Robert James Kaes;
Copyright (c) 2009-2010 Mukund Sivaraman;
Copyright (c) 2009-2010 Michael Adam.

This program is distributed under the terms of the GNU General Public
License version 2 or above. See the COPYING file for additional
information.