.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" 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 .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . 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 .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "MTPOLICYD 1p" .TH MTPOLICYD 1p "2017-01-13" "perl v5.24.1" "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" mtpolicyd \- the mtpolicyd executable .SH "VERSION" .IX Header "VERSION" version 2.02 .SH "DESCRIPTION" .IX Header "DESCRIPTION" mtpolicyd is a policy daemon for postfix access delegation. .PP It can be configured to accept connections on several ports from a postfix mta. For each port a VirtualHost can be configured and for each VirtualHost several Plugins can be configured. .PP For more info, mailing list, see: .SH "NAME" mtpolicyd \- a modular policy daemon for postfix .SH "EXAMPLE" .IX Header "EXAMPLE" In postfix main.cf: .PP .Vb 1 \& smtpd_recipient_restrictions = check_policy_service inet:127.0.0.1:12345 .Ve .PP In mtpolicyd.conf: .PP .Vb 2 \& # listen on port 12345 (multiple ports can be separated by \*(Aq,\*(Aq) \& port="127.0.0.1:12345" \& \& # defined host for this port \& \& name=example_vhost \& \& module="RBL" \& domain="sbl.spamhaus.org" \& mode=reject \& \& .Ve .PP This check will execute a simple \s-1RBL\s0 lookup against dbl.spamhaus.org. .SH "COMMANDLINE OPTIONS" .IX Header "COMMANDLINE OPTIONS" .Vb 6 \& mtpolicyd \& [\-h|\-\-help] \& [\-c|\-\-config=] \& [\-f|\-\-foreground] \& [\-l|\-\-loglevel=] \& [\-d|\-\-dump_vhosts] .Ve .IP "\-h \-\-help" 4 .IX Item "-h --help" Show available command line options. .IP "\-c \-\-config= (default: /etc/mtpolicyd/mtpolicyd.conf)" 4 .IX Item "-c --config= (default: /etc/mtpolicyd/mtpolicyd.conf)" Specifiy the path to the configuration file. .IP "\-f \-\-foreground" 4 .IX Item "-f --foreground" Do not fork to background and log to stdout. .IP "\-l \-\-loglevel=" 4 .IX Item "-l --loglevel=" Overwrite the log level specified in the configuration with the specified level. .IP "\-d \-\-dump_vhosts" 4 .IX Item "-d --dump_vhosts" Parse VirtualHosts configuration, print it to stdout and exit. .SH "CONFIGURATION FILE" .IX Header "CONFIGURATION FILE" The configuration file is implementend with Config::General which allows apache style configuration files. .PP mtpolicyd accepts global configuration parameters in the style: .PP .Vb 1 \& key=value .Ve .PP Comments begin with '#'. .PP VirtualHosts must be configured with VirtualHost sections: .PP .Vb 3 \& > \& name= \& .Ve .PP Each VirtualHost should contain at least on Plugin. .PP .Vb 8 \& > \& name= \& > \& module = "" \& # plugin options \& key=value \& \& .Ve .PP For individual plugin configuration options see the man page of the plugin: .PP .Vb 1 \& Mail::MtPolicyd::Plugin:: .Ve .SS "\s-1GLOBAL CONFIGURATION OPTIONS\s0" .IX Subsection "GLOBAL CONFIGURATION OPTIONS" .IP "user" 4 .IX Item "user" user id to run as .IP "group" 4 .IX Item "group" group id to run as .IP "pid_file" 4 .IX Item "pid_file" location of the pid file .IP "log_level" 4 .IX Item "log_level" Verbosity of logging: 0=>'err', 1=>'warning', 2=>'notice', 3=>'info', 4=>'debug' .IP "host" 4 .IX Item "host" ip address to bind to. .IP "port" 4 .IX Item "port" comma separated list of ports to listen on. .IP "min_servers (default: 4)" 4 .IX Item "min_servers (default: 4)" The minimum number of client processes to start. .IP "min_spare_servers (default: 4)" 4 .IX Item "min_spare_servers (default: 4)" The minimum number of client processes that should hanging around idle and wait for new connections. .Sp If the number of free processes is below this threshold mtpolicyd will start to create new child processes. .IP "max_spare_servers (default: 12)" 4 .IX Item "max_spare_servers (default: 12)" The maximum number of idle processes. .Sp If the number of idle processes is over this threshold mtpolicyd will start to shutdown child processes. .IP "max_servers (default: 25)" 4 .IX Item "max_servers (default: 25)" The absolute maximum number of child processes to start. .IP "max_requests (default: 1000)" 4 .IX Item "max_requests (default: 1000)" .PD 0 .IP "max_keepalive (default: 0)" 4 .IX Item "max_keepalive (default: 0)" .PD Number of requests after that mtpolicyd closes the connection or no limit if set to zero. .Sp Should be the same value as smtpd_policy_service_reuse_count_limit (postfix >2.12) in postfix/smtpd configuration. .IP "vhost_by_policy_context (default: 0)" 4 .IX Item "vhost_by_policy_context (default: 0)" Select VirtualHost by 'policy_context' request field. .Sp The policy_context will be matched against the 'name' field of the VirtualHost. .Sp For example in postfix main.cf use advanced syntax: .Sp .Vb 3 \& check_policy_service { inet:localhost:12345, policy_context=reputation } \& ... \& check_policy_service { inet:localhost:12345, policy_context=accounting } .Ve .Sp In mtpolicyd.conf: .Sp .Vb 6 \& port="127.0.0.1:12345" # only 1 port \& vhost_by_policy_context=1 \& \& name=reputation \& ... plugins ... \& \& \& \& name=accounting \& ... plugins ... \& .Ve .Sp The policy_context feature will be available in postfix 3.1 and later. .Sp If you just need small differentiations consider using the Mail::MtPolicyd::Plugin::Condition plugin to match against plugin_context field. .IP "request_timeout" 4 .IX Item "request_timeout" Maximum total time for one request. .SH "CONFIGURE CONNECTIONS" .IX Header "CONFIGURE CONNECTIONS" mtpolicyd has a global per process connection pool. .PP Connections could be registered within the connection pool using a block within the configuration. You must at least specify the name of the connection and the module for the connection type. .PP .Vb 4 \& \& module = "[connection type]" \& # ... addditional parameters \& .Ve .PP Connection modules may require additional parameters. .PP Currently supported connection modules: .IP "Sql" 4 .IX Item "Sql" Perl \s-1DBI\s0 based connections for \s-1SQL\s0 databases. .Sp Mail::MtPolicyd::Connection::Sql .IP "Memcached" 4 .IX Item "Memcached" Connection to a memcached server/cluster. .Sp Mail::MtPolicyd::Connection::Memcached .IP "Ldap" 4 .IX Item "Ldap" Connection to an \s-1LDAP\s0 directory server. .Sp Mail::MtPolicyd::Connection::Ldap .SH "SESSION MANAGEMENT" .IX Header "SESSION MANAGEMENT" mtpolicyd implements session managemend to cache data across different checks for requests with the same instance id. .PP mtpolicy is able to generate a session for each mail passed to it and store it within the session cache. The attached session information will be available to all following plugins across child processes, virtual hosts and ports. .PP Plugins will use this session information to cache lookup etc. across multiple requests for the same mail. Postfix will send a query for each recipient and for each configured check_policy_service call. .PP To enable the SessionCache specify a block within your configuration: .PP .Vb 7 \& \& module = "Memcached" \& expire = "300" \& lock_wait=50 \& lock_max_retry=50 \& lock_timeout=10 \& .Ve .PP The example requires that a connection of type \*(L"Memcached\*(R" and the name \&\*(L"memcached\*(R" is configured within the connection pool. For details read Mail::MtPolicyd::SessionCache::Memcached. .PP As of version 2.00 it is possible to implement different session caches. .PP Currently there are 2 session cache modules: .IP "Mail::MtPolicyd::SessionCache::Memcached" 4 .IX Item "Mail::MtPolicyd::SessionCache::Memcached" .PD 0 .IP "Mail::MtPolicyd::SessionCache::Redis" 4 .IX Item "Mail::MtPolicyd::SessionCache::Redis" .PD .SH "PROCESSING OF REQUEST" .IX Header "PROCESSING OF REQUEST" The policy daemon will process all plugins in the order they appear in the configuration file. It will stop as soon as a plugin returns an action and will return this action to the \s-1MTA.\s0 .SH "SCORING" .IX Header "SCORING" Most plugins can be configured to not return an action if the performed check matched. .PP For example the \s-1RBL\s0 module could be set to passive mode and instead a score could be applied to the request: .PP .Vb 6 \& \& module = "RBL" \& mode = "passive" \& domain="zen.spamhaus.org" \& score=5 \& .Ve .PP Check the documentation of the plugin for certain score/mode parameters. Plugin may provide more than one mode/score parameters if the do several checks. .PP Now if you configure more than one \s-1RBL\s0 check the score will add up. Later an action can be taken based on the score. The ScoreAction plugin will return an action based on the score and the AddScoreHeader plugin will prepend the score as a header to the mail: .PP .Vb 9 \& \& module = "ScoreAction" \& threshold = 15 \& action = "reject sender ip %IP% is blocked (score=%SCORE%%SCORE_DETAIL%)" \& \& \& module = "AddScoreHeader" \& spam_score=5 \& .Ve .SH "UPGRADING" .IX Header "UPGRADING" .SS "\s-1FROM 1\s0.x to 2.x" .IX Subsection "FROM 1.x to 2.x" With mtpolicyd 2.x configuration of connections and session cache has been changed. .PP \fIDatabase Connections\fR .IX Subsection "Database Connections" .PP In mtpolicyd 2.00 the connections defined globaly in the configuration file have been replaced by a dynamic connection pool. .PP The global options db_* ldap_* and memcached_* have been removed. .PP Instead connections are registred within a connection pool. .PP You can define them using blocks: .PP .Vb 5 \& \& module = "" \& # parameter = "value" \& # ... \& .Ve .PP In mtpolicyd 1.x: .PP .Vb 3 \& db_dsn=DBI:mysql:mtpolicyd \& db_user=mtpolicyd \& db_password=secret .Ve .PP In mtpolicyd 2.x: .PP .Vb 5 \& \& dsn = "DBI:mysql:mtpolicyd" \& user = "mtpolicyd" \& password = "secret" \& .Ve .PP All \s-1SQL\s0 modules will by default use the connection registred as \*(L"db\*(R". .PP See modules in Mail::MtPolicyd::Connection::* for available connection adapters. .PP \fISession Cache\fR .IX Subsection "Session Cache" .PP Starting with mtpolicyd 2.x it is possible to use other session caches then memcached. .PP The global session_* parameters have been removed. .PP Instead the session cache is defined by a block: .PP .Vb 5 \& \& module = "" \& # parameter = "value" \& # ... \& .Ve .PP A memcached session cache in mtpolicyd v1.x: .PP .Vb 1 \& memcached_servers="127.0.0.1:11211" \& \& session_lock_wait=50 \& session_lock_max_retry=50 \& session_lock_timeout=10 .Ve .PP In mtpolicyd 2.x: .PP .Vb 3 \& \& servers = "127.0.0.1:11211" \& \& \& \& module = "Memcached" \& # defaults to connection "memcached" \& # memcached = "memcached" \& lock_wait = "50" \& lock_max_retry = "50" \& lock_timeout = "10" \& .Ve .PP If no is defined it will default to the dummy session cache module \*(L"None\*(R". .PP See modules in Mail::MtPolicyd::SessionCache::* for available session cache modules. .SH "AUTHOR" .IX Header "AUTHOR" Markus Benning .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is Copyright (c) 2014 by Markus Benning . .PP This is free software, licensed under: .PP .Vb 1 \& The GNU General Public License, Version 2, June 1991 .Ve