Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
greylist.conf(5)					      greylist.conf(5)

NAME
       greylist.conf - milter-greylist configuration file

DESCRIPTION
       greylist.conf  configures  milter-greylist(8)  operation. The format is
       simple: each line contains a keyword and	optional arguments.  Any  line
       starting	 with  a  #  is	 considered as a comment and is	ignored. Blank
       lines are ignored as well. Comments at the end of lines are accepted in
       some  situations,  but do not take them as granted.  A statement	can be
       continued on the	next line by using a  backslash.  Anything  after  the
       backslash will be ignored.

WHITELIST
       The  primary  use  of  greylist.conf  is	 to  setup  milter-greylist(8)
       whitelist. It also offers  a  handy  blacklist  feature.	  Access-lists
       (ACL) are used to do that. ACL enable the administrator to specify com-
       plex conditions on sender IP, sender DNS	 address,  sender  e-mail  ad-
       dress,  and  recipient e-mail address. If support for DNSRBL was	built-
       in, it is even possible to use DNSRBL in	ACL.

       An access-list entry starts with	the racl keyword followed  by  an  op-
       tional  id  quoted  string, then	the greylist, whitelist, blacklist, or
       continue	keyword, and by	any set	of the following  clauses:  addr,  do-
       main,  from, rawfrom, rcpt, rcptcount, helo, sm_macro, time, auth, tls,
       spf (if build with SPF support),	geoip (if build	with  GeoIP  support),
       p0f (if build with p0f support),	ldapcheck (if build with --with-openl-
       dap), urlcheck (if built	with --with-libcurl), dnsrbl  (if  built  with
       --enable-dnsrbl),  and  nsupdate	(if supported by the DNS resolver).  A
       message will match an ACL entry	when  it  complies  with  all  of  its
       clauses.

       The  greylist, whitelist, and blacklist keywords	will cause the message
       to be respectively greylisted, accepted or rejected if all ACL  clauses
       match,  and ACL evaluation is terminated	there. If an ACL with continue
       keyword does match, nothing is decided and next ACL are evaluated.

       Clauses can be negated, by prefixing them by the	not keyword.  Here  is
       the detail of all possible clauses.

       addr   This  clause  is	used  to  specify  a netblock of source	IP ad-
	      dresses. The syntax is an	IP address followed by a slash	and  a
	      CIDR netmask. Here is an example:

		racl whitelist addr 127.0.0.0/8
		racl whitelist addr 192.168.3.0/24
		racl whitelist addr ::1

	      If  the  netmask	is omitted, /32	is assumed for an IPv4 address
	      and /128 is assumed for an IPv6 address.

	      You should at least whitelist localhost  (127.0.0.1/8),  and  if
	      you have some user clients connecting to the machine, you	should
	      whitelist	the addresses they connect from	if you don't want them
	      to get error messages when sending e-mail.

       domain This  clause  selects  source  machines based on their DNS name,
	      performing a suffix search.  For instance, this  will  whitelist
	      any machine in the example.net domain:

		racl whitelist domain example.net

	      Suffix  search  matching	 means,	for example, that gle.com will
	      match google.com.	If you want domain names to match on subdomain
	      boundaries  (e.g.	  gle.com  will	match mail.gle.com and gle.com
	      but not google.com) then enable domainexact

       The name	resolution is made by Sendmail,	 which	hands  it  to  milter-
       greylist(8).  As	a result, it is	impossible to use DNS aliases here. On
       the other hand, this will work even if your DNS resolver	is not thread-
       safe.

       from   This  is	used  to select	sender e-mail addresses	You should not
	      use that feature,	because	sender e-mail addresses	can  be	 triv-
	      ially forged.

	      Please  note  that  the sender e-mail is cleared from spaces and
	      anything leading an equal	(=) sign so that mailing-lists return-
	      address  with  unique return paths can still match.  If you need
	      unedited sender address, use a rawfrom clause.

	      Here is an example:

		racl whitelist from postmaster@example.com

       rawfrom
	      Same as from but the sender e-mail address is  not  modified  to
	      stip anything.  rcpt This	is used	to select recipient addresses.
	      Example:

		racl greylist rcpt John.Doe@example.net

       rcptcount
	      Followed by an operator and a recipient count, this is  used  to
	      select the amount	of recipients. Example:

		racl  blacklist	 rcptcount  >= 25 msg "No more than 25 recipi-
	      ents, please"

       helo   Followed by a quoted string or a regular expression, this	can be
	      used to filter on	the HELO string.

       sm_macro
	      This  is	used to	select a Sendmail macro	value. See the section
	      on that topic for	more information.

       time   This is used to specify a	time set. It should be followed	 by  a
	      quoted  string of	crontab(5)-like	time specification. Here is an
	      example that whitelists mail addressed  to  a  single  recipient
	      during office hours (from	8:00 to	16:59 from monday to friday):

		racl whitelist time "* 8-16 * *	1-5" rcpt info@example.net

       geoip  This  is	used  to  specify a country, as	reported by GeoIP. The
	      country code must	be upper case, and is only available  if  mil-
	      ter-greylist  was	built with GeoIP support. Special country code
	      ZZ is used when the country cannot be determined	(this  happens
	      for  private addresses, for instance). The geoipdb statement can
	      be used to specify the location of  GeoIP	 database.   geoipv6db
	      statement	 can  be used to specify the location of GeoIPv6 data-
	      base.  geoip2db statement	can be used to specify the location of
	      GeoIP2 (maxminddb) database.

       p0f    This  is	used to	match against the remote system	OS fingerprint
	      genre and	detail,obtained	from p0f. It is	only available if mil-
	      ter-greylist  was	 built	with  p0f support.  p0f	clauses	can be
	      used with	a quoted string	for case-insensitive substring	match,
	      or  against  regular  expressions.  The p0fsock statement	can be
	      used to specify the location of the p0f socket.

       auth   This is used to select a user that succeeded SMTP	AUTH. In order
	      to  select any user that succeeds	SMTP AUTH, you can use a regu-
	      lar expression matching, like below;

		racl whitelist auth /.*/

	      Using such a clause automatically	disable	 global	 STARTTLS  and
	      SMTP  AUTH  whitelisting,	 like if the noauth keyword would have
	      been used.

       tls    This is used to select the distinguished name  (DN)  of  a  user
	      that  succeeded STARTTLS.	Using such a clause automatically dis-
	      able global STARTTLS and SMTP AUTH  whitelisting,	 like  if  the
	      noauth keyword would have	been used.

       spf    This is used to test SPF status. Possible	values are pass, soft-
	      fail, fail, neutral, unknown, error, none, and self.  The	 first
	      seven  values are	plain SPF validation status. The self value is
	      a	special	test that checks the server's local IP address against
	      the  sender's  SPF record. If that test validates, odds are good
	      that the sender SPF record is wide open, and this	is  hint  that
	      SPF should not be	trusted.

	      In  order	 to use	spf self, Postfix users	must specify the local
	      address in the configuration file, using the localaddr option.

	      Absence of any value after the spf keyword is a synonym for  spf
	      pass.  This is present for backward compatibility.

	      The spf clause is	only available if SPF support was compiled in.
	      Using it will disable global SPF whitelisting, like if the nospf
	      keyword would have been used.

       ldapcheck
	      This  is	used  to  query	an LDAP	directory.  See	the section on
	      that topic for more information.

       urlcheck
	      This is used to query an external	configuration  source  through
	      an URL.  See the section on that topic for more information.

       dnsrbl This  is	used to	select a DNSRBL. See the section on that topic
	      for more information.

       nsupdate
	      This always-matching clause performs a DNS update, see the  sec-
	      tion on that topic for more information.

       The  domain,  from,  and	 rcpt clauses may be used with regular expres-
       sions. The regular expressions must be enclosed by slashes (/). No  es-
       caping  is available to provide a slash inside a	regular	expression, so
       just do not use it. Regular expressions follow the format described  in
       re_format(7).  Here is an example:

	 racl greylist rcpt /@example\.net$/

       When  regular  expressions  are not used, from, and rcpt	perform	a case
       insensitive substring match with	leading	and trailing brackets,	spaces
       and  tabs  stripped  out.   domain  performs  a case insensitive	suffix
       match.  This means, for example,	that gle.com will match	google.com. If
       you  want  domain names to match	on subdomain boundaries	(e.g.  gle.com
       will match mail.gle.com and gle.com but not google.com) then enable do-
       mainexact

       An  ACL	entry  can also	hold various optional parameter	used on	match:
       delay, autowhite, flushaddr, nolog, code, ecode,	report,	 maxpeek,  ad-
       dheader,	addfooter, and msg

       delay  Specify the greylisting delay used before	the message can	be ac-
	      cepted.  This overrides the greylist global setting, and it only
	      makes sense on an	racl greylist entry.

       autowhite
	      Specify the autowhitelisting duration for	messages matching this
	      ACL.  This overrides the autowhite global	setting, and  it  only
	      makes sense on an	racl greylist entry. Example:

		racl greylist rcpt JDoe@example.net delay 15m autowhite	3d
		racl greylist rcpt root@example.net delay 1h autowhite 3d

       flushaddr
	      If  a message matches the	rule, any entry	in the greylist	or au-
	      towhite databases	matching the sender IP is removed. Used	with a
	      DNSRBL blacklist ACL, it is useful for freeing the database from
	      entries set up by	a machine which	is known to be a spammer.  Ex-
	      ample:

		racl blacklist dnsrbl "known-spammer" flushaddr

       nolog  Do not generate syslog message if	this rule matches. Example:

		racl whitelist default nolog

       code

       ecode

       msg    These  3	values	can  be	used to	choose the SMTP	code, extended
	      code and reply message for temporary failures and	rejects. Exam-
	      ple:

		racl blacklist dnsrbl "spamstomp" msg "IP caught by spamstomp"
		racl greylist default code "451" ecode "4.7.1"

	      The msg strings accepts format string substitution as documented
	      in the FORMAT STRINGS section. For instance, %A gets substituted
	      by the ACL line number.

	      None of the last 3 values	makes sense for	a whitelist entry.

       report This  value  overrides  the  text	 displayed  in	the X-Greylist
	      header, for messages that	milter-greylist(8) lets	pass  through,
	      either  because  they  are  whitelisted,	or because they	passed
	      greylisting (see REPORTING).  This string	can be substituted  as
	      documented in the	FORMAT STRINGS section.

       maxpeek
	      This  parameter  only  makes sense in a RCPT-stage ACL. It over-
	      rides the	global maxpeek setting for DATA-stage handling of  the
	      message. It has no effect	if global maxpeek is set to 0.

       addheader
	      This  quoted  string  is	a RFC822 header	that gets added	to the
	      message.	Format string substitution is supported. No  check  is
	      done  for	 header	 length	 standard compliance, so make sure the
	      substituted string is shorter than 2048 characters. Headers  are
	      appended to the bottom, unless an	optionnal comma-separated pos-
	      itive index is specified after the quoted	string;	in  this  case
	      the  header  will	 be inserted at	this index point from the top.
	      Here is an example:
	      racl continue addheader "X-Personnal-Header: Hello world!",1

       addfooter
	      Append a footer to the message. Usual escape sequences  such  as
	      \n  can be used to get special characters. The string is subject
	      to format	string expantion as described in  the  FORMAT  STRINGS
	      section.	The  footer  will not be append	if milter-greylist was
	      not able to capture the whole message, therefore maxpeek must be
	      set approriately.

       Entries in the access-list are evaluated	sequentially, so order is very
       important. The first matching entry is used to decide if	a message will
       be  whitelisted	or greylisted. A special default clause	can be used in
       the last	ACL entry as a wildcard.  Here are a few  complete  ACL	 exam-
       ples:

       Example 1:

       racl whitelist from friend@toto.com rcpt	grandma@example.com
       racl whitelist from other.friend@example.net rcpt grandma@example.com
       racl greylist rcpt grandma@example.com
       racl whitelist default

       Example 2:

       racl whitelist addr 193.54.0.0/16 domain	friendly.com
       racl greylist rcpt user1@atmine.com
       racl greylist rcpt user2@atmine.com
       racl greylist rcpt user3@atmine.com
       racl whitelist default

       Example 3:

       racl whitelist rcpt /@.*otherdomain\.org$/
       racl whitelist addr 192.168.42.0/24 rcpt	user1@mydomain.org
       racl whitelist from friend@example.net rcpt /@.*mydomain\.org$/
       racl whitelist rcpt user2@mydomain.org
       racl greylist rcpt /@.*mydomain\.org$/
       racl whitelist default

