access-map

The access-map is used to manage a variety of facilities such as black & white listings, message limits & sizes, concurrency & rate throttling. Many elements can be specified by IP, subnet, host name, and/or sender & recipient address or domain.

The file referenced by the access-map option can be a simple text file, SQLite3 database, or socket-map server. The recommended configuration uses an SQLite3 database generated from an access.cf text file. This can be done in one of two ways:

# cd /etc/smtpf
# kvmap -l "access!sql!access.sq3" \
  < access.cf

or simply by using the supplied Makefile

# cd /etc/smtpf
# make access.sq3

If you do not specify the access.sq3 explicitly, then the make command will build all the configuration files if necessary.

The access.cf text file consists of lines of key-value pairs. Each line consists of a key field separated by white space from the value field, which is the remainder of the line. Comments start with a hash (#) on a line by themselves. The key lookups are case insensitive, while the values are case sensitive. The order in which keys are looked up is outlined below and by the access-map option.

There are essentially three types of keys used in the access-map. Many of the tags available will use one or more of these lookup sequences.

IP Address Lookups

An IP address lookup is typically applied to the connected SMTP client. It will start with a complete IPv4 or IPv6 address and break it down on delimiter boundaries from right to left.

IPv4 Lookup		IPv6 Lookup
tag:192.0.2.9		tag:2001:0DB8:0:0:0:0:1234:5678
tag:192.0.2		tag:2001:0DB8:0:0:0:0:1234
tag:192.0		tag:2001:0DB8:0:0:0:0
tag:192		tag:2001:0DB8:0:0:0
		tag:2001:0DB8:0:0
		tag:2001:0DB8:0
		tag:2001:0DB8
		tag:2001

Note that the compact form of an IPv6 address, "2001:0DB8::1234:5678", cannot be used. Only the full IPv6 address format, with all intervening zeros, is currently supported.

Domain Name Lookups

A domain lookup may be applied to either the connected SMTP client, where the client's host name found through a DNS PTR record is searched for, or using the domain portion of an mail address (see below). A domain lookup will try the IP-domain literal if applicable, then continue with the FQDN, breaking it down one label at a time from left to right.

tag:[ipv6:2001:0DB8::1234:5678]

tag:[192.0.2.9]

tag:sub.domain.tld

tag:domain.tld

tag:tld

tag:

Note that the bare tag is often used to specify system wide defaults.

Mail Address Lookups

A mail address lookup is similar to a domain lookup, but the search first starts with a complete mail address, before trying the address's domain, and finally only the local part of the address.

tag:account@sub.domain.tld

tag:sub.domain.tld

tag:domain.tld

tag:tld

tag:account@

tag:

Note that the bare tag is often used to specify system wide defaults.

Tags

The following list outlines the available tags and their supported key lookups:

Archname-Connect:ip

Archname-Connect:domain

Archname-From:mail

Archname-To:mail

The right hand side value is a semi-colon separated list of unacceptable file patterns to reject when found RAR or ZIP attachments. This overrides the global option deny-compressed-name when defined for a specific host, sender, or recipient.

Body:ip

Body:domain

Body:mail

Used to black (REJECT) or ignore (OK) domains that make up mail addresses or URLs found within the header or body content of a message. See uri-bl and uri-dns-bl.

Concurrent-Connect:ip

Concurrent-Connect:domain

This is used to specify the maximum number of concurrent connections an SMTP client is permitted at any one time. Specify an integer or zero (0) to disable. The bare tag can be used to specify a global setting. If an SMTP client exceeds the allotted number of connections, then the incoming connection is dropped, while existing connections continue.

Connect:ip

Connect:domain

Used to black or white list an SMTP client. If black listed (REJECT), the connection will be dropped. If white listed (OK), then the messages from this connection by-passes all the filtering except anti-virus. The connection can also be "grey-listed" (CONTENT), similar to dns-gl, which only white lists a connection as far as, but not including, the data content filters.

Connect:ip:From:mail

Connect:domain:From:mail

This set of combination tags are used to black or white list sender addresses when sent from a given SMTP client. The sender address can be easily forged and using the From: tag by itself could allow spam with a forged address. By adding the sender's SMTP client as an extra constraint, it is possible to limit such abuse. Note that the lookup variants with blank IP, domain, or mail are not supported.

Connect:ip:To:mail

Connect:domain:To:mail

This set of combination tags are used to black or white list recipient addresses that a given SMTP client may contact. This allows for finer granularity of control in place of the To: tag. Note that the lookup variants with blank IP, domain, or mail are not supported.

Emew:mail

Used to specify an alternative EMEW secret for the sender or sender's domain.

Filename-Connect:ip

Filename-Connect:domain

Filename-From:mail

Filename-To:mail

The right hand side value is a semi-colon separated list of unacceptable file patterns to reject when found as MIME attachments. This overrides the global option deny-content-name when defined for a specific host, sender, or recipient.

From:mail

Used to black or white list a sender's mail address. If black listed (REJECT), mail from this sender is refused. If white listed (OK), then the messages from this sender will by-pass all the filtering except anti-virus. Black listing using this tag is fine, but white listing is not recommended as it is too easy for someone to fake the sender address.

From:mail:To:mail

This set of combination tags are used to black or white list a pair of sender and recipient addresses. This allows for finer granularity of control in place of the To: tag. Note that the lookup variants with blank mail elements are not supported.

Grey-Connect:ip

Grey-Connect:domain

Grey-To:mail

This is the amount of time in seconds a correspondent's grey-list record will be temporarily rejected before being accepted. If several keys are possible for a given message, then the minimum value is used. Specify an integer number of seconds or zero (0) to disable.

Helo:ip

Helo:domain

Used to black or white list an SMTP client based on the HELO/EHLO argument. If black listed (REJECT), the connection will be dropped. If white listed (OK), then the messages from this connection by-passes all the filtering except anti-virus. The connection can also be "grey-listed" (CONTENT), similar to dns-gl, which only white lists a connection as far as, but not including, the data content filters.

This tag is not recommended for white listing as the HELO argument it can be too easily falsified. It is primarily intended for data gathering and diagnostics when used with SAVE, TAG, or TRAP actions. The other actions are supported for completeness.

Length-Connect:ip

Length-Connect:domain

Length-From:mail

Length-To:mail

Used to limit the maximum length of a message in octets. It is expressed as a number with an optional scale suffix K (kilo), M (mega), or G (giga). If no length is given or is -1, then the message can be any length (ULONG_MAX).

When there are multiple message length limits possible, then the limit applied, in order of precedence is:

1. Length-To:. If there is more than one Length-To:, then the maximum limit specified will be used.
2. Length-From:
3. Length-Connect:

Mimetype-Connect:ip

Mimetype-Connect:domain

Mimetype-From:mail

Mimetype-To:mail

The right hand side value is a semi-colon separated list of unacceptable attachment MIME types to reject. This overrides the global option deny-content-type when defined for a specific host, sender, or recipient.

Msg-Limit-Connect:ip

Msg-Limit-Connect:domain

Msg-Limit-From:mail

Msg-Limit-To:mail

Used to limit the number of messages a SMTP client, sender, or recipient can send/receive in a given time period. A message limit is given as:

messages '/' time [unit]

which is the number of messages per time interval. The time unit specifier can be one of week, day, hour, minute, or seconds (note only the first letter is significant). A negative number for messages will disable any limit.

When there are multiple message limits possible, then the limit applied, in order of precedence is: Msg-Limit-To:, Msg-Limit-From:, and Msg-Limit-Connect.

Null-Rate-To:mail

Spammers will often impersonate some random or otherwise false mail address within a legitimate domain, like hotmail.com. In some cases when a third party mail system rejects spam or virus mail during the SMTP session, a DSN (bounce message) is generated and sent back to the false sender. Since spammers typically send millions of messages with falsified sender addresses, the mail system of the abused domain can be swamped by the backscatter. smtpf's EMEW facility was designed in part to help with backscatter, but cannot be deployed in some mail system architectures.

So smtpf provides another mechanism to help with backscatter situations, where smtpf monitors the rate of DSN or MDN messages (essentially any message from the "null sender" ie. MAIL FROM:<>) arriving per minute and rejects such messages above a certain threshold that can be configured globally, by domain, and by recipient.

The right-hand-side value is a positive number representing the permitted number of messages from the null sender per minute to the given recipient or domain; -1 to disable.

Rate-Connect:ip

Rate-Connect:domain

This is used to specify the number of connections per minute a host is allowed. Simply specify an integer or zero (0) to disable. The bare tag can be used to specify a global setting. If an SMTP client connects too frequently in excess of this limit, then the incoming connection is dropped.

Spamd:mail

Spamd:domain

Spamd:

Used to specify a SpamAssassin configuration to use. If the message is addressed to a single recipient, then a Spamd:mail lookup is done. If the message is for more than one recipient, all of whom are within the same domain, then a Spamd:domain lookup is done. Otherwise the Spamd: default configuration is used. The right hand side action must be a user name or address to pass to spamd. It can be a pattern list. If the special user name OK is used, then the message is not processed by spamd.

Tls-Connect:ip

Tls-Connect:domain

These tags accept the action words SKIP, REQUIRE, or VERIFY (see below). The SKIP word has a different meaning here; it indicates that STARTTLS extension is not to be offered to the given host(s). Note they currently do not support pattern lists.

Tls-From:mail

Tls-To:mail

These tags accept the action words REQUIRE, or VERIFY (see below). Note they currently do not support pattern lists.

To:mail

Used to black or white list a recipient's mail address. If black listed (REJECT), mail to this recipient will be refused; the current message transaction is permitted to specify addition recipients or abandon the transaction. If white listed (OK), then the message will by-passes all the filtering except anti-virus.

Top-Mimetype-Connect:ip

Top-Mimetype-Connect:domain

Top-Mimetype-From:mail

Top-Mimetype-To:mail

The right hand side value is a semi-colon separated list of unacceptable message MIME types to reject. This overrides the global option deny-top-content-type when defined for a specific host, sender, or recipient.

It should be noted that black & white listing with Connect:, Connect:From:, Connect:To:, From:, From:To:, and To: take effect immediately in the SMTP state they apply to. This can be changed by enabling smtp-delay-checks which delays policy rejections until the recipients have been specified with the possibility to white list. The auth-delay-checks option can be used to delay the connection and EHLO related tests until a MAIL FROM: is received allowing for an SMTP AUTH command to be issued.

Action

When a key lookup matches, then the value returned is a pattern list, which in its simplest and most common form is either an action word like OK, CONTENT, DISCARD, REJECT, IREJECT, TAG, etc; or a numerical value depending on the tag involved. For example:

Connect:192.168.0	OK
Rate-Connect:fsl.com	17
Msg-Limit-From:hotmail.com	150/30m

The action words supported are:

OK	White list, by-pass one or more tests, except anti-virus scanning
CONTENT	White list as far as, but not including, the content filters; used only with Connect: or Helo:.
DISCARD:"log-comment"	Accept and discard message skipping tests; use with care. The :"log-comment" is optional
IREJECT:"custom-reply"	Immediate REJECT, ignore smtp-delay-checks; applies only to Connect:, Connect:From:, From:, and Helo:. :"custom-reply" is optional
PROTOCOL	Similar to CONTENT, reject on pre-DATA tests, but ignore post-DATA ones, execpt for anti-virus. Useful for some mailing lists. Used with Connect:, from:, to:, connect:from:, connect:to:, or from:to:.
REJECT:"custom-reply"	Black list, either reject or drop. The :"custom-reply" is optional
REQUIRE	The client is required to establish STARTTLS before the server will accept messages. Used only with Tls-Connect:, Tls-From:, and Tls-To:.
SAVE:"path"	Save a copy of message if delivered and save message to save-dir, unles the optional :"path" is specified
SKIP	Stop lookup and return no result ie. continue testing. For Tls-Connect: by-pass the offering of STARTTLS extension.
SPF-PASS	White list sender if SPF returns Pass; used only with Connect:From: and From:
TAG	If a policy rejection or drop would occur, simply tag the Subject: header and by-pass remaining tests
TEMPFAIL:"custom-reply"	Report a temporary failure condition. The :"custom-reply" is optional
TRAP:"path"	Accept and save message, but do not deliver, to trap-dir, unless the optional :"path" is specified
VERIFY:"CN=name"	The client is required to establish STARTTLS before the server will accept messages and the client certificate must validated. Used only with Tls-Connect:, Tls-From:, and Tls-To:. The :CN=name is optional; when specified the CN field of client certificate must match name.

Pattern Lists

In most instances, the above forms of key lookup and values are sufficient. However, there may be times when finer granularity of control is required, in which case pattern lists can be used. A pattern list is a white space separated list of pattern-action pairs followed by an optional default action. The supported types are:

[network/cidr]action	Classless Inter-Domain Routing (only with IP address lookups)
!pattern!action	Simple fast text matching.
/regex/action	Extended Regular Expressions.

The simple pattern matching, !pattern!, uses an asterisk (*) for a wildcard, scanning over zero or more characters; a question-mark (?) matches any single character; a backslash followed by any character treats that character as a literal. This method always tries to match the beginning and end of string. For example:

!abc!	exact match for 'abc'
!abc*!	match 'abc' at start of string
!*abc!	match 'abc' at the end of string
!abc*def!	match 'abc' at the start and match 'def' at the end, maybe with stuff in between.
!*abc*def*!	find 'abc', then find 'def'

The following is an example using a simple pattern to reject client connections that originate from a range of IP addresses of an ISP assigned to ADSL customers. Using a pattern like this allows you to drop connects from the ISP's ADSL, while still accepting connections from mail and web servers.

Connect:hananet.net	!adsl-*-*.usr.hananet.net!REJECT

If you know that an ISP's mail and web servers follow a standard naming convention, you might prefer to only accept mail from those instead. We include web servers here to handle the case where a web server might have to send a mail response based on a form being filled in.

Connect:hananet.net	!smtp*.hananet.net!OK !www*.hananet.net!OK REJECT

Note that SPF was designed to help mail servers identify originators of mail, so creating patterns as shown in the above two examples is not normally required. However, SPF is still considered experimental and not as widely deployed as one might hope.

The next example, /regex/, uses Extended Regular Expressions to validate the format of the local-part of an AOL address, which must be between 3 and 16 characters long, can contain dots and RFC 2822 ``atext'' characters except % and /. The NEXT word allows the one regular expression to validate the format of the address and resume key lookup if the pattern matches; otherwise if the regular expression failed to match, REJECT the suspect aol.com address.

From:grandma@aol.com OK
From:aol.com /^[a-zA-Z0-9!#$&'*+=?^_`{|}~.-]{3,16}@aol.com$/NEXT REJECT

The discussion of Extended Regular Expressions is vast and complex, well beyond the scope of this document. There are many on-line tutorials and references available and the book Mastering Regular Expressions, 3e from O'Reilly covers the topic in depth.

If you need to use a pattern list, then try and follow these suggestions:

• A pattern cannot be used as the key in an access-map lookup. Key-value tables work with constants for the keys using a predefined lookup order as outlined above.
• Use the key lookup as a selector to find a pattern list.
• Use simple !pattern! matching where possible, as it will be faster than Extended Regular Expressions, /regex/.
• Avoid using pattern lists with bare tag variants that specify a global default. It will more often than not cause a lot of unnecessary attempts to match a pattern.
• Keep your pattern lists short & simple.

- TOP -

Copyright 2006, 2016 by SnertSoft. All rights reserved.
BarricadeMX trademark & patents pending.