GreenArrow Email Software Documentation

Convert PowerMTA® Configuration

Introduction

GreenArrow provides a command for converting a PowerMTA® configuration file to the greenarrow.conf format.

This converter handles many PowerMTA configuration directives. Those that are supported are listed below. No all directives are supported in all scopes. These differences are discussed in the directive documentation below.

Any unsupported directives or scopes will produce warnings when running the converter.

If you need an additional scope or directive, please contact GreenArrow.

(PowerMTA is a registered trademark of Port25 Solutions, Inc. – Port25 Solutions, Inc. is not affiliated or associated with GreenArrow.)

Converting your PowerMTA configuration file

The greenarrow_convert_powermta_configuration command comes with GreenArrow. This command accepts, on its standard input, a PowerMTA configuration file. On success, it prints a greenarrow.conf configuration to standard output.

To use this system:

  • The output of greenarrow_convert_powermta_configuration must be included into your /var/hvmail/control/greenarrow.conf file. We recommend using an include directive in greenarrow.conf.

  • Your greenarrow.conf file must enable define_virtual_mtas_in_config_file.

  • Your greenarrow.conf file must define a default_virtual_mta.

WARNING!! Defining define_virtual_mtas_in_config_file yes will cause all VirtualMTAs, Relay Servers, and Routing Rules that you defined in the Web UI or through the API to be deleted and replaced with those defined in the configuration file.

WARNING!! If you omit define_virtual_mtas_in_config_file yes, the configuration will validate, but none of the IP addresses or Routing Rules that you defined will have any effect.

Example

Given the file /usr/local/etc/our_powermta_config.conf containing PowerMTA configuration directives.

Run the following to create a GreenArrow configuration file:

greenarrow_convert_powermta_configuration \
  < /usr/local/etc/our_powermta_config.conf \
  > /usr/local/etc/our_converted_greenarrow_config.conf

Then, edit /var/hvmail/control/greenarrow.conf to:

This would look like:

general {
  define_virtual_mtas_in_config_file yes
  default_virtual_mta my-ipaddr-defined-in-powermta-config
}
include "/usr/local/etc/our_converted_greenarrow_config.conf"

Defaults

On some directives, GreenArrow and PowerMTA have different defaults.

If you’d like to use the PowerMTA defaults in GreenArrow, put this configuration block into your /var/hvmail/control/greenarrow.conf:

ip_address * {
  domain * {
    starttls_require yes
    reuse_connections yes
    reuse_connections_max_messages 0
    max_concurrent_connections 20
    retry_time 10m
    queue_lifetime 108h
  }
}

Supported Directives

These are the PowerMTA configuration directives that are supported by the converter.

domain

  • Grouping directive
  • Scope: top-level, virtual-mta
  • Converted to: domain

This directive contains settings related to one or more domain names.

In PowerMTA, it can exist either in the virtual-mta grouping directive or at the top level. In GreenArrow, the domain directive is always contained within an ip_address. To have the same effect, the top-level PowerMTA virtual-mta directive is translated to a GreenArrow domain directive inside of a ip_address directive set to the wildcard value (*).

Supports a comma-separated list of domain names and/or wildcards.

Supports the following forms of wildcards:

  • * – match anything
  • *.domain – match foo.domain, bar.domain, but not domain
  • [*.]domain – match foo.domain, bar.domain, and domain

Does not support [ip/mask] form (which is supported by PowerMTA).

Supports domain-macro replacement codes and expansions, such as $aol.$topLevel.

When looking up delivery to foo.example.com domain strings are searched for in the following order:

foo.example.com
[*.]foo.example.com
*.example.com
[*.]example.com
*.com
[*.]com

When searching for the first match from the above list of strings, each string is always first looked for in a matching domain directive inside of a matching virtual-mta directive, and then a top-level/general domain directive. So, for example, the lookup for foo.example.com starts out as:

  • foo.example.com in matching domain directive inside a matching virtual-mta directive
  • foo.example.com in top-level domain directive
  • [*.]foo.example.com in matching domain directive inside a matching virtual-mta directive
  • [*.]foo.example.com in top-level domain directive

…etc

Example:

<domain aol.com,aol.co.uk>
retry-after 1h
</domain>

This searching order is the same as PowerMTA.

For more information on how GreenArrow matches domains, see the domain directive.

retry-after

  • Scope: domain
  • Attributes: interval
  • PowerMTA Default: 10 minutes
  • GreenArrow Default: Retry Schedule
  • Converts to: retry_time

The interval between message retries.

GreenArrow, by default, uses a retry schedule wherein retries get further apart until the message succeeds, fails, or reaches its maximum age due to queue_lifetime.