DATA-STAGE ACL
       ACL  using the racl keyword are evaluated at the	RCPT stage of the SMTP
       transaction. It is also possible	to have	 ACL  evaluated	 at  the  DATA
       stage  of  the  SMTP  transaction, using	the dacl keyword, provided the
       message went through RCPT-stage ACL,  and  possibly  greylisting.  Note
       that you	cannot use the greylist	action at DATA-stage if	the RCPT-stage
       ACL that	matched	had a greylist action itself.  The  following  clauses
       can be used to work on message content:

       dkim   DKIM  status  (if	 build with DKIM support). Possible values are
	      pass, fail, unknown, error, and none,

       header String or	regular	expression searched in message headers

       body   String or	regular	expression searched in message body

       msgsize
	      Operator followed	by a message size (k or	M suffix  allowed  for
	      kilobytes	or megabytes). Example:

		dacl blacklist msgsize >= 4M msg "No more than 4 MB please"

       spamd  SpamAssassin score (if build with	SpamAssassin support). If used
	      without comparison operator spamd	is true	if the score is	 above
	      threshold.  The spamdsock	keyword	can be used to specify the lo-
	      cation of	the spamd socket.

	      Example 1:

		spamdsock unix "/var/spamassassin/spamd.sock"
		racl whitelist default
		dacl greylist spamd

	      Example 2:

		spamdsock inet "127.0.0.1:783"
		racl whitelist default
		dacl blacklist spamd > 15 msg "Your message is considered spam."
		dacl greylist  spamd > 10 delay	2h
		dacl greylist  spamd > 5  delay	1h

       Note that if there are multiple recipient, a rcpt clause	at DATA	 stage
       evaluates  to  true if it matches any of	them.  If you want to match an
       exact set of recipients,	you can	use multiple rcpt clauses along	with a
       rcptcount clause.

