"Fossies" - the Fresh Open Source Software Archive

Member "httpbl/mod_httpbl_for_apache_2.0/mod_httpbl_manual/mod_httpbl.xml" (15 May 2007, 43371 Bytes) of package /linux/www/apache_httpd_modules/old/mod_httpbl.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <?xml version="1.0"?>
    2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
    3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
    4 
    5 <modulesynopsis>
    6     <name>mod_httpbl</name>
    7     <description>Validates visitor IPs through http:BL's DNSBL (DNS Block List) and gives the web administrator the ability to allow or deny based on multiple data points supplied by http:BL</description>
    8     <status>alpha</status>
    9     <sourcefile>mod_httpbl.c</sourcefile>
   10     <identifier>httpbl_module</identifier>
   11     <compatibility>Available in Apache 2.0 and later, tested on 32bit and 64bit Linux servers</compatibility>
   12     <summary>
   13         <p>This module is an access tool designed to pull data from http:BL (a <a href="http://www.projecthoneypot.org/">Project Honey Pot</a> <directive>Access Key</directive> is required for DNSRBL use).</p>
   14         <p>http:BL is a service provided by a group of philanthropic ISPs powered by the data gathered by <a href="http://www.projecthoneypot.org/">Project Honey Pot</a>.</p>
   15         <p>This module allows fine-grained control of authorization to files (or directories or virtual hosts or servers) based on rules which define which DNSBL-returned values should be granted what kind of authorization.</p>
   16         <p>Also available within the module are features such as email address translation (for email address protection).</p>
   17         <example>
   18             <title>Basic Module Directives</title>
   19             # To get you up and running quickly, here is an example block of directives<br />
   20             <directive>HTTPBLRBLEnabled</directive> On<br />
   21             <directive>HTTPBLAccessKey</directive> <strong>*** get this from your Project Honey Pot account (free to register) ***</strong><br />
   22             <directive>HTTPBLDefaultAction</directive> Allow<br />
   23             # allow all search engines<br />
   24             <directive>HTTPBLRBLReqHandler</directive> 255:0-255:0-255:0 allow<br />
   25             # deny any other listed IPs with any &quot;score&quot; that have been active in the last 30 days<br />
   26             <directive>HTTPBLRBLReqHandler</directive> 255:0-30:0-255:255 deny<br />
   27         </example>
   28         <p>Currently supported and stable features:<ul>
   29             <li>DNSBL lookups (lookups performed against <a href="http://www.projecthoneypot.org/">Project Honey Pot</a> data)</li>
   30             <li>Child process DNSBL value caching (via a modified hash-list)</li>
   31             <li>Manual whitelisting (via directives)</li>
   32             <li>Email address translation within webpages (strings that look like email addresses or mailto: links can be replaced with web administrator-specifiable text and links)</li>
   33             <li>Tiered logging and debugging (still in development)</li>
   34             <li>Diagnostics page which attempts to help web administrators troubleshoot the module</li></ul></p>
   35         <p>Future features:<ul>
   36             <li>Inter-process communication between child processes</li>
   37             <li>The ability to whitelist visitors' IPs based on the ability of the visitor to pass a challenge/captcha</li>
   38             <li>&quot;Virtual Honey Pot&quot; requests served customizable partial URLs</li>
   39             <li>Additional options for request handlers including challenges/captchas and honeypots</li>
   40             <li>The ability to report 404 and POST meta-data back to the Project Honey Pot servers (to try and catch exploiting crawlers)</li>
   41             <li>More thorough diagnostics testing and reporting</li>
   42             <li>Persistent storage of http:BL lookup values and other data (to restore data after an Apache restart)</li>
   43             <li>The ability to customize forbidden (403) response pages</li></ul></p>
   44         <note type="warning">
   45             Warning: module is still somewhat experimental.  It is tested to be stable on a small number of architectures, Apache versions, and permutations of directives.
   46             We need help testing more permutations to ensure long-term stability.<br />
   47             Many new features are planned but currently disabled and we need help from anyone willing to test leading-edge features.
   48         </note>
   49         <p>The directives below are in alphabetical order which is unfortunately misleading.</p>
   50     </summary>
   51     <seealso><a href="http://www.ProjectHoneyPot.org/">Project Honey Pot website</a></seealso>
   52     <!--
   53     <seealso><module>mod_evasive</module></seealso>
   54     <seealso><module>mod_access_rbl</module></seealso>
   55     -->
   56     
   57     
   58     <directivesynopsis>
   59         <name>HTTPBLRBLEnabled</name>
   60         <description>Enables the main portion of the module to run for this context (directory, virtual host, or server)</description>
   61         <syntax>HTTPBLRBLEnabled <var>on|off</var></syntax>
   62         <default>HTTPBLRBLEnabled <var>off</var></default>
   63         <contextlist>
   64             <context>server config</context>
   65             <context>virtual host</context>
   66             <context>directory</context>
   67             <context>.htaccess</context>
   68         </contextlist>
   69         <override>Limit</override>
   70         
   71         <usage>
   72             <p>Enables the DNSBL-lookup part of the module</p>
   73         </usage>
   74     </directivesynopsis>
   75     
   76     <!--
   77     <directivesynopsis>
   78         <name>HTTPBLCapture404s</name>
   79         <description>Enables the 404-capture part of the module for this context (directory, virtual host, or server)</description>
   80         <syntax>HTTPBLCapture404s <var>on|off</var></syntax>
   81         <default>HTTPBLCapture404s <var>off</var></default>
   82         <contextlist>
   83             <context>server config</context>
   84             <context>virtual host</context>
   85             <context>directory</context>
   86             <context>.htaccess</context>
   87         </contextlist>
   88         <override>Limit</override>
   89         <status>experimental; not compiled in with wide release code</status>
   90     
   91         <usage>
   92             <p>Enables the 404-capture part of the module.</p>
   93             <p>If you enable 404-recording, the module will record only the following data points:<ul>
   94                 <li>Request HTTP method (i.e. GET or HEAD)</li>
   95                 <li>Visitor's IP</li>
   96                 <li>Request Timestamp</li>
   97                 <li>Referral String</li>
   98                 <li>User Agent String</li>
   99                 <li>URL Requested</li></ul>.
  100                 Data handled looks very much like a standard Apache access log.</p>
  101             <p>This data is very handy in detecting if the vistor is a robot automatically looking for a large variety of exploitable URLs.
  102                 By allowing Project Honey Pot to analyze your 404 logs, you are helping to improve the quality and coverage of the DNSBL data-set.</p>
  103             <p>Any other directives beginning with <directive>HTTPBL404</directive> will have no effect if this directive is off.</p>
  104             <p>POST recording is a subsection of the 404-recording system and the directive (HTTPBLCapturePOSTs) is off by default (even if this directive is on).</p>
  105         </usage>
  106     </directivesynopsis>
  107         
  108         
  109     <directivesynopsis>
  110         <name>HTTPBLCapturePOSTs</name>
  111         <description>Enables the 404-recording portion of the module to record POSTs for this context (directory, virtual host, or server)</description>
  112         <syntax>HTTPBLCapturePOSTs <var>on|off</var></syntax>
  113         <default>HTTPBLCapturePOSTs <var>off</var></default>
  114         <contextlist>
  115             <context>server config</context>
  116             <context>virtual host</context>
  117             <context>directory</context>
  118             <context>.htaccess</context>
  119         </contextlist>
  120         <override>Limit</override>
  121         <status>experimental; not compiled in with wide release code</status>
  122         
  123         <usage>
  124             <p>Enables POST-recording in the 404-recording part of the module.</p>
  125             <p>If you enable POST-recording, the module will record only the following data points:<ul>
  126                 <li>Visitor's IP</li>
  127                 <li>Request Timestamp</li>
  128                 <li>Referral String</li>
  129                 <li>User Agent String</li>
  130                 <li>URL POSTed to</li></ul>.
  131                 <strong>No additional data (such as the POST variables inside the HTTP header or content of a POST request) is gathered.</strong>
  132                 Data handled looks very much like a standard Apache access log.</p>
  133             <p>Requires 404-recording be enabled for this directive to have any effect. POST recording can not be enabled if 404 recording is not enabled for this context.</p>
  134         </usage>
  135     </directivesynopsis>
  136         
  137         
  138     <directivesynopsis>
  139         <name>HTTPBLChallengeToken</name>
  140         <description>Sets the token URL-path to be used when a visitor passes a challenge.</description>
  141         <syntax>HTTPBLChallengeToken <var>URL-path</var></syntax>
  142         <default>HTTPBLChallengeToken <var>(NULL)</var></default>
  143         <contextlist>
  144             <context>server config</context>
  145             <context>virtual host</context>
  146             <context>directory</context>
  147             <context>.htaccess</context>
  148         </contextlist>
  149         <status>experimental; not compiled in with wide release code</status>
  150         
  151         <usage>
  152             <p>Sets the token URL-path to be used when a visitor passes a challenge.</p>
  153             <p>Apache should not point resolve the fully-rendered URL (as seen by a browser) to an existing file.
  154                 This token is used to tell Apache that a visitor has passed a challenge/captcha.
  155                 After the token is accepted and processed, Apache will redirect the visitor to the URL which originally triggered the challenge/captcha.</p>
  156             <p>A visitor should be redirected to this URL-path when they pass a challenge.
  157                 When a visitor is redirected to this URL-path, the visitor's IP will be whitelisted.
  158                 All Apache processes which share the same whitelist cachefile (or more generally, the HTTPBL Repos Directory), will have the visitor's IP whitelisted. </p>
  159             <p>This URL should be kept secret as anyone who knows and uses this URL-path will be able to whitelist their IP in your cache.
  160                 Please ensure that you do not publish your Apache (server or virtualhost) access logs without parsing out this URL-path.</p>
  161             <p>If this directive's value is non-(NULL), the value will be tested against all incoming requests to see if the URL after the &quot;http://domain(:port)&quot; matches this token.
  162                 If this token does not begin with a forwardslash (&quot;/&quot;), this token can and will never match an incoming request.
  163                 If this directive's value is set, it cannot be later unset (there is no way to pass a NULL value to the directive).</p>
  164         </usage>
  165     </directivesynopsis>
  166         
  167         
  168     <directivesynopsis>
  169         <name>HTTPBLChallengeURL</name>
  170         <description>Sets the URL-path to be used for rules which decide to challenge the visitor</description>
  171         <syntax>HTTPBLChallengeURL <var>URL-path</var></syntax>
  172         <default>HTTPBLChallengeURL <var>URL-path</var></default>
  173         <contextlist>
  174             <context>server config</context>
  175             <context>virtual host</context>
  176         </contextlist>
  177         <status>experimental; not compiled in with wide release code</status>
  178         
  179         <usage>
  180             <p>Sets the URL to be used for challenging the visitor.</p>
  181             <p>Challenges are also referred to as &quot;captchas&quot;.</p>
  182             <p>Once set, this URL will have to point to a page that the website administrator has created to receive challenges/captchas.
  183                 From those challenge/captcha pages, successful visitors should be redirected to the <directive>HTTPBLChallengeToken</directive> URL, which must be set whenever this directive is set.</p>
  184             <p>This URL should have <directive>HTTPBLExempt On</directive> (preferrably via a &lt;Directory&gt; or &lt;Location&gt; tag in an Apache configuration file) to allow visitors to be granted access to the challenge page.</p>
  185         </usage>
  186     </directivesynopsis>
  187         -->
  188         
  189     <directivesynopsis>
  190         <name>HTTPBLTestingURL</name>
  191         <description>Enables the main portion of the module to run for this context (directory, virtual host, or server)</description>
  192         <syntax>HTTPBLTestingURL <var>URL-path</var></syntax>
  193         <default>HTTPBLTestingURL <var>/httpbl_diagnostics/</var></default>
  194         <contextlist>
  195             <context>server config</context>
  196             <context>virtual host</context>
  197         </contextlist>
  198         
  199         <usage>
  200             <p>Sets the URL-path to be used to access the diagnostics page for mod_httpbl.</p>
  201             <p>This page should be visited every time you restart the webserver after making changes to mod_httpbl directives.</p>
  202             <p>This page should be visited every time the module is not working correctly (i.e. any of these conditions:<ul>
  203                 <li>you suspect the DNSBL-lookup portion of the module isn't working correctly</li>
  204                 <li>you suspect 404 submissions or POST submissions (future releases only) aren't being recorded correctly when they are enabled</li>
  205                 <li>some requests are being denied while some requests from the same IP are being allowed (images, css, and other associated files are not consistently displaying in rendered HTML)</li></ul>.</p>
  206         </usage>
  207     </directivesynopsis>
  208         
  209         <!--
  210     <directivesynopsis>
  211         <name>HTTPBLHoneypotURL</name>
  212         <description>Enables the honey pots to be served by your webserver at this URL-path</description>
  213         <syntax>HTTPBLHoneypotURL <var>URL-path</var></syntax>
  214         <default>HTTPBLHoneypotURL <var>(NULL)</var></default>
  215         <contextlist>
  216             <context>server config</context>
  217             <context>virtual host</context>
  218             <context>directory</context>
  219         </contextlist>
  220         <status>experimental; not compiled in with wide release code</status>
  221         
  222         <usage>
  223             <p>Sets the token to be used to respond to the HTTP request with only honey pot content.</p>
  224             <p>This token will override the serving of a file at the same URL-path with a honey pot.</p>
  225             <p>If the honey pot can not be generated, the reponse to the visitor will be a blank page with status code 200.</p>
  226             <p>Please ensure that your honey pot request system works by visiting the Diagnostics page after you create this directive.</p>
  227         </usage>
  228     </directivesynopsis>
  229         -->
  230         
  231     <directivesynopsis>
  232         <name>HTTPBLAccessKey</name>
  233         <description>Sets the access key for your DNSBL lookups</description>
  234         <syntax>HTTPBLAccessKey <var>STRING</var></syntax>
  235         <default>HTTPBLAccessKey <var>(NULL)</var></default>
  236         <contextlist>
  237             <context>server config</context>
  238             <context>virtual host</context>
  239             <context>directory</context>
  240             <context>.htaccess</context>
  241         </contextlist>
  242         
  243         <usage>
  244             <p>Sets the access key string (which is required to access the DNSBL).</p>
  245             <p>The access key string is an alphabetic character string of a specific length.
  246                 It is pre-pended to your DNSBL requests<!-- and determines which Project Honey Pot server you submit your 404 recording data to-->.</p>
  247             <p>Your http:BL DNSBL requests are subject to be halted if you do not use the access key created specifically for your <a href="http://www.projecthoneypot.org/">Project Honey Pot</a> account or violate the Project Honey Pot <a href="http://www.projecthoneypot.org/terms_of_service_use.php">Terms of Service</a>.
  248                 Note: if your DNSBL requests are halted, you will not be able to do any DNSBL lookups and all requests will appear to be from clean IPs.</p>
  249             <p><strong>To receive an access key for the Project Honey Pot DNSBL<!--, 404 submission system, and POST submission system-->, you must log-in to your Project Honey Pot account at <a href="http://www.projecthoneypot.org/">Project Honey Pot's website</a>.
  250                 If you don't have an account, please create one for free.</strong></p>
  251         </usage>
  252     </directivesynopsis>
  253         
  254         
  255     <directivesynopsis>
  256         <name>HTTPBLExempt</name>
  257         <description>A quick way to skip module authorization processing for this context (directory, virtual host, or server)</description>
  258         <syntax>HTTPBLExempt <var>on|off</var></syntax>
  259         <default>HTTPBLExempt <var>off</var></default>
  260         <contextlist>
  261             <context>server config</context>
  262             <context>virtual host</context>
  263             <context>directory</context>
  264             <context>.htaccess</context>
  265         </contextlist>
  266         <override>Limit</override>
  267         
  268         <usage>
  269             <p>Disables the DNSBL-lookup part of the module for this context.</p>
  270             <p>This directive is preferrable to <directive>HTTPBLRBLEnabled Off</directive> and when the desired effect is to retain features of mod_httpbl (such as challenged whitelisting and 404 or POST recording) but to exempt this context (i.e. VirtualHost, Directory, Location, Files, etc.) from the constraints of DNSBL-based access.</p>
  271             <p>This directive should be used for:<ul>
  272                  <li>challenge directories to ensure the challenge HTML page is not denied to the visitor who is tasked with passing the challenge or</li>
  273                  <li>certain CSS, image, or script directories to ensure particular files are served to all visitors</li></ul></p>
  274         </usage>
  275     </directivesynopsis>
  276         
  277         
  278     <directivesynopsis>
  279         <name>HTTPBLHashTableSize</name>
  280         <description>Sets the preferred size of the internal hash-table (used for storing the IP hitlist) array</description>
  281         <syntax>HTTPBLHashTableSize <var>integer</var></syntax>
  282         <default>HTTPBLHashTableSize <var>3097</var></default>
  283         <contextlist>
  284             <context>server config</context>
  285             <context>virtual host</context>
  286         </contextlist>
  287         <status>experimental</status>
  288         
  289         <usage>
  290             <p>This directive adjusts the size of the hashtable array.</p>
  291             <p>A large number takes slightly more memory, but reduces hashtable collisions (reducing average lookup time on large servers).
  292                 If you want to optimize request-handling speed for a busy (a broad range of simultaneously connected IPs) server, use a larger value than default.
  293                 This value defines the number of contiguous elements in the static hashtable array.
  294                 If your Apache daemon runs as multiple processes (an MPM), each process will get an array of this directive's value size.
  295                 This value is typically negligible compared to the memory used by unnecessarily large <directive>HTTPBLBlockingPeriod</directive>s.</p>
  296             <p>In general, this number should be a prime number (for collision-frequency reduction reasons).</p>
  297             <p>This value is global to the module (redefinitions will override previous definitons) and is only available from Apache configuration files in a &lt;Server&gt; or &lt;VirtualHost&gt; scope.</p>
  298         </usage>
  299     </directivesynopsis>
  300         
  301         
  302     <directivesynopsis>
  303         <name>HTTPBLBlockingPeriod</name>
  304         <description>Sets the blocking period (in minutes) for both the hitlist and the whitelist</description>
  305         <syntax>HTTPBLBlockingPeriod <var>int</var></syntax>
  306         <default>HTTPBLBlockingPeriod <var>1440</var></default>
  307         <contextlist>
  308             <context>server config</context>
  309             <context>virtual host</context>
  310         </contextlist>
  311         
  312         <usage>
  313             <p>Sets the Time To Live (in minutes) for entries in both the hitlist and whitelist.</p>
  314             <p>This value determines how long DNSBL values should be cached before re-requesting the values from the http:BL DNSBL server.</p>
  315             <p>The default value, 1440, is equivilent to 1 day.</p>
  316             <p>This value is global to the module (redefinitions will override previous definitons) and is only available from *.conf files outside &lt;location&gt; and &lt;directory&gt; tags.</p>
  317         </usage>
  318     </directivesynopsis>
  319         
  320         
  321     <directivesynopsis>
  322         <name>HTTPBLLogDir</name>
  323         <description>Enables the main portion of the module to run for this context (directory, virtual host, or server)</description>
  324         <syntax>HTTPBLLogDir <var>directory-path</var></syntax>
  325         <default>HTTPBLLogDir <var>(NULL)</var></default>
  326         <contextlist>
  327             <context>server config</context>
  328             <context>virtual host</context>
  329         </contextlist>
  330         
  331         <usage>
  332             <p>Sets the log directory for any log files (other than the standard server and virtualhost logfiles) used by this module.</p>
  333             <p>This value is <strong>necessary for modules compiled with the IS_DEBUG_MODE on</strong> (the server could crash if this reccomendation is not followed).</p>
  334             <p>This value is global to the module (redefinitions will override previous definitons) and is only available from *.conf files outside &lt;location&gt; and &lt;directory&gt; tags.</p>
  335         </usage>
  336     </directivesynopsis>
  337         
  338         
  339     <directivesynopsis>
  340         <name>HTTPBLReposDir</name>
  341         <description>Sets the repository directory where all cache files are written</description>
  342         <syntax>HTTPBLReposDir <var>directory-path</var></syntax>
  343         <default>HTTPBLReposDir <var>(NULL)</var></default>
  344         
  345         <contextlist>
  346             <context>server config</context>
  347             <context>virtual host</context>
  348         </contextlist>
  349         
  350         <usage>
  351             <p>Sets the directory to be used for storing all cache files.</p>
  352             <p>This value is <strong>necessary for everyone running the module</strong>.</p>
  353             <p>This value is global to the module (redefinitions will override previous definitons) and is only available from *.conf files outside &lt;location&gt; and &lt;directory&gt; tags.</p>
  354         </usage>
  355     </directivesynopsis>
  356         
  357         
  358     <directivesynopsis>
  359         <name>HTTPBLWhitelist</name>
  360         <description>Manually add an IP address to your server's whitelist</description>
  361         <syntax>HTTPBLWhitelist <var>IPv4</var></syntax>
  362         <default>HTTPBLWhitelist <var>(NULL)</var></default>
  363         <contextlist>
  364             <context>server config</context>
  365             <context>virtual host</context>
  366             <context>directory</context>
  367             <context>.htaccess</context>
  368         </contextlist>
  369         <override>Limit</override>
  370         
  371         <usage>
  372             <p>Adds an IPv4 address (in decimal-dot notation) to the whitelist (which bypasses any DNSBL lookups for visitors with this IP address.</p>
  373             <p>The value should be written in the standard IPv4 decimal-dot notation with no characters other than 0-9 and period (&quot;.&quot;).
  374                 Acceptable values include the entire range of IPv4 addresses (from 0.0.0.0 to 255.255.255.255, inclusive), but no shorthand or masks are allowed.</p>
  375             <p>This value is global to the module (any usage of this directive will whitelist this IP for all requests to this server or servers using the same Repos Directory).</p>
  376         </usage>
  377     </directivesynopsis>
  378         
  379         <!--
  380     <directivesynopsis>
  381         <name>HTTPBL404POSTInterval</name>
  382         <description>Sets the preferred interval for submitting 404 data to Project Honey Pot</description>
  383         <syntax>HTTPBL404POSTInterval <var>integer</var></syntax>
  384         <default>HTTPBL404POSTInterval <var>180</var></default>
  385         <contextlist>
  386             <context>server config</context>
  387             <context>virtual host</context>
  388         </contextlist>
  389         <status>experimental; not compiled in with wide release code</status>
  390         
  391         <usage>
  392             <p>Sets the 404 submission minimum interval (in seconds).
  393                 Your server will not submit your 404 records any more frequently than this value.
  394                 Actual submission intervals will depend on factors such as:<ul>
  395                     <li>Time passed since last 404 record submission</li>
  396                     <li>Maximum filesize of the 404 record cachefile</li>
  397                     <li>Number of records in the 404 record cachefile</li></ul>
  398                 There is a hard-coded minimum submission interval of 60 seconds (to prevent abuse of the Project Honey Pot server which receives 404 submissions).</p>
  399             <p>This value is global to the module (redefinitions will override previous definitons) and is only available from *.conf files outside &lt;location&gt; and &lt;directory&gt; tags.</p>
  400         </usage>
  401     </directivesynopsis>
  402         
  403         
  404     <directivesynopsis>
  405     <name>HTTPBL404POSTMaxRetries</name>
  406         <description>Sets the number of 404 sumbission retries before clearing the 404 cache</description>
  407         <syntax>HTTPBL404POSTMaxRetries <var>integer</var></syntax>
  408         <default>HTTPBL404POSTMaxRetries <var>3</var></default>
  409         <contextlist>
  410             <context>server config</context>
  411             <context>virtual host</context>
  412         </contextlist>
  413         <status>experimental; not compiled in with wide release code</status>
  414         
  415         <usage>
  416             <p>Sets the number of 404 submission retries before the 404 cache is cleared.</p>
  417         </usage>
  418     </directivesynopsis>
  419         
  420         
  421     <directivesynopsis>
  422         <name>HTTPBL404POSTWhenRecordsReaches</name>
  423         <description>Sets the minimum number of 404 records between 404 submissions</description>
  424         <syntax>HTTPBL404POSTWhenRecordsReaches <var>integer</var></syntax>
  425         <default>HTTPBL404POSTWhenRecordsReaches <var>3</var></default>
  426         <contextlist>
  427             <context>server config</context>
  428             <context>virtual host</context>
  429         </contextlist>
  430         <status>experimental; not compiled in with wide release code</status>
  431         
  432         <usage>
  433             <p>Sets the minimum number of 404 records between 404 submissions.</p>
  434             <p>Actual submission intervals will depend on factors such as:<ul>
  435                 <li>Time passed since last 404 record submission</li>
  436                 <li>Maximum filesize of the 404 record cachefile</li>
  437                 <li>Number of records in the 404 record cachefile</li></ul></p>
  438         </usage>
  439     </directivesynopsis>
  440         
  441         
  442     <directivesynopsis>
  443         <name>HTTPBLExtPOSTTimeout</name>
  444         <description>Sets the number of seconds for an external HTTP connection to timeout</description>
  445         <syntax>HTTPBLExtPOSTTimeout <var>integer</var></syntax>
  446         <default>HTTPBLExtPOSTTimeout <var>2</var></default>
  447         <contextlist>
  448             <context>server config</context>
  449             <context>virtual host</context>
  450         </contextlist>
  451         <status>experimental; not compiled in with wide release code</status>
  452         
  453         <usage>
  454             <p>Sets the number of seconds before an external connection (a 404 submission or a honey pot request) times out.</p>
  455             <p>Connections which do not finish within the timeout interval will expire (a 404 submission failure will occure and a honeypot will be served empty).</p>
  456             <p>This directive has not been tested.</p>
  457         </usage>
  458     </directivesynopsis>
  459         -->
  460         
  461     <directivesynopsis>
  462         <name>HTTPBLDefaultAction</name>
  463         <description>Sets the default action for non-whitelisted DNSBLs</description>
  464         <syntax>HTTPBLDefaultAction <var>allow|deny<!--|challenge|honeypot--></var></syntax>
  465         <default>HTTPBLDefaultAction <var>allow</var></default>
  466         <contextlist>
  467             <context>server config</context>
  468             <context>virtual host</context>
  469             <context>directory</context>
  470             <context>.htaccess</context>
  471         </contextlist>
  472         <override>Limit</override>
  473         
  474         <usage>
  475             <p>Sets the default action for a context.</p>
  476             <p><strong>Default actions are only used if no RBLReqHandlers (see usage for <directive>HTTPBLRBLReqHandler</directive>) match the DNSBL-value returned by an http:BL DNSBL lookup.
  477                 This directive does not apply to visitor IPs which have no value returned by http:BL (also known as &quot;clean IPs&quot;).</strong></p>
  478             <p>If this action is set to &quot;Challenge&quot;, please make sure that your challenge directives are set (via the ChallengeURL and ChallengeToken values).</p>
  479         </usage>
  480     </directivesynopsis>
  481         
  482         
  483     <directivesynopsis>
  484         <name>HTTPBLRBLDomain</name>
  485         <description>Sets the domain to use for RBL lookups</description>
  486         <syntax>HTTPBLRBLDomain <var>(subdomain.)domain.tld</var></syntax>
  487         <default>HTTPBLRBLDomain <var>dnsbl.httpbl.org</var></default>
  488         <contextlist>
  489             <context>server config</context>
  490             <context>virtual host</context>
  491         </contextlist>
  492         
  493         <usage>
  494             <p>This directive sets the domain to use for DNSBL lookups.
  495                 The default is the http:BL combined zone which serves all IPs and types known to Project Honey Pot with a calculated threat score and the number of days since last activity was seen.</p>
  496             <p>Please see <a href="http://www.projecthoneypot.org/">Project Honey Pot's website</a> for a list of other valid http:BL zones (and/or domains) to use.</p>
  497         </usage>
  498     </directivesynopsis>
  499         
  500         
  501     <directivesynopsis>
  502         <name>HTTPBLRewriteEmailLinksTo</name>
  503         <description>Sets the replacement text to be used with email rewriting</description>
  504         <syntax>HTTPBLRewriteEmailLinksTo <var>URL</var></syntax>
  505         <default>HTTPBLRewriteEmailLinksTo <var>.</var></default>
  506         <contextlist>
  507             <context>server config</context>
  508             <context>virtual host</context>
  509             <context>directory</context>
  510             <context>.htaccess</context>
  511         </contextlist>
  512         <override>Limit</override>
  513             
  514         <usage>
  515             <p>Sets the URL to replace &quot;mailto:&quot; link URLs when &quot;allow-xlate-emails&quot; is the action triggered by a <directive>HTTPBLRBLReqHandler</directive>.</p>
  516             <p>Note: spaces are not valid inside this value.
  517                 Please URL-encode then &quot;HTML Entity&quot;ize this value.</p>
  518             <p>Only pages served with content-type: &quot;text/html&quot; will have email addresses translated.
  519                 All other content-types are skipped.
  520                 There may be a future version which allows custom replacement of text in user-selectable content-types.</p>
  521         </usage>
  522     </directivesynopsis>
  523         
  524         
  525     <directivesynopsis>
  526         <name>HTTPBLRewriteEmailTextTo</name>
  527         <description>Sets the replacement text to be used with email rewriting</description>
  528         <syntax>HTTPBLRewriteEmailTextTo <var>STRING</var></syntax>
  529         <default>HTTPBLRewriteEmailTextTo <var>(PROTECTED_EMAIL)</var></default>
  530         <contextlist>
  531             <context>server config</context>
  532             <context>virtual host</context>
  533             <context>directory</context>
  534             <context>.htaccess</context>
  535         </contextlist>
  536         <override>Limit</override>
  537             
  538         <usage>
  539             <p>Sets the text to replace text that appears to be a valid email in URLs when &quot;allow-xlate-emails&quot; is the action triggered by a <directive>RBLReqHandler</directive>.</p>
  540             <p>Note: spaces are not valid inside this value.
  541                 Please &quot;HTML Entity&quot;ize this value (the html entity &quot;&amp;amp;&quot; can be an alternative to a space in this value).</p>
  542             <p>Only pages served with content-type: &quot;text/html&quot; will have email addresses translated.
  543                 All other content-types are skipped.
  544                 There may be a future version which allows custom replacement of text in user-selectable content-types.</p>
  545         </usage>
  546     </directivesynopsis>
  547         
  548         
  549     <directivesynopsis>
  550         <name>HTTPBLRBLReqHandler</name>
  551         <description>Creates a rule to handle a range of DNSBL values</description>
  552         <syntax>HTTPBLRBLReqHandler <var>integer:integer[-integer]:integer[-integer]:integer</var> <var>allow|allow-xlate-emails|deny<!--|challenge|honeypot--></var></syntax>
  553         <contextlist>
  554             <context>server config</context>
  555             <context>virtual host</context>
  556             <context>directory</context>
  557             <context>.htaccess</context>
  558         </contextlist>
  559         <override>Limit</override>
  560         
  561         <usage>
  562             <p>Creates a rule to test an DNSBL value against.
  563                 If the DNSBL value of a visitor's IP matches the rule, the RBLReqHandler's action is taken and no more RBLReqHandlers are tested.</p>
  564             <p><directive>RBLReqHandlers</directive> stack (multiple handlers are tested).</p>
  565             <p>If handlers are defined in a more general context below a more specific context (i.e. RBLReqHandler 2, defined in a &lt;virtualhost&gt;, is below <directive>RBLReqHandler 1</directive>, defined in a &lt;directory&gt;), behavior is undefined.
  566                 What will probably happen is <directive>RBLReqHandler</directive> will be processed in requests which match the &lt;virtualhost&gt; in question, but never be attached to the &lt;directory&gt; in question.</p>
  567             <p><directive>RBLReqHandler</directive>s are stored and, therefore, tested first by top-down within a context, then fall back to a more general context if further <directive>RBLReqHandler</directive> testing is needed.</p>
  568             <p>Sample httpd.conf excerpt:<br />
  569                 <example>
  570                 &lt;VirtualHost&gt;
  571                     <indent>
  572                        <directive>HTTPRBLReqHandler (criteria_aaa)</directive><br />
  573                         &lt;Directory ~ ^/dir1/&gt;<br />
  574                             <indent>
  575                                 <directive>HTTPRBLReqHandler (criteria_bbb)</directive><br />
  576                                 <directive>HTTPRBLReqHandler (criteria_ccc)</directive>
  577                             </indent>
  578                         &lt;/Directory&gt;<br />
  579                         <directive>HTTPRBLReqHandler (criteria_ddd)</directive><br />
  580                         &lt;Directory ~ ^/dir1/images/&gt;<br />
  581                             <indent>
  582                                 <directive>HTTPRBLReqHandler (criteria_eee)</directive><br />
  583                                 <directive>HTTPRBLReqHandler (criteria_fff)</directive>
  584                             </indent>
  585                         &lt;/Directory&gt;<br />
  586                         <directive>HTTPRBLReqHandler (criteria_ggg)</directive>
  587                     </indent>
  588                 &lt;/VirtualHost&gt;
  589                 </example></p>
  590             <p>Example 1:<br />
  591                 With requests matching <code>^/dir1/images/</code>, testing is done in the following order:<ol>
  592                     <li>criteria_eee</li>
  593                     <li>criteria_fff</li>
  594                     <li>criteria_bbb</li>
  595                     <li>criteria_ccc</li>
  596                     <li>criteria_aaa</li>
  597                     <li>criteria_ddd</li></ol>
  598                 Behavior concerning criteria_ggg is undefined since it is defined in a more general context and below the matching directory.</p>
  599             <p>Example 2:<br />
  600                 With requests matching <code>^/dir1/</code> (but not matching <code>^/dir1/images/</code>), testing is done in the following order:<ol>
  601                     <li>criteria_bbb</li>
  602                     <li>criteria_ccc</li>
  603                     <li>criteria_aaa</li></ol>
  604                 Behavior concerning criteria_ddd and criteria_ggg are undefined since they are both defined in a more general context and below the matching directory.</p>
  605             <p>Example 3:<br />
  606                 With requests matching the &lt;VirtualHost&gt; (but not matching <code>^/dir1/images/</code> or <code>^/dir1/</code>), testing is done in the following order:<ol>
  607                     <li>criteria_aaa</li>
  608                     <li>criteria_ddd</li>
  609                     <li>criteria_ggg</li></ol>
  610                 Behavior concerning criteria_ddd and criteria_ggg is predictable and normal within this set of requests.</p>
  611             <p>For reference below, the IP values returned by http:BL's DNSBL are in the format:<br />
  612                 <code>127.X.Y.Z</code><br />
  613                 Where:<ul>
  614                     <li>X - The number of days [0-255] since activity from the IP has been observed.</li>
  615                     <li>Y - A score [0-255] which describes how &quot;threatening&quot; the IP is (at the current time).</li>
  616                     <li>Z - A bitmask [0-255] of the categories this IP matches (i.e. search engine, harvester, comment spammer, generally suspicious).</li></ul><br />
  617                 Refer to documenttation on <a href="http://www.projecthoneypot.org/">Project Honey Pot's website</a> for more details on exactly what these values mean.</p>
  618             <p>The actual criteria generation is simple but the syntax is prone to errors.
  619                 A wizard will be available soon for HTTPBLRBLReqHandler directive generation.</p>
  620             <p>There are five parameters acctepted by the RBLReqHandler directives:<ol>
  621                    <li>The &quot;HTTP method&quot; bitset</li>
  622                    <li>The &quot;Days since last activity&quot; range</li>
  623                    <li>The &quot;Score&quot; range</li>
  624                    <li>The &quot;Offender category&quot; bitset</li>
  625                    <li>The action to take, should the <directive>HTTPBLRBLReqHandler</directive> match the DNSBL value of the requesting IP</li></ol><br />
  626                     The first four parameters are separated by colons (:), while the fourth and fifth are seperated by a space ( ).<br />
  627                     <strong>bitsets</strong> are integers which represent a set of bits; each bit has a decimal value (1, 2, 4, 8, 16, etc.) and the bitset parameter is created by summing the desired matching bits.
  628                         A bitset of decimal value 0 (zero), would match none of the 8 possible bits, while a bitset of decimal value of 255 would match every one of the 8 bits.<br />
  629                     <strong>ranges</strong> are two integers seperated by a hyphen (-)  The former integer MUST be no greater than the latter (i.e. given range &quot;A-B&quot;, A must be &lt;= B).<br />
  630                     <strong>actions</strong> are one of small set of valid strings.  Currently the only four supported actions are: {allow, allow-xlate-emails, <!--challenge, honeypot, -->and deny}.<br /></p>
  631             <p>A example RBLReqHandler (provided for discussion) is as follows:<br />
  632                 <code>HTTPBLRBLReqHandler [A]:[B]-[C]:[D]-[E]:[F] ACTION_STRING</code><br />
  633                 Explanations of the integers (represented by [A] thru [F] are as follows:<ul>
  634                     <li>[A] - A bitmask [0-255] of the HTTP methods (in decimal representation) which should match.  Method decimal values:<ul>
  635                        <li>1 - GET</li>
  636                        <li>2 - POST</li>
  637                        <li>4 - HEAD</li>
  638                        <li>8 - PUT</li>
  639                        <li>16 - DELETE</li>
  640                        <li>32 - Reserved for future use</li>
  641                        <li>128 - Reserved for future use</li>
  642                        <li>128 - Reserved for future use</li></ul><br />
  643                         It is recommended that you leave this value as 255 (match all methods) unless you want very-fine control of IP authorization.</li>
  644                     <li>[B] - The lower bound for DNSBL value octet 2 (X in the example DNSBL value above)</li>
  645                     <li>[C] - The upper bound for DNSBL value octet 2 (X in the example DNSBL value above);<br />
  646                         [C], and the hypen (&quot;-&quot;) which preceeds it are now optional.  This means that ranges can be a single number.</li>
  647                     <li>[D] - The lower bound for DNSBL value octet 3 (Y in the example DNSBL value above)</li>
  648                     <li>[E] - The upper bound for DNSBL value octet 3 (Y in the example DNSBL value above);<br />
  649                         [E], and the hypen (&quot;-&quot;) which preceeds it are now optional.  This means that ranges can be a single number.</li>
  650                     <li>[F] - A bitmask [0-255] of the offending type (in decimal representation) which should match.  Type decimal values:<ul>
  651                        <li>1 - Generally suspicious IP (no offensive actions seen, <strong>yet</strong>)</li>
  652                        <li>2 - A known harvester</li>
  653                        <li>4 - A comment spammer</li>
  654                        <li>8 - A known exploiter</li>
  655                        <li>16 - Reserved for future use</li>
  656                        <li>32 - Reserved for future use</li>
  657                        <li>64 - Reserved for future use</li>
  658                        <li>128 - Reserved for future use</li></ul><br />
  659                             <strong>If no bits are set (DNSBL octet 4 is 0), then the IP is of a known search engine.</strong><br />
  660                             If this is the case, then DNSBL octet 3 (Y, above) is not a score counter, but rather a &quot;serial number&quot; for the search engine (refer to <a href="http://www.projecthoneypot.org/">Procjet Honey Pot's website</a> for details).</li></ul></p>
  661             <example><title>Specific Examples:</title>
  662                 # Serve all search engines, but replace email address text and links in HTML content.<br />
  663                 HTTPBLRBLReqHandler 255:0-255:0-255:0 allow-xlate-emails<br />
  664                 <br />
  665                 # Deny known comment spammers the ability to POST.<br />
  666                 HTTPBLRBLReqHandler 2:0-255:0-255:4 deny<br />
  667                 <br />
  668                 # Serve all harvesters, but replace email address text and links in HTML content.<br />
  669                 HTTPBLRBLReqHandler 255:0-255:0-255:2 allow-xlate-emails<br />
  670                 <br />
  671                 # Deny known exploiters the ability to request via HTTP method HEAD<br />
  672                 HTTPBLRBLReqHandler 4:0-255:0-255:8 deny<br />
  673                 <br />
  674                 # Send mildly offensive IPs to a challenge page, if they pass the &quot;captcha&quot;, whitelist them for the duration of the blocking_period.<br />
  675                 HTTPBLRBLReqHandler challenge<br />
  676                 <br />
  677                 # Deny any requests originating from IPs known to Project Honey Pot to be suspicious or offensive.<br />
  678                 HTTPBLRBLReqHandler 255:0-255:0-255:deny<br /></example>
  679         </usage>
  680     </directivesynopsis>
  681 </modulesynopsis>
  682