smtp-proxy

smtp-proxy
Prev	Kernun UTM Reference (5)	Next

Name

smtp-proxy — format of smtp-proxy component configuration

DESCRIPTION

General syntax rules of Kernun Firewall configuration files are described in configuration(7). This man page describes types, sections and items specific for the smtp-proxy component configuration.

Repeatable sections/items are marked by the '*' before section/item name.

TYPES

Configuration directives have attributes of several value-types. For the basic types description, see configuration(7).

Enumeration is a list of words (names) representing integer values. Some enumerations accept both names and direct integer values; in this case, enumeration description contains values for every name (in parenthesis next to name). For other enumerations, using of names is obligatory.

The following enumerations are used in smtp-proxy configuration directives:

enabling (see common(5))

yes-no (see common(5))

direction (see common(5))

ip-version (see common(5))

osi4-proto (see common(5))

time-cond (see common(5))

zip-mode (see common(5))

obligation (see common(5))

range-op (see common(5))

dbglev (see log(5))

logfail-mode (see log(5))

week-day (see time(5))

month (see time(5))

lock-type (see ipc(5))

auth-method (see auth(5))

virus-status (see antivirus(5))

source-address-mode (see source-address(5))

transparency (see acl(5))

user-auth-spec (see acl(5))

doctype-ident-method (see acl(5))

header-op (see acl(5))

listen-on-sock (see listen-on(5))

smtp-error (see mod-mail-doc(5))

mime-header-check-type (see mod-mail-doc(5))

smtp-cmd (name-usage obligatory)

SMTP commands

NONE, HELO, EHLO, MAIL, RCPT, DATA, RSET, ETRN, TURN, VRFY, EXPN, HELP, NOOP, SEND, SAML, SOML, VERB, AUTH, STARTTLS, QUIT

smtp-size-usage (name-usage obligatory)

disable, input

ssl-startup-mode (name-usage obligatory)

Modes of SSL startup

session: SSL started immediately
command: SSL started after STARTTLS command

postfix-security-level (name-usage obligatory)

Postfix SMTP agent security levels.

none: No TLS.
may: Opportunistic TLS.
encrypt: Mandatory TLS encryption.
dane: Opportunistic DANE TLS.
dane-only: Mandatory DANE TLS.
fingerprint: Certificate fingerprint verification.
verify: Mandatory server certificate verification.
secure: Secure-channel TLS.

postfix-transport-map-mode (name-usage obligatory)

Postfix SMTP agent TRANSPORT-MAP modes.

none: No transport maps used.
relay: All forwarder domains mapped to the relay host.
fallback: All forwarder domains mapped to the relay host, rest of the world to the fallback socket.
extern: External (unhashed) map.

smtp-err-switch (name-usage obligatory)

ok, error, ignore-err

spf-result (name-usage obligatory)

White-listing (Sender Policy Framework) results.

None: Not enough information for checking available.
Neutral: Domain owner stated no decision about this client.
Pass: Client is authorized.
Fail: Client is not authorized.
SoftFail: Client is neither authorized nor strongly rejected.
TempError: Temporary error occured while checking client.
PermError: SPF record cannot be correctly interpreted.

spf-modes (name-usage obligatory)

SPF checking modes.

sender-only: Check only sender domain.
highest-mx: Try to check sender domain and in case of no SPF, check domain of the highest priority sender MX.
check-all: Try to check sender domain and in case of no SPF, check all alternate domains from the list.
matching-mx: Try to check sender domain and in case of no SPF, check domain of the highest priority sender MX that matches any of the domains in the list.

ITEMS AND SECTIONS

Configuration of smtp-proxy library component consists of following prototypes:

  smtp-limit { ... }
  smtp-agent { ... }
* smtp-forwarder name { ... }
* smtp-arg-check ... ;
  smtp-reply ... ;
* mailbox ... ;
  grey-listing { ... }
* smtp-proxy name { ... }

Description:

smtp-limit {

  soft ... ;
  hard ... ;
}

This section defines two-level (soft/hard) SMTP limitation.

Items & subsections:

soft [val [text]];

Soft-limit.

Reaching this limit causes error state (response to client).

val (type: uint64, optional, default: 0)

Limitation value.

Value of zero disables soft-checking of particular limitation.

text (type: str, optional, default: <NULL>)

Error message.

If omitted, default reply is used.

hard [val [text]];

Hard-limit.

Reaching this limit causes immediate session termination.

val (type: uint64, optional, default: 0)

Limitation value.

Value of zero disables hard-checking of particular limitation.

text (type: str, optional, default: <NULL>)

Error message.

If omitted, default reply is used.

[End of section smtp-limit description.]

smtp-agent {

  phase ... ;
* tag ... ;
  relayhost ... ;
  source-address ... ;
  myhostname ... ;
  smtp-helo-name ... ;
  myorigin ... ;
  inet-protocol ... ;
  relay-domains ... ;
  mydestinations ... ;
  mynetworks ... ;
  message-size-limit ... ;
  bounce-size-limit ... ;
  bounce-queue-lifetime ... ;
  delay-warning-time ... ;
  tls { ... }
* set-var ... ;
  master-cf ... ;
  smtpd-option ... ;
  transport-map ... ;
}

Local MTA definition.

Constraints:

Relayhost must be defined for automatic transport maps.

MASTER-CF must be specified.

Items & subsections:

phase [number];

Application Startup Phase.

number (type: uint8, optional, default: 40): Phase number; the lower one, the earlier start.

tag value;

Configuration factorization tag.

This feature allows admin to create groups of Kernun applications (specially proxies and servers) according to various aspects (belonging to one customer, applications of particular network traffic etc.).

Each application can have several tag attributes and the KAT tool can run some commands (like 'ps', 'start' atc.) for applications with or without given tag.

value (type: str)
Constraints:: Tag must contain letters, digits, hyphens and dots, only.

relayhost next-hop;

MTA next-hop relay.

If omitted, MTA will deliver mail according to RCPTs DNS resolution.

next-hop (type: sock)

source-address [client] [addr4 addr4] [addr6 addr6] cluster [cluster];