LISTS
       It  is  often useful to group several users or sender IP	addresses in a
       single ACL. This	can be done with lists.	Lists must  be	first  defined
       and given a name	before they can	be used	in ACL entries.	Here is	an ex-
       ample:

		list "my users"	rcpt { user1@example.com user2@example.com }
		list "local" addr { 192.0.2.0/24 10.0.0.0/8 }

		racl whitelist list "local"
		racl greylist list "my users"
		racl whitelist default

BACKWARD COMPATIBILITY
       Previous	versions of milter-greylist(8) used addr,  domain,  from,  and
       rcpt  lines,  without  the racl keyword.	 Access-list management	is in-
       tended to replace them.	These lines  are  still	 accepted  by  milter-
       greylist(8),  but they are deprecated.  milter-greylist(8) handles them
       as access-list entries with a single clause. They are added at the head
       of  the	access-list  so	the use	of these keywords and access-lists may
       lead to unspecified behaviour. Do not mix them.

       test mode (using	-T) is also deprecated.	Access-list semantics  do  not
       depend on this flag.

       milter-greylist(8)  also	 used to only have a RCPT-stage	ACL, which was
       configured through acl statements. These	have  been  replaced  by  racl
       statements  (as	opposed	 to  dacl statements for DATA-stage ACL).  acl
       statements are still accepted for backward compatibility	and are	a syn-
       onym for	racl statements.

MX SYNC
       Synchronization	of  the	greylist among multiple	MX is configured using
       the peer	keyword. List each other MX IP addresses using the  peer  key-
       word. Here is an	example:

	 peer 192.0.2.18
	 peer 192.0.2.17
	 peer 192.0.2.22 timeout 7
	 peer 192.0.2.38 timeout 5m

       You  can	 list the local	machine	in the peer statements,	it will	be ig-
       nored.

       The timeout clause sets a peer communication timeout to have proper re-
       trial in	case of	slow MX	peer. The default value	is 3 seconds. The spe-
       cial value of 0 disables	the connection retrials.

       By default, milter-greylist will	listen on  all	interfaces  using  TCP
       port 5252 or the	port number given by service named mxglsync if defined
       in /etc/services	or other directory  service.  This  behaviour  can  be
       changed by using	the syncaddr keyword. Here are a few examples:

	 syncaddr *
	 syncaddr * port 7689
	 syncaddr 192.0.2.2 port 9785
	 syncaddr 2001:db8::1:c3b5:123
	 syncaddr 2001:db8::1:c3b5:123 port 1234

       Using  '*'  as  the  address means to bind to all local interfaces' ad-
       dresses.	 Note that if you are not using	the default port, all MXs must
       use the same port number.

       For  outbound  connections  the system is selecting one of the possible
       addresses.  If you want to use a	specific IP you	can use:

	 syncsrcaddr 123.456.78.9

