General Settings

• Table of Contents
• Networking
  • Server Name
  • Port Conflicts
  • NAT and Co-Existing with Another MTA
• Notifications
  • Error Notification Address
  • Disk Space Depletion Notifications
• Disk Space and RAM
  • Delivery Attempt Log Retention
  • SimpleMH and Studio Remote List Email Address Retention
  • ram-queue Size
  • Queue Lifetime
  • Maximum SMTP Message Size
  • Maximum Bounce Message Size
• Web Interface
  • Web Interface Password
  • Hiding Internal Sends
• SMTP Settings
  • Customizing SMTP HELO Values for Outgoing SMTP Sessions
  • Customizing the SMTP Greeting Banner for Incoming SMTP Sessions
  • Idle Connections with SMTP Clients
  • Timeout in Connections to Remote SMTP Servers
  • Delivery Concurrency
  • IADB Headers

Networking

Server Name

You must set the domain name that the server uses to refer to itself. This should be a fully qualified domain name that resolves to a publicly accessible IP address on the GreenArrow Engine server. This will sometimes match the value that’s returned when the hostname command is executed.

• To set:

  hvmail_set me server.example.com
  hvmail_init restart
  

• To read:

  cat /var/hvmail/control/me
  

Some of the places that this value is used are:

1. The Message-ID header that gets inserted when GreenArrow Studio or a local injection option such as qmail-inject is used to inject a message into GreenArrow Engine.
2. The Received header that GreenArrow Engine inserts by default for messages injected via SMTP or QMQP.
3. The Server-Default TLS Certificate, unless overwritten by tls_certificate_files or tls_certificate_auto_generate.

Port Conflicts

This setting allows GreenArrow Engine to kill a process that it observes using an IP address/port combination that GreenArrow Engine is configured to use. For example, if the Sendmail MTA is installed, it might bind to port 25 before GreenArrow Engine does. With this setting enabled, GreenArrow Engine will attempt to kill the Sendmail process that’s bound to port 25 before starting up its SMTP service.

• To enable forcibly taking ports:

  echo 1 > /var/hvmail/control/tcp.take_ports
  

• To disable forcibly taking ports:

  echo 0 > /var/hvmail/control/tcp.take_ports
  

NAT and Co-Existing with Another MTA

The /var/hvmail/control/replaceipme file contains a list of IP addresses that the server should not deliver mail to on port 25. If this file is missing, then the variable that this file sets is initialized to a list of all of the IP addresses locally assigned to the server. The purpose of not sending mail to these IP addresses is to prevent mail loops.

You may need to override the default value if the server has additional IP addresses via NAT. Configure this file to include all local IP addresses plus all IP addresses that are NATed back to this server.

You may also need to override this if the server is running both GreenArrow Engine and another MTA. To enable GreenArrow Engine to send mail to the other MTA, configure this file to have a list of IP addresses that GreenArrow Engine is listening for SMTP connections on port 25. Make sure the IP addresses served by the other MTA are excluded, otherwise GreenArrow Engine will not be able to send to the other MTA.

GreenArrow expects this file to have one IP address per line. The order of IP addresses in this list does not matter.

Here is an example /var/hvmail/control/replaceipme file:

127.0.0.1
10.0.0.1
1.2.3.4

No steps are required to apply changes to this file.

Notifications

Error Notification Address

GreenArrow Engine will send out email notifications. The default is to send an email to root @ the server name.

• To set this value, edit the /var/hvmail/control/notifications_to file. You may specify multiple, comma separated addresses if you wish. For example:

  [email protected], [email protected]
  

• To read:

  cat /var/hvmail/control/notifications_to
  

Disk Space Depletion Notifications

The /var/hvmail/control/disk_space_check file can be used to set the threshold at which to send disk space depletion notifications to the Error Notification Address. By default, notifications are sent if any mounted filesystem’s disk space utilization exceeds 80%. For example, to set the threshold of / to 60%, and /media/psql to 70%, the following lines would be added:

