OpenSMTPD receiving mail

Erm, um... this guide was initially supposed to be primarily about setting up OpenSMTPD to be able to receive E-Mail. However, the guide does also currently cover details on setting up the software to be able to send mail as well.

Note: At the time of this writing, this guide should probably be considered preliminary. Some things have not been tested as fully as desired. However, significant work was placed to even get the document into this state. The hope is the progress so far might be helpful, and save time, for anybody who finds this document at this time.

Getting a mail server going:

First, we got a server going. This involved installing an operating system.

Network setup

For this setup, we used the following configuration. (Using this precise configuration is fairly unrelated to the topic of setting up the E-Mail server. These details probably won't matter much at all, but they are being provided in case they are helpful.)

A physical machine ran a virtual machine. (See: making a virtual machine.) Main firewall services were in fact provided by that virtual machine. This virtual machine was created using some older guides (including the older “general guide” that had been at the tutorial on making a virtual machine.)

The physical machine really had just two jobs: running virtual machines, and redirecting traffic to the main firewall. This E-Mail server was set up on a second virtual machine. Creating that was done using a newer, more specific walkthrough which is at: making a virtual machine.)

Machine prepared

The main things to note about the E-Mail server is that it was sufficiently prepared: the operating system was installed, some basic configuration (to harden the system) were performed, networking was operational (as proven by the ability to remotely access the system), and remote access was set up. The automatic addressing (DHCP/IPv4) server and name resolution (DNS) servers were configured with details about this server. (Since this was a virtual machine being added to an existing network, all of these details were pretty well covered by the specific walkthrough section of the tutorial on making a virtual machine.) In addition to these features, which should be considered some of the basic necessities, some additional configuration has been applied, such as running a file integrity checker.

The recommended E-Mail program

When you are running commands on the command line, the recommended program to be running is quite often: the mailwrapper command.

Commands end up running the mailwrapper program. The mailwrapper program looks at its /etc/mailer.conf configuration file and then figures out what other program to really be running. The reason to use mailwrapper is basically to effectively enable compatability with quite a bit of older code which might rely on the specific exectable names that were used by the program called “sendmail”. There is too much pre-existing code, including code made by third parties (other than just the distributors of operating systems), that supporting this limited code seemed more sensible than trying to coordinate a widespread effort to update all of the code which assumes that “sendmail” is being used.

Now, the next question ends up being: what programs should be referenced inside mailwrapper's /etc/mailer.conf file (so that mailwrapper ends up using those programs)? There are some various opinions on the answer to that question.

Reviewing some potential resources

I really didn't find much of anything on the OpenBSD site, other than the manual pages for certain commands. OpenBSD 5.3 upgrade guide mentioned OpenSMTPD, and the team said, “we encourage you to look at” (The OpenBSD manual page for smtpd) “if you are using” ... “any other mail transport agent.” A reference was also made to OpenBSD manual page for smtpd.conf file.

The OpenBSD FAQ did not seem to refer to this software.

I decided to hold off on checking for other sites posting guides, to try to get some of the most official information first.

The OpenSMTP site's “manual” page referred to multiple topics, including OpenSMTPD.org's manual page for the newaliases, OpenSMTPD.org's manual page for a .forward file, OpenSMTPD.org's manual page for an aliases file, which might all be discussed by forwarding E-Mail and there is also a manual page referenced for makemap, which may be discussed by the section on Sendmail virtuser

Those may be interesting topics related to handling mail and getting the mail delivered where desired, but they are probably best viewed as separate topics from getting the main SMTP server operational. A reason to think of those as separate tasks is because those tasks might work identically whether using OpenSMTPD or SendMail. So, for now, let's focus on the OpenSMTPD portions, and then look at additional mail handling options later.

This left me with references to three manual pages to check out early on:

[#cmlosmtp]:

Some information on Calomel.org shows some people finding that Calomel.org has provided problematic information, especially for the OpenSMTPD guide at that site.)

Know that the examples provided from this resource were initially meant for OpenSMTPD version 5.3.

Stopping sendmail