TEXT DUMP
       milter-greylist(8) uses a text dump of its database to resume operation
       after  a	 crash.	The dump is performed at regular time interval,	but as
       it is a heavy operation,	you might want to configure a particular  time
       interval, using the dumpfreq option.

       If  the dumpfreq	value is too small, it will kill performance. If it is
       too high, you will loose	a bigger part of the database on a crash.

       Set dumpfreq to 0 to get	a dump on each change (kills performance), Set
       it to -1	to never dump to a file	(unsafe	as you lose the	whole greylist
       on each crash), or give a time value for	the delay between dumps.   The
       time  is	 given in seconds, except if a unit is given: m	for minutes, h
       for hours, and d	for days.

       You may further improve the performance of the dump  operation  at  the
       expense	of  humanly  readable  timestamp which by default appears as a
       comment at the end of each line in the dumpfile.	You may	disable	gener-
       ation  of this comment by specifying dump_no_time_translation option in
       the configuration file. This is specifically recommended	if your	 dump-
       file  grows  to	100's of megabytes - it	can reduce the time needed for
       the dump	operation by the order of magnitude!

REPORTING
       By default, milter-greylist(8) will add a X-Greylist header to any mes-
       sage it handles.	The header shows what happened to the message: delayed
       or not  delayed,	 and  why.  The	 following  options  can  be  used  in
       greylist.conf to	alter this behavior:

       report none
	      Never add	a X-Greylist header.

       report delays
	      Only add a header	if the message was delayed.

       report nodelays
	      Add a header if the message was not delayed. The header explains
	      why the message was not delayed.

       report all
	      Always add a header. This	is the default.

SENDER CALLBACK	SYSTEMS
       Sender callback systems are another anti-spam measure that attempts  to
       send  a	DSN  to	the sender address before accepting a message. If that
       fails, then the sender address is wrong and the	message	 is  rejected.
       Such systems usually stop their callback	check at the RCPT stage	of the
       SMTP transaction.

       Greylisting temporarily rejects at the RCPT stage, so  sender  callback
       and  greylisting	love to	fight each other.  milter-greylist(8) proposes
       a workaround to that problem with the delayedreject  option.  For  mes-
       sages  coming  from  <> (that is, for DSN), it will cause the temporary
       reject to happen	at the DATA stage of the SMTP transaction  instead  of
       the RCPT	stage. That way, milter-greylist(8) will cope much better with
       sender callback systems.

       This has	a minor	drawback (and this is why it is	 not  enabled  by  de-
       fault):	for  a	multi recipient	DSN, whitelisted recipient will	not be
       honoured: the message will be delayed for everyone.

SENDMAIL MACROS
       Any sendmail macro can be used as a clause in the access	list. You need
       to define a (macro, value) pair using the sm_macro keyword before using
       it.  Here is an example that uses the {client_resolve} macro to apply a
       larger greylisting delay	to hosts that have a bogus reverse DNS:

		sm_macro "maybe_forged"	"{client_resolve}" "FORGED"

		racl greylist sm_macro "maybe_forged" delay 1h
		racl greylist default delay 15m

       A  regular  expression can be used as the macro value.  It must be sur-
       rounded with slashes and	not by quotes.	The special  value  unset  can
       also be used to match an	unset macro:

		sm_macro "not_foo" "{foo}" unset

       Note  that  any	Sendmail  macro	 that  is  not exported	using the Mil-
       ter.macros.envrcpt setting of sendmail.cf will be seen  as  unset  from
       milter-greylist.

DNSRBL
       DNS  Reverse  Black List	can be used to toggle an ACL. They must	be de-
       fined and named before they can be used.	Here is	an example which  uses
       a  bigger  greylisting delay for	hosts caught in	the SORBS dynamic pool
       DNRSBL (this will include DSL and cable customers pools,	which are well
       known to	be massively infected by spamwares):

		dnsrbl "SORBS DUN" dnsbl.sorbs.net 127.0.0.10/32

		racl greylist dnsrbl "SORBS DUN" delay 1h
		racl greylist default delay 15m

       The  definition	of  a DNSRBL starts by the dnsrbl keyword, followed by
       the quoted name of the DNSRBL, the DNS domain on	which addresses	should
       be looked up, and the answer we should consider as a positive hit.

       DNSRBL support is only available	if enabled through the --enable-dnsrbl
       config flag. Please make	sure milter-greylist(8)	is  linked  against  a
       thread-safe DNS resolver, otherwise it shall crash.

DNS updates
       ACL  are	 able  to  trigger  a  DNS update, which can be	used to	feed a
       DNSRBL.	That functionnality is enabled at build	time if	 the  DNS  re-
       solver has DNS update support.

       Configuration  is  done	with the nsupdate statement, which may be used
       several times, and the optionnal	tsig statement,	if you want ot use au-
       thenticated DNS update. Here is an example syntax:

		tsig "dns-update" "hmac-md5" "1B2M2Y8AsgTpgAmY7PhCfg=="
		nsupdate  "bl.example.net"  { rname "%j.bl.example.net"	rvalue
	      "127.0.0.2" tsig "dns-update" }

       The options for nsupdate	are:

       rname  Created record name, which uses format strings.

       rvalue Created record value, which uses format strings.

       servers
	      Quoted comma-separated list of DNS server	the update  should  be
	      sent  to.	  Default  is to use the system	confifugration,	usualy
	      from /etc/resolv.conf

       ttl    TTL of created DNS record. Default is 0 seconds.

       class  Created record class, as numeric value. Default  is  1,  for  IN
	      class.

       type   Created record type, as numeric value. Default is	1, for A type.

       tsig   The  name	of a tsig configuration, which must have been supplied
	      before. If unspecified, unauthenticated  DNS  updates  are  per-
	      formed.

       Once configured,	DNS updates can	be used	in any ACL:

		racl  blacklist	 rcpt  spamtrap@example.net nsupdate "bl.exam-
	      ple.net"

