.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (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
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "Mail::SpamAssassin::Plugin::Redirectors 3"
.TH Mail::SpamAssassin::Plugin::Redirectors 3 2025-12-13 "perl v5.42.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
Redirectors \- Check for redirected URLs
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  loadplugin    Mail::SpamAssassin::Plugin::Redirectors
\&
\&  url_redirector bing.com
\&
\&  body HAS_REDIR_URL          eval:redir_url()
\&  describe HAS_REDIR_URL      Message has one or more redirected URLs
\&
\&  body REDIR_URL_CHAINED      eval:redir_url_chained()
\&  describe REDIR_URL_CHAINED  Message has redirected URL chained to other redirectors
\&
\&  body REDIR_URL_CHAINED_DOM      eval:redir_url_chained_domain()
\&  describe REDIR_URL_CHAINED_DOM  Message has redirected URL chained to another redirector on the same domain
\&
\&  body REDIR_URL_MAXCHAIN     eval:redir_url_maxchain()
\&  describe REDIR_URL_MAXCHAIN Message has redirected URL that causes too many redirections
\&
\&  body REDIR_URL_LOOP         eval:redir_url_loop()
\&  describe REDIR_URL_LOOP     Message has redirected URL that loops back to itself
\&
\&  body REDIR_URL_404          eval:redir_url_code(\*(Aq404\*(Aq) # Can check any non\-redirect HTTP code
\&  describe REDIR_URL_404      Message has redirected URL returning HTTP 404
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This plugin looks for URLs redirected by a list of URL redirector services. 
Upon finding a matching URL, plugin will send a HTTP request to the
redirector service and retrieve the Location\-header which points to the
actual redirected URL.  It then adds this URL to the list of URIs extracted
by SpamAssassin which can then be accessed by uri rules and plugins such as
URIDNSBL.
.PP
This plugin will follow chained redirections, where a redirected URL redirects to
another redirector.  Redirection depth limit can be set with
\&\f(CW\*(C`max_redir_url_redirections\*(C'\fR.
.PP
Maximum of \f(CW\*(C`max_redir_urls\*(C'\fR redirected URLs are checked in a message (10 by
default).  Setting it to 0 disables HTTP requests, allowing only \fBredir_url()\fR
test to work and report found redirectors.
.PP
All supported rule types for checking redirector URLs and redirection status are
documented in SYNOPSIS section.
.SH NOTES
.IX Header "NOTES"
This plugin runs before priority 0 so that it may
modify the parsed URI list prior to normal uri rules or the URIDNSBL plugin.
It should run before DecodeShortURLs plugin so that redirected short uris are also
checked.
.SH "USER SETTINGS"
.IX Header "USER SETTINGS"
.IP "url_redirector  domain [domain...]     (default: none)" 4
.IX Item "url_redirector domain [domain...] (default: none)"
Domains that should be considered as an URL redirector.  If the domain begins
with a \*(Aq.\*(Aq, 3rd level tld of the main domain will be checked.
The 3rd level starting with www with always be checked for every 2tld.
.Sp
Example:
.Sp
.Vb 2
\& url_redirector bing.com
\& url_redirector .sendgrid.com
.Ve
.IP "clear_url_redirector  [domain] [domain...]" 4
.IX Item "clear_url_redirector [domain] [domain...]"
Clear configured url_redirector domains, for example to
override default settings from an update channel.  If domains are specified,
then only those are removed from list.
.IP "url_redirector_get  domain [domain...]     (default: none)" 4
.IX Item "url_redirector_get domain [domain...] (default: none)"
Domains that should be considered as an URL redirector.  If the domain begins
with a \*(Aq.\*(Aq, 3rd level tld of the main domain will be checked.
The http GET method will be used to check those domains.
.IP "url_redirector_params regexp (default: (?:adurl|af_web_dp|cm_destination|continue|destination|destURL|h|l|login|location|p1|pval|r|redir|redirect|redirectTo|return|returnUrl|referer|service|target|tid|u|url)=(.*))" 4
.IX Item "url_redirector_params regexp (default: (?:adurl|af_web_dp|cm_destination|continue|destination|destURL|h|l|login|location|p1|pval|r|redir|redirect|redirectTo|return|returnUrl|referer|service|target|tid|u|url)=(.*))"
Regexp used to parse uri parameters in order to detect redirectors and to get redirected domains.
The regexp must match only the redirected domain.
.SH "PRIVILEGED SETTINGS"
.IX Header "PRIVILEGED SETTINGS"
.IP "url_redirector_cache_type     (default: none)" 4
.IX Item "url_redirector_cache_type (default: none)"
The cache type that is being utilized.  Currently only supported value is
\&\f(CW\*(C`dbi\*(C'\fR that implies \f(CW\*(C`url_redirector_cache_dsn\*(C'\fR is a DBI connect string.
DBI module is required.
.Sp
Example:
url_redirector_cache_type dbi
.IP "url_redirector_cache_dsn		(default: none)" 4
.IX Item "url_redirector_cache_dsn (default: none)"
The DBI dsn of the database to use.
.Sp
For SQLite, the database will be created automatically if it does not
already exist, the supplied path and file must be read/writable by the
user running spamassassin or spamd.
.Sp
For MySQL/MariaDB or PostgreSQL, see sql\-directory for database table
creation clauses.
.Sp
You will need to have the proper DBI module for your database.  For example
DBD::SQLite, DBD::mysql, DBD::MariaDB or DBD::Pg.
.Sp
Minimum required SQLite version is 3.24.0 (available from DBD::SQLite 1.59_01).
.Sp
Examples:
.Sp
.Vb 1
\& url_redirector_cache_dsn dbi:SQLite:dbname=/var/lib/spamassassin/Redirectors.db
.Ve
.IP "url_redirector_cache_username  (default: none)" 4
.IX Item "url_redirector_cache_username (default: none)"
The username that should be used to connect to the database.  Not used for
SQLite.
.IP "url_redirector_cache_password  (default: none)" 4
.IX Item "url_redirector_cache_password (default: none)"
The password that should be used to connect to the database.  Not used for
SQLite.
.IP "url_redirector_cache_ttl		(default: 86400)" 4
.IX Item "url_redirector_cache_ttl (default: 86400)"
The length of time a cache entry will be valid for in seconds.
Default is 86400 (1 day).
.Sp
See \f(CW\*(C`url_redirector_cache_autoclean\*(C'\fR for database cleaning.
.SH "ADMINISTRATOR SETTINGS"
.IX Header "ADMINISTRATOR SETTINGS"
.IP "url_redirector_cache_autoclean	(default: 1000)" 4
.IX Item "url_redirector_cache_autoclean (default: 1000)"
Automatically purge old entries from database.  Value describes a random run
chance of 1/x.  The default value of 1000 means that cleaning is run
approximately once for every 1000 messages processed.  Value of 1 would mean
database is cleaned every time a message is processed.
.Sp
Set 0 to disable automatic cleaning and to do it manually.
.IP "url_redirector_loginfo           (default: 0 (off))" 4
.IX Item "url_redirector_loginfo (default: 0 (off))"
If this option is enabled (set to 1), then redirected URLs and the decoded URLs will be logged with info priority.
.IP "url_redirector_timeout     (default: 5)" 4
.IX Item "url_redirector_timeout (default: 5)"
Maximum time a redirection URL HTTP request can take, in seconds.
.IP "max_redir_urls                 (default: 10)" 4
.IX Item "max_redir_urls (default: 10)"
Maximum amount of redirector URLs that will be looked up per message.  Chained
redirections are not counted, only initial redirection URLs found.
.Sp
Setting it to 0 disables HTTP requests, allowing only \fBredir_url()\fR test to
work and report any found redirector URLs.
.IP "max_redir_url_redirections     (default: 10)" 4
.IX Item "max_redir_url_redirections (default: 10)"
Maximum depth of chained redirections that a redirector can generate.
.IP "url_redirector_user_agent       (default: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.67 Safari/537.36)" 4
.IX Item "url_redirector_user_agent (default: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.67 Safari/537.36)"
Set User\-Agent header for HTTP requests.  Some services require it to look
like a common browser.