Incorporated patches from Marc Silver to improve the readability and

understandability of the documentation.

1 files changed, 86 insertions, 61 deletions

diff --git a/doc/tinyproxy.conf b/doc/tinyproxy.conf
index a06bd51..981cd26 100644
--- a/doc/tinyproxy.conf
+++ b/doc/tinyproxy.conf
@@ -3,32 +3,39 @@
 ##
 
 #
-# Name of the user the tinyproxy daemon should switch to after the port
-# has been bound.
+# User/Group: This allows you to set the username and group that will be
+# used for tinyproxy after the initial binding to the port has been done
+# as the root user.  
 #
-User nobody
+# Please note that you may not use UID/GID's here.  
+#
+User nobody 
 Group nogroup
 
 #
-# Port to listen on.
+# Port: Specify the port which tinyproxy will listen on.  Please note
+# that should you choose to run on a port lower than 1024 you will need
+# to start tinyproxy using root.
 #
 Port 8888
 
 #
-# If you have multiple interfaces this allows you to bind to only one. If
-# this is commented out, tinyproxy will bind to all interfaces present.
+# Listen: If you have multiple interfaces this allows you to bind to
+# only one. If this is commented out, tinyproxy will bind to all
+# interfaces present.
 #
 #Listen 192.168.0.1
 
 #
-# The Bind directive allows you to bind the outgoing connections to a
-# particular IP address.
+# Bind: This allows you to specify which interface will be used for
+# outgoing connections.  This is useful for multi-home'd machines where
+# you want all traffic to appear outgoing from one particular interface.
 #
 #Bind 192.168.0.1
 
 #
-# Timeout: The number of seconds of inactivity a connection is allowed to
-# have before it closed by tinyproxy.
+# Timeout: The maximum number of seconds of inactivity a connection is
+# allowed to have before it is closed by tinyproxy.
 #
 Timeout 600
 
@@ -40,11 +47,11 @@ Timeout 600
 #   /usr/share/tinyproxy
 #   /etc/tinyproxy
 #
-# ErrorFile 404 "/usr/share/tinyproxy/404.html"
-# ErrorFile 400 "/usr/share/tinyproxy/400.html"
-# ErrorFile 503 "/usr/share/tinyproxy/503.html"
-# ErrorFile 403 "/usr/share/tinyproxy/403.html"
-# ErrorFile 408 "/usr/share/tinyproxy/408.html"
+#ErrorFile 404 "/usr/share/tinyproxy/404.html"
+#ErrorFile 400 "/usr/share/tinyproxy/400.html"
+#ErrorFile 503 "/usr/share/tinyproxy/503.html"
+#ErrorFile 403 "/usr/share/tinyproxy/403.html"
+#ErrorFile 408 "/usr/share/tinyproxy/408.html"
 
 # 
 # DefaultErrorFile: The HTML file that gets sent if there is no
@@ -61,13 +68,23 @@ DefaultErrorFile "/usr/share/tinyproxy/default.html"
 StatFile "/usr/share/tinyproxy/stats.html"
 
 #
-# Where to log the information. Either LogFile or Syslog should be set,
-# but not both.
+# Logfile: Allows you to specify the location where information should
+# be logged to.  If you would prefer to log to syslog, then disable this
+# and enable the Syslog directive.  These directives are mutually
+# exclusive.
 #
 Logfile "/var/log/tinyproxy.log"
-# Syslog On
 
 #
+# Syslog: Tell tinyproxy to use syslog instead of a logfile.  This
+# option must not be enabled if the Logfile directive is being used.
+# These two directives are mutually exclusive.
+#
+#Syslog On
+
+#
+# LogLevel: 
+#
 # Set the logging level. Allowed settings are:
 #	Critical	(least verbose)
 #	Error
@@ -75,9 +92,10 @@ Logfile "/var/log/tinyproxy.log"
 #	Notice
 #	Connect		(to log connections without Info's noise)
 #	Info		(most verbose)
-# The LogLevel logs from the set level and above. For example, if the LogLevel
-# was set to Warning, than all log messages from Warning to Critical would be
-# output, but Notice and below would be suppressed.
+#
+# The LogLevel logs from the set level and above. For example, if the
+# LogLevel was set to Warning, than all log messages from Warning to
+# Critical would be output, but Notice and below would be suppressed.
 #
 LogLevel Info
 
@@ -88,12 +106,14 @@ LogLevel Info
 PidFile "/var/run/tinyproxy.pid"
 
 #
-# Include the X-Tinyproxy header, which has the client's IP address when
-# connecting to the sites listed.
+# XTinyproxy: Include the X-Tinyproxy header, which has the client's IP
+# address when connecting to the sites listed.
 #
 #XTinyproxy mydomain.com
 
 #
+# Upstream:
+#
 # Turns on upstream proxy support.
 #
 # The upstream rules allow you to selectively route upstream connections
@@ -130,88 +150,93 @@ PidFile "/var/run/tinyproxy.pid"
 #Upstream some.remote.proxy:port
 
 #