source-address [client] [addr4 addr4] [addr6 addr6] [physical];

source-address [client] [addr4 addr4] [addr6 addr6] no-fallback;

Source address of connections outgoing from forwarder to next MTA.

client (type: key, optional)

addr4 addr4 (type: host, optional, default: [0.0.0.0])

addr6 addr6 (type: host, optional, default: [::])

<branching element> (type: source-address-mode, optional, default: physical)

cluster (type: host-list, optional, default: {})

Constraints:

Address family must respect the element's address family..

Using of client source address is not possible.

Using of cluster source address is not possible.

myhostname hostname;

Official hostname.

This value is copied to the main.cf 'myhostname' variable. If omitted, the regular hostname is used.

hostname (type: str)

smtp-helo-name hostname;

Name used in HELO/EHLO command.

This value is copied to the main.cf 'smtp_helo_name' variable. If omitted, the regular hostname is used instead.

hostname (type: str)

myorigin hostname;

Host name used for locally posted mails.

This value is copied to the main.cf 'myorigin' variable. If omitted, the regular hostname is used.

hostname (type: str)

inet-protocol version;

Internet protocol version support.

If omitted, IPv4 is enabled and IPv6 too, if supported.

version (type: ip-version)

relay-domains domains;

Destinations for which this agent relays mails to.

domains (type: str)

mydestinations domains;

Destinations for which this agent accepts mails.

domains (type: str)

mynetworks networks;

List of trusted remote SMTP clients.

If omitted, the 127.0.0.0/8 network is used.

networks (type: net-list)

message-size-limit [bytes];

MTA mail size limit.

bytes (type: uint64, optional, default: 10000000)

bounce-size-limit [bytes];

MTA DSN message size limit.

bytes (type: uint64, optional, default: 50000)

bounce-queue-lifetime [seconds];

MTA queue lifetime.

seconds (type: uint32, optional, default: 5d)

delay-warning-time [seconds];

MTA delay warning time.

seconds (type: uint32, optional, default: 3h)

tls {

  security-level ... ;
  log-level ... ;
}

Client TLS parameters.

Items & subsections:

security-level [level];

Security level.

level (type: postfix-security-level, optional, default: may)

log-level [level];

Log level (0..4).

level (type: uint8, optional, default: 1)

[End of section smtp-agent.tls description.]

set-var name value;

Postfix main.cf variables setting.

name (type: str): Variable name.
value (type: str): Variable value.
Constraints:: Variable name must contain alphanumeric chars only.

master-cf file;

Postfix master.cf configuration file.

This file serves as the source for the master.cf files copied into etc/postfix.NAME directories. The referenced file can be the master.cf file from the Postfix distribution, because the CML modifies this file according to its purpose, i.e.

- for the LOCAL-MAILER, CML comments off all listening modules

- for SMTP-FORWARDERs, CML comments off local delivery module (if LOCAL-MAILER is used).

file (type: name of shared-file, see common(5))

smtpd-option option;

Additional option to smtpd call from master.cf file.

option (type: str)

transport-map [none];

transport-map relay;

transport-map fallback fallback port;

transport-map extern file;

Transport map definition.

<branching element> (type: postfix-transport-map-mode, optional, default: none)
fallback (type: host): Fallback address.
port (type: port): Fallback port.
file (type: name of shared-file, see common(5))
Constraints:: Fallback port must differ from smtp port.

[End of section smtp-agent description.]

smtp-forwarder name {

* server ... ;
  agent { ... }
  timeouts { ... }
  hostname ... ;
  size ... ;
  source-address ... ;
* domain ... ;
  server-ssl ... ;
* server-cert-match ... ;
  altq ... ;
}

This section defines SMTP forwarding channel.

Constraints:

At least one server must be specified.

At most 31 servers can be used.

SSL/TLS required on connection in order to match server certificates.

Items & subsections:

server addr;

Forwarding MTA description.

addr (type: sock): Server IP address/port