bounce-after

  • Scope: domain
  • Attributes: one-time interval
  • PowerMTA Default: 4 days, 12 hours
  • GreenArrow Default: 2 days
  • Converts to: queue_lifetime

The maximum amount of time to retry a message.

use-starttls

  • Scope: domain
  • Attributes: one boolean
  • PowerMTA Default: false
  • GreenArrow Default: false
  • Converts to: starttls_use

If true, GreenArrow will attempt to use the STARTTLS extension, if offered.

require-starttls

  • Scope: domain
  • Attributes: one boolean
  • PowerMTA Default: true
  • GreenArrow Default: false
  • Converts to: starttls_require

If use-starttls is enabled, then do not deliver email unless STARTTLS is available and the STARTTLS command succeeds.

If use-starttls is not enabled, require-starttls has no effect.

In GreenArrow, the starttls_require_action directive determines what kind of failure results from STARTTLS not being offered, or failing to establish.

type

  • Scope: domain
  • Attributes: string, either smtp or discard
  • PowerMTA Default: smtp
  • GreenArrow Default: The equivalent of smtp is delivery_override none
  • Converts to: delivery_override

smtp means the delivery should be done through SMTP (which is the default). discard means the delivery should be discarded (permanently failed).

domain-macro

  • Scope: top-level
  • Attributes: first argument is macro name, and second argument is a comma-separated list of domains
  • Converts to: domain_macro

Example:

domain-macro microsoft hotmail.com, msn.com, live.com, outlook.com

Allows you to then specify:

<domain $microsoft>
...
</domain>

Or, additionally multiple macros may be expanded at the same time:

domain-macro tlds "com, co.uk, co.in"
domain-macros aol "aol, aim"
<domain $aol.$tls>
...
</domain>

Is equivalent to specifying:

<domain aol.com, aim.com, aol.co.uk, aim.co,uk, aol.co.in, aim.co.in>
...
</domain>

virtual-mta

Specifies the configuration of a specific IP address record in GreenArrow.

Each virtual-mta is required to have both the smtp-source-ip and host-name configuration directives defined.

Example:

<virtual-mta out17>
  smtp-source-ip 10.0.0.17
  host-name mail-out17.example.com
</virtual-mta>

host-name

Specifies the hostname to use for the IP Address record created by parent virtual-mta directive.

smtp-source-ip

  • Scope: smtp-source-ip
  • Attribute: IP address
  • Converts to: smtp_source_ip

Specifies the IP address for the IP Address record created by the parent virtual-mta directive.

assume-delivery-upon-data-termination-timeout

When true, if there is a timeout or connection termination while waiting for the reply to the . which terminates the message, the message delivery will be considered successful. When false, a timeout or connection termination will be considered a temporary error.

bounce-upon-transfer-failure

When true, if the delivery attempt fails or times out while transmitting the message, then consider the delivery a permanent failure. When false, this failure or timeout will be considered a temporary error.

log-data

  • Scope: domain
  • Attribute: boolean
  • PowerMTA Default: false
  • GreenArrow Default: false
  • Converts to: log_smtp_hexdump

Logs binary data from conversations with remote SMTP servers.

log-commands

  • Scope: domain
  • Attribute: boolean
  • PowerMTA Default: false
  • GreenArrow Default: false
  • Converts to: log_smtp_commands

Will log the SMTP conversation excluding the DATA of the message.

log-connections

  • Scope: domain
  • Attribute: boolean
  • PowerMTA Default: false
  • GreenArrow Default: false
  • Converts to: log_smtp_connections

When true, log information about SMTP connections opened and closed.

log-resolution

  • Scope: domain
  • Attribute: boolean
  • PowerMTA Default: false
  • GreenArrow Default: false
  • Converts to: log_dns

When true, log diagnostic information about DNS lookups – the query sent and the answer received.

max-msg-per-connection

This configures the maximum number of messages that may be transmitted in a single SMTP connection. 0 means unlimited.

max-smtp-out

  • Scope: domain
  • Attribute: numeric
  • PowerMTA Default: 20 when in a domain, 0 (unlimited) when in a virtual-mta
  • GreenArrow Default: 0 (unlimited)
  • Converts to: max_concurrent_connections

Limits the number of SMTP concurrent connections. 0 means unlimited.

Differences from PowerMTA: In PowerMTA max-smtp-out can be specified in the domain and virtual-mta scope. This converter only supports the domain scope.