-# This is the absolute highest number of threads which will be created. In
-# other words, only MaxClients number of clients can be connected at the
-# same time.
+# MaxClients: This is the absolute highest number of threads which will
+# be created. In other words, only MaxClients number of clients can be
+# connected at the same time.
 #
 MaxClients 100
 
 #
-# These settings set the upper and lower limit for the number of
-# spare servers which should be available. If the number of spare servers
-# falls below MinSpareServers then new ones will be created. If the number
-# of servers exceeds MaxSpareServers then the extras will be killed off.
+# MinSpareServers/MaxSpareServers: These settings set the upper and
+# lower limit for the number of spare servers which should be available.
+#
+# If the number of spare servers falls below MinSpareServers then new
+# server processes will be spawned.  If the number of servers exceeds
+# MaxSpareServers then the extras will be killed off.
 #
 MinSpareServers 5
 MaxSpareServers 20
 
 #
-# Number of servers to start initially.
+# StartServers: The number of servers to start initially.
 #
 StartServers 10
 
 #
-# MaxRequestsPerChild is the number of connections a thread will handle
-# before it is killed. In practise this should be set to 0, which disables
-# thread reaping. If you do notice problems with memory leakage, then set
-# this to something like 10000
+# MaxRequestsPerChild: The number of connections a thread will handle
+# before it is killed. In practise this should be set to 0, which
+# disables thread reaping. If you do notice problems with memory
+# leakage, then set this to something like 10000.
 #
 MaxRequestsPerChild 0
 
 #
-# The following is the authorization controls. If there are any access
-# control keywords then the default action is to DENY. Otherwise, the
-# default action is ALLOW.
+# Allow: Customization of authorization controls. If there are any
+# access control keywords then the default action is to DENY. Otherwise,
+# the default action is ALLOW.
 #
-# Also the order of the controls are important. The incoming connections
-# are tested against the controls based on order.
+# The order of the controls are important. All incoming connections are
+# tested against the controls based on order.
 #
 Allow 127.0.0.1
 Allow 192.168.1.0/25
 
 #
-# The "Via" header is required by the HTTP RFC, but using the real host name
-# is a security concern.  If the following directive is enabled, the string
-# supplied will be used as the host name in the Via header; otherwise, the
-# server's host name will be used.
+# ViaProxyName: The "Via" header is required by the HTTP RFC, but using
+# the real host name is a security concern.  If the following directive
+# is enabled, the string supplied will be used as the host name in the
+# Via header; otherwise, the server's host name will be used.
 #
 ViaProxyName "tinyproxy"
 
 #
-# The location of the filter file.
+# Filter: This allows you to specify the location of the filter file.
 #
 #Filter "/etc/tinyproxy/filter"
 
 #
-# Filter based on URLs rather than domains.
+# FilterURLs: Filter based on URLs rather than domains.
 #
 #FilterURLs On
 
 #
-# Use POSIX Extended regular expressions rather than basic.
+# FilterExtended: Use POSIX Extended regular expressions rather than
+# basic.
 #
 #FilterExtended On
 
 #
-# Use case sensitive regular expressions.
+# FilterCaseSensitive: Use case sensitive regular expressions.
 #                                                                         
 #FilterCaseSensitive On     
 
 #
-# Change the default policy of the filtering system.  If this directive is
-# commented out, or is set to "No" then the default policy is to allow
-# everything which is not specifically denied by the filter file.
+# FilterDefaultDeny: Change the default policy of the filtering system.
+# If this directive is commented out, or is set to "No" then the default
+# policy is to allow everything which is not specifically denied by the
+# filter file.
 #
-# However, by setting this directive to "Yes" the default policy becomes to
-# deny everything which is _not_ specifically allowed by the filter file.
+# However, by setting this directive to "Yes" the default policy becomes
+# to deny everything which is _not_ specifically allowed by the filter
+# file.
 #
 #FilterDefaultDeny Yes
 
 #
-# If an Anonymous keyword is present, then anonymous proxying is enabled.
-# The headers listed are allowed through, while all others are denied. If
-# no Anonymous keyword is present, then all header are allowed through.
-# You must include quotes around the headers.
+# Anonymous: If an Anonymous keyword is present, then anonymous proxying
+# is enabled.  The headers listed 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.
@@ -221,10 +246,10 @@ ViaProxyName "tinyproxy"
 #Anonymous "Cookie"
 
 #
-# This is a list of ports allowed by tinyproxy when the CONNECT method
-# is used.  To disable the CONNECT method altogether, set the value to 0.
-# If no ConnectPort line is found, all ports are allowed (which is not
-# very secure.)
+# ConnectPort: This is a list of ports allowed by tinyproxy when the
+# CONNECT method is used.  To disable the CONNECT method altogether, set
+# the value to 0.  If no ConnectPort line is found, all ports are
+# allowed (which is not very secure.)
 #
 # The following two ports are used by SSL.
 #