PROPERTIES
       Properties are variables	that can be set, evaluated and printed in ACL.
       A  property  may	be dropped once	the current recipient is processed, or
       it can be retained until	the message is processed. They can be  created
       through the following always-matching ACL clauses:

       set $name="value"
	      This  sets a property that will be retained for all next recipi-
	      ents. Right hand side of the  clause  may	 be  a	quoted	string
	      (which will be substituted using format strings, as described in
	      the FORMAT STRINGS section), a number, or	another	property  name
	      (which will be substituted by the	property value).

       rset $name="value"
	      Same as set clause, except that the property will	be droped once
	      the current user will have been processed.

       urlcheck
	      These clause will	cause properties to be fetched from an	exter-
	      nal web service.	See the	URL checks section below for details.

       ldapcheck
	      These clause will	cause properties to be fetched from a LDAP di-
	      rectory See the LDAP CHECKS section below	for details.

       Properties can be used as left-hand side	part of	ACL clauses:

		racl blacklist $name "badvalue"
		racl blacklist $name /badregex/

       If used left-hand side and prefixed by a	star,  the  property  will  be
       evaluated as a glob(7) pattern, In the example below, if	sender DNS do-
       main is test.example.net	and $domain is *.example.net, we get a match.

		racl blacklist *$domain	"%f"

       They are	also available as right-hand side of many ACL clauses:

		racl continue set $badword="spam"
		racl blacklist body $badword

       Values of properties can	be obtained in any quoted string that is  sub-
       ject to format string expantion:

		racl continue set $webmaster="webmaster@example.net"
		racl  blacklist	 domain	evil.net msg "blacklisted, ask $P{web-
	      master} why"

       When the	property value is a number, it can be increased	 or  decreased
       using this syntax:

		racl continue set $score+=5
		racl continue set $score-=5

       Here again, right hand side may be a quoted string, a number or another
       property. For the quoted	string and property  cases,  a	conversion  is
       first  made  to an integer, using 0 as a	value on failure. Note that no
       arithmetic evaluation occurs. For instance, the quoted string "1	 +  1"
       will be evaluated as 0.

       The  log	ACL clause can be helpful when one need	to figure what happens
       to property values during the ACL flow. See the CUSTOM  REPORT  section
       for more	details.

URL checks
       milter-greylist(8)  is  able  to	 query external	sources	of information
       through various URL, if it was built with --with-libcurl.  Here	is  an
       example:

		urlcheck "glusr" "http://www.example.net/mgl-config?rcpt=%r" 5

		racl greylist urlcheck "glusr" delay 15m
		racl whitelist default

       The  trailing  5	 at  the end of	the urlcheck definition	is the maximum
       number of simultaneous connections we want to launch on this  URL.  For
       each  message,  the URL will be queried,	with  %	format tags being sub-
       stituted. For instance, %r is substituted by  the  recipient.  See  the
       FORMAT STRINGS section for the complete list of substitutions.

       milter-greylist(8) expects an answer containing a list of \n terminated
       lines, with key:	value pairs. The most basic answer to get a match is:

		milterGreylistStatus: Ok

       TRUE can	be used	as an alias for	Ok here.

       The answer can be more complex, with keys that will  overload  the  ACL
       settings:

       milterGreylistDelay
	      The greylisting delay to use (time unit suffix allowed).

       milterGreylistAutowhite
	      The autowhite delay to use (time unit suffix allowed).

       milterGreylistFlushAddr
	      The  value  is  ignored. If this key is present, then the	IP ad-
	      dress for	the sender machine will	be flushed from	 greylist  and
	      autowhite	databases.

       milterGreylistCode
	      The SMTP code to return (e.g.: 551).

       milterGreylistECode
	      The SMTP extended	code to	return (e.g.: 5.7.1)

       milterGreylistMsg
	      The string to return with	SMTP codes.

       milterGreylistReport
	      The string to display in the X-Greylist header.

       milterGreylistIgnore
	      This line	will be	ignored, without warnings in the logs.

       milterGreylistAction
	      This  feature  is	nifty but use it with caution, as it makes the
	      access list a bit	difficult to  understand.  By  specifying  the
	      values  greylist,	 whitelist,  or	 blacklist,  it	is possible to
	      overload the ACL action itself.

       The ACL will match if any of the	above key is returned: milterGreylist-
       Status is not mandatory.

       Optional	keywords can be	appended to a urlcheck definition:

       postmsg
	      On  DATA-stage  ACL,  This  causes the message to	be sent	(up to
	      maxpeek bytes) in	a POST request.	Here is	an example:

		urlcheck "extfilter" "http://www.example.net/f.cgi" 5 postmsg

		dacl blacklist urlcheck	"extfilter"
		dacl whitelist default

       getprop
	      Gather the properties returned by	the URL	and reuse them in  the
	      ACL.  The	gathered properties can	be accessed in the current and
	      following	ACL by prefixing them by a dollar ($).

       clear  This causes gathered properties to be cleared on each new	recip-
	      ient.  This avoids properties for	several	recipients to mix.

       fork   Tells  milter-greylist(8)	 to fork a separate instance of	itself
	      for performing the queries. Use  it  if  you  encounter  thread-
	      safety problems.	fork is	not compatible with postmsg.

       domatch
	      Cause  the  ldapcheck clause to be evaluated in ACL. Default be-
	      havior is	to ignore the result and just fecth properties,	except
	      if  the  LDAP directory is unreachecable,	in which case a	tempo-
	      rary failure occurs.  The	fixldapcheck gloabal settings may also
	      be  used	to globaly cause all ldapcheck and urlcheck clauses to
	      match.

       Here is an example that will use	various	DNSRBL depending on a  per-re-
       cipient setting stored in the dnsrbl attribute of a LDAP	directory.

		dnsrbl "RBL2" "rbl.example.net"	"127.0.0.2"
		dnsrbl "RBL3" "rbl.example.net"	"127.0.0.3"
		dnsrbl "RBL4" "rbl.example.net"	"127.0.0.4"
		urlcheck  "userconf"  "ldap://localhost/dc=example,dc=net?mil-
	      terGreylistStatus,dnsrbl?one?mail=%r" 5 getprop clear

		racl  blacklist	 urlcheck  "userconf"  $dnsrbl	"RBL2"	dnsrbl
	      "RBL2"
		racl blacklist $dnsrbl "RBL3" dnsrbl "RBL3"
		racl blacklist $dnsrbl "RBL4" dnsrbl "RBL4"

       Note  that  when	matching gathered properties, format strings and regex
       can be used.

