diff options
| -rw-r--r-- | configure.ac | 37 | ||||
| -rw-r--r-- | docs/man5/Makefile.am | 24 | ||||
| -rw-r--r-- | docs/man5/tinyproxy.conf.txt.in | 540 | ||||
| -rw-r--r-- | docs/man8/Makefile.am | 28 | ||||
| -rw-r--r-- | docs/man8/tinyproxy.txt.in | 157 |
5 files changed, 389 insertions, 397 deletions
diff --git a/configure.ac b/configure.ac index e645dc1..900af95 100644 --- a/configure.ac +++ b/configure.ac @@ -97,9 +97,9 @@ if test x"$transparent_enabled" = x"yes"; then fi dnl Let user decide whether he wants support for manpages -dnl Which require either a2x/asciidoctor or a tarball release +dnl Which require either pod2man or a tarball release AH_TEMPLATE([MANPAGE_SUPPORT], - [Build manpages with a2x/asciidoctor if they are missing from the distribution.]) + [Build manpages with pod2man if they are missing from the distribution.]) TP_ARG_ENABLE(manpage_support, [Enable support for building manpages (default is YES)], yes) @@ -183,39 +183,18 @@ AC_SUBST(LIBS) AC_SUBST(ADDITIONAL_OBJECTS) if test x"$manpage_support_enabled" = x"yes"; then -# Check for asciidoc -AC_PATH_PROG(A2X, a2x, no) -if test "x$A2X" = "xno" ; then -# Check for asciidoctor -AC_PATH_PROG(ASCIIDOCTOR, asciidoctor, no) -else -# checking xmllint, which is only used together with a2x -AC_PATH_PROG(XMLLINT, xmllint, no) -if test "x$XMLLINT" != "xno"; then - AS_ECHO_N("testing xmllint... ") - echo "TEST" > conftest.txt - if $A2X -f docbook conftest.txt 2>/dev/null; then - AS_ECHO("ok") - else - AS_ECHO("failed") - XMLLINT="no" - fi - rm -f conftest.txt conftest.xml -fi -fi #a2x installed +AC_PATH_PROG(POD2MAN, pod2man, no) -if test "x$A2X" = "xno" -a "x$ASCIIDOCTOR" = "xno" && \ +if test "x$POD2MAN" = "xno" && \ ! test -e docs/man5/tinyproxy.conf.5 -a -e docs/man8/tinyproxy.8 ; then AC_MSG_ERROR([ - manpage generation requested, but neither a2x, asciidoctor + manpage generation requested, but neither pod2man nor pre-generated manpages found. Use --disable-manpage-support if you want to compile anyway.]) fi fi #manpage_support_enabled -AM_CONDITIONAL(HAVE_A2X, test "x$A2X" != "x" -a "x$A2X" != "xno") -AM_CONDITIONAL(HAVE_XMLLINT, test "x$XMLLINT" != "x" -a "x$XMLLINT" != "xno") -AM_CONDITIONAL(HAVE_ASCIIDOCTOR, test "x$ASCIIDOCTOR" != "x" -a "x$ASCIIDOCTOR" != "xno") +AM_CONDITIONAL(HAVE_POD2MAN, test "x$POD2MAN" != "x" -a "x$POD2MAN" != "xno") AC_CONFIG_FILES([ Makefile @@ -237,12 +216,12 @@ scripts/Makefile AC_OUTPUT # the manpages are shipped in the release tarball and we don't want them to -# get regenerated if a2x is not available. the intermediate files from +# get regenerated if pod2man is not available. the intermediate files from # AC_CONFIG_FILES are created with config.status, which is created at configure # runtime, so we need to touch them after config.status terminated to prevent # make from rebuild them. -if test "x$A2X" = "xno" -a "x$ASCIIDOCTOR" = "xno" ; then +if test "x$POD2MAN" = "xno" ; then touch docs/man5/tinyproxy.conf.txt touch docs/man8/tinyproxy.txt if test -e docs/man5/tinyproxy.conf.5 ; then diff --git a/docs/man5/Makefile.am b/docs/man5/Makefile.am index 3447ad2..31b8ddf 100644 --- a/docs/man5/Makefile.am +++ b/docs/man5/Makefile.am @@ -3,33 +3,23 @@ MAN5_FILES = \ tinyproxy.conf.txt endif -if HAVE_XMLLINT -A2X_ARGS = -d manpage -f manpage -else -A2X_ARGS = -d manpage -f manpage -L -endif - -ASCIIDOCTOR_ARGS = -b manpage +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 -if HAVE_ASCIIDOCTOR - $(AM_V_GEN) $(ASCIIDOCTOR) $(ASCIIDOCTOR_ARGS) $< -else - @echo "*** a2x (asciidoc) or asciidoctor is required to regenerate $(@) ***"; exit 1; -endif + @echo "*** pod2man is required to regenerate $(@) ***"; exit 1; endif MAINTAINERCLEANFILES = \ $(MAN5_FILES:.txt=.5) -CLEANFILES = \ - $(MAN5_FILES:.txt=.xml) - EXTRA_DIST = \ $(MAN5_FILES:.txt=.5) diff --git a/docs/man5/tinyproxy.conf.txt.in b/docs/man5/tinyproxy.conf.txt.in index cf8fab5..b5619dd 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,322 +27,340 @@ 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. + +=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. - 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<Syslog> -*Group*:: +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 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<LogLevel> -*Port*:: +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: - 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. +=over 4 -*Listen*:: +=item * Critical (least verbose) - 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 * Error -*Bind*:: +=item * Warning - This allows you to specify which address Tinyproxy will bind - to for outgoing connections to web servers or upstream proxies. +=item * Notice -*BindSame*:: +=item * Connect (log connections without Info's noise) - 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 * Info (most verbose) -*Timeout*:: +=back - The maximum number of seconds of inactivity a connection is - allowed to have before it is closed by Tinyproxy. +=item B<PidFile> -*ErrorFile*:: +This option controls the location of the file where the main +Tinyproxy process stores its process ID for signaling purposes. - 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<XTinyproxy> -*DefaultErrorFile*:: +Setting this option to `Yes` tells Tinyproxy to add a header +`X-Tinyproxy` containing the client's IP address to the request. - This parameter controls the HTML template file returned when an - error occurs for which no specific error file has been set. +=item B<Upstream> -*StatHost*:: +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: - 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@`. +=over 4 -*StatFile*:: +=item * I<upstream type host:port> turns proxy upstream support on generally. - 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 user:pass@host:port> +does the same, but uses the supplied credentials for authentication. -*LogFile*:: +=item * I<upstream type host:port "site_spec"> +turns on the upstream proxy for the sites matching `site_spec`. - This controls the location of the file to which Tinyproxy - writes its debug output. Alternatively, Tinyproxy can log - to syslog -- see the Syslog option. +`type` can be one of `http`, `socks4`, `socks5`, `none`. -*Syslog*:: +=item * I<upstream none "site_spec"> +turns off upstream support for sites matching `site_spec`, that means the +connection is done directly. - 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. +=back -*LogLevel*:: +The site can be specified in various forms as a hostname, domain +name or as an IP range: - 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 - * Critical (least verbose) - * Error - * Warning - * Notice - * Connect (log connections without Info's noise) - * Info (most verbose) +=item * I<name> matches host exactly -*PidFile*:: +=item * I<.name> matches any host in domain "name" - This option controls the location of the file where the main - Tinyproxy process stores its process ID for signaling purposes. +=item * I<.> matches any host with no domain (in 'empty' domain) -*XTinyproxy*:: +=item * I<IP/bits> 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. +=item * I<IP/mask> matches network/mask -*Upstream*:: +=back - 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: +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"` - * 'upstream type host:port' turns proxy upstream support on generally. +=item B<MaxClients> - * 'upstream type user:pass@host:port' does the same, but uses the - supplied credentials for authentication. +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 host:port "site_spec"' turns on the upstream proxy - for the sites matching `site_spec`. +=item B<Allow> - `type` can be one of `http`, `socks4`, `socks5`, `none`. +=item B<Deny> - * 'upstream none "site_spec"' turns off upstream support for sites - matching `site_spec`, that means the connection is done directly. +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. - The site can be specified in various forms as a hostname, domain - name or as an IP range: +=item B<AddHeader> - * '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 +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. - 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. - -*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... + AddHeader "X-My-Header" "Powered by Tinyproxy" -*Filter*:: +=item B<ViaProxyName> - 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. +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. -*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/" ----- +=item B<DisableViaHeader> -*ReverseOnly*:: +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... - 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*:: +=item B<Filter> - 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. +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. -*ReverseBaseURL*:: +=item B<FilterURLs> - 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. +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> -BUGS ----- +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. This program is distributed under the terms of the GNU General Public License version 2 or above. See the COPYING file for additional information. + diff --git a/docs/man8/Makefile.am b/docs/man8/Makefile.am index 0d1eda1..d2d7e19 100644 --- a/docs/man8/Makefile.am +++ b/docs/man8/Makefile.am @@ -1,35 +1,25 @@ if HAVE_MANPAGE_INTEREST -MAN8_FILES = \ +MAN8_FILES = \ tinyproxy.txt endif -if HAVE_XMLLINT -A2X_ARGS = -d manpage -f manpage -else -A2X_ARGS = -d manpage -f manpage -L -endif - -ASCIIDOCTOR_ARGS = -b manpage +M_SECTION=8 +M_NAME=TINYPROXY man_MANS = \ $(MAN8_FILES:.txt=.8) .txt.8: -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 -if HAVE_ASCIIDOCTOR - $(AM_V_GEN) $(ASCIIDOCTOR) $(ASCIIDOCTOR_ARGS) $< -else - @echo "*** a2x (asciidoc) or asciidoctor is required to regenerate $(@) ***"; exit 1; -endif + @echo "*** pod2man is required to regenerate $(@) ***"; exit 1; endif MAINTAINERCLEANFILES = \ $(MAN8_FILES:.txt=.8) -CLEANFILES = \ - $(MAN8_FILES:.txt=.xml) - -EXTRA_DIST= \ +EXTRA_DIST = \ $(MAN8_FILES:.txt=.8) diff --git a/docs/man8/tinyproxy.txt.in b/docs/man8/tinyproxy.txt.in index 54da867..a7882c1 100644 --- a/docs/man8/tinyproxy.txt.in +++ b/docs/man8/tinyproxy.txt.in @@ -1,24 +1,20 @@ -TINYPROXY(8) -============ -:man source: Version @VERSION@ -:man manual: Tinyproxy manual +=pod -NAME ----- +=encoding utf8 + +=head1 NAME tinyproxy - A light-weight HTTP proxy daemon -SYNOPSIS --------- +=head1 SYNOPSIS -*tinyproxy* [-vdch] +B<tinyproxy> [-vdch] -DESCRIPTION ------------ +=head1 DESCRIPTION -*tinyproxy* is a light-weight HTTP proxy daemon designed to consume a +B<tinyproxy> is a light-weight HTTP proxy daemon designed to consume a minimum amount of system resources. It listens on a given TCP port and handles HTTP proxy requests. Designed from the ground up to be fast and yet small, it is an ideal solution for use cases such as embedded @@ -26,46 +22,59 @@ deployments where a full featured HTTP proxy is required, but the system resources for a larger proxy are unavailable. -OPTIONS -------- +=head1 OPTIONS + +B<tinyproxy> accepts the following options: + +=over 4 + +=item B<-c <config-file>> + +Use an alternate configuration file. + +=item B<-d> -*tinyproxy* accepts the following options: +Don't daemonize and stay in the foreground. Useful for debugging purposes. -*-c <config-file>*:: - Use an alternate configuration file. +=item B<-h> -*-d*:: - Don't daemonize and stay in the foreground. Useful for debugging purposes. +Display a short help screen of command line arguments and exit. -*-h*:: - Display a short help screen of command line arguments and exit. +=item B<-v> -*-v*:: - Display version information and exit. +Display version information and exit. +=back -SIGNALS -------- +=head1 SIGNALS In addition to command-line options, there are also several signals that -can be sent to *tinyproxy* while it is running to generate debugging +can be sent to B<tinyproxy> while it is running to generate debugging information and to force certain events. -*SIGHUP*:: - Force Tinyproxy to do a garbage collection on the current - connections linked list. This is usually done automatically after a - certain number of connections have been handled. +=over 4 +=item B<SIGHUP> -TEMPLATE FILES --------------- +Force Tinyproxy to do a garbage collection on the current +connections linked list. This is usually done automatically after a +certain number of connections have been handled. + +=back + +=head1 TEMPLATE FILES There are two occasions when Tinyproxy delivers HTML pages to the client on it's own right: -. When an error occurred, a corresponding error page is returned. -. When a request for the stathost is made, a page summarizing the - connection statistics is returned. (See STATHOST below.) +=over 4 + +=item * When an error occurred, a corresponding error page is returned. + +=item * When a request for the stathost is made, a page summarizing the +connection statistics is returned. (See STATHOST below.) + +=back The layout of both error pages and the statistics page can be controlled via configurable HTML template files that are plain @@ -73,46 +82,60 @@ HTML files that additionally understand a few template variables. -TEMPLATE VARIABLES ------------------- +=head1 TEMPLATE VARIABLES There are several standard HTML variables that are available in every template file: -*request*:: - The full HTTP request line. +=over 4 + +=item B<request> -*cause*:: - The abbreviated cause of the error condition. +The full HTTP request line. -*clientip*:: - The IP address of the client making the request. +=item B<cause> -*clienthost*:: - The hostname of the client making the request. +The abbreviated cause of the error condition. -*version*:: - The version of Tinyproxy. +=item B<clientip> -*package*:: - The package name. Presently, resolves to 'tinyproxy'. +The IP address of the client making the request. -*date*:: - The current date/time in HTTP format. +=item B<clienthost> + +The hostname of the client making the request. + +=item B<version> + +The version of Tinyproxy. + +=item B<package> + +The package name. Presently, resolves to 'tinyproxy'. + +=item B<date> + +The current date/time in HTTP format. + +=back In addition, almost all templates support: -*detail*:: - A detailed, plain English explanation of the error and possible - causes. +=over 4 + +=item B<detail> + +A detailed, plain English explanation of the error and possible +causes. + +=back When Tinyproxy finds a variable name enclosed in braces, e.g. -"\{request}", then this is replaced by the value of the corresponding +"{request}", then this is replaced by the value of the corresponding variable before delivery of the page. -STATHOST --------- +=head1 STATHOST Tinyproxy returns a HTML page with connection statistics when it receives a HTTP request for a certain host -- the stathost. The @@ -124,31 +147,27 @@ The stat file template can be changed at runtime through the configuration variable `StatFile`. -FILES ------ +=head1 FILES `/etc/tinyproxy/tinyproxy.conf`, `/var/run/tinyproxy/tinyproxy.pid`, `/var/log/tinyproxy/tinyproxy.log` -BUGS ----- +=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.conf(5) +L<tinyproxy.conf(5)> -AUTHOR ------- +=head1 AUTHOR This manpage was written by the Tinyproxy project team. -COPYRIGHT ---------- +=head1 COPYRIGHT Copyright (c) 1998-2018 the Tinyproxy authors. |