<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<modulesynopsis>
<name>mod_httpbl</name>
<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>
<status>alpha</status>
<sourcefile>mod_httpbl.c</sourcefile>
<identifier>httpbl_module</identifier>
<compatibility>Available in Apache 2.0 and later, tested on 32bit and 64bit Linux servers</compatibility>
<summary>
<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>
<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>
<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>
<p>Also available within the module are features such as email address translation (for email address protection).</p>
<example>
<title>Basic Module Directives</title>
# To get you up and running quickly, here is an example block of directives<br />
<directive>HTTPBLRBLEnabled</directive> On<br />
<directive>HTTPBLAccessKey</directive> <strong>*** get this from your Project Honey Pot account (free to register) ***</strong><br />
<directive>HTTPBLDefaultAction</directive> Allow<br />
# allow all search engines<br />
<directive>HTTPBLRBLReqHandler</directive> 255:0-255:0-255:0 allow<br />
# deny any other listed IPs with any "score" that have been active in the last 30 days<br />
<directive>HTTPBLRBLReqHandler</directive> 255:0-30:0-255:255 deny<br />
</example>
<p>Currently supported and stable features:<ul>
<li>DNSBL lookups (lookups performed against <a href="http://www.projecthoneypot.org/">Project Honey Pot</a> data)</li>
<li>Child process DNSBL value caching (via a modified hash-list)</li>
<li>Manual whitelisting (via directives)</li>
<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>
<li>Tiered logging and debugging (still in development)</li>
<li>Diagnostics page which attempts to help web administrators troubleshoot the module</li></ul></p>
<p>Future features:<ul>
<li>Inter-process communication between child processes</li>
<li>The ability to whitelist visitors' IPs based on the ability of the visitor to pass a challenge/captcha</li>
<li>"Virtual Honey Pot" requests served customizable partial URLs</li>
<li>Additional options for request handlers including challenges/captchas and honeypots</li>
<li>The ability to report 404 and POST meta-data back to the Project Honey Pot servers (to try and catch exploiting crawlers)</li>
<li>More thorough diagnostics testing and reporting</li>
<li>Persistent storage of http:BL lookup values and other data (to restore data after an Apache restart)</li>
<li>The ability to customize forbidden (403) response pages</li></ul></p>
<note type="warning">
Warning: module is still somewhat experimental. It is tested to be stable on a small number of architectures, Apache versions, and permutations of directives.
We need help testing more permutations to ensure long-term stability.<br />
Many new features are planned but currently disabled and we need help from anyone willing to test leading-edge features.
</note>
<p>The directives below are in alphabetical order which is unfortunately misleading.</p>
</summary>
<seealso><a href="http://www.ProjectHoneyPot.org/">Project Honey Pot website</a></seealso>
<!--
<seealso><module>mod_evasive</module></seealso>
<seealso><module>mod_access_rbl</module></seealso>
-->
<directivesynopsis>
<name>HTTPBLRBLEnabled</name>
<description>Enables the main portion of the module to run for this context (directory, virtual host, or server)</description>
<syntax>HTTPBLRBLEnabled <var>on|off</var></syntax>
<default>HTTPBLRBLEnabled <var>off</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<override>Limit</override>
<usage>
<p>Enables the DNSBL-lookup part of the module</p>
</usage>
</directivesynopsis>
<!--
<directivesynopsis>
<name>HTTPBLCapture404s</name>
<description>Enables the 404-capture part of the module for this context (directory, virtual host, or server)</description>
<syntax>HTTPBLCapture404s <var>on|off</var></syntax>
<default>HTTPBLCapture404s <var>off</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<override>Limit</override>
<status>experimental; not compiled in with wide release code</status>
<usage>
<p>Enables the 404-capture part of the module.</p>
<p>If you enable 404-recording, the module will record only the following data points:<ul>
<li>Request HTTP method (i.e. GET or HEAD)</li>
<li>Visitor's IP</li>
<li>Request Timestamp</li>
<li>Referral String</li>
<li>User Agent String</li>
<li>URL Requested</li></ul>.
Data handled looks very much like a standard Apache access log.</p>
<p>This data is very handy in detecting if the vistor is a robot automatically looking for a large variety of exploitable URLs.
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>
<p>Any other directives beginning with <directive>HTTPBL404</directive> will have no effect if this directive is off.</p>
<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>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>HTTPBLCapturePOSTs</name>
<description>Enables the 404-recording portion of the module to record POSTs for this context (directory, virtual host, or server)</description>
<syntax>HTTPBLCapturePOSTs <var>on|off</var></syntax>
<default>HTTPBLCapturePOSTs <var>off</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<override>Limit</override>
<status>experimental; not compiled in with wide release code</status>
<usage>
<p>Enables POST-recording in the 404-recording part of the module.</p>
<p>If you enable POST-recording, the module will record only the following data points:<ul>
<li>Visitor's IP</li>
<li>Request Timestamp</li>
<li>Referral String</li>
<li>User Agent String</li>
<li>URL POSTed to</li></ul>.
<strong>No additional data (such as the POST variables inside the HTTP header or content of a POST request) is gathered.</strong>
Data handled looks very much like a standard Apache access log.</p>
<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>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>HTTPBLChallengeToken</name>
<description>Sets the token URL-path to be used when a visitor passes a challenge.</description>
<syntax>HTTPBLChallengeToken <var>URL-path</var></syntax>
<default>HTTPBLChallengeToken <var>(NULL)</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<status>experimental; not compiled in with wide release code</status>
<usage>
<p>Sets the token URL-path to be used when a visitor passes a challenge.</p>
<p>Apache should not point resolve the fully-rendered URL (as seen by a browser) to an existing file.
This token is used to tell Apache that a visitor has passed a challenge/captcha.
After the token is accepted and processed, Apache will redirect the visitor to the URL which originally triggered the challenge/captcha.</p>
<p>A visitor should be redirected to this URL-path when they pass a challenge.
When a visitor is redirected to this URL-path, the visitor's IP will be whitelisted.
All Apache processes which share the same whitelist cachefile (or more generally, the HTTPBL Repos Directory), will have the visitor's IP whitelisted. </p>
<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.
Please ensure that you do not publish your Apache (server or virtualhost) access logs without parsing out this URL-path.</p>
<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 "http://domain(:port)" matches this token.
If this token does not begin with a forwardslash ("/"), this token can and will never match an incoming request.
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>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>HTTPBLChallengeURL</name>
<description>Sets the URL-path to be used for rules which decide to challenge the visitor</description>
<syntax>HTTPBLChallengeURL <var>URL-path</var></syntax>
<default>HTTPBLChallengeURL <var>URL-path</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
</contextlist>
<status>experimental; not compiled in with wide release code</status>
<usage>
<p>Sets the URL to be used for challenging the visitor.</p>
<p>Challenges are also referred to as "captchas".</p>
<p>Once set, this URL will have to point to a page that the website administrator has created to receive challenges/captchas.
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>
<p>This URL should have <directive>HTTPBLExempt On</directive> (preferrably via a <Directory> or <Location> tag in an Apache configuration file) to allow visitors to be granted access to the challenge page.</p>
</usage>
</directivesynopsis>
-->
<directivesynopsis>
<name>HTTPBLTestingURL</name>
<description>Enables the main portion of the module to run for this context (directory, virtual host, or server)</description>
<syntax>HTTPBLTestingURL <var>URL-path</var></syntax>
<default>HTTPBLTestingURL <var>/httpbl_diagnostics/</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
</contextlist>
<usage>
<p>Sets the URL-path to be used to access the diagnostics page for mod_httpbl.</p>
<p>This page should be visited every time you restart the webserver after making changes to mod_httpbl directives.</p>
<p>This page should be visited every time the module is not working correctly (i.e. any of these conditions:<ul>
<li>you suspect the DNSBL-lookup portion of the module isn't working correctly</li>
<li>you suspect 404 submissions or POST submissions (future releases only) aren't being recorded correctly when they are enabled</li>
<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>
</usage>
</directivesynopsis>
<!--
<directivesynopsis>
<name>HTTPBLHoneypotURL</name>
<description>Enables the honey pots to be served by your webserver at this URL-path</description>
<syntax>HTTPBLHoneypotURL <var>URL-path</var></syntax>
<default>HTTPBLHoneypotURL <var>(NULL)</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
</contextlist>
<status>experimental; not compiled in with wide release code</status>
<usage>
<p>Sets the token to be used to respond to the HTTP request with only honey pot content.</p>
<p>This token will override the serving of a file at the same URL-path with a honey pot.</p>
<p>If the honey pot can not be generated, the reponse to the visitor will be a blank page with status code 200.</p>
<p>Please ensure that your honey pot request system works by visiting the Diagnostics page after you create this directive.</p>
</usage>
</directivesynopsis>
-->
<directivesynopsis>
<name>HTTPBLAccessKey</name>
<description>Sets the access key for your DNSBL lookups</description>
<syntax>HTTPBLAccessKey <var>STRING</var></syntax>
<default>HTTPBLAccessKey <var>(NULL)</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<usage>
<p>Sets the access key string (which is required to access the DNSBL).</p>
<p>The access key string is an alphabetic character string of a specific length.
It is pre-pended to your DNSBL requests<!-- and determines which Project Honey Pot server you submit your 404 recording data to-->.</p>
<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>.
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>
<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>.
If you don't have an account, please create one for free.</strong></p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>HTTPBLExempt</name>
<description>A quick way to skip module authorization processing for this context (directory, virtual host, or server)</description>
<syntax>HTTPBLExempt <var>on|off</var></syntax>
<default>HTTPBLExempt <var>off</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<override>Limit</override>
<usage>
<p>Disables the DNSBL-lookup part of the module for this context.</p>
<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>
<p>This directive should be used for:<ul>
<li>challenge directories to ensure the challenge HTML page is not denied to the visitor who is tasked with passing the challenge or</li>
<li>certain CSS, image, or script directories to ensure particular files are served to all visitors</li></ul></p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>HTTPBLHashTableSize</name>
<description>Sets the preferred size of the internal hash-table (used for storing the IP hitlist) array</description>
<syntax>HTTPBLHashTableSize <var>integer</var></syntax>
<default>HTTPBLHashTableSize <var>3097</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
</contextlist>
<status>experimental</status>
<usage>
<p>This directive adjusts the size of the hashtable array.</p>
<p>A large number takes slightly more memory, but reduces hashtable collisions (reducing average lookup time on large servers).
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.
This value defines the number of contiguous elements in the static hashtable array.
If your Apache daemon runs as multiple processes (an MPM), each process will get an array of this directive's value size.
This value is typically negligible compared to the memory used by unnecessarily large <directive>HTTPBLBlockingPeriod</directive>s.</p>
<p>In general, this number should be a prime number (for collision-frequency reduction reasons).</p>
<p>This value is global to the module (redefinitions will override previous definitons) and is only available from Apache configuration files in a <Server> or <VirtualHost> scope.</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>HTTPBLBlockingPeriod</name>
<description>Sets the blocking period (in minutes) for both the hitlist and the whitelist</description>
<syntax>HTTPBLBlockingPeriod <var>int</var></syntax>
<default>HTTPBLBlockingPeriod <var>1440</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
</contextlist>
<usage>
<p>Sets the Time To Live (in minutes) for entries in both the hitlist and whitelist.</p>
<p>This value determines how long DNSBL values should be cached before re-requesting the values from the http:BL DNSBL server.</p>
<p>The default value, 1440, is equivilent to 1 day.</p>
<p>This value is global to the module (redefinitions will override previous definitons) and is only available from *.conf files outside <location> and <directory> tags.</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>HTTPBLLogDir</name>
<description>Enables the main portion of the module to run for this context (directory, virtual host, or server)</description>
<syntax>HTTPBLLogDir <var>directory-path</var></syntax>
<default>HTTPBLLogDir <var>(NULL)</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
</contextlist>
<usage>
<p>Sets the log directory for any log files (other than the standard server and virtualhost logfiles) used by this module.</p>
<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>
<p>This value is global to the module (redefinitions will override previous definitons) and is only available from *.conf files outside <location> and <directory> tags.</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>HTTPBLReposDir</name>
<description>Sets the repository directory where all cache files are written</description>
<syntax>HTTPBLReposDir <var>directory-path</var></syntax>
<default>HTTPBLReposDir <var>(NULL)</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
</contextlist>
<usage>
<p>Sets the directory to be used for storing all cache files.</p>
<p>This value is <strong>necessary for everyone running the module</strong>.</p>
<p>This value is global to the module (redefinitions will override previous definitons) and is only available from *.conf files outside <location> and <directory> tags.</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>HTTPBLWhitelist</name>
<description>Manually add an IP address to your server's whitelist</description>
<syntax>HTTPBLWhitelist <var>IPv4</var></syntax>
<default>HTTPBLWhitelist <var>(NULL)</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<override>Limit</override>
<usage>
<p>Adds an IPv4 address (in decimal-dot notation) to the whitelist (which bypasses any DNSBL lookups for visitors with this IP address.</p>
<p>The value should be written in the standard IPv4 decimal-dot notation with no characters other than 0-9 and period (".").
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>
<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>
</usage>
</directivesynopsis>
<!--
<directivesynopsis>
<name>HTTPBL404POSTInterval</name>
<description>Sets the preferred interval for submitting 404 data to Project Honey Pot</description>
<syntax>HTTPBL404POSTInterval <var>integer</var></syntax>
<default>HTTPBL404POSTInterval <var>180</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
</contextlist>
<status>experimental; not compiled in with wide release code</status>
<usage>
<p>Sets the 404 submission minimum interval (in seconds).
Your server will not submit your 404 records any more frequently than this value.
Actual submission intervals will depend on factors such as:<ul>
<li>Time passed since last 404 record submission</li>
<li>Maximum filesize of the 404 record cachefile</li>
<li>Number of records in the 404 record cachefile</li></ul>
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>
<p>This value is global to the module (redefinitions will override previous definitons) and is only available from *.conf files outside <location> and <directory> tags.</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>HTTPBL404POSTMaxRetries</name>
<description>Sets the number of 404 sumbission retries before clearing the 404 cache</description>
<syntax>HTTPBL404POSTMaxRetries <var>integer</var></syntax>
<default>HTTPBL404POSTMaxRetries <var>3</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
</contextlist>
<status>experimental; not compiled in with wide release code</status>
<usage>
<p>Sets the number of 404 submission retries before the 404 cache is cleared.</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>HTTPBL404POSTWhenRecordsReaches</name>
<description>Sets the minimum number of 404 records between 404 submissions</description>
<syntax>HTTPBL404POSTWhenRecordsReaches <var>integer</var></syntax>
<default>HTTPBL404POSTWhenRecordsReaches <var>3</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
</contextlist>
<status>experimental; not compiled in with wide release code</status>
<usage>
<p>Sets the minimum number of 404 records between 404 submissions.</p>
<p>Actual submission intervals will depend on factors such as:<ul>
<li>Time passed since last 404 record submission</li>
<li>Maximum filesize of the 404 record cachefile</li>
<li>Number of records in the 404 record cachefile</li></ul></p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>HTTPBLExtPOSTTimeout</name>
<description>Sets the number of seconds for an external HTTP connection to timeout</description>
<syntax>HTTPBLExtPOSTTimeout <var>integer</var></syntax>
<default>HTTPBLExtPOSTTimeout <var>2</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
</contextlist>
<status>experimental; not compiled in with wide release code</status>
<usage>
<p>Sets the number of seconds before an external connection (a 404 submission or a honey pot request) times out.</p>
<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>
<p>This directive has not been tested.</p>
</usage>
</directivesynopsis>
-->
<directivesynopsis>
<name>HTTPBLDefaultAction</name>
<description>Sets the default action for non-whitelisted DNSBLs</description>
<syntax>HTTPBLDefaultAction <var>allow|deny<!--|challenge|honeypot--></var></syntax>
<default>HTTPBLDefaultAction <var>allow</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<override>Limit</override>
<usage>
<p>Sets the default action for a context.</p>
<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.
This directive does not apply to visitor IPs which have no value returned by http:BL (also known as "clean IPs").</strong></p>
<p>If this action is set to "Challenge", please make sure that your challenge directives are set (via the ChallengeURL and ChallengeToken values).</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>HTTPBLRBLDomain</name>
<description>Sets the domain to use for RBL lookups</description>
<syntax>HTTPBLRBLDomain <var>(subdomain.)domain.tld</var></syntax>
<default>HTTPBLRBLDomain <var>dnsbl.httpbl.org</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
</contextlist>
<usage>
<p>This directive sets the domain to use for DNSBL lookups.
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>
<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>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>HTTPBLRewriteEmailLinksTo</name>
<description>Sets the replacement text to be used with email rewriting</description>
<syntax>HTTPBLRewriteEmailLinksTo <var>URL</var></syntax>
<default>HTTPBLRewriteEmailLinksTo <var>.</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<override>Limit</override>
<usage>
<p>Sets the URL to replace "mailto:" link URLs when "allow-xlate-emails" is the action triggered by a <directive>HTTPBLRBLReqHandler</directive>.</p>
<p>Note: spaces are not valid inside this value.
Please URL-encode then "HTML Entity"ize this value.</p>
<p>Only pages served with content-type: "text/html" will have email addresses translated.
All other content-types are skipped.
There may be a future version which allows custom replacement of text in user-selectable content-types.</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>HTTPBLRewriteEmailTextTo</name>
<description>Sets the replacement text to be used with email rewriting</description>
<syntax>HTTPBLRewriteEmailTextTo <var>STRING</var></syntax>
<default>HTTPBLRewriteEmailTextTo <var>(PROTECTED_EMAIL)</var></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<override>Limit</override>
<usage>
<p>Sets the text to replace text that appears to be a valid email in URLs when "allow-xlate-emails" is the action triggered by a <directive>RBLReqHandler</directive>.</p>
<p>Note: spaces are not valid inside this value.
Please "HTML Entity"ize this value (the html entity "&amp;" can be an alternative to a space in this value).</p>
<p>Only pages served with content-type: "text/html" will have email addresses translated.
All other content-types are skipped.
There may be a future version which allows custom replacement of text in user-selectable content-types.</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>HTTPBLRBLReqHandler</name>
<description>Creates a rule to handle a range of DNSBL values</description>
<syntax>HTTPBLRBLReqHandler <var>integer:integer[-integer]:integer[-integer]:integer</var> <var>allow|allow-xlate-emails|deny<!--|challenge|honeypot--></var></syntax>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<override>Limit</override>
<usage>
<p>Creates a rule to test an DNSBL value against.
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>
<p><directive>RBLReqHandlers</directive> stack (multiple handlers are tested).</p>
<p>If handlers are defined in a more general context below a more specific context (i.e. RBLReqHandler 2, defined in a <virtualhost>, is below <directive>RBLReqHandler 1</directive>, defined in a <directory>), behavior is undefined.
What will probably happen is <directive>RBLReqHandler</directive> will be processed in requests which match the <virtualhost> in question, but never be attached to the <directory> in question.</p>
<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>
<p>Sample httpd.conf excerpt:<br />
<example>
<VirtualHost>
<indent>
<directive>HTTPRBLReqHandler (criteria_aaa)</directive><br />
<Directory ~ ^/dir1/><br />
<indent>
<directive>HTTPRBLReqHandler (criteria_bbb)</directive><br />
<directive>HTTPRBLReqHandler (criteria_ccc)</directive>
</indent>
</Directory><br />
<directive>HTTPRBLReqHandler (criteria_ddd)</directive><br />
<Directory ~ ^/dir1/images/><br />
<indent>
<directive>HTTPRBLReqHandler (criteria_eee)</directive><br />
<directive>HTTPRBLReqHandler (criteria_fff)</directive>
</indent>
</Directory><br />
<directive>HTTPRBLReqHandler (criteria_ggg)</directive>
</indent>
</VirtualHost>
</example></p>
<p>Example 1:<br />
With requests matching <code>^/dir1/images/</code>, testing is done in the following order:<ol>
<li>criteria_eee</li>
<li>criteria_fff</li>
<li>criteria_bbb</li>
<li>criteria_ccc</li>
<li>criteria_aaa</li>
<li>criteria_ddd</li></ol>
Behavior concerning criteria_ggg is undefined since it is defined in a more general context and below the matching directory.</p>
<p>Example 2:<br />
With requests matching <code>^/dir1/</code> (but not matching <code>^/dir1/images/</code>), testing is done in the following order:<ol>
<li>criteria_bbb</li>
<li>criteria_ccc</li>
<li>criteria_aaa</li></ol>
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>
<p>Example 3:<br />
With requests matching the <VirtualHost> (but not matching <code>^/dir1/images/</code> or <code>^/dir1/</code>), testing is done in the following order:<ol>
<li>criteria_aaa</li>
<li>criteria_ddd</li>
<li>criteria_ggg</li></ol>
Behavior concerning criteria_ddd and criteria_ggg is predictable and normal within this set of requests.</p>
<p>For reference below, the IP values returned by http:BL's DNSBL are in the format:<br />
<code>127.X.Y.Z</code><br />
Where:<ul>
<li>X - The number of days [0-255] since activity from the IP has been observed.</li>
<li>Y - A score [0-255] which describes how "threatening" the IP is (at the current time).</li>
<li>Z - A bitmask [0-255] of the categories this IP matches (i.e. search engine, harvester, comment spammer, generally suspicious).</li></ul><br />
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>
<p>The actual criteria generation is simple but the syntax is prone to errors.
A wizard will be available soon for HTTPBLRBLReqHandler directive generation.</p>
<p>There are five parameters acctepted by the RBLReqHandler directives:<ol>
<li>The "HTTP method" bitset</li>
<li>The "Days since last activity" range</li>
<li>The "Score" range</li>
<li>The "Offender category" bitset</li>
<li>The action to take, should the <directive>HTTPBLRBLReqHandler</directive> match the DNSBL value of the requesting IP</li></ol><br />
The first four parameters are separated by colons (:), while the fourth and fifth are seperated by a space ( ).<br />
<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.
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 />
<strong>ranges</strong> are two integers seperated by a hyphen (-) The former integer MUST be no greater than the latter (i.e. given range "A-B", A must be <= B).<br />
<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>
<p>A example RBLReqHandler (provided for discussion) is as follows:<br />
<code>HTTPBLRBLReqHandler [A]:[B]-[C]:[D]-[E]:[F] ACTION_STRING</code><br />
Explanations of the integers (represented by [A] thru [F] are as follows:<ul>
<li>[A] - A bitmask [0-255] of the HTTP methods (in decimal representation) which should match. Method decimal values:<ul>
<li>1 - GET</li>
<li>2 - POST</li>
<li>4 - HEAD</li>
<li>8 - PUT</li>
<li>16 - DELETE</li>
<li>32 - Reserved for future use</li>
<li>128 - Reserved for future use</li>
<li>128 - Reserved for future use</li></ul><br />
It is recommended that you leave this value as 255 (match all methods) unless you want very-fine control of IP authorization.</li>
<li>[B] - The lower bound for DNSBL value octet 2 (X in the example DNSBL value above)</li>
<li>[C] - The upper bound for DNSBL value octet 2 (X in the example DNSBL value above);<br />
[C], and the hypen ("-") which preceeds it are now optional. This means that ranges can be a single number.</li>
<li>[D] - The lower bound for DNSBL value octet 3 (Y in the example DNSBL value above)</li>
<li>[E] - The upper bound for DNSBL value octet 3 (Y in the example DNSBL value above);<br />
[E], and the hypen ("-") which preceeds it are now optional. This means that ranges can be a single number.</li>
<li>[F] - A bitmask [0-255] of the offending type (in decimal representation) which should match. Type decimal values:<ul>
<li>1 - Generally suspicious IP (no offensive actions seen, <strong>yet</strong>)</li>
<li>2 - A known harvester</li>
<li>4 - A comment spammer</li>
<li>8 - A known exploiter</li>
<li>16 - Reserved for future use</li>
<li>32 - Reserved for future use</li>
<li>64 - Reserved for future use</li>
<li>128 - Reserved for future use</li></ul><br />
<strong>If no bits are set (DNSBL octet 4 is 0), then the IP is of a known search engine.</strong><br />
If this is the case, then DNSBL octet 3 (Y, above) is not a score counter, but rather a "serial number" for the search engine (refer to <a href="http://www.projecthoneypot.org/">Procjet Honey Pot's website</a> for details).</li></ul></p>
<example><title>Specific Examples:</title>
# Serve all search engines, but replace email address text and links in HTML content.<br />
HTTPBLRBLReqHandler 255:0-255:0-255:0 allow-xlate-emails<br />
<br />
# Deny known comment spammers the ability to POST.<br />
HTTPBLRBLReqHandler 2:0-255:0-255:4 deny<br />
<br />
# Serve all harvesters, but replace email address text and links in HTML content.<br />
HTTPBLRBLReqHandler 255:0-255:0-255:2 allow-xlate-emails<br />
<br />
# Deny known exploiters the ability to request via HTTP method HEAD<br />
HTTPBLRBLReqHandler 4:0-255:0-255:8 deny<br />
<br />
# Send mildly offensive IPs to a challenge page, if they pass the "captcha", whitelist them for the duration of the blocking_period.<br />
HTTPBLRBLReqHandler challenge<br />
<br />
# Deny any requests originating from IPs known to Project Honey Pot to be suspicious or offensive.<br />
HTTPBLRBLReqHandler 255:0-255:0-255:deny<br /></example>
</usage>
</directivesynopsis>
</modulesynopsis>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
2f1b9e471d338bdd6dbc8cda30274d25
>
files
>
5