LDAP CHECKS
       If milter-greylist was built with --with-openldap, then	you  can  also
       use  ldapcheck  for  pulling  information  from an LDAP directory. This
       works exactly like urlcheck, except that	 properties  are  always  col-
       lected: The getprop option is implicit.

       A  list	of LDAP	URL to use can be specified with the ldapconf keyword.
       The network timeout is optional.

		ldapconf "ldap://localhost  ldaps://ldap.example.net"  timeout
	      2s

       When  ldaps://  is  used, the system's ldap.conf	file is	used to	locate
       x509 certificates.

       When defining LDAP queries with the ldapcheck statement,	note that  the
       scheme  and  host part of the URL are ignored.  Servers listed in ldap-
       conf are	used instead.

RATE LIMIT
       The ratelimit keyword specifies a ratelimit configuration to be used in
       access lists. It	must be	followed by the	rate limit configuration name,
       what is being accounted (i.e.: session for SMTP sessions, rcpt for  re-
       cipients,  data	for  bytes in body and headers), the actual limit, and
       the sampling period. Example:

		ratelimit "internalclients" rcpt 10 / 1m

		racl blacklist addr 192.0.2.0/24 ratelimit "internalclients" \
		   msg "you speak too much"

       The  ratelimit keyword can also have an option key statement, which de-
       termine the set of key for message accounting. The default  is  %i  for
       per IP address accounting (see the FORMAT STRINGS sections for the pos-
       sible syntax of this field). Here is an example that configures a  rate
       limit of	100 messages per hour for each individual recipient-IP set.

		ratelimit "internalclients" rcpt 100 / 1h key "%r%i"

		racl blacklist addr 192.0.2.0/24 ratelimit "internalclients" \
		   msg "you speak too much"

CUSTOM REPORTS
       The stat	keyword	can be used to specify a  custom  report  for  milter-
       greylist	 activity.   It	should be supplied with	an output (either file
       or external command) and	a format string. Here is an example:

		stat ">>/var/log/milter-greylist.log" "%T{%T},%i,%f,%r,%A\n"

       If the output starts by __ or _ then it is a file. Use __ to append  to
       an  existing file, and use _ to overwrite it. If	the output starts by a
       | then the output is a shell command, like in the example below:

		stat "|logger -p local7.info" "%T{%T},%i,%f,%r,%A\n"

       The format string gets substituted as URL checks	format string: %r gets
       substituted by the recipient, %f	by the sender, and so on. See the FOR-
       MAT STRINGS section for a complete list of available substitutions.

       There is	also an	always-matching	log ACL	clause that  can  be  used  to
       send a formated string to syslog	with LOG_INFO level.  Here is an exam-
       ple:

	      racl continue rcpt /@example\.com$/ log "I was here"

COMMAND-LINE FLAG EQUIVALENTS
       Most milter-greylist(8) command-line options  have  equivalent  options
       that  can be set	in the configuration file. Note	that if	a command line
       option is supplied, it will always override the configuration file.

       If a command-line equivalent keyword is used more than once,  the  last
       keyword will override the previous ones.

       verbose
	      Enable debug output. This	is equivalent to the -v	flag.

       quiet  Do  not  tell  clients how much time remains before their	e-mail
	      will be accepted.	This is	equivalent to the -q flag.

       nodetach
	      Do not fork and go into the background. This  is	equivalent  to
	      the -D flag.

       noauth Greylist	clients	 regardless  if	 they  succeeded  SMTP AUTH or
	      STARTTLS.	 Equivalent to the -A flag.

       noaccessdb
	      Normally milter-greylist(8) will whitelist a  message  if	 send-
	      mail(8)  defines	a ${greylist} macro set	to WHITE. This enables
	      complex whitelisting rules based on the Sendmail access DB. This
	      option inhibits this behavior.

       nospf  Greylist	clients	 regardless if they are	SPF-compliant. Equiva-
	      lent to the -S flag.

       testmode
	      Enable test mode.	Equivalent to the -T flag. This	option is dep-
	      recated.

       greylist
	      The argument sets	how much time milter-greylist(8) will want the
	      client to	wait between the first attempt and the time  the  mes-
	      sage is accepted.	The time is given in seconds, except if	a unit
	      is given:	m for minutes, h for  hours,  and  d  for  days.   The
	      greylist	keyword	is equivalent to the -w	option.	Here is	an ex-
	      ample that sets the delay	to 45 minutes:

		greylist 45m

       autowhite
	      This sets	the auto-whitelisting duration,	equivalent to  the  -a
	      command-line  option.  As	for the	greylist keyword, units	can be
	      supplied.	Here is	an example for a 3 day long auto-whitelisting:

		autowhite 3d

       pidfile
	      This causes milter-greylist(8) to	write its PID  into  the  file
	      given  as	 argument, like	the -P command line argument does. The
	      path to the file must be absolute	and it	must  be  enclosed  in
	      quotes. Here is an example:

		pidfile	"/var/run/greylist.pid"

       dumpfile
	      This chooses the location	of the greylist	dump file, like	the -d
	      command line option does.	The path must be absolute and enclosed
	      in quotes.  It can optionally be followed	by an octal permission
	      mode.  Example:

		dumpfile "/var/milter-greylist/greylist.db" 640

       subnetmatch
	      This is equivalent to the	-L command line	 option.  It  takes  a
	      slash  followed  by a CIDR mask as argument, and it commands the
	      subnet matching feature. Example,	for a class C wide matching:

		subnetmatch /24

       subnetmatch6
	      This is equivalent to the	-M command line	 option.  It  takes  a
	      slash  followed  by a prefixlen as argument, and it commands the
	      subnet matching feature. Example,	for a subnet wide matching:

		subnetmatch6 /64

       socket Like the -p command line option, this keyword is used to specify
	      the socket used to communicate with sendmail(8).	It must	be en-
	      closed in	quotes and can optionally be followed by an octal per-
	      mission  mode  (valid  values  are 666, 660 or 600, other	values
	      cause an error):

		socket "/var/milter-greylist/milter-greylist.sock" 660

       user   This keyword should be followed by a quoted user login  and  op-
	      tionally	a  colon followed by a groupname.  Like	the -u option,
	      this is used to run milter-greylist(8) as	a non root user.  Here
	      is an example:

		user "smmsp"

