.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mail::SpamAssassin::Plugin::URILocalBL 3"
.TH Mail::SpamAssassin::Plugin::URILocalBL 3 2024-09-01 "perl v5.40.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
URILocalBL \- blocklist URIs using local information (ISP names, address lists, and country codes)
.SH SYNOPSIS
.IX Header "SYNOPSIS"
This plugin creates some new rule test types, such as "uri_block_cc",
"uri_block_cidr", and "uri_block_isp".  These rules apply to the URIs
found in the HTML portion of a message, i.e. <a href=...> markup.
.PP
.Vb 1
\&  loadplugin    Mail::SpamAssassin::Plugin::URILocalBL
.Ve
.PP
Why local blocklisting? There are a few excellent, effective, and
well-maintained DNSBL's out there. But they have several drawbacks:
.IP \(bu 2
blocklists can cover tens of thousands of entries, and you can't select which ones you use;
.IP \(bu 2
verifying that it's correctly configured can be non-trivial;
.IP \(bu 2
new blocklisting entries may take a while to be detected and entered, so it's not instantaneous.
.PP
Sometimes all you want is a quick, easy, and very surgical blocklisting of
a particular site or a particular ISP. This plugin is defined for that
exact usage case.
.SH "RULE DEFINITIONS AND PRIVILEGED SETTINGS"
.IX Header "RULE DEFINITIONS AND PRIVILEGED SETTINGS"
The format for defining a rule is as follows:
.PP
.Vb 2
\&  uri_block_cc SYMBOLIC_TEST_NAME cc1 cc2 cc3 cc4 ..
\&  uri_block_cc SYMBOLIC_TEST_NAME !cc1 !cc2 ..
.Ve
.PP
or:
.PP
.Vb 2
\&  uri_block_cont SYMBOLIC_TEST_NAME co1 co2 co3 co4 ..
\&  uri_block_cont SYMBOLIC_TEST_NAME !co1 !co2 ..
.Ve
.PP
or:
.PP
.Vb 1
\&  uri_block_cidr SYMBOLIC_TEST_NAME a.a.a.a b.b.b.b/cc
.Ve
.PP
or:
.PP
.Vb 1
\&  uri_block_isp SYMBOLIC_TEST_NAME "Data Rancid" McCarrier Phishers\-r\-Us
.Ve
.PP
Example rule for matching a URI in China:
.PP
.Vb 1
\&  uri_block_cc TEST1 cn
.Ve
.PP
If you specify list of negations, such rule will match ANY country except
the listed ones (Finland, Sweden):
.PP
.Vb 1
\&  uri_block_cc TEST1 !fi !se
.Ve
.PP
Continents uri_block_cont works exactly the same as uri_block_cc.
.PP
This would block the URL http://www.baidu.com/index.htm.  Similarly, to
match a Spam-haven netblock:
.PP
.Vb 1
\&  uri_block_cidr TEST2 65.181.64.0/18
.Ve
.PP
would match a netblock where several phishing sites were recently hosted.
.PP
And to block all CIDR blocks registered to an ISP, one might use:
.PP
.Vb 1
\&  uri_block_isp TEST3 "Data Rancid" ColoCrossing
.Ve
.PP
Quote ISP names containing spaces.
.PP
Lastly, if there's a country that you want to block but there's an explicit
host you wish to exempt from that blocklist, you can use:
.PP
.Vb 1
\&  uri_block_exclude TEST1 www.baidu.com
.Ve
.PP
if you wish to exempt URL's referring to this host. The same syntax is
applicable to CIDR and ISP blocks as well.
.SH DEPENDENCIES
.IX Header "DEPENDENCIES"
The Country-Code based filtering can use any Mail::SpamAssassin::GeoDB
supported module like MaxMind::DB::Reader (GeoIP2) or Geo::IP.  ISP based
filtering might require a paid subscription database like GeoIPISP.