The OpenBSD manual page for the smtpd command (“DESCRIPTION”) section recommends stopping sendmail program. (This is recommended before any discussion of updating mailwrapper's configuration. This probably should be done before modifying the mailwrapper configuration.) (The OpenSMTPD.org's manual page for the smtpd command (“DESCRIPTION”) section does not provide this same recommendation. However, this is probably a good idea for any system that is actively running a mail server. OpenBSD happens to run the sendmail program my default.)

Note that this does start to cause downtime for mail services.

e.g., with modern versions of OpenBSD:

sudo /etc/rc.d/sendmail stop

Also, the OpenBSD manual page for the smtpd command (“DESCRIPTION”) section provides the instruction to “Disable the sendmail clientmqueue entry in” the crontab. (Once again, the OpenSMTPD.org's manual page for the smtpd command (“DESCRIPTION”) section does not provide this same recommendation.) This instruction is actually provided after the instructions for modifying the mailwrapper configuration, but there seems to be no reason to do things in that order (of handling sendmail, then handling something else, and then handling sendmail again).

commentary about removing the sm-msp-queue crontab entry

sudo crontab -l -u root
echo ${VISUAL}
cpytobak /var/cron/tabs/root
sudo crontab -e -u root

Find the lines that say:

# sendmail clientmqueue runner
*/30 * * * * /usr/sbin/sendmail -L sm-msp-queue -Ac -q

On an 80-column screen, part of the command line (e.g. the “ -q”) may typically extend past the right border of the screen. That's fine.

Comment out that last line by prepending a comment (“#”) character.

# sendmail clientmqueue runner
#*/30 * * * * /usr/sbin/sendmail -L sm-msp-queue -Ac -q
Modifying the mailwrapper configuration

OpenSMTPD.org's manual page for the smtpd command (“DESCRIPTION”) section (similar to OpenBSD manual page for the smtpd command (“DESCRIPTION”) section) states, “If you are running a BSD Operating System, you should use and modify” the mailwrapper program's “settings by editing /etc/mailer.conf:”

cpytobak /etc/mailer.conf
echo ${VISUAL}
sudo ${VISUAL} /etc/mailer.conf

After applying the changes made to the web page, the file looked something like this:

#sendmail /usr/libexec/sendmail/sendmail
#send-mail /usr/libexec/sendmail/sendmail
#mailq /usr/libexec/sendmail/sendmail
#makemap /usr/libexec/sendmail/makemap
#newaliases /usr/libexec/sendmail/sendmail
sendmail /usr/sbin/smtpctl
send-mail /usr/sbin/smtpctl
mailq /usr/sbin/smtpctl
makemap /usr/libexec/smtpd/makemap
newaliases /usr/libexec/smtpd/makemap
hoststat /usr/libexec/sendmail/sendmail
purgestat /usr/libexec/sendmail/sendmail
Skipping some steps

OpenSMTPD.org's manual page for the smtpd command (“DESCRIPTION”) section (similar to OpenBSD manual page for the smtpd command (“DESCRIPTION” section)) states to run the newaliases command. (Furthermore, from the example prompt, this apparently should be done as root).

sudo newaliases

This isn't particularly harmful, but OpenSMTPD.org's manual page for the newaliases command (“DESCRIPTION” section) states that the program is primarily provided for compatability with the program called “sendmail”, but the “preferred way of rebuilding the database is with” the makemap program. That is shown later; for now we skip the example command of running newaliases.

The OpenBSD team is fairly prominent, since this is the team behind the OpenSMTPD software. In the OpenBSD manual page for the smtpd command (“DESCRIPTION”) section (though not in OpenSMTPD.org's manual page for the smtpd command (“DESCRIPTION”) section), there are some directions to make OpenBSD not start sendmail, and instead to start OpenSMTPD, each time the system reboots. For now, we're going to delay making that sort of change.

Performing additional configuration
References

OpenSMTPD.org's manual page for the /etc/mail/smtpd.conf configuration file, OpenBSD manual page for smtpd.conf file.

Changes

(Note: based on Calomel.org's guide to OpenSMTPD, it seems that there were some configuration file syntax changes which were effective by OpenSMTPD 5.3's release, and that older syntax was used by “opensmtpd 201303011853 or earlier”. According to the examples on that site, maps were referenced differently, and the hostname option was a separate configuration line, rather than being part of the listen line. However, before simply accepting all of the details provided by that guide, be aware of concerns about the Calomel.org site and specifically the OpenSMTPD guide on that site.

OpenBSD Journal entry on updated syntax

cpytobak /etc/mail/smtpd.conf
echo include \"/etc/mail/smtpd.conf.local\" | sudo -n tee -a /etc/mail/smtpd.conf
[ -f /etc/mail/stmpd.conf.local ] && cpytobak /etc/mail/smtpd.conf.local
Specifying which network interfaces to listen on

In the main configuration file, comment out the line that says to listen on the loopback interface. So,

echo ${VISUAL}
sudo ${VISUAL} /etc/mail/smtpd.conf

In this file:

listen on lo0

... needs to become ...

#listen on lo0

Otherwise, if another configuration line (even in another file) tries to listen on all interfaces, /var/log/maillog will have output like:

Mmm  D hh:mm:ss hostname smtpd[PID]: fatal: smtpd: bind: Address already in use

and the result is that the software will have entirely stopped.

echo ${VISUAL}
sudo ${VISUAL} /etc/mail/smtpd.conf.local

By following the above examples, there are minimal changes made to the initial files. This means that if the changes get lost due to some accident when upgrading or re-installing the operating system, the amount of effort required to fix the problem will hopefully be minimal. If the OpenBSD team treats the /etc/mail/smtpd.conf.local file (which they use as an example filename on the OpenBSD manual page for smtpd.conf file) similar to how the OpenBSD team has treated the /etc/rc.local and /etc/rc.conf.local files, which seems likely, then the people who release the installation and upgrading software will probably not be overwriting the /etc/mail/smtpd.conf.local file by default.

(The following example/information may show commands meant to be run from the command line. If there are no additional customizations that are desired to be entered via a text editor, then feel free to exit the text editor. Even leaving a zero byte file might help to prevent an error about a file not being found?)

At this point, further customizations may be made. For example, to listen on more than just the loopback interface, run the following command.

(At this time, it seems questional whether to use “listen on all”, as specified by the example/comment in the default /etc/mail/smtpd.conf file, or “listen on any”, which might be a newly required way to phrase this, as mentioned by Upgrade guide for OpenBSD 5.3 Upgrade Guide: section on smtpd.conf syntax change.

echo listen on all | sudo -n tee -a /etc/mail/smtpd.conf.local

Perhaps see also: Calomel.org page on OpenSMTPD

Identifying available usernames

This may have the same two-part process as sendmail, which is:

  • Make sure the MSA/MTA can accept E-Mails for a particular domain
  • Support individual users/addresses on the domain(s) that are supported

Until completion of the first task just mentioned, the second task is not likely to be working well.

Accepting E-Mails for desired domain(s)
Understanding default actions

In the default /etc/mail/smtpd.conf file, there may be a line saying:

accept for local alias <aliases> deliver to mbox

The “accept” command has an implied “from local” unless otherwise specified. So, this command only accepts E-Mail that both comes from local and is also for local users.

Accepting outside mail for local users

To add a rule that accepts E-Mail from any machine in the world, and will forward on the E-Mail if the destination is an address in the domain that the E-Mail server is a part of, perform a couple of things:

Preventing some errors

First, edit the main /etc/smtpd.conf file.

echo ${VISUAL}
sudo ${VISUAL} /etc/smtpd.conf

Then, comment out the lines that have some other mail handling rules:

accept for local alias <aliases> deliver to mbox
accept for any relay

... needs a comment (“#”) character prepended at the start of the lines, to become:

#accept for local alias <aliases> deliver to mbox
accept for any relay

The reason for commenting out the first line, which allows E-Mail for local users but only when the E-Mail is from local users, is to avoid an error that occurs if that line remains and the new configuration line (shown in the upcoming directions) is added, then the main program will log an error message and then exit. The sub-components will also log some warnings and then exit. If this happens, then:

/var/log/maillogsmtpd.conf file will say:

sudo cat /var/log/maillog

will show the error message, which may look something like:

fatal: smtpd: bind: Can't assign requested address

(The error message almost sounds like an issue with reserving the TCP port on a specific IP address. However, the cause is actually related to the mail-handling rules.)

The reason for commenting out the “accept for any relay” line is that, if the other line is commented out, then local E-Mail will simply be relayed to the mail server that handles these E-Mail addresses. A single E-Mail message will heavily pollute the log files, but eventually the status of the E-Mail will be logged as “stat=Loop detected”.

Adding support for listening from all users:
echo accept from any for local alias \<aliases\> deliver to mbox | sudo -n tee -a /etc/mail/smtpd.conf.local
echo accept from any for local deliver to mbox | sudo -n tee -a /etc/mail/smtpd.conf.local

The way that smtpd will figure out the domain of the E-Mail server is documented by OpenBSD's manual page for the smtpd.conf file: section called “DEFAULT SERVER NAME”. (This section seems to not exist in the OpenSMTPD.org's manual page for the smtpd.conf file. Perhaps that is just because OpenSMTPD.org's manual page seems to be based off of OpenBSD 5.2 at the time of this writing, and the cited OpenBSD manual page is from OpenBSD 5.3 at the time of this writing. The OpenBSD 5.2 version of the manual page did not have that section either.)

If the /etc/mailname file does not exist (which is a file that, by default, does not exist), then the system uses the name from the gethostname/getaddrinfo code. That code will look inside the /etc/myname file, and can be seen by running the hostname command.

Accepting E-Mails from the world, for local users

First, follow the just-provided previous instructions about preventing errors.

Make sure that the /etc/mail/smtpd.conf file has the following line. (This line might commonly not exist, by default, so this may need to be added.) Run this from the command line:

echo include \"/etc/mail/smtpd.conf.local\" | sudo -n tee -a /etc/mail/smtpd.conf
cat /etc/mail/smtpd.conf

This should cuase the last line of the file to say:

include "/etc/mail/smtpd.conf.local"

(This is not trying to say that the include line absolutely must be at the end of the file. Simply, that is what will likely happen when using “ tee -a ” as shown in the example.)

Then:

echo ${VISUAL}
sudo ${VISUAL} /etc/mail/smtpd.conf.local

(The file might not pre-exist, and so might not be blank.) Add the following lines. (If the file does pre-exist, perhaps before any other mail rules, if any other mail rules exist yet).

echo accept from any for local alias \<aliases\> deliver to mbox | sudo -n tee -a /etc/mail/smtpd.conf.local
echo accept from any for local deliver to mbox | sudo -n tee -a /etc/mail/smtpd.conf.local
echo accept from any for domain \"\*.example.com\" alias \<aliases\> deliver to mbox | sudo -n tee -a /etc/mail/smtpd.conf.local
echo accept from any for domain \"\*.example.com\" alias \<aliases\> deliver to mbox | sudo -n tee -a /etc/mail/smtpd.conf.local
Accepting more E-Mail for more domains

If there are additional desired domains, add support for them. e.g.:

echo accept from any for domain \"example.com\" alias \<aliases\> deliver to mbox | sudo -n tee -a /etc/mail/smtpd.conf.local
echo accept from any for domain \"example.com\" deliver to mbox | sudo -n tee -a /etc/mail/smtpd.conf.local
echo accept from any for domain \"\*.example.com\" alias \<aliases\> deliver to mbox | sudo -n tee -a /etc/mail/smtpd.conf.local
echo accept from any for domain \"\*.example.com\" alias \<aliases\> deliver to mbox | sudo -n tee -a /etc/mail/smtpd.conf.local

It seems that SMTP servers usually do not seem to accept E-Mails that specify the destination as an IP address instead of a DNS name. If you would like to be more accepting than this common practice, then find the IP addresses that are used (see find the addresses that are used), and then add support for any desired IP address. Run a command such as the following, customizing the IP addresses as appropriate, and run a command such as:

echo accept from any for domain \"192.51.100.75\" alias \<aliases\> deliver to mbox | sudo -n tee -a /etc/mail/smtpd.conf.local

After adding support for incoming E-Mails on other domains,

Handling E-Mails for a specific user

First of all, the E-Mail server needs to accept E-Mail for the domain. (With SendMail, that's basically a separate configuration file. With OpenSMTPD, this is basically covered by the same configuration rules as the rules that specify how the users are being handled.)

The user needs to either be a local user on the system (if local users are actively being checked), or to have an entry in a supported database.

(This is probably rather similar to similarities to using SendMail as an MDA, except that supporting virtual users ends up being less work. That is simply because virtual users are rather supported by default in OpenSMTPD, but are rather unsupported by default with SendMail, so SendMail requires more work for configuration.)

Overview of options/approaches: Understanding the smtpd.conf configuration

(At the time of this writing, this section may be based on some speculation after a brief reading of documentation.)

Basically, the two options are:

  • Have a rule that does accept E-Mail and which does not use a table at all. Instead, that rule will rely on the computer's list of local users. If a rule accepts E-Mail and relies upon the computer's list of local users, then simply add a user to the computer system. The key to using the computer's local list/database of local users is to have a rule that accepts E-Mail but does not make any references, at all, to any type of table. (Neither an “alias” table, nor a “vmap” table that is a table storing information about “virtual” users/“E-Mail addresses”.)
  • Adjust the configuration files that are used to make a supported database file. Then adjust the smtpd.conf to make a table that references the supported database file. Then create an “E-Mail”-handling rule that references the table.

The supported database files are created by using a configuration file, such as the /etc/aliases file, and using a command such as makemap. Another program that creates these database files is the newaliases command. With SendMail's version of the newaliases command, the only thing the newaliases command does might be to simply run “sendmail -bi” (which means that running “sendmail -bi” performs the same task as the newaliases command.

There are a few different types of tables that can be referenced:

aliases

There is an “aliases” database. This database is made using the /etc/aliases file. An example line of this text file may say:

postmaster: root

Those are E-Mail accounts, even though there is no @ or computer/system name being mentioned. In that simple example, if an E-Mail was sent to postmaster@example.org, then the E-Mail may end up getting sent to root@example.org E-Mail box. The database does not need to, and might not even be allowed to, specify an @ or the name of a computer/system name. Instead, the E-Mail program figures out the name of a computer/system based on what is specified by the destination E-Mail address.

vmap/“virtual users”

Note: Some of this section may be based on comments in an example file that was probably meant for SendMail. Do not expect that all of the examples in this section have been fully tested and successfully implemented with OpenSMTPD.

A “virtual E-Mail address” that specifies an E-Mail domain (that is, a computer/system name), and specifies some portion of an E-Mail address. For examples:

info@sample.example.com user
@demo.example.net user@example.org
@demo.example.com %1@example.org

E-Mail sent to info@sample.example.com will get delivered to user@sample.example.com. This rule does not apply to info@sample.example.prg, so this rule is rather specific on which domain it applies to.

An E-Mail sent to root@demo.example.net will end up being sent to the user@example.org E-Mail address because of what the second rule specifies.

An E-Mail sent to root@demo.example.com will end up being sent to the root@example.org E-Mail address, because of what the third rule states. (The username @example.org will be unchanged from, and so will match, the username @demo.example.com E-Mail address.) (This is documented in the example virtusertable file... The %1 does not seem to be mentioned by OpenSMTPD.org's manual page for the makemap command, so be sure to test that functionality before relying too much on it...

OpenBSD's sample /etc/mail/virtusertable file states, “See the "virtusertable" section of /usr/share/sendmail/README for” “more information.” (The README file may be found online from OpenBSD source code: CVSWeb of SendMail's README file.)

userbase
This may be yet another way to reference a table.

Here is an example to take all E-Mail sent to someuser@example.org and send a copy of the E-Mail to partner@example.org

(Neither the /etc/mail/myvrtusr nor the /etc/mail/virtusertable files need to pre-exist. The default /etc/mail/virtusertable is simply a bunch of comments. If the files don't exist, the first commands may simply generate some harmless error messages.)

cpytobak /etc/mail/myvrtusr
sudo cp -i /etc/mail/virtusertable /etc/mail/myvrtusr
echo someuser@example.org partner | sudo -n tee -a /etc/mail/myvrtusr
Notes about configuration file possibilities

Note: There may be some more flexibility than just what this example shows: OpenSMTPD.org's manual page for the makemap command: “Virtual Domains” section notes some different possibilities. It notes:

Virtual domains expect a mapping of virtual users to real users in order to determine if a recipient is accepted or not. The mapping format is an extension to aliases(5), which allows the use of “user@domain.tld” to accept user only on the specified domain, “user” to accept the user for any of the virtual domains, “@domain.tld” to provide a catch-all for the specified domain and “@” to provide a global catch-all for all domains. smtpd(8) will perform the lookups in that specific order.

(Hypertext markup was added to the quoted text.)

However, trying to use:

someuser@example.net someuser@example.org

did not seem to work as expected. Instead, the recipient was not accepting E-Mail. In fact, even a simpler:

someuser@example.org someuser@example.org

(where every E-Mail address is on the same domain) did not seem to work as expected. OpenSMTPD.org's manual page for the makemap command: “Virtual Domains” section went on to say:

To create single virtual address, add “user@example.com user” to the users map. To handle all mail destined to any user at example.com, add “@example.com user” to the virtual map.

Using the simpler syntax mentioned by that paragraph did seem to work as expected.

OpenBSD Journal @ Undeadly.org write-up on some OpenSMTPD updates: section titled “REALLY VIRTUAL users” suggests some changes there were made fairly recently (as of January 2013). The document shows references a syntax like: “accept for domain domainName users <tableName>...” That syntax does not seem to be documented, so perhaps changes are being made to the code behind this type of functionality. (Therefore, extensive further testing is not being performed at this time.)

Optional step: Converting source configuration file to a supported database file

The following uses SendMail's makemap since that is what is packaged with OpenBSD (at the time of this writing). There don't seem to be any entirely mutually compatible, useful variations that also work with OpenSMTPD.org's manual page for the makemap command. Instead, this example is based on information from OpenBSD's manual page for the makemap command (e.g. OpenBSD 5.3's manual page for the makemap command). Which variation should be used depends on whether /etc/mailer.conf maps makemap to the /usr/libexec/sendmail/makemap file or the /usr/libexec/smtpd/makemap file.

Example using SendMail's:

sudo makemap -v hash /etc/mail/myvrtusr

Example using OpenSMTPD's:

sudo makemap -o /etc/mail/myvrtusr.db /etc/mail/myvrtusr

Now, modify the configuration file to start using that file that was just made. (If using databases, the configuration file needs to use the database file that was just made. If not using databases, use the ASCII text file.)

The OpenSMTPD.org's manual page for the makemap command: “Virtual Domains” section may help with an example.

echo table "vusrstbl" db:/etc/mail/myvrtusr.db | sudo -n tee -a /etc/mail/smtpd.conf.local

Note: If the configuration file is not a database file, and instead is the ASCII text source configuration file, then do not specify “db:”. (Instead, the default will be “file:”.)

echo accept from any for domain example.org virtual \<vusrstbl\> deliver to mbox | sudo -n tee -a /etc/mail/smtpd.conf.local
smtpd -dn
sudo /etc/rc.d/smtpd restart

The only other important note to make is that the aliases that should redirect to root@ seem to actually redirect to the owner of the smtpd process. The owner of the smtpd likely is root when the server is started automatically during system startup, but starting the server manually (or restarting it) using sudo may lead to some unexpected E-Mail routing. Fortunately, the logs do properly indicate exactly what actually happened with the E-Mails.

From reading OpenSMTPD.org's manual page for the smtpd.conf file, it appears that the main mail delivery rules follow this pattern:

  • starts with either accept or reject
  • Applies filter rules, such as rules containing the word “from”. If this is left off, then “from local” is the implied default. So, all rules do go through this filtering.
  • applies a “selection” process by considering who the E-Mail is to, and uses a rule portion that involves the word “for
  • Might specify an alternate database, by using the “userbase” keyword (followed by a table name)
  • (Presumably only if the E-Mail was accepted): Specifies a delivery method. Outgoing E-Mails use a delivery method involving the word relay. Incoming E-Mails specify a delivery method involving the phrase “deliver to”.
  • There may be additional configuration: there is an optional “expire” “per-rule adjustment”.

At least for incoming E-Mails, E-Mails are handled by either using a “table” or by looking up users from a user database. One method, which may be the easiest to work with, is to have the system use the “getpwname” function to locate users from the “system database”. (Quotes are coming from OpenSMTPD.org's manual page for the smtpd.conf file.) Using the “getpwname” function with the “system database” basically means checking whether a user exists in the /etc/passwd file.

The way to specify using this “system database” is simply to not specify any other method of looking up users. So, here is an overview on the various ways to specify alternate methods of looking up users. If none of these are done, then the “system database” is used.

The way to reference a table is to do one of the following items:

  • On one of the “for” select rules, specify “alias” and then a table that is based on an “aliases” database file
  • On one of the “for” select rules, specify “virtual” and then a “vmap” table that is based on an “virtual users” database file
  • After the selection process, use the userbase rule.

If a “table” is used, then there needs to be another line in the configuration file that describes the “table”. In at least some cases, these tables may refer to a database file that is supported by this mail routing functionality.

The origin of the supported database files

These database files, which are supported by this mail routing functionality, are created using the makemap command or, possibly, the similar newaliases command. (Or, if using SendMail, the “ sendmail -bi ” which has the same effect as the newaliases command. In fact, the SendMail version of the newaliases command might simply run “ sendmail -bi ”.)

The main difference between newaliases and makemap appears to be that newaliases inserts some extra “tokens” designed to help the sendmail program deal with the “aliases” database. (This information comes from OpenBSD 5.3's manual page for newaliases; presumably in a future version that manual page might change to be more like OpenSMTPD.org's manual page for the newaliases command.)

Both the makemap and the newaliases commands create the database by reviewing information found in a text file. The SendMail version of the newaliases command (as documented by OpenBSD 5.3's manual page for newaliases: “Files” section) uses an /etc/mail/aliases file. OpenSMTPD.org's manual page for the newaliases command also mentinos that same configuration file for a “List of local user mail aliases”, and also mentions /etc/mail/virtual for a “List of virtual host aliases.”

(OpenSMTPD.org's manual page for the makemap command mentions /etc/mail/aliases as well as a /etc/mail/secrets file, while OpenBSD's manual page for the makemap command does not have a “FILES” section, and does not list any files at the time of this writing, when OpenBSD's manual page is documenting the SendMail version of the command.)

The other piece related to mail routing is that OpenSMTPD's manual page for the .forward files states, “Users may put a .forward file in their home directory.” There are some requirements for permissions which may be relevant. (See that manual page for the details.) More details about forwarding may be found at: Forwarding/Relaying E-Mail.)

Testing configuration
sudo smtpd -nv
Starting

The OpenBSD manual page for the smtpd command (“DESCRIPTION”) section (though not in OpenSMTPD.org's manual page for the smtpd command (“DESCRIPTION”) section) provides some directions on how to make OpenBSD not start sendmail on every reboot, and instead to start OpenSMPTd. The way to do that will vary between different operating systems: automatically started files provides details. The following lines effectively accomplish what is shown by OpenBSD's example (and also backs up the file before making a change).

cpytobak /etc/rc.conf.local
echo "sendmail_flags=NO" | sudo -n tee -a /etc/rc.conf.local
echo smtpd_flags=\"\" | sudo -n tee -a /etc/rc.conf.local

(Note: In OpenBSD's manual page, the quotation marks are unescaped and they surround the text. If using a shell other than /bin/ksh, perhaps just leave off the “\"\"” portion of the command line. If the previous example was already run, the safest thing to do may be to check on the file. The best way to handle this might be to edit the text file by using a text editor.)

Adjusting the system startup scripts may actually impact how well the software works on this boot. Trying to start the program may result in the following output:

/etc/rc.d/smtpd: no start without -f, smtpd_flags=NO

(If adjusting the startup process seems unpleasant, then it appears the alternative is to use: “ smtpd -f /etc/mail/smtpd.conf ”)

If the system startup process has been configured as expected, then OpenSMTPD.org's manual page for the smtpd command and The manual page for smtpd document a command line such as the following. (Therefore, using the /etc/rc.d/ script is the generally recommended documented way to start OpenSMTPD).

sudo /etc/rc.d/smtpd start

The software should provide the following as output:

smtpd(ok)

Note that there are some things worth doing before testing connections: increase logging, and before trying any connections from a remote system, make sure that any required firewall adjustments have been performed.

Adjusting configuration
Increase logging
sudo smtpctl log verbose

(Perhaps that command should go into a startup file? Or is the setting somehow saved/maintained?)

sudo less /var/log/maillog
Restarting (to reload configuration file)

If there is any need to do that, try running:

smtpd -nv
sudo smtpctl stop
echo That is the same effect as: sudo /etc/rc.d/smtpd stop
sudo /etc/rc.d/smtpd start

Or:

smtpd -nv
sudo /etc/rc.d/smtpd restart

The /etc/rc.d/smtpd command specifies “rc_reload=NO”. So, presumably the software won't respond to a HUP signal.

Testing

Testing is probably something best to do after adjusting the configuration so that logging is increased.

Testing by using telnet

From the machine, use:

telnet localhost 25

Once the telnet command establishes the TCP connection, it is up to the client to start communicating using SMTP. So, do not expect to see a banner until after typing a line of text. Create an E-Mail message using SMTP. (See: SMTP sample.)

Using other programs to test

Note that using programs may require some adjustment to the configuration file so that they stop using SendMail. e.g.: Alpine MTA configuration adjustment.)

The /etc/maillog file will contain log entries. They may start with something like:

MON  D hh:mm:ss srvrname smtpd[#####]:

The numbers between the square brackets represent a PID.

Upon a successful delivery, text like the following may show up (after the standard start of a line in this log).

smtp-in: New session 0000000fdb975321 from host nameOrIP [192.51.100.222]
smtp-in: Accepted message eca86420 on session 0000000fdb975321: from=<author@servername.serverdomain>, size=149, nrcpts=1, proto=SMTP
delivery: Ok for eca86420369cfda7: from=<author@servername.serverdomain>, to=reader@example.org>, user=reader, method=mbox, delay=14s, stat=Delivered
smtp-in: Closing session 0000000fdb975321

The PID of the line that says delivery will be different than the PID from the other lines that say smtp-in.

The first random number of note is the session id; it also shows up in the second and fourth lines of this example.

The next random-looking number is the message ID, after the words Accepted message. This message ID shows up in the first half of a later random-looking number, after the words “Ok for ”.

In this case, the third line lets us know that the message has a status of Delivered. The user who will be receiving the message is shown in the user= field. (In cases of a mail alias, the username here may be different than the username specified by the E-Mail. This specifies the actual user name that received the E-Mail.) The method of mbox tells us to check out a file in /var/mail/ and named after the user (e.g. /var/mail/receiver).

If the contents of the mail are successfully in that file, then it would appear that the SMTP server's MDA role, and the SMTP server's MSA/MTA role, have done their job. Remaining issues are likely on the client's end (e.g. an issue within the MUA software), or an issue with the client's ability to check the mail (an issue with the role of the MRA being successful). In many/most/perhaps-all cases, those roles are different software than the SMTP server. (This is not to say that the issue is not with the computer running on the server hardware. A possibility, for instance, is that the computer which is the E-Mail server might be failing to run the protocol that the MRA is expecting. However, checking the MUA settings, including DNS functionality to successfully look up a valid and contactable IP address, may be more likely to locate an actual problem.

Want to learn more about this software's recent developments? Check out poolp.org and, in the upper corners, look for black circles with inequality signs (starting with a greater-than sign in the upper-right corner of the first page).

LDAP support: post (especially/particularly 24 Jul 2012 09:43 reply indicates that support has been started, but may not have been commited. Although, the post did say “I think it will be committed sometime this summer.” That was over a year ago, so maybe these observations are outdated...)