.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "TINYPROXY.CONF 5"
.TH TINYPROXY.CONF 5 "2022-05-27" "Version 1.11.1" "Tinyproxy manual"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
tinyproxy.conf \- Tinyproxy HTTP proxy daemon configuration file
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBtinyproxy.conf\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBtinyproxy\fR\|(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.
.PP
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.
.PP
The possible keywords and their descriptions are as follows:
.IP "\fBUser\fR" 4
.IX Item "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 \s-1UID\s0 may be specified.
.IP "\fBGroup\fR" 4
.IX Item "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 \s-1GID\s0 may be specified.
.IP "\fBPort\fR" 4
.IX Item "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.
.IP "\fBListen\fR" 4
.IX Item "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.
.IP "\fBBind\fR" 4
.IX Item "Bind"
This allows you to specify which address Tinyproxy will bind
to for outgoing connections to web servers or upstream proxies.
This parameter may be specified multiple times, then Tinyproxy
will try all the specified addresses in order.
.IP "\fBBindSame\fR" 4
.IX Item "BindSame"
If this boolean parameter is set to `yes`, then Tinyproxy will
bind the outgoing connection to the \s-1IP\s0 address of the incoming
connection that triggered the outgoing request.
.IP "\fBTimeout\fR" 4
.IX Item "Timeout"
The maximum number of seconds of inactivity a connection is
allowed to have before it is closed by Tinyproxy.
.IP "\fBErrorFile\fR" 4
.IX Item "ErrorFile"
This parameter controls which \s-1HTML\s0 file Tinyproxy returns when a
given \s-1HTTP\s0 error occurs. It takes two arguments, the error number
and the location of the \s-1HTML\s0 error file.
.IP "\fBDefaultErrorFile\fR" 4
.IX Item "DefaultErrorFile"
This parameter controls the \s-1HTML\s0 template file returned when an
error occurs for which no specific error file has been set.
.IP "\fBStatHost\fR" 4
.IX Item "StatHost"
This configures the host name or \s-1IP\s0 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.stats`.
.IP "\fBStatFile\fR" 4
.IX Item "StatFile"
This configures the \s-1HTML\s0 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 \s-1STATHOST\s0 section in the \fBtinyproxy\fR\|(8) manual page
for details.
.Sp
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 \*(L"{cause}\*(R" for an abbreviated error description and
\&\*(L"{detail}\*(R" for a detailed error message.  The \fBtinyproxy\fR\|(8)
manual page contains a description of all template variables.
.IP "\fBLogFile\fR" 4
.IX Item "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.
.IP "\fBSyslog\fR" 4
.IX Item "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.
.IP "\fBLogLevel\fR" 4
.IX Item "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:
.RS 4
.IP "\(bu" 4
Critical (least verbose)
.IP "\(bu" 4
Error
.IP "\(bu" 4
Warning
.IP "\(bu" 4
Notice
.IP "\(bu" 4
Connect (log connections without Info's noise)
.IP "\(bu" 4
Info (most verbose)
.RE
.RS 4
.RE
.IP "\fBPidFile\fR" 4
.IX Item "PidFile"
This option controls the location of the file where the main
Tinyproxy process stores its process \s-1ID\s0 for signaling purposes.
.IP "\fBXTinyproxy\fR" 4
.IX Item "XTinyproxy"
Setting this option to `Yes` tells Tinyproxy to add a header
`X\-Tinyproxy` containing the client's \s-1IP\s0 address to the request.
.IP "\fBUpstream\fR" 4
.IX Item "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
\&\s-1LAST\s0 matching rule wins. The following forms for specifying upstream
rules exist:
.RS 4
.IP "\(bu" 4
\&\fIupstream type host:port\fR turns proxy upstream support on generally.
.IP "\(bu" 4
\&\fIupstream type user:pass@host:port\fR
does the same, but uses the supplied credentials for authentication.
.IP "\(bu" 4
\&\fIupstream type host:port \*(L"site_spec\*(R"\fR
turns on the upstream proxy for the sites matching `site_spec`.
.Sp
`type` can be one of `http`, `socks4`, `socks5`, `none`.
.IP "\(bu" 4
\&\fIupstream none \*(L"site_spec\*(R"\fR
turns off upstream support for sites matching `site_spec`, that means the
connection is done directly.
.RE
.RS 4
.Sp
The site can be specified in various forms as a hostname, domain
name or as an \s-1IP\s0 range:
.IP "\(bu" 4
\&\fIname\fR     matches host exactly
.IP "\(bu" 4
\&\fI.name\fR    matches any host in domain \*(L"name\*(R"
.IP "\(bu" 4
\&\fI.\fR        matches any host with no domain (in 'empty' domain)
.IP "\(bu" 4
\&\fIIP/bits\fR  matches network/mask
.IP "\(bu" 4
\&\fIIP/mask\fR  matches network/mask
.RE
.RS 4
.Sp
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 \*(L".adserver.com\*(R"`
.RE
.IP "\fBMaxClients\fR" 4
.IX Item "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.
.IP "\fBAllow\fR" 4
.IX Item "Allow"
.PD 0
.IP "\fBDeny\fR" 4
.IX Item "Deny"
.PD
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 \s-1IP\s0 address
of a client host, like `127.0.0.1`, an \s-1IP\s0 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.
.IP "\fBBasicAuth\fR" 4
.IX Item "BasicAuth"
Configure \s-1HTTP\s0 \*(L"Basic Authentication\*(R" username and password
for accessing the proxy.  If there are any entries specified,
access is only granted for authenticated users.
.Sp
.Vb 1
\&    BasicAuth user password
.Ve
.IP "\fBAddHeader\fR" 4
.IX Item "AddHeader"
Configure one or more \s-1HTTP\s0 request headers to be added to outgoing
\&\s-1HTTP\s0 requests that Tinyproxy makes. Note that this option will not
work for \s-1HTTPS\s0 traffic, as Tinyproxy has no control over what
headers are exchanged.
.Sp
.Vb 1
\&    AddHeader "X\-My\-Header" "Powered by Tinyproxy"
.Ve
.IP "\fBViaProxyName\fR" 4
.IX Item "ViaProxyName"
\&\s-1RFC 2616\s0 requires proxies to add a `Via` header to the \s-1HTTP\s0
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.
.IP "\fBDisableViaHeader\fR" 4
.IX Item "DisableViaHeader"
When this is set to yes, Tinyproxy does \s-1NOT\s0 add the `Via` header
to the requests. This virtually puts Tinyproxy into stealth mode.
Note that \s-1RFC 2616\s0 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...
.IP "\fBFilter\fR" 4
.IX Item "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.
.Sp
Rules are specified as \s-1POSIX\s0 basic regular expressions (\s-1BRE\s0), unless
another FilterType is specified.
Comment lines start with a `#` character.
.Sp
Example filter file contents:
.Sp
.Vb 2
\& # filter exactly cnn.com
\& ^cnn\e.com$
\& 
\& # filter all subdomains of cnn.com, but not cnn.com itself
\& .*\e.cnn.com$
\& 
\& # filter any domain that has cnn.com in it, like xcnn.comfy.org
\& cnn\e.com
\& 
\& # filter any domain that ends in cnn.com
\& cnn\e.com$
\& 
\& # filter any domain that starts with adserver
\& ^adserver
.Ve
.IP "\fBFilterType\fR" 4
.IX Item "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 \s-1POSIX\s0 basic regular expressions, when set to `ere`, using
\&\s-1POSIX\s0 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.
.IP "\fBFilterURLs\fR" 4
.IX Item "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.
.Sp
Note that filtering for URLs works only in plain \s-1HTTP\s0 scenarios.
Since \s-1HTTPS\s0 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.
.IP "\fBFilterExtended\fR" 4
.IX Item "FilterExtended"
Deprecated. Use `FilterType ere` instead.
If this boolean option is set to `Yes`, then extended \s-1POSIX\s0
regular expressions are used for matching the filter rules.
The default is to use basic \s-1POSIX\s0 regular expressions.
.IP "\fBFilterCaseSensitive\fR" 4
.IX Item "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.
.IP "\fBFilterDefaultDeny\fR" 4
.IX Item "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.
.IP "\fBAnonymous\fR" 4
.IX Item "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.
.Sp
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.
.Sp
Example:
.Sp
.Vb 3
\&    Anonymous "Host"
\&    Anonymous "Authorization"
\&    Anonymous "Cookie"
.Ve
.IP "\fBConnectPort\fR" 4
.IX Item "ConnectPort"
This option can be used to specify the ports allowed for the
\&\s-1CONNECT\s0 method. If no `ConnectPort` line is found, then all
ports are allowed. To disable \s-1CONNECT\s0 altogether, include a
single ConnectPort line with a value of `0`.
.IP "\fBReversePath\fR" 4
.IX Item "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.
.Sp
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/.
.Sp
.Vb 1
\&    ReversePath "/example/" "http://www.example.com/"
.Ve
.IP "\fBReverseOnly\fR" 4
.IX Item "ReverseOnly"
When using Tinyproxy as a reverse proxy, it is \s-1STRONGLY\s0
recommended that the normal proxy is turned off by setting
this boolean option to `Yes`.
.IP "\fBReverseMagic\fR" 4
.IX Item "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.
.IP "\fBReverseBaseURL\fR" 4
.IX Item "ReverseBaseURL"
The \s-1URL\s0 that is used to access this reverse proxy. The \s-1URL\s0 is
used to rewrite \s-1HTTP\s0 redirects so that they won't escape the
proxy. If you have a chain of reverse proxies, you'll need to
put the outermost \s-1URL\s0 here (the address which the end user
types into his/her browser).  If this option is not set then
no rewriting of redirects occurs.
.SH "BUGS"
.IX Header "BUGS"
To report bugs in Tinyproxy, please visit
<https://tinyproxy.github.io/>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBtinyproxy\fR\|(8)
.SH "AUTHOR"
.IX Header "AUTHOR"
This manpage was written by the Tinyproxy project team.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1998\-2020 the Tinyproxy authors.
.PP
This program is distributed under the terms of the \s-1GNU\s0 General Public
License version 2 or above. See the \s-1COPYING\s0 file for additional
information.