GreenArrow Documentation

SMTP AUTH and POP3 Email Users

Once your GreenArrow Engine server is configured to receive email for a domain, it can also be configured with SMTP AUTH and POP3 users.

SMTP AUTH

When relaying messages into GreenArrow Engine via SMTP, you have two authorization options. The first option is to specify which IP addresses are authorized to relay mail through GreenArrow Engine. The second option is to create email users, then use SMTP AUTH, or username/password based authentication to log in as an email user before relaying messages.

When a new email user is created within GreenArrow Engine (see below), it’s granted SMTP AUTH access to GreenArrow Engine’s SMTP services. GreenArrow Engine’s default configuration includes SMTP services that listen on ports 25 and 587. Some ISPs block outgoing access to port 25, so configuring your injecting application or email client to connect to port 587 is recommended in most configurations.

SMTP AUTH is enabled by default. You can disable SMTP AUTH by sending in a request to GreenArrow technical support or following the steps in the SMTP Services page’s Authorizing SMTP Clients section.

POP3 and Email Forwarders

When a new email user is created within GreenArrow Engine, you have a few different options for how to deliver mail received by that user:

  • Deliver to local mailbox - stores incoming mail on your GreenArrow Engine server in a Maildir that can be accessed via POP3. GreenArrow Engine’s POP3 server listens on port 110 by default.
  • Forward to another address - provides the same options for incoming mail as you have when creating an email forwarder.
  • Deliver to local mailbox and forward - combines the Deliver to local mailbox and Forward to another address options.
  • Follow dot-qmail delivery instructions - allows you to include the contents of a .qmail file, and have its logic processed for all incoming messages to this account.

Use the following information to configure your POP3 client:

Field Value
Username The username of the email user that was created.
Password The password of the email user that was created.
Server The hostname of your GreenArrow server. For example, if you log in to GreenArrow Engine’s web interface by going to http://example.com/greenarrowadmin, then the POP3 server is example.com.
Port 110
SSL Off by default. Contact GreenArrow technical support if you would like SSL to be enabled for POP3.
TLS Off

Adding a New Email User

Complete the following steps to create a new email user:

  1. Login to GreenArrow Engine’s web interface.
  2. Navigate to Configure => Domains:
    configure-domains.png
  3. Click the Edit Users/Forwarders button next to the domain that you’d like the forwarder to be created for:
    edit-users-forwarders.png
  4. Click the Add Email User button:
    add-new-email-user.png
  5. Enter the username and password of the user that you’d like to create, and select the desired mail delivery option before clicking Save:
    create-new-email-user.png
    Checking the Use wildcard matching box causes the new email user to receive mail for both the address that’s entered and any address of the form localpart-*@domain. For example, if the username were [email protected], then it would receive mail addressed to [email protected] and [email protected].

    To create a catch-all email address that will accept all emails for users that do not already exist on that domain, create an email address with the username default and click the Use wildcard matching option.

Custom SMTP Authorization

In addition to GreenArrow Engine’s user database, you may add your own users to the database.

GreenArrow Engine provides a eng_smtp_auth_users__raw_db_access table with the following definition.

You may insert, delete, or update this table at will.

                             Table "public.eng_smtp_auth_users__raw_db_access"
     Column     |  Type   |                                    Modifiers
----------------+---------+---------------------------------------------------------------------------------
 id             | bigint  | not null default nextval('eng_smtp_auth_users__raw_db_access_id_seq'::regclass)
 username       | text    | not null
 crypt_password | text    | not null
 crypt_salt     | text    | not null
 active         | boolean | not null default true
Indexes:
    "eng_smtp_auth_users__raw_db_access_pkey" PRIMARY KEY, btree (id)
    "eng_smtp_auth_users__raw_db_access__username__uniq" UNIQUE, btree (lower(username))

The username field must be case-insensitive unique.

The crypt_salt field can be any value you wish to use to increase the entropy of the hashed passwords.

The crypt_password field should be set to the lowercase hexadecimal SHA256 hash of the concatenation of crypt_salt and the raw password.

<?php
$crypt_password = strtolower(hash("sha256", $crypt_salt . $raw_password));

You may use the active column to disable users temporarily. Only users with active = TRUE will be successfully authenticated.

Users authorized in this way are for sending only. This feature is only enabled if the control flag /var/hvmail/control/opt.smtp_auth_user_database is enabled by running

echo 1 > /var/hvmail/control/opt.smtp_auth_user_database