MISCELLANEOUS
       These options have no command line equivalent:

       logfac Sets the syslog facility for messages.  Can be set to any	of the
	      standard facilities: kern, user,	mail,  daemon,	auth,  syslog,
	      lpr,  news,  uucp,  cron,	authpriv, ftp, local0, local1, local2,
	      local3, local4, local5, local6, local7.  Can also	be set to none
	      to disable syslog	output completely.

       timeout
	      is  used to control how long greylist tuples are retained	in the
	      database.	 Value is in seconds, except if	a suffix is  given  (m
	      for minutes, h for hours,	d for days). Default is	5 days.

       extendedregex
	      Use  extended  regular  expressions instead of basic regular ex-
	      pressions.

       unbracket
	      Attempt to resolve sender	address	when  the  MTA	handed	it  as
	      bracketed	 IP address (e.g.: [192.0.2.18]	). Default is to leave
	      it as is.

       maxpeek
	      Limit (in	bytes) how much	of messages are	 examined  for	header
	      and body searches.

       lazyaw Make  auto-whitelist  look at just the IP	instead	of the (sender
	      IP, sender e-mail	address, recipient e-mail address) tuple.

       domainexact
	      match on subdomain boundaries  instead  of  the  default	suffix
	      matching.	 E.g. if domainexact is	not enabled (the default) then
	      gle.com will match google.com in addition	 to  gle.com.  If  do-
	      mainexact	 is enabled then, domain names will match on subdomain
	      boundaries (e.g.	gle.com	will match  mail.gle.com  and  gle.com
	      but not google.com)

       drac db
	      Tell  where  the DRAC DB file is.	This is	only available if DRAC
	      support was compiled in. Here is an example:

		drac db	"/usr/local/etc/drac.db"

       nodrac Disable DRAC.

       logexpired
	      This option causes greylist entries that expire to be logged via
	      syslog.	This allows you	to easily collect the IP addresses and
	      sender names and use them	for blacklisting, SPAM	scoring,  etc.
	      Normally,	 expiration's  are  only logged	if the debug option is
	      set, but that generates a	lot of extra messages.

       localaddr
	      This keyword can be used to manually define the local  MTA's  IP
	      address for such uses as spf self	and p0f	in absence of the mil-
	      ter-API {if_addr}	macro support in your MTA (Postfix, Sun/Oracle
	      CommSuite	 Messaging  Server).  This is not so useful when using
	      Sendmail,	since it serves	the macro and the local	address	can be
	      detected automatically.

       The  configuration  file	 is reloaded automatically once	it is modified
       when new	e-mail arrives.	Most configuration keywords will  take	effect
       immediately,  except the	following, which will only take	effect after a
       restart of milter-greylist(8): nodetach,	pidfile, socket, and user.

       The dumpfreq option can be changed dynamically,	but  the  change  will
       only take effect	after the next dump.

       multiracl
	      By  default,  once a RCPT-stage ACL whitelists a recipient, next
	      recipient	gets automatically whitelisted.	This historical	behav-
	      ior can be considered a bug, and this option disables it.