/:60
/media/psql:70

You can set the notification threshold for all mounted filesystems by specifying a filesystem path of default. Here’s an example:

default:80

Disk Space and RAM

Delivery Attempt Log Retention

GreenArrow Engine can be configured to store a variable amount of delivery attempt log files.

• To set, replace n in the command below with the number of gigabytes that you wish to allocate:

  hvmail_set log_disk_space n
  svc -t /service/hvmail-*-qmail-send/log && sleep 7 && svstat /service/hvmail-*-qmail-send/log
  

• GreenArrow’s default is 4GB, but if this config has already been modified from the default, there is not currently a method for reading this value. To view the current disk space usage of these log files:

  du -hc /var/hvmail/log/*-qmail-send/ | grep total
  

SimpleMH and Studio Remote List Email Address Retention

The /var/hvmail/control/opt.click_bounce_emaillist_retention_days file, which does not exist by default can be created to control the retention period, in days for data in the /var/hvmail/var/clickthrough-tracking-emaillist/ directory. This directory is used to store data including lists of email addresses sent to for the following:

• SimpleMH click and open tracking
• SimpleMH bounce passthrough
• SimpleMH email that uses a click tracking ID
• SimpleMH email where the localpart of the Return-Path is more than 64-characters long
• Bounce processing for Studio remote list email

The following happens when this data is deleted:

• New clicks/opens/bounces are not recorded with the correct email address and click tracking ID
• If SimpleMH’s bounce passthrough feature is turned on then bounce pass through stops working

This data is retained for 60 days by default.

Setting this file equal to 0 will cause this data to be retained indefinitely. Setting the file equal to any other positive integer will cause GreenArrow to retain this data for the specified number of days.

To increase the retention period for this data to 365 days, run:

echo 365 > /var/hvmail/control/opt.click_bounce_emaillist_retention_days

No services need to be restarted to apply changes to this file.

ram-queue Size

GreenArrow Engine uses three mail queues. Two of these - the ram-queue, and bounce-queue are stored in RAM. The ram-queue is used for messages that have not yet had their first delivery attempt take place.

Here’s how to set the total amount of RAM that’s allocated to the ram-queue and bounce-queue:

1. Update the configuration by running the following command, replacing SETTING with a value from the table shown below:

   hvmail_set ramdisk_size SETTING
   

   Setting	Description
   auto	Autoconfigure the RAM and Bounce queues based on installed RAM. Assumes that this server is dedicated to GreenArrow
   xxlarge_3300mb_12000conn	High-performance server with 3.3 GB of RAM to dedicate to the ram-queue. We usually only recommend this setting for servers with at least 16GB of RAM installed.
   xxlarge_3300mb_12000conn_multiqueue	High-performance server with 3.3 GB of RAM to dedicate to the ram-queue and which has MultiQueue or Message Batching enabled. We usually only recommend this setting for servers with at least 16GB of RAM installed.
   xlarge_500mb_2000conn	Server with at least 4GB of RAM. This is the default setting.
   xlarge_1000mb_2000conn_multiqueue	Server with at least 4GB of RAM and which has MultiQueue or Message Batching enabled.
   large_250mb_1000conn	Servers with more than 1 GB of RAM.
   medium_160mb_1000conn	Servers with 1 GB of RAM or less.
   small_100mb_500conn	Servers with less than 500MB of RAM, lower performance.
   micro_30mb_100conn	Very low performance, demo server installs.

   For example, you could run:

   hvmail_set ramdisk_size large_500mb_2000conn
   

2. Restart GreenArrow’s MTA services:

   hvmail_init restart
   

To view the space, in megabytes that was allocated to the ram-queue and bounce-queue, run:

cat /var/hvmail/control/queue.ram.ramdisk.size
cat /var/hvmail/control/queue.bounce.ramdisk.size

If you receive a qq write error or disk full (#4.3.0) error when attempting to inject a message into GreenArrow Engine, this most likely means that there is not sufficient space in your ram-queue to store the message.

Each file that’s in the ram-queue or bounce-queue occupies an inode. To view the number of inodes that have been allocated to the ram-queue and bounce-queue, run:

cat /var/hvmail/control/queue.ram.ramdisk.inodes
cat /var/hvmail/control/queue.bounce.ramdisk.inodes

Queue Lifetime

The queue lifetime controls how long to retry delivery for deferred or throttled messages. The default value is 2 days.

When delivery attempts are deferred or throttled, the messages that were deferred or throttled accumulate. These accumulated messages have the potential to take up a significant amount of disk space. To view the amount of disk space that’s currently being used by these messages, run:

greenarrow disk_usage --area="Engine:Disk Queue"

The queue lifetime can be set server-wide, on a per-VirtualMTA basis, or on a per-recipient-domain basis.

The queue lifetime for each message is the first match in the following list:

1. The queue_lifetime configured for the recipient’s domain within the virtual_mta_injected block for the Virtual MTA requested at the time of injection.

2. The queue_lifetime configured for the recipient’s domain within the wildcard * virtual_mta_injected block if present.

3. The queue_lifetime configured for the recipient’s domain within the ip_address block for the VirtualMTA that the most recent delivery attempt used.

4. The queue_lifetime configured for the recipient’s domain within the wildcard * ip_address block if present.

5. The default value of 2 days.

Reducing the queue lifetime can free disk space, and boost performance in the long run. In the short term, a queue lifetime update causes a performance hit proportionate to the amount of mail that expires once the new setting goes into effect. This is because of the bounce processing that takes place any time a message expires. For this reason, we recommend that changes be made cautiously, at non-peak hours.

Messages which have had their queue lifetime reduced will receive one final delivery attempt, even if the message has technically “expired”. This is because expiration is checked after each deferred or throttled delivery attempt.

Maximum SMTP Message Size

The databytes parameter controls how large messages accepted via SMTP or other network protocols can be. By default, there’s a 1MB limit. This limit applies to the message body and any attachments. If you see this error, the value in this config file most likely needs to be increased:

sorry, that message size exceeds my databytes limit (#5.3.4)

To change this value to 10MB, run:

echo 10485760 > /var/hvmail/control/databytes

No services need to be restarted for changes to this file’s value to take effect.

Maximum Bounce Message Size

The bouncemaxbytes parameter controls how many bytes of the original message to include when generating a bounce message. By default, this file is set to 102400, meaning there’s a 100KB limit. To change this value to 20KB, run:

echo 20480 > /var/hvmail/control/bouncemaxbytes
hvmail_init restart

Enter 1 into this file to create the smallest possible bounce message size. Doing this will effectively include only the first line of the original message. The bounce message itself won’t be omitted, and the Return-Path has already been read by the time that setting is checked:

echo 1 > /var/hvmail/control/bouncemaxbytes
hvmail_init restart

Web Interface

Web Interface Password

• To set the password used by the admin user in GreenArrow Engine’s web interface, run this command, replacing PASSWORD below with the new password you’d like to use:

  hvmail_set admin_password PASSWORD
  

• To read the current list of users (passwords are encrypted):

  cat /var/hvmail/control/htpasswd
  

• You can create additional users by editing the /var/hvmail/control/htpasswd file. This file is in the Apache htpasswd format. For example, to add or modify the password of a new user named greenarrow, you could run:

  /var/hvmail/apache/bin/htpasswd /var/hvmail/control/htpasswd greenarrow
  

  Usernames with a -statsonly suffix are only able to view stats.

Hiding Internal Sends

If the /var/hvmail/control/webapp.hide_internal_sends file is set to 1, then internal sends (messages sent with a SendID of -ic) will be hidden from the web browser interface.

The most common example of such a message is a bounce.

• To hide internal seeds:

  echo 1 > /var/hvmail/control/webapp.hide_internal_sends
  

• To make internal seeds visible:

  echo 0 > /var/hvmail/control/webapp.hide_internal_sends
  

SMTP Settings

Customizing SMTP HELO Values for Outgoing SMTP Sessions

An outgoing SMTP session is one in which GreenArrow Engine is acting as an SMTP client.

The hostname that’s contained within the HELO value that’s used for outgoing SMTP sessions can be configured by updating an IP address’ Hostname value, as described in the IP Address VirtualMTAs page.

Customizing the SMTP Greeting Banner for Incoming SMTP Sessions

An incoming SMTP session is one in which GreenArrow Engine is acting as an SMTP server.

GreenArrow Engine uses the server name, located in the /var/hvmail/control/me file as the default hostname value when constructing the SMTP greeting banner for all incoming SMTP sessions. This default value can be overwritten on a per-IP-address basis by updating the /var/hvmail/control/smtpgreetings file.

In most cases GreenArrow Engine’s default behavior is correct, and the /var/hvmail/control/smtpgreetings file does not need to be created.

• To update the /var/hvmail/control/smtpgreetings file manually, use the following format to map each locally assigned IP address to its hostname. Note that if you’re using NAT, you’ll need to map the NATed IP addresses, rather than the public IP addresses that are being mapped to:

  1.2.3.4:smtp1-1.domain.com
  2.3.4.5:smtp1-2.domain.com
  

• Alternatively, you can use the script below to populate /var/hvmail/control/smtpgreetings automatically. The script performs a reverse DNS lookup for each locally assigned IP address and writes the result to /var/hvmail/control/smtpgreetings. For this script to work, reverse DNS must already be configured for all IP addresses.

  The script was tested in CentOS 8.x. It may require some modification to work on other Linux distributions::

  for i in `ifconfig | grep inet | grep -v 127.0.0.1 | grep -v inet6 | cut -d' ' -f10 | awk '{print $1}' | sort -n -t . -k 1,1 -k 2,2 -k 3,3 -k 4,4` ; do host=`host $i | grep arpa | awk '{print $5}' ` ; echo $i:$host ; done | sed 's/.$//g' > /var/hvmail/control/smtpgreetings
  

  NOTE: this script overwrites the /var/hvmail/control/smtpgreetings file

Idle Connections with SMTP Clients

GreenArrow Engine will allow idle SMTP clients to keep connections open for up to 120 seconds by default. This value can be adjusted by updating the /var/hvmail/control/timeoutsmtpd file.

For example, to reduce this value to 60 seconds, run:

echo 60 > /var/hvmail/control/timeoutsmtpd

Timeout in Connections to Remote SMTP Servers

GreenArrow Engine will allow a delivery attempt’s remote connection to stay open so long as communication is received from the remote server periodically. The maximum allowable length of time between communications before the connection times out can be adjusted by updating the /var/hvmail/control/timeoutremote file.

For example, to reduce this value to 60 seconds, run:

echo 60 > /var/hvmail/control/timeoutremote

The behavior of timeouts is modified when using the proxy_server configuration directive. See the Proxy Protocol documentation for more information.

Delivery Concurrency

The /var/hvmail/control/opt.greenarrow_remote_concurrency file controls the max number of concurrent remote connections GreenArrow Engine is allowed to make. A value of 0 means unlimited. The default is 10,000.

This file does not normally need to be tuned.

IADB Headers

GreenArrow MTA can write the IADB headers.

To enable this feature:

echo 1 > /var/hvmail/control/add_iadb_header

To turn it off:

echo 0 > /var/hvmail/control/add_iadb_header

With this feature enabled, the following headers will be added to emails sent:

X-IADB-IP
X-IADB-IP-REVERSE
X-IADB-URL