agent {

Relaying by local MTA.

If used, this section defines parameters of a local agent listening on 'server' addresses and delivering mails sent by smtp-proxy.

The agent section is derived from smtp-agent section prototype. For detail description of it, see above.

timeouts {

  welcome ... ;
  mail-cmd ... ;
  rcpt-cmd ... ;
  data-cmd ... ;
  data-blk ... ;
  data-end ... ;
  terminate ... ;
  default ... ;
}

This section defines several timeouts for server reply.

Items & subsections:

welcome [seconds];

Timeout for intial 220 reply.

seconds (type: uint16, optional, default: 300): Default value set by RFC2821.

mail-cmd [seconds];

Timeout for reply to MAIL command.

seconds (type: uint16, optional, default: 300): Default value set by RFC2821.

rcpt-cmd [seconds];

Timeout for reply to RCPT command.

seconds (type: uint16, optional, default: 300): Default value set by RFC2821.

data-cmd [seconds];

Timeout for reply to DATA command.

seconds (type: uint16, optional, default: 120): Default value set by RFC2821.

data-blk [seconds];

Timeout for reply to DATA block send completion.

seconds (type: uint16, optional, default: 180)

Default value set by RFC2821.

In fact, RFC says client should have timeout for "awaiting the completion of each TCP SEND call". Instead, smtp-proxy does not start this timeout unless output buffer is full.

data-end [seconds];

Timeout for reply to CRLF.CRLF marker.

seconds (type: uint16, optional, default: 600): Default value set by RFC2821.

terminate [seconds];

Timeout for enforced session termination.

seconds (type: uint16, optional, default: 10)

default [seconds];

Timeout for all other situations.

seconds (type: uint16, optional, default: 300)

[End of section smtp-forwarder.timeouts description.]

hostname name;

Hostname to introduce myself to server.

If omitted, global smtp-proxy.hostname is used.

name (type: str)

size [usage];

Usage of SIZE ESMTP extension to the server.

This item defines, whether smtp-proxy uses SIZE extension to MAIL command. Possible values are:

DISABLE ... do not use SIZE.
INPUT ... use SIZE (if supported by server) with received mail size instead of computing correct one.

usage (type: smtp-size-usage, optional, default: disable)

source-address [client] [addr4 addr4] [addr6 addr6] cluster [cluster];

source-address [client] [addr4 addr4] [addr6 addr6] [physical];

source-address [client] [addr4 addr4] [addr6 addr6] no-fallback;

Source address for outgoing connections to servers.

If omitted, the proper address of the proxy will be used, i.e. in the case of a cluster, the cluster address will be used.

If not specified by the SOURCE-PORT item, a generic port will be used.

The elements entered within this item will be used by the proxy until the first of them is applicable:

- The CLIENT keyword means the original client IP address is used. This mode will be succesful in all cases except mismatch of IP address families.

- The ADDR4/ADDR6 keyword-value pairs mean that the specified address is used for a connection of corresponding address family.

- The CLUSTER keyword means that one of cluster addresses will be used. By default, the main address of the bridge is used, however, any preferred alias address can be listed in the cluster list.- The PHYSICAL option means that the address of the physical interface is used instead of the cluster one.

- The DEFAULT option means the default behavior - i.e. using of the physical address.

- The NO-FALLBACK option means that if no other way of setting the address is acceptable, the session is rejected. Without this option, the system tries to find a suitable source IP address automatically.

client (type: key, optional)
addr4 addr4 (type: host, optional, default: [0.0.0.0])
addr6 addr6 (type: host, optional, default: [::])
<branching element> (type: source-address-mode, optional, default: physical)
cluster (type: host-list, optional, default: {})
Constraints:: Address family must respect the element's address family..

domain names;

List of mail server domain names handled by this forwarder.

These items are used when smtp-proxy needs to send either a copy of a mail, or a DSN message, for choosing the right forwarder. The first forwarder section with matching DOMAIN item(s) is used. More occurences of item are treated as a disjunction (OR-mode).

names (type: str-list)

server-ssl params [session];

server-ssl params command [obligation];

Use SSL/TLS on the connection to a server.

params (type: name of ssl-params, see ssl(5))
<branching element> (type: ssl-startup-mode, optional, default: session)
obligation (type: obligation, optional, default: allowed)

server-cert-match [subject subject] [issuer issuer];

Requirements for server certificate.

subject subject (type: str-set, optional, default: *): acceptable certificate subjects
issuer issuer (type: str-set, optional, default: *): acceptable certificate issuers

altq altq [paltq paltq];

ALTQ queues for data sent to forwarder.

altq (type: name of pf-queue, see pf-queue(5)): queue name
paltq paltq (type: name of pf-queue, see pf-queue(5), optional, default: NULL): priority queue name (if set, used for TCP ACK without data)

[End of section smtp-forwarder description.]

smtp-arg-check [local-part-len local-part-len] ok [addrs];

smtp-arg-check [local-part-len local-part-len] error [errors [addrs]];

smtp-arg-check [local-part-len local-part-len] ignore-err [addrs];

This item defines SMTP envelope arguments check conditions.

local-part-len local-part-len (type: uint8, optional, default: 64)

Maximum length of local part (default set by RFC2821).

<branching element> (type: smtp-err-switch)

This element controls which parsing results match this item:

OK: only correct arguments match
ERROR: arguments with further specified error match
IGNORE-ERR: all arguments (correct and errorneous) match

errors (type: smtp-error-set, optional, default: *)

Set of errors matching this configuration item.

addrs (type: str-set, optional, default: *)

Set of addresses matching this configuration item.

The matching rules are slightly modified for the purpose of email addresses matching:

Regular expressions are matched as usual.
Addresses defined by string ended with the '@' character match given local-part in any domain.
Addresses defined by string beginning by the '@' character match any address within given domain.
Other addresses containing the '@' character match exactly given address.
Addresses defined by string containing no '@' character match any address within given domain and any its subdomain.

Warning: in case of ARG-INVALID error, an empty string (instead of the errorneous address) is being matched against the list.

smtp-reply [code [subject [detail [text]]]];

This item defines SMTP reply code and text.

The default code & text is used if values are omitted.

code (type: uint16, optional, default: 0)

The 3-digit response code; the first digit is also used as the first sub-code (class) of ESC (Enhanced Status Code).

If omitted, the default response code is used.

subject (type: uint8, optional, default: 255)

The second sub-code (subject) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

detail (type: uint8, optional, default: 255)

The third sub-code (detail) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

text (type: str, optional, default: <NULL>)

Response message text.

Constraints:

Reply-code must be 4xx or 5xx.

mailbox email;

Mail recipient address.

email (type: str): Deliver mail to this address, using SMTP-FORWARDER chosen by comparing the address domain name with forwarder DOMAIN(s).
Constraints:: E-mail must comply with RFC.

grey-listing {

  reply ... ;
  block-time ... ;
  retry-time ... ;
  guard-time ... ;
  client-mask ... ;
  file ... ;
}

Grey-listing verification parameters.

If the grey-listing method is used, mails for a newly seen triplet <client, sender, recipient> are temporarily rejected for the BLOCK-TIME period and it is expected their delivery to be successfully retried within the RETRY-TIME period. The triplets are stored into a database file.

For more details, see triplicator(1) manual page.

The particular attributes are normally set at smtp-proxy level (for the default values, see the description at that point) and redefined at delivery-acl level, if needed.

Items & subsections:

reply [code [subject [detail [text]]]];

Default refusal response code and text.

code (type: uint16, optional, default: 0)

The 3-digit response code; the first digit is also used as the first sub-code (class) of ESC (Enhanced Status Code).

If omitted, the default response code is used.

subject (type: uint8, optional, default: 255)

The second sub-code (subject) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

detail (type: uint8, optional, default: 255)

The third sub-code (detail) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

text (type: str, optional, default: <NULL>)

Response message text.

Constraints:

Reply-code must be 4xx or 5xx.

Refusing must be temporary (4xx).

block-time seconds;

Timeout for blocking of newly seen triplets.

seconds (type: uint32)

retry-time seconds;

Total time of waiting for triplet delivery retrying.

Within this time (after the initial BLOCK-TIME period), the triplet is normally processed.

After this time, the triplet is set into initial state.

seconds (type: uint32)

guard-time seconds;

Time of guarded delivery for a triplet.

If the triplet was retried to deliver by the client (and the triplet is thereby enabled), all mails for the triplet are normally processed for the GUARD-TIME period. Every new mail resets this period.

seconds (type: uint32)

client-mask [bits];

Database wide client netmask.

Clients are stored into the database using this mask. This feature allows correct function of grey-listing even for MTAs using a cluster of several machines with several IP addresses.

bits (type: uint8, optional, default: 24)

file name;

Triplet database file name.

This file must be set at smtp-proxy level because it is common for the whole proxy.

name (type: str)

[End of section grey-listing description.]

smtp-proxy name {

  phase ... ;
* tag ... ;
  log-debug { ... }
  log-stats { ... }
  use-resolver ... ;
  cfg-resolution ... ;
  monitoring { ... }
  stats-daily { ... }
  stats-weekly { ... }
  stats-monthly { ... }
  nodaemon ... ;
  singleproc ... ;
  app-user ... ;
  idle-timeout ... ;
  run-block-sigalrm ... ;
  listen-on { ... }
  tcpserver { ... }
  doctype-identification { ... }
  client-conn { ... }
  server-conn { ... }
  mail-pool ... ;
  quarantine ... ;
  postmaster ... ;
  hostname ... ;
  init-timeout ... ;
  bad-commands ... ;
  bad-recipients ... ;
  dsn-mail-copy ... ;
  use-antivirus ... ;
  use-antispam ... ;
  ssl-session-cache { ... }
  grey-listing { ... }
* session-acl name { ... }
* delivery-acl name { ... }
* mail-acl name { ... }
* doc-acl name { ... }
}

This section defines SMTP-proxy attributes.

The smtp-proxy section is derived from proxy section prototype. For detail description of it, see application(5).

Changes to the smtp-proxy section:

Section udpserver is not valid.

Item source-address is not valid.

MAIL-POOL must be specified.

POSTMASTER must be specified.

At least one SESSION-ACL must be specified (proxy must be named in some SYSTEM.ACL.SERVICES).

At least one DELIVERY-ACL must be specified.

At least one MAIL-ACL must be specified.

At least one DOC-ACL must be specified.

USE-ANTIVIRUS must be configured if VIRUS-STATUS used.

QUARANTINE must be configured at proxy level if used in ACLs.

Proxy must listen on QUARANTINE.PORT if used.

GREY-LISTING must be configured if used in DELIVERY-ACL.

WHITE-LISTING must be configured if SPF used in DELIVERY-ACL.

Section monitoring (see monitoring(5))

Item aproxy-user is not valid.

Item data used as rcpts.

Item idle-timeout (see application(5))

Element seconds is optional, default: 300.

Item listen-on.non-transparent (see listen-on(5))

Element port is optional, default: 25.

Element proto is optional, default: tcp.

Item listen-on.transparent (see listen-on(5))

Element port is optional, default: 25.

Element proto is optional, default: tcp.

Item doctype-identification.order (see acl(5))

Only UPLOAD direction can be used.

Added items & subsections:

client-conn {

  recv-bufsize ... ;
  close-timeout ... ;
  send-bufsize ... ;
  log-limit ... ;
}

Client connection options.

The client-conn section is derived from sock-opt section prototype. For detail description of it, see netio(5).

Changes to the client-conn section:

Item conn-timeout is not valid.

Item recv-timeout is not valid.

Item send-timeout is not valid.

Item recv-bufsize (see netio(5))

Buffer must be at least 1002 bytes long.

Item send-bufsize (see netio(5))

Buffer must be at least 1002 bytes long.

server-conn {

  conn-timeout ... ;
  recv-bufsize ... ;
  close-timeout ... ;
  send-bufsize ... ;
  log-limit ... ;
}

Server connection options.

In particular, output buffer size must be large enough to hold all lines of maximal allowed SMTP document header.

The server-conn section is derived from sock-opt section prototype. For detail description of it, see netio(5).

Changes to the server-conn section:

Item recv-timeout is not valid.

Item send-timeout is not valid.

Item recv-bufsize (see netio(5))

Buffer must be at least 1002 bytes long.

Item send-bufsize (see netio(5))

Buffer must be at least 1002 bytes long.

mail-pool name;

Mail pool directory.

The directory is used for temporary storing of incoming mails.

name (type: str): Directory path name (relative to the CHROOT-DIR if any).

quarantine dir [port];

Quarantine directory and resend-port.

dir (type: str)

Directory path name (relative to the CHROOT-DIR if any).

port (type: port, optional, default: 0)

Port for receiving mails sent by admin from quarantine.

This must be one of LISTEN-ON.NON-TRANSPARENT addresses with IP address [127.0.0.1]. Can be omitted if this proxy won't resend quarantine mails.

postmaster email;

Postmaster address.

Mails for <postmaster> are forwarded to this address.

email (type: str): Postmaster email; local-part with quotting is not valid.
Constraints:: E-mail must comply with RFC.

hostname name;

Hostname used instead of regular host name.

name (type: str)

init-timeout [seconds];

Timeout for initial command reception.

seconds (type: uint16, optional, default: 30)

bad-commands [limit];

Maximum of rejected SMTP commands per session.

limit (type: uint16, optional, default: 100)

bad-recipients [limit];

Maximum of rejected RCPT commands per mail.

limit (type: uint16, optional, default: 100)

dsn-mail-copy disable;

dsn-mail-copy [enable] [bytes];

Sending of original mail copy in DSN messages.

Delivery Status Notification (DSN) messages (RFC1894, RFC1982) optionally contain portion of the original mail, delivery status of which is being reported. By default, smtp-proxy sends original mail headers and portion of mail body.

This item allows to disable this behavior, or declare the size limit of mail body portion being sent. When enabled, mail headers are sent always complete.

<branching element> (type: enabling, optional, default: enable)
bytes (type: uint32, optional, default: 16K)

use-antivirus disable;

use-antivirus enable channel;

Antivirus usage mode.

If omitted, or disabled, no antivirus is enabled. In this case, neither any ANTIVIRUS global section can be present nor any MAIL-ACL and DOC-ACL can have VIRUS item specified.

<branching element> (type: enabling)
channel (type: name-list of antivirus, see antivirus(5))

use-antispam disable;

use-antispam enable channel [limit];

Antispam usage.

This section defines type of antispam daemon used and mode of antispam checking operation.

<branching element> (type: enabling)

channel (type: name of antispam, see mod-antispam(5))

Name of antispam global section used.

Referred section defines the way how to communicate with the antispam daemon (see above).

limit (type: uint64, optional, default: 0)

Size limit (in bytes) for antispam check.

Antispam checking used to be very exhausting operation, and typical spam mails used to be not very large (both for passing by size limit filters and for being able to send a lot of copies). That's why it can be desired to avoid checking of very large mails.

Setting of this limit says antispam module not to check mails larger than given limit and declare their spam score to zero.

Setting this limit to zero disables this feature and enables using of antispam to all mails. Be prepared for high machine load and noticeable delay in delivery if used so.

ssl-session-cache {

  capacity ... ;
  dir ... ;
  lock ... ;
}

The ssl-session-cache section is derived from ssl-session-cache section prototype. For detail description of it, see ssl(5).

grey-listing {

  reply ... ;
  block-time ... ;
  retry-time ... ;
  guard-time ... ;
  client-mask ... ;
  file ... ;
}

Grey-listing global default parameters.

Most of these parameters can be redefined in DELIVERY-ACL.

The grey-listing section is derived from grey-listing section prototype. For detail description of it, see above.
Changes to the grey-listing section:: Triplet database file name must be defined.
Item block-time (see above): Element seconds is optional, default: 1h.
Item retry-time (see above): Element seconds is optional, default: 4h.
Item guard-time (see above): Element seconds is optional, default: 36d.

session-acl name {

* from ... ;
* to ... ;
* time ... ;
  time-period-set { ... }
  deny ... ;
  accept ... ;
* doctype-ident-order ... ;
  rule ... ;
  idle-timeout ... ;
  source-address ... ;
  hostname ... ;
  welcome-msg ... ;
  client-ssl ... ;
* client-cert-match ... ;
  unknown-client ... ;
  unmatching-client ... ;
* blacklisted-client ... ;
  white-listing ... ;
  strict-rfc-arg ... ;
  size-limit { ... }
  size-tolerance ... ;
  rcpt-limit { ... }
  dsn-rcpt-limit { ... }
  mail-filter ... ;
  client-altq ... ;
}

The first level of ACL decides whether to accept incoming connection.

The session-acl section is derived from acl-1 section prototype. For detail description of it, see acl(5).

Changes to the session-acl section:

Item user is not valid.

Item auth is not valid.

Item idle-timeout-peer is not valid.

Item plug-to is not valid.

SSL/TLS required on connection in order to match client certificates.

Item doctype-ident-order (see acl(5))

Only UPLOAD direction can be used.

Added items & subsections:

hostname name;

Hostname to introduce myself to client.

If omitted, global smtp-proxy.hostname is used.

name (type: str)

welcome-msg text;

Welcome greeting message text.

Hostname and date/time are added automatically.

If omitted, Kernun proxy name and version is used.

text (type: str)

client-ssl params [session];

client-ssl params command [obligation];

Use SSL/TLS on the connection from a client.

params (type: name of ssl-params, see ssl(5))
<branching element> (type: ssl-startup-mode, optional, default: session)
obligation (type: obligation, optional, default: allowed)

client-cert-match [subject subject] [issuer issuer];

Requirements for client certificate.

subject subject (type: str-set, optional, default: *): acceptable certificate subjects
issuer issuer (type: str-set, optional, default: *): acceptable certificate issuers

unknown-client [text];

Check client's reverse DNS record.

If set, all clients are checked to have DNS reverse record and service is rejected for such that do not.

text (type: str, optional, default: <NULL>): If omitted, default text is used.

unmatching-client [text];

Check client's IP against all client's names' addresses.

If set, all clients are checked to have DNS reverse record correct. It means that at least one name got as reverse client name must have IP address equal to the one of client connection.

text (type: str, optional, default: <NULL>): If omitted, default text is used.

blacklisted-client database [text];

Check client's IP against DNS black-list databases.

If set, all clients are checked to have a DNS A record in given domain and if so, the session is rejected.

If used multiple times, a new resolution operation with full CONN-TIMEOUT is started for every domain (until some query will succeed with an A RR response). Thus, too many items can lead to mail delivery timing out.

database (type: str): List of checked domains.
text (type: str, optional, default: <NULL>): If omitted, default text is used.
Constraints:: Blacklist domain name too long.

white-listing [sender-only];

white-listing highest-mx;

white-listing check-all [alt-domains];

white-listing matching-mx [alt-domains];

Provide white-listing (Sender Policy Framework) checking.

The result can be matched in DELIVERY-ACL.

<branching element> (type: spf-modes, optional, default: sender-only)
alt-domains (type: str-list, optional, default: {}): Alternate domains for SPF check.

strict-rfc-arg;

Check strict RFC2821 MAIL/RCPT argument format.

RFC 2821 defines correct command argument format, but allows for some obsolete formats to be accepted. This item controls (rejects) usage of these old formats.

size-limit {

  soft ... ;
  hard ... ;
}

Maximum mail size.

Soft-limit is also used as SIZE parameter in EHLO response.

The size-limit section is derived from smtp-limit section prototype. For detail description of it, see above.

size-tolerance percent;

Tolerance to clients' SIZE declaration.

If used, client can send given number of percent more data than declared in MAIL SIZE parameter.

If omitted, real size is not checked against declared one.

percent (type: uint32)
Constraints:: Size tolerance must be at most 100%.

rcpt-limit {

  soft ... ;
  hard ... ;
}

Maximum number of recipients per message.

Setting to less than 100 is RFC2821 violation.

The rcpt-limit section is derived from smtp-limit section prototype. For detail description of it, see above.
Item soft (see above): Element val is optional, default: 100.

dsn-rcpt-limit {

  soft ... ;
  hard ... ;
}

Maximum number of recipients per DSN report.

There is no such limit in RFC2821, however, such mails SHOULD have only one recipient (original sender) and null sender (MAIL FROM: <>) is often used by spammers.

This limitation is additional one to the RCPT-LIMIT.

The dsn-rcpt-limit section is derived from smtp-limit section prototype. For detail description of it, see above.
Item soft (see above): Element val is optional, default: 5.

mail-filter name;

SMTP/MIME document filtering/checking rules.

name (type: name of mail-filter, see mod-mail-doc(5))

client-altq altq [paltq paltq];

ALTQ queues for data sent to client.

altq (type: name of pf-queue, see pf-queue(5)): queue name
paltq paltq (type: name of pf-queue, see pf-queue(5), optional, default: NULL): priority queue name (if set, used for TCP ACK without data)

[End of section smtp-proxy.session-acl description.]

delivery-acl name {

* from ... ;
* time ... ;
  time-period-set { ... }
* session-acl ... ;
  deny ... ;
  accept ... ;
* doctype-ident-order ... ;
  rule ... ;
* helo ... ;
* sender ... ;
* recipient ... ;
  spf ... ;
* client-cert-match ... ;
  abort ... ;
  reject ... ;
  refuse ... ;
  discard ... ;
  deliver ... ;
  grey-listing { ... }
* copy-to ... ;
  quarantine ... ;
}

The second level of ACL decides about reply to particular RCPT command and way how to deliver mail.

The delivery-acl section is derived from acl-2 section prototype. For detail description of it, see acl(5).

Changes to the delivery-acl section:

Item server is not valid.

Item user is not valid.

Item parent-acl used as session-acl.

ABORT, REJECT or REFUSE must be specified if DENY is on.

ABORT, REJECT and REFUSE cannot be specified if ACCEPT is on.

DISCARD, DELIVER, QUARANTINE and COPY-TO cannot be specified if DENY is on.

ABORT, REJECT and REFUSE are mutually exclusive.

DISCARD and DELIVER are mutually exclusive.

At least one SENDER must be specified.

At least one RECIPIENT must be specified.

Item doctype-ident-order (see acl(5))

Only UPLOAD direction can be used.

Added items & subsections:

helo [local-part-len local-part-len] ok [addrs];

helo [local-part-len local-part-len] error [errors [addrs]];

helo [local-part-len local-part-len] ignore-err [addrs];

Entry condition - matching HELO/EHLO command parameter.

local-part-len local-part-len (type: uint8, optional, default: 64)

Maximum length of local part (default set by RFC2821).

<branching element> (type: smtp-err-switch)

This element controls which parsing results match this item:

OK: only correct arguments match
ERROR: arguments with further specified error match
IGNORE-ERR: all arguments (correct and errorneous) match

errors (type: smtp-error-set, optional, default: *)

Set of errors matching this configuration item.

addrs (type: str-set, optional, default: *)

Set of addresses matching this configuration item.

The matching rules are slightly modified for the purpose of email addresses matching:

Regular expressions are matched as usual.
Addresses defined by string ended with the '@' character match given local-part in any domain.
Addresses defined by string beginning by the '@' character match any address within given domain.
Other addresses containing the '@' character match exactly given address.
Addresses defined by string containing no '@' character match any address within given domain and any its subdomain.

Warning: in case of ARG-INVALID error, an empty string (instead of the errorneous address) is being matched against the list.

sender [local-part-len local-part-len] ok [addrs];

sender [local-part-len local-part-len] error [errors [addrs]];

sender [local-part-len local-part-len] ignore-err [addrs];

Entry condition - matching MAIL command parameter.

local-part-len local-part-len (type: uint8, optional, default: 64)

Maximum length of local part (default set by RFC2821).

<branching element> (type: smtp-err-switch)

This element controls which parsing results match this item:

OK: only correct arguments match
ERROR: arguments with further specified error match
IGNORE-ERR: all arguments (correct and errorneous) match

errors (type: smtp-error-set, optional, default: *)

Set of errors matching this configuration item.

addrs (type: str-set, optional, default: *)

Set of addresses matching this configuration item.

The matching rules are slightly modified for the purpose of email addresses matching:

Regular expressions are matched as usual.
Addresses defined by string ended with the '@' character match given local-part in any domain.
Addresses defined by string beginning by the '@' character match any address within given domain.
Other addresses containing the '@' character match exactly given address.
Addresses defined by string containing no '@' character match any address within given domain and any its subdomain.

Warning: in case of ARG-INVALID error, an empty string (instead of the errorneous address) is being matched against the list.

recipient [local-part-len local-part-len] ok [addrs];

recipient [local-part-len local-part-len] error [errors [addrs]];

recipient [local-part-len local-part-len] ignore-err [addrs];

Entry condition - matching RCPT command parameter.

local-part-len local-part-len (type: uint8, optional, default: 64)

Maximum length of local part (default set by RFC2821).

<branching element> (type: smtp-err-switch)

This element controls which parsing results match this item:

OK: only correct arguments match
ERROR: arguments with further specified error match
IGNORE-ERR: all arguments (correct and errorneous) match

errors (type: smtp-error-set, optional, default: *)

Set of errors matching this configuration item.

addrs (type: str-set, optional, default: *)

Set of addresses matching this configuration item.

The matching rules are slightly modified for the purpose of email addresses matching:

Regular expressions are matched as usual.
Addresses defined by string ended with the '@' character match given local-part in any domain.
Addresses defined by string beginning by the '@' character match any address within given domain.
Other addresses containing the '@' character match exactly given address.
Addresses defined by string containing no '@' character match any address within given domain and any its subdomain.

Warning: in case of ARG-INVALID error, an empty string (instead of the errorneous address) is being matched against the list.

spf [results];

Entry condition - white-listing (SPF) result.

results (type: spf-result-set, optional, default: *)

client-cert-match [subject subject] [issuer issuer];

Entry condition - matching SSL client certificate.

subject subject (type: str-set, optional, default: *): acceptable certificate subjects
issuer issuer (type: str-set, optional, default: *): acceptable certificate issuers

abort [code [subject [detail [text]]]];

SMTP session is to be immediately closed.

In fact, the operation consists of three steps on client channel: specified reply is sent, reply 421 is sent and connection is closed.

code (type: uint16, optional, default: 0)

The 3-digit response code; the first digit is also used as the first sub-code (class) of ESC (Enhanced Status Code).

If omitted, the default response code is used.

subject (type: uint8, optional, default: 255)

The second sub-code (subject) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

detail (type: uint8, optional, default: 255)

The third sub-code (detail) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

text (type: str, optional, default: <NULL>)

Response message text.

Constraints:

Reply-code must be 4xx or 5xx.

reject [code [subject [detail [text]]]];

Mail is rejected.

If such an action is taken for at least one recipient, the mail will not be accepted and specified reply is sent to the client as a response to both RCPT and DATA commands.

code (type: uint16, optional, default: 0)

The 3-digit response code; the first digit is also used as the first sub-code (class) of ESC (Enhanced Status Code).

If omitted, the default response code is used.

subject (type: uint8, optional, default: 255)

The second sub-code (subject) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

detail (type: uint8, optional, default: 255)

The third sub-code (detail) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

text (type: str, optional, default: <NULL>)

Response message text.

Constraints:

Reply-code must be 4xx or 5xx.

refuse [code [subject [detail [text]]]];

Mail sending to particular recipient is refused.

RCPT command is answered by specified reply code with no impact to other recipients.

code (type: uint16, optional, default: 0)

The 3-digit response code; the first digit is also used as the first sub-code (class) of ESC (Enhanced Status Code).

If omitted, the default response code is used.

subject (type: uint8, optional, default: 255)

The second sub-code (subject) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

detail (type: uint8, optional, default: 255)

The third sub-code (detail) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

text (type: str, optional, default: <NULL>)

Response message text.

Constraints:

Reply-code must be 4xx or 5xx.

discard;

Mail is accepted, but discarded.

The mail will not be sent to this recipient but client is informed as if it was (by reply code 250). No impact to sending to other recipients.

deliver [via via] [to to];

Mail is normally delivered.

via via (type: name of smtp-forwarder, see above, optional, default: NULL)

Name of FORWARDER used for delivery.

If omitted, forwarder is selected according to their DOMAIN attributes.

to to (type: str, optional, default: <NULL>)

New addressee (for forwarding to alias).

grey-listing {

  reply ... ;
  block-time ... ;
  retry-time ... ;
  guard-time ... ;
}

Grey-listing method setting.

Using of this section enables grey-listing mode.

Omitted parameters take value from proxy-global section.

The grey-listing section is derived from grey-listing section prototype. For detail description of it, see above.

Changes to the grey-listing section:

Item client-mask is not valid.

Item file is not valid.

copy-to email;

Blind-copy of mail will be sent to given address.

email (type: str): Deliver mail to this address, using SMTP-FORWARDER chosen by comparing the address domain name with forwarder DOMAIN(s).
Constraints:: E-mail must comply with RFC.

quarantine;

Store mail into quarantine.

[End of section smtp-proxy.delivery-acl description.]

mail-acl name {

* from ... ;
* time ... ;
  time-period-set { ... }
* delivery-acl ... ;
  deny ... ;
  accept ... ;
  rule ... ;
* size ... ;
* content-type ... ;
  virus-status ... ;
* modify-header ... ;
  replace ... ;
* sender ... ;
* recipient ... ;
* recipients ... ;
* spam-score ... ;
* header ... ;
  from-quarantine ... ;
  prefix-subject ... ;
  abort ... ;
  reject ... ;
  discard ... ;
  cancel ... ;
* copy-to ... ;
* redirect-to ... ;
  quarantine ... ;
  omit-dsn ... ;
}

The first ACL on the third level decides how to handle the mail as whole.

In fact, one more decision for the whole mail can be made - in DOC-ACL corresponding to the root of MIME tree.For particular recipient, all denial actions from the third level ACL are collected, the one with highest severity (abort > reject > discard > cancel) from all DOC-ACLs is chosen. Some actions (discard, cancel) have per-recipient impact and no influence to sending mail to other recipients. However, other actions (abort, reject) have per-mail impact and the one with highest severity from all recipients is executed.

If no ACL is found, ABORT action is preformed.

The mail-acl section is derived from mail-acl section prototype. For detail description of it, see mod-mail-doc(5).

Changes to the mail-acl section:

Item parent-acl used as delivery-acl.

Item direction is not valid.

ABORT, REJECT, DISCARD or CANCEL must be specified if DENY is on.

ABORT, REJECT, DISCARD and CANCEL cannot be specified if ACCEPT is on.

ABORT, REJECT, DISCARD and CANCEL are mutually exclusive.

Items QUARANTINE/COPY-TO and ABORT are mutually exclusive.

Items REDIRECT-TO/OMIT-DSN and DENY are mutually exclusive.

Item REDIRECT-TO must be used only once.

Added items & subsections:

abort [code [subject [detail [text]]]];

SMTP session is to be immediately closed.

In fact, the operation consists of three steps on client channel: specified reply is sent, reply 421 is sent and connection is closed.

code (type: uint16, optional, default: 0)

The 3-digit response code; the first digit is also used as the first sub-code (class) of ESC (Enhanced Status Code).

If omitted, the default response code is used.

subject (type: uint8, optional, default: 255)

The second sub-code (subject) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

detail (type: uint8, optional, default: 255)

The third sub-code (detail) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

text (type: str, optional, default: <NULL>)

Response message text.

Constraints:

Reply-code must be 4xx or 5xx.

reject [code [subject [detail [text]]]];

Mail is rejected.

If such an action is taken for at least one recipient, the mail is not accepted and specified reply is sent to the client as a response to DATA command.

code (type: uint16, optional, default: 0)

The 3-digit response code; the first digit is also used as the first sub-code (class) of ESC (Enhanced Status Code).

If omitted, the default response code is used.

subject (type: uint8, optional, default: 255)

The second sub-code (subject) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

detail (type: uint8, optional, default: 255)

The third sub-code (detail) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

text (type: str, optional, default: <NULL>)

Response message text.

Constraints:

Reply-code must be 4xx or 5xx.

discard;

Mail sending to this recipient is denied but the client is informed as if it was sent (recipient is not added to the DSN report).

cancel [code [subject [detail [text]]]];

Mail will not be sent to particular recipient.

The mail still can be successfully sent to other recipients, given response code is used in DSN report that will be sent to the original sender address.

code (type: uint16, optional, default: 0)

The 3-digit response code; the first digit is also used as the first sub-code (class) of ESC (Enhanced Status Code).

If omitted, the default response code is used.

subject (type: uint8, optional, default: 255)

The second sub-code (subject) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

detail (type: uint8, optional, default: 255)

The third sub-code (detail) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

text (type: str, optional, default: <NULL>)

Response message text.

Constraints:

Reply-code must be 4xx or 5xx.

copy-to email;

Blind-copy of mail will be sent to given address.

email (type: str): Deliver mail to this address, using SMTP-FORWARDER chosen by comparing the address domain name with forwarder DOMAIN(s).
Constraints:: E-mail must comply with RFC.

redirect-to email;

Change final mail recipient.

email (type: str): Deliver mail to this address, using SMTP-FORWARDER chosen by comparing the address domain name with forwarder DOMAIN(s).
Constraints:: E-mail must comply with RFC.

quarantine;

Store mail into quarantine.

omit-dsn;

Discard in case of delivery failure.

This item defines proxy behavior in case when a delivery process fails for particular recipient. If it is used, the recipient is dealt like if the delivery succeeds. Thus, this delivery failure does not cause sending of the Delivery Status Notification (DSN) message.

[End of section smtp-proxy.mail-acl description.]

doc-acl name {

* from ... ;
* time ... ;
  time-period-set { ... }
* delivery-acl ... ;
  deny ... ;
  accept ... ;
  rule ... ;
* size ... ;
* content-type ... ;
* mime-type ... ;
  virus-status ... ;
* modify-header ... ;
  force-doctype-ident ... ;
  replace ... ;
  html-filter ... ;
* sender ... ;
* recipient ... ;
* spam-score ... ;
* header ... ;
* filename ... ;
  from-quarantine ... ;
  add-virus-names ... ;
  abort ... ;
  reject ... ;
  discard ... ;
  cancel ... ;
* copy-to ... ;
  quarantine ... ;
}

The second ACL on the third level decides how to process particular documents (or precisely: MIME tree nodes) contained in the mail.

Denial actions (if any) concern whole mail-copy for particular recipient, not only a single document. The one with highest severity (abort > reject > discard > cancel) from all DOC-ACLs is executed.

If no ACL is found, ABORT action is preformed.

The doc-acl section is derived from mail-doc-acl section prototype. For detail description of it, see mod-mail-doc(5).

Changes to the doc-acl section:

Item parent-acl used as delivery-acl.

Item direction is not valid.

ABORT, REJECT, DISCARD or CANCEL must be specified if DENY is on.

ABORT, REJECT, DISCARD and CANCEL cannot be specified if ACCEPT is on.

ABORT, REJECT, DISCARD and CANCEL are mutually exclusive.

Items QUARANTINE/COPY-TO and ABORT are mutually exclusive.

Added items & subsections:

abort [code [subject [detail [text]]]];

SMTP session is to be immediately closed.

In fact, the operation consists of three steps on client channel: specified reply is sent, reply 421 is sent and connection is closed.

code (type: uint16, optional, default: 0)

The 3-digit response code; the first digit is also used as the first sub-code (class) of ESC (Enhanced Status Code).

If omitted, the default response code is used.

subject (type: uint8, optional, default: 255)

The second sub-code (subject) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

detail (type: uint8, optional, default: 255)

The third sub-code (detail) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

text (type: str, optional, default: <NULL>)

Response message text.

Constraints:

Reply-code must be 4xx or 5xx.

reject [code [subject [detail [text]]]];

Mail is rejected.

If such an action is taken for at least one recipient, the mail is not accepted and specified reply is sent to the client as a response to final dot.

code (type: uint16, optional, default: 0)

The 3-digit response code; the first digit is also used as the first sub-code (class) of ESC (Enhanced Status Code).

If omitted, the default response code is used.

subject (type: uint8, optional, default: 255)

The second sub-code (subject) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

detail (type: uint8, optional, default: 255)

The third sub-code (detail) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

text (type: str, optional, default: <NULL>)

Response message text.

Constraints:

Reply-code must be 4xx or 5xx.

discard;

Mail sending to this recipient is denied but the client is informed as if it was sent (recipient is not added to the DSN report).

cancel [code [subject [detail [text]]]];

Mail will not be sent to particular recipient.

The mail still can be successfully sent to other recipients, given response code is used in DSN report that will be sent to the original sender address.

code (type: uint16, optional, default: 0)

The 3-digit response code; the first digit is also used as the first sub-code (class) of ESC (Enhanced Status Code).

If omitted, the default response code is used.

subject (type: uint8, optional, default: 255)

The second sub-code (subject) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

detail (type: uint8, optional, default: 255)

The third sub-code (detail) of ESC (Enhanced Status Code).

If omitted, the default sub-code is used.

text (type: str, optional, default: <NULL>)

Response message text.

Constraints:

Reply-code must be 4xx or 5xx.

copy-to email;

Blind-copy of mail will be sent to given address.

email (type: str): Deliver mail to this address, using SMTP-FORWARDER chosen by comparing the address domain name with forwarder DOMAIN(s).
Constraints:: E-mail must comply with RFC.

quarantine;

Store mail into quarantine.

[End of section smtp-proxy.doc-acl description.]

[End of section smtp-proxy description.]

Prev	Up	Next
sip-proxy.cfg	Home	smtp-proxy.cfg

Name

DESCRIPTION

TYPES

ITEMS AND SECTIONS

SEE ALSO