FORMAT STRINGS
       Various	statements  in	the  configuration file	accept format strings,
       where the following % prefixed tokens are substituted. Here is the com-
       plete list of available substitutions (Note that	some substitutions are
       not relevant in any context).

       %r     the message recipient e-mail address. This  is  not  substituted
	      for  DATA	 stage	ACL since there	can be multiple	recipients for
	      the message.

       %f     the message sender e-mail	address

       %i     the sender machine IP address

       %j     the reversed sender machine IP address. For instance, 192.0.2.12
	      becomes 12.2.0.192.

       %I     the sender machine IP address masked by a	CIDR. Example: %I{/24}

       %d     the sender machine DNS address

       %h     the SMTP transaction HELO	string

       %mr    the  mailbox part	of %r (before the @ sign). This	is not substi-
	      tuted for	DATA stage ACL since there can be multiple  recipients
	      for the message.

       %sr    the  site	part of	%r (after the @	sign). This is not substituted
	      for DATA stage ACL since there can be  multiple  recipients  for
	      the message.

       %mf    the mailbox part of %f (before the @ sign)

       %sf    the site part of %f (after the @ sign)

       %md    the machine part of %d (before the first . sign)

       %sd    the site part of %d (after the first . sign)

       %Xc    the SMTP code returned

       %Xe    the SMTP extended	code returned

       %Xm    the SMTP message returned

       %Xh    the message displayed in the X-Greylist header

       %D     Comma-separated list of DNSRBL for which the sender host matched

       %M     a	sendmail macro value. Examples:	%Mj or %M{if_addr}

       %g     a	 regex	back reference.	For instance, %g{\2} is	substituted by
	      the string matching the second  parenthesis  group  in  all  ACL
	      regex clauses

       %T     a	 brace-enclosed	strftime(3) format string that will be substi-
	      tuted by the system time.	Example: %T{%Y%m%d:%H%M%S}

       %v     milter-greylist's	version

       %G     Offset to	GMT (e.g.: -0100)

       %C     Sender IP	country	code, as  reported  by	GeoIP.	This  is  only
	      available	if milter-greylist was built with GeoIP	support

       %Fx    p0f  OS  fingerprint genre and detail. This is only available if
	      milter-greylist was built	with p0f support.

       %V     Shortcut to "milter-greylist-%v (%Mj [%M{if_addr}]);  %T{%a,  %d
	      %b %Y %T}	%G (%T{%Z})"

       %S     the action performed: accept, tempfail, or reject.

       %A     the line number of the ACL that caused the action.

       %a     the  id  string  of the ACL that caused the action. If no	id was
	      given, the line number is	used instead.

       %cA    the line number of the ACL being evaluated, whether  it  matches
	      or not.

       %ca    the  id string of	the ACL	being avaluated, whether it matches or
	      not.  If no id was given,	the line number	is used	instead.

       %Et    total elapsed time in seconds before a  greylisted  message  has
	      been accepted

       %Eh    hours elapsed

       %Em    minutes elapsed (modulo one hour)

       %Es    seconds elapsed (modulo one minute)

       %E     shortcut to %Eh:%Em:Es

       %Rt    total remaining time in seconds before a greylisted message will
	      be accepted

       %Rh    hours remaining

       %Rm    minutes remaining	(modulo	one hour)

       %Rs    seconds remaining	(modulo	one minute)

       %R     shortcut to %Rh:%Rm:Rs

       %Hs    SpamAssassin score (if build with	SpamAssassin support)

       %pn    Name of last LDAP	or CURL	gathered property that matched an ACL.

       %pv    Value of last LDAP or CURL gathered  property  that  matched  an
	      ACL.

       %pr    Recipient	 that caused storage of	the last matching LDAP or CURL
	      gathered property.  %P a LDAP or CURL gathered propery. Example:
	      %P{mail}	Note that this copes very badly	with multivalued prop-
	      erties.

       %Qd    DKIM query result	(pass, fail, etc.), if built  with  DKIM  sup-
	      port.

       %Qs    SPF  query  result  (pass,  (soft)fail, etc.), if	built with SPF
	      support.

       %QA    Authentication results summary, suitable for  Authentication-Re-
	      sults  header.  Will  included formatted query results from DKIM
	      and SPF if checked.

       %QS    SPF result, suitable for	Received-SPF  header.  Available  when
	      compiled with libspf2.

       %%     a	single % character

AUTHORS
       Emmanuel	Dreyfus	<manu@netbsd.org>

       milter-greylist	received  many contributions from (in alphabetical or-
       der): Adrian Dabrowski, Aida Shinra, Adam Katz, Alexander  Lobodzinski,
       Alexandre  Cherif, Alexey Popov,	Andrew McGill, Attila Bruncsak,	Benoit
       Branciard, Bernhard Schneider, Bob Smith, Constantine A.	Murenin, Chris
       Bennett,	Christian Pelissier, Cyril Guibourg, Dan Hollis, David Binder-
       man, Denis Solovyov, Elrond,  Enrico  Scholz,  Eugene  Crosser,	Fabien
       Tassin,	Fredrik	 Pettai,  Gary	Aitken,	Georg Horn, Gert Doering, Greg
       Troxel, Guido Kerkewitz,	Hajimu Umemoto,	Hideki ONO, Ivan F.  Martinez,
       Jacques	Beigbeder,  Jean  Benoit,  Jean-Jacques	 Puig,	Jeff Rife, Jim
       Klimov, Jobst  Schmalenbach,  Joe  Pruett,  Joel	 Bertrand,  Johann  E.
       Klasek,	Johann	Klasek,	 John  Thiltges,  John	Wood,  Jorgen Lundman,
       Kazuyuki	Yoshida, Klas Heggemann, Kouhei	Sutou, Laurence	Moindrot,  Lev
       Walkin, Manuel Badzong, Markus Wennrich,	Mart Pirita, Martin Paul, Matt
       Kettler,	Mattheu	 Herrb,	 Matthias  Scheler,  Matthieu  Herrb,  Michael
       Fromme, Moritz Both, Nerijus Baliunas, Ole Hansen, Pavel	Cahyna,	Pascal
       Lalonde,	Per Holm, Petar	Bogdanovic, Petr Kristof,  Piotr  Wadas,  R  P
       Herrold,	 Ralf S. Engelschall, Ranko Zivojnovic,	Remy Card, Rick	Adams,
       Rogier Maas, Romain Kang, Rudy Eschauzier, Stephane Lentz, Steven  His-
       cocks,  Thomas Scheunemann, Tim Mooney, Vincent Dufresne, Wolfgang Sol-
       frank, and Yaroslav Boychuk.

       Thanks to Helmut	Messerer and Thomas Pfau for  their  feedback  on  the
       first releases of this software.

SEE ALSO
       milter-greylist(8), sendmail(8),	syslogd(8).

       Evan Harris's paper:
	      http://projects.puremagic.com/greylisting/

       milter-greylist's web site:
	      http://hcpnet.free.fr/milter-greylist/

				 May 10, 2005		      greylist.conf(5)

NAME | DESCRIPTION | WHITELIST | DATA-STAGE ACL | LISTS | BACKWARD COMPATIBILITY | MX SYNC | TEXT DUMP | REPORTING | SENDER CALLBACK SYSTEMS | SENDMAIL MACROS | DNSRBL | DNS updates | PROPERTIES | URL checks | LDAP CHECKS | RATE LIMIT | CUSTOM REPORTS | COMMAND-LINE FLAG EQUIVALENTS | MISCELLANEOUS | FORMAT STRINGS | AUTHORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=greylist.conf&sektion=5&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help