diff options
Diffstat (limited to 'docs/man5')
| -rw-r--r-- | docs/man5/Makefile.am | 22 | ||||
| -rw-r--r-- | docs/man5/tinyproxy.conf.txt.in | 586 |
2 files changed, 317 insertions, 291 deletions
diff --git a/docs/man5/Makefile.am b/docs/man5/Makefile.am index 247b7ef..31b8ddf 100644 --- a/docs/man5/Makefile.am +++ b/docs/man5/Makefile.am @@ -1,25 +1,25 @@ +if HAVE_MANPAGE_INTEREST MAN5_FILES = \ tinyproxy.conf.txt - -if HAVE_XMLLINT -A2X_ARGS = -d manpage -f manpage -else -A2X_ARGS = -d manpage -f manpage -L endif +M_SECTION=5 +M_NAME=TINYPROXY.CONF + man_MANS = \ $(MAN5_FILES:.txt=.5) .txt.5: -if HAVE_A2X - $(AM_V_GEN) $(A2X) $(A2X_ARGS) $< +if HAVE_POD2MAN + $(AM_V_GEN) $(POD2MAN) --center="Tinyproxy manual" \ + --section=$(M_SECTION) --name=$(M_NAME) --release="Version @VERSION@" \ + $< > $@ else - @echo "*** a2x (asciidoc) is required to regenerate $(@) ***"; exit 1; + @echo "*** pod2man is required to regenerate $(@) ***"; exit 1; endif -CLEANFILES = \ - $(MAN5_FILES:.txt=.5) \ - $(MAN5_FILES:.txt=.xml) +MAINTAINERCLEANFILES = \ + $(MAN5_FILES:.txt=.5) EXTRA_DIST = \ $(MAN5_FILES:.txt=.5) diff --git a/docs/man5/tinyproxy.conf.txt.in b/docs/man5/tinyproxy.conf.txt.in index b3b94ec..0629a9a 100644 --- a/docs/man5/tinyproxy.conf.txt.in +++ b/docs/man5/tinyproxy.conf.txt.in @@ -1,24 +1,20 @@ -TINYPROXY.CONF(5) -================= -:man source: Version @VERSION@ -:man manual: Tinyproxy manual +=pod -NAME ----- +=encoding utf8 + +=head1 NAME tinyproxy.conf - Tinyproxy HTTP proxy daemon configuration file -SYNOPSIS --------- +=head1 SYNOPSIS -*tinyproxy.conf* +B<tinyproxy.conf> -DESCRIPTION ------------ +=head1 DESCRIPTION -`tinyproxy(8)` reads its configuration file, typically stored in +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. @@ -31,341 +27,371 @@ contain spaces. The possible keywords and their descriptions are as follows: -*User*:: +=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. +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. + +=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> - 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. +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. -*Group*:: +=item B<LogLevel> - 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. +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: -*Port*:: +=over 4 - 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 * Critical (least verbose) -*Listen*:: +=item * Error - 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 * Warning -*Bind*:: +=item * Notice - This allows you to specify which address Tinyproxy will bind - to for outgoing connections to web servers or upstream proxies. +=item * Connect (log connections without Info's noise) -*BindSame*:: +=item * Info (most verbose) - 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. +=back -*Timeout*:: +=item B<PidFile> - The maximum number of seconds of inactivity a connection is - allowed to have before it is closed by Tinyproxy. +This option controls the location of the file where the main +Tinyproxy process stores its process ID for signaling purposes. -*ErrorFile*:: +=item B<XTinyproxy> - 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. +Setting this option to `Yes` tells Tinyproxy to add a header +`X-Tinyproxy` containing the client's IP address to the request. -*DefaultErrorFile*:: +=item B<Upstream> - This parameter controls the HTML template file returned when an - error occurs for which no specific error file has been set. +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: -*StatHost*:: +=over 4 - 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 * I<upstream type host:port> turns proxy upstream support on generally. -*StatFile*:: +=item * I<upstream type user:pass@host:port> +does the same, but uses the supplied credentials for authentication. - 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. +=item * I<upstream type host:port "site_spec"> +turns on the upstream proxy for the sites matching `site_spec`. -*LogFile*:: +`type` can be one of `http`, `socks4`, `socks5`, `none`. - 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 * I<upstream none "site_spec"> +turns off upstream support for sites matching `site_spec`, that means the +connection is done directly. -*Syslog*:: +=back - 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. +The site can be specified in various forms as a hostname, domain +name or as an IP range: -*LogLevel*:: +=over 4 - 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: +=item * I<name> matches host exactly - * Critical (least verbose) - * Error - * Warning - * Notice - * Connect (log connections without Info's noise) - * Info (most verbose) +=item * I<.name> matches any host in domain "name" -*PidFile*:: +=item * I<.> matches any host with no domain (in 'empty' domain) - This option controls the location of the file where the main - Tinyproxy process stores its process ID for signaling purposes. +=item * I<IP/bits> matches network/mask -*XTinyproxy*:: +=item * I<IP/mask> matches network/mask - Setting this option to `Yes` tells Tinyproxy to add a header - `X-Tinyproxy` containing the client's IP address to the request. +=back -*Upstream*:: +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"` - 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: +=item B<MaxClients> - * 'upstream type host:port' turns proxy upstream support on generally. +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. - * 'upstream type user:pass@host:port' does the same, but uses the - supplied credentials for authentication. +=item B<Allow> - * 'upstream type host:port "site_spec"' turns on the upstream proxy - for the sites matching `site_spec`. +=item B<Deny> - `type` can be one of `http`, `socks4`, `socks5`, `none`. +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. - * 'upstream none "site_spec"' turns off upstream support for sites - matching `site_spec`. +=item B<BasicAuth> - The site can be specified in various forms as a hostname, domain - name or as an IP range: +Configure HTTP "Basic Authentication" username and password +for accessing the proxy. If there are any entries specified, +access is only granted for authenticated users. - * '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 + BasicAuth user password -*MaxClients*:: +=item B<AddHeader> - 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. +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. -*MinSpareServers*:: -*MaxSpareServers*:: + AddHeader "X-My-Header" "Powered by Tinyproxy" - 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. +=item B<ViaProxyName> -*Allow*:: -*Deny*:: +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. - 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*:: +=item B<DisableViaHeader> - 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/" ----- +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... -*ReverseOnly*:: +=item B<Filter> - 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*:: +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. - 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. +Rules are specified as POSIX basic regular expressions (BRE), unless +FilterExtended is activated. +Comment lines start with a `#` character. -*ReverseBaseURL*:: +Example filter file contents: - 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. + # 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> -BUGS ----- +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 -<https://tinyproxy.github.io/[https://tinyproxy.github.io/]>. +L<https://tinyproxy.github.io/>. + +=head1 SEE ALSO -SEE ALSO --------- -tinyproxy(8) +L<tinyproxy(8)> -AUTHOR ------- +=head1 AUTHOR This manpage was written by the Tinyproxy project team. -COPYRIGHT ---------- +=head1 COPYRIGHT -Copyright (c) 1998-2018 the Tinyproxy authors. +Copyright (c) 1998-2020 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. + |