max-msg-rate

  • Scope: domain
  • Attribute: rate (unlimited, 0, or number/[h|hr|m|min|s|sec])
  • PowerMTA Default: 0
  • GreenArrow Default: 0 (unlimited)
  • Converts to: max_delivery_rate

Limits the maximum speed at which delivery attempts may be made. 0 means unlimited.

max-name-queries

  • Scope: global
  • Attribute: number
  • PowerMTA Default: 100
  • GreenArrow Default: 100
  • Converts to: max_dns_queries

This configures the maximum number of concurrent DNS requests that may be performed at one time.

total-max-smtp-out

The system-wide maximum number of concurrent SMTP connections.

virtual-mta-pool

  • Scope: global
  • Grouping directive
  • Attribute: string
  • Converts to: routing_rule

Defines a Routing Rule in GreenArrow’s configuration, where delivery attempts may be randomized through multiple VirtualMTAs. The attribute will be used as the name of the created Routing Rule. Each contained VirtualMTA will receive an equal proportion of delivery attempts.

For example:

<virtual-mta-pool customer1>
  virtual-mta smtp1
  virtual-mta smpt2
</virtual-mta-pool>

virtual-mta (when inside virtual-mta-pool)

Defines one of the destination VirtualMTAs for a virtual-mta-pool. The attribute must be the name of a <virtual-mta> or a <virtual-mta-pool> in this configuration file.

include

  • Scope: global
  • Attribute: filename

Includes configuration from another file.

This directive is not converted by the GreenArrow to PowerMTA® converter. Instead, the included file’s contents are read in and converted.

GreenArrow does, however, support an include directive.

domain-key

  • Scope: global, virtual-mta, virtual-mta-pool
  • Attribute: string: “selector,domain_name,private_key_filename”
  • Converts to: pcompat_dkim_key

Specifies the combination of a selector, domain and private key to use for DKIM signing.

The key in the referenced file must be in PEM format.

The domain_name may be * to match all domain names.

Keys are searched for as follows:

  • The first key (in the order specified in the configuration file) that contains a domain name equal to or a parent of the messages sending domain name is used for signing.
  • Keys defined on the virtual-mta or virtual-mta-pool level take precedence over keys defined on the global level.
  • If no matching domain name is found, then the message is not signed.

The message’s sending domain name is equal to the domain name of the Sender header, and if that does not exist the domain name of the From header.

Differences from PowerMTA: DKIM signing appears to be done by PowerMTA at the time of email delivery. GreenArrow DKIM signs at the time of message queueing (using the VirtualMTA name assigned to the message at that time.)

dkim-sign

  • Scope: domain (but only in domain blocks that specify *)
  • Attribute: boolean
  • PowerMTA Default: false
  • GreenArrow Default: false
  • Converts to: pcompat_dkim_sign

If true, then messages will be DKIM signed if there is a matching key provided with a domain-key record.

Differences from PowerMTA: In GreenArrow’s PowerMTA configuration adapter, dkim-sign can only be specified in domain blocks with a domain of *, whereas in PowerMTA they can be in any domain block. We have not found any GreenArrow customers that need to specify dkim-sign based on the domain name. If you need this, please let us know.

dkim-identity

  • Scope: domain (but only in domain blocks that specify *)
  • Attribute: string
  • Converts to: pcompat_dkim_identity

Allows you to DKIM sign email with a domain name that does not match the From/Sender header, a technique often used by ESPs.

If no exact matching domain-key record is found for the From/Sender header domain name, then:

  • If a dkim-identity record exists, and the domain name in the dkim-identity record has a matching dkim-sign record or a dkim-sign record that is a parent of the domain name of the dkim-identity domain name, then:
    • A DKIM signature will be produced with:
      • d= paramenter = the domain name used in the dkim-sign directive
      • i= parameter = the domain name used in the dkim-identity directive

Differences from PowerMTA: In GreenArrow’s PowerMTA configuration adapter, dkim-identity can only be specified in domain blocks with a domain of *, whereas in PowerMTA they can be in any domain block. We have not found any GreenArrow customers that need to specify dkim-identity based on the domain name. If you need this, please let us know.

route

  • Scope: domain
  • Attribute: string
  • Converts to: smtp_route

Overrides MX resolution for the destination to deliver email.

Valid formats:

  • route example.com – lookup DNS A record for example.com and deliver email there
  • route 1.2.3.4 – deliver to this IP address
  • route 1.2.3.4:26 – deliver to this IP address on port 26

Note: does not support multiple destinations in a round-robin fashion or with different priorities (as is supported by PowerMTA; we may add this in the future).

 URL Domains
Secret Constants 

Copyright © 2012–2024 GreenArrow Email