Chapter 32. Electronic Mail | FreeBSD Documentation Portal
Description: This chapter provides a basic introduction to running a mail server on FreeBSD, as well as an introduction to sending and receiving email using FreeBSD
Keywords: mail,sendmail,dma,MTA,SMTP,mail user agents,fetchmail,procmail,alpine,mutt,postfix

# Chapter 32. Electronic Mail

## 32.1. Synopsis

"Electronic Mail", better known as email, is one of the most widely used forms of communication today. This chapter provides a basic introduction to running a mail server on FreeBSD, as well as an introduction to sending and receiving email using FreeBSD. For a complete coverage of this subject, refer to the books listed in Bibliography.

This chapter covers:

- Which software components are involved in sending and receiving electronic mail.

- How to configure DragonFly Mail Agent.

- Where basic Sendmail configuration files are located in FreeBSD.

- The difference between remote and local mailboxes.

- How to install and configure an alternate Mail Transfer Agent, replacing DragonFly Mail Agent or Sendmail.

- How to troubleshoot common mail server problems.

- How to configure Sendmail to only send mail.

- How to configure SMTP authentication for added security in Sendmail.

- How to install and use a Mail User Agent, such as mutt, to send and receive email.

- How to download mail from a remote POP or IMAP server.

- How to automatically apply filters and rules to incoming email.

## 32.2. Mail Components

There are five major parts involved in an email exchange: the Mail User Agent (MUA), the Mail Transfer Agent (MTA), a mail host, a remote or local mailbox, and DNS. This section provides an overview of these components.

Mail User Agent (MUA)

  The Mail User Agent (MUA) is an application which is used to compose, send, and receive emails. This application can be a command line program, such as the built-in `mail` utility or a third-party application from the Ports Collection, such as alpine, elm, or mutt. Dozens of graphical programs are also available in the Ports Collection, including Claws Mail, Evolution, and Thunderbird. Some organizations provide a web mail program which can be accessed through a web browser. More information about installing and using a MUA on FreeBSD can be found in Mail User Agents.

Mail Transfer Agent (MTA)

  The Mail Transfer Agent (MTA) is responsible for receiving incoming mail and delivering outgoing mail. Starting with FreeBSD version 14.0, the default MTA is DragonFly Mail Agent (dma(8)); in earlier versions, it is sendmail(8). Other MTAs, including Exim, Postfix, and qmail, may be installed to replace the default MTA.

Mail Host and Mailboxes

  The mail host is a server that is responsible for delivering and receiving mail for a host or a network. The mail host collects all mail sent to the domain and stores it either in the default `mbox` or the alternative Maildir format, depending on the configuration. Once mail has been stored, it may either be read locally using a MUA or remotely accessed and collected using protocols such as POP or IMAP. If mail is read locally, a POP or IMAP server does not need to be installed.

Domain Name System (DNS)

  The Domain Name System (DNS) and its daemon named(8) play a large role in the delivery of mail. In order to deliver mail from one site to another, the MTA will look up the remote site in DNS to determine which host will receive mail for the destination. This process also occurs when mail is sent from a remote host to the MTA.

## 32.3. DragonFly Mail Agent (DMA)

DragonFly Mail Agent (DMA) is the default MTA in FreeBSD starting with version 14.0. dma(8) is a small Mail Transport Agent (MTA), designed for home and office use. It accepts mails from locally installed Mail User Agents (MUA) and delivers the mails either locally or to a remote destination. Remote delivery includes several features like TLS/SSL support and SMTP authentication.

dma(8) is not intended as a replacement for real, big MTAs like sendmail(8) or postfix(1). Consequently, dma(8) does not listen on port 25 for incoming connections.

### 32.3.1. Configuring DragonFly Mail Agent (DMA)

DMA comes with a default configuration that will be suitable for many deployments. Custom settings are defined in /etc/dma/dma.conf, and SMTP authentication is configured in /etc/dma/auth.conf.

#### 32.3.1.1. Using DMA to Route Outgoing Mail through Gmail (STARTTLS:SMTP example)

This example /etc/dma/dma.conf can be used to send mail using Google’s SMTP servers.

    SMARTHOST smtp.gmail.com
    PORT 587
    AUTHPATH /etc/dma/auth.conf
    SECURETRANSFER
    STARTTLS
    MASQUERADE username@gmail.com

Authentication can be set with one line in /etc/dma/auth.conf:

    username@gmail.com|smtp.gmail.com:password

| With enabled 2-factor authentication a generated application-specific password as the normal login password will be rejected. See Google documentation for more information on app-specific passwords.

Execute the following command to test the configuration:

    % echo this is a test | mail -v -s testing-email username@gmail.com

#### 32.3.1.2. Using DMA to Route Outgoing Mail through Fastmail (SSL/TLS example)

This example /etc/dma/dma.conf can be used to send mail using Fastmail’s SMTP servers.

    SMARTHOST smtp.fastmail.com
    PORT 465
    AUTHPATH /etc/dma/auth.conf
    SECURETRANSFER
    MAILNAME example.server.com

Authentication can be set with one line in /etc/dma/auth.conf:

    username@fastmail.com|smtp.fastmail.com:password

Execute the following command to test the configuration:

    % echo this is a test | mail -v -s testing-email username@fastmail.com

#### 32.3.1.3. Using DMA to Route Outgoing Mail through a Custom Mail Host

This example /etc/dma/dma.conf can be used to send mail using a custom mail host.

    SMARTHOST mail.example.org
    PORT 587
    AUTHPATH /etc/dma/auth.conf
    SECURETRANSFER
    STARTTLS

Authentication can be set with one line in /etc/dma/auth.conf:

    username@example.org|mail.example.org:password

Execute the following command to test the configuration:

    % echo this is a test | mail -v -s testing-email username@example.org

## 32.4. Sendmail

Sendmail is a venerable and versatile Mail Transfer Agent (MTA) with a long history in UNIX® and UNIX-like systems. It was a part of the FreeBSD base system until FreeBSD 13, offering robust email transport capabilities, extensive customization options, and support for complex routing and filtering.

### 32.4.1. Configuration Files

The configuration files for Sendmail are located in /etc/mail/.

/etc/mail/access

  This access database file defines which hosts or IP addresses have access to the local mail server and what kind of access they have. Hosts listed as `OK`, which is the default option, are allowed to send mail to this host as long as the mail’s final destination is the local machine. Hosts listed as `REJECT` are rejected for all mail connections. Hosts listed as `RELAY` are allowed to send mail for any destination using this mail server. Hosts listed as `ERROR` will have their mail returned with the specified mail error. If a host is listed as `SKIP`, Sendmail will abort the current search for this entry without accepting or rejecting the mail. Hosts listed as `QUARANTINE` will have their messages held and will receive the specified text as the reason for the hold.

  Examples of using these options for both IPv4 and IPv6 addresses can be found in the FreeBSD sample configuration, /etc/mail/access.sample:

  To configure the access database, use the format shown in the sample to make entries in /etc/mail/access, but do not put a comment symbol (`#`) in front of the entries. Create an entry for each host or network whose access should be configured. Mail senders that match the left side of the table are affected by the action on the right side of the table.

  Whenever this file is updated, update its database and restart Sendmail:

      # makemap hash /etc/mail/access < /etc/mail/access
      # service sendmail restart

/etc/mail/aliases

  This database file contains a list of virtual mailboxes that are expanded to users, files, programs, or other aliases. Here are a few entries to illustrate the file format:

      root: localuser
      ftp-bugs: joe,eric,paul
      bit.bucket:  /dev/null
      procmail: "|/usr/local/bin/procmail"

  The mailbox name on the left side of the colon is expanded to the target(s) on the right. The first entry expands the `root` mailbox to the `localuser` mailbox, which is then looked up in the /etc/mail/aliases database. If no match is found, the message is delivered to `localuser`. The second entry shows a mail list. Mail to `ftp-bugs` is expanded to the three local mailboxes `joe`, `eric`, and `paul`. A remote mailbox could be specified as user@example.com. The third entry shows how to write mail to a file, in this case /dev/null. The last entry demonstrates how to send mail to a program, /usr/local/bin/procmail, through a UNIX® pipe. Refer to aliases(5) for more information about the format of this file.

  Whenever this file is updated, run `newaliases` to update and initialize the aliases database.

/etc/mail/sendmail.cf

  This is the master configuration file for Sendmail. It controls the overall behavior of Sendmail, including everything from rewriting email addresses to printing rejection messages to remote mail servers. Accordingly, this configuration file is quite complex. Fortunately, this file rarely needs to be changed for standard mail servers.

  The master Sendmail configuration file can be built from m4(1) macros that define the features and behavior of Sendmail. Refer to /usr/src/contrib/sendmail/cf/README for some of the details.

  Whenever changes to this file are made, Sendmail needs to be restarted for the changes to take effect.

/etc/mail/virtusertable

  This database file maps mail addresses for virtual domains and users to real mailboxes. These mailboxes can be local, remote, aliases defined in /etc/mail/aliases, or files. This allows multiple virtual domains to be hosted on one machine.

  FreeBSD provides a sample configuration file in /etc/mail/virtusertable.sample to further demonstrate its format. The following example demonstrates how to create custom entries using that format:

      root@example.com                root
      postmaster@example.com          postmaster@noc.example.net
      @example.com                    joe

  This file is processed in a first match order. When an email address matches the address on the left, it is mapped to the local mailbox listed on the right. The format of the first entry in this example maps a specific email address to a local mailbox, whereas the format of the second entry maps a specific email address to a remote mailbox. Finally, any email address from `example.com` which has not matched any of the previous entries will match the last mapping and be sent to the local mailbox `joe`. When creating custom entries, use this format and add them to /etc/mail/virtusertable. Whenever this file is edited, update its database and restart Sendmail:

      # makemap hash /etc/mail/virtusertable < /etc/mail/virtusertable
      # service sendmail restart

/etc/mail/relay-domains

  In a default FreeBSD installation, Sendmail is configured to only send mail from the host it is running on. For example, if a POP server is available, users will be able to check mail from remote locations but they will not be able to send outgoing emails from outside locations. Typically, a few moments after the attempt, an email will be sent from `MAILER-DAEMON` with a `5.7 Relaying Denied` message.

  The most straightforward solution is to add the ISP’s FQDN to /etc/mail/relay-domains. If multiple addresses are needed, add them one per line:

      your.isp.example.com
      other.isp.example.net
      users-isp.example.org
      www.example.org

  After creating or editing this file, restart Sendmail with `service sendmail restart`.

  Now any mail sent through the system by any host in this list, provided the user has an account on the system, will succeed. This allows users to send mail from the system remotely without opening the system up to relaying SPAM from the Internet.

## 32.5. Changing the Mail Transfer Agent

Starting with FreeBSD version 14.0, dma(8) is the default MTA, and before 14.0, the default MTA is sendmail(8). However, the system administrator can change the system’s MTA. A wide choice of alternative MTAs is available from the `mail` category of the FreeBSD Ports Collection.

| If the default’s outgoing mail service is disabled, it is important that it is replaced with an alternative mail delivery system. Otherwise, system functions such as periodic(8) will be unable to deliver their results by email. Many parts of the system expect a functional MTA. If applications continue to use the default binaries to try to send email after they are disabled, mail could go into an inactive queue and never be delivered.

### 32.5.1. Replacing Sendmail with Other MTA

In order to completely disable sendmail(8) execute the following commands:

    # sysrc sendmail_enable="NO"
    # sysrc sendmail_submit_enable="NO"
    # sysrc sendmail_outbound_enable="NO"
    # sysrc sendmail_msp_queue_enable="NO"

To only disable sendmail(8)'s incoming mail service execute the following command:

    # sysrc sendmail_enable="NO"

Then stop the sendmail(8) service:

    # service sendmail onestop

Some extra configuration is needed as sendmail(8) is so ubiquitous that some software assumes it is already installed and configured. Check /etc/periodic.conf and make sure that these values are set to `NO`. If this file does not exist, create it with these entries:

    daily_clean_hoststat_enable="NO"
    daily_status_mail_rejects_enable="NO"
    daily_status_include_submit_mailq="NO"
    daily_submit_queuerun="NO"

The next step is to install another MTA, dma(8) will be used in this example. As pointed above, dma(8) is the default MTA in FreeBSD starting with version 14.0. Therefore, it is only necessary to install it from the ports when using a previous version.

To install it execute the following command:

    # pkg install dma

Perform the configuration as indicated in Configuring DragonFly Mail Agent (DMA).

Then change all the entries in the file /etc/mail/mailer.conf to dma(8):

    # Execute the "real" sendmail program, named /usr/libexec/sendmail/sendmail
    #
    # If dma(8) is installed, an example mailer.conf that uses dma(8) instead can
    # be found in /usr/share/examples/dma
    #
    sendmail        /usr/local/libexec/dma
    mailq           /usr/local/libexec/dma
    newaliases      /usr/local/libexec/dma

| When using the version of dma(8) included in the base system, the paths will change to /usr/libexec/dma.

To ensure that anything in the queue is flushed at boot or before shutdown, execute the following command:

    # sysrc dma_flushq_enable="YES"

Once everything is configured, it is recommended to reboot the system. Rebooting provides the opportunity to ensure that the system is correctly configured to start the new MTA automatically on boot.

### 32.5.2. Replacing DragonFly Mail Agent (DMA) with Other MTA

As noted above, starting with FreeBSD version 14.0, the default MTA is DMA. In this example, mail/postfix will be used as the alternative MTA.

Before installing mail/postfix some extra configuration is needed. Check /etc/periodic.conf and make sure that these values are set to `NO`. If this file does not exist, create it with these entries:

    daily_clean_hoststat_enable="NO"
    daily_status_mail_rejects_enable="NO"
    daily_status_include_submit_mailq="NO"
    daily_submit_queuerun="NO"

Then install mail/postfix:

    # pkg install postfix

To start mail/postfix at system boot execute the following command:

    # sysrc postfix_enable="YES"

| It is good practice to read the installation message after installing an application. Provides useful information about settings, etc.

If postfix is not already activated in /usr/local/etc/mail/mailer.conf execute the following commands:

    mv /usr/local/etc/mail/mailer.conf /usr/local/etc/mail/mailer.conf.old
    install -d /usr/local/etc/mail
    install -m 0644 /usr/local/share/postfix/mailer.conf.postfix /usr/local/etc/mail/mailer.conf

When employing SASL, ensure that postfix has access to read the sasldb file. This is accomplished by adding postfix to group mail and making the /usr/local/etc/sasldb* file(s) readable by group mail (this should be the default for new installs).

Once everything is configured, it is recommended to reboot the system. Rebooting provides the opportunity to ensure that the system is correctly configured to start the new MTA automatically on boot.

## 32.6. Mail User Agents

A MUA is an application that is used to send and receive email. As email "evolves" and becomes more complex, MUAs are becoming increasingly powerful and provide users increased functionality and flexibility. The `mail` category of the FreeBSD Ports Collection contains numerous MUAs. These include graphical email clients such as Evolution or Balsa and console based clients such as mutt or alpine.

### 32.6.1. mail

mail(1) is the default MUA installed with FreeBSD. It is a console based MUA that offers the basic functionality required to send and receive text-based email. It provides limited attachment support and can only access local mailboxes.

Although mail(1) does not natively support interaction with POP or IMAP servers, these mailboxes may be downloaded to a local `mbox` using an application such as fetchmail or getmail.

In order to send and receive email, run mail(1):

    % mail

The contents of the user’s mailbox in /var/mail are automatically read by mail(1). Should the mailbox be empty, the utility exits with a message indicating that no mail could be found. If mail exists, the application interface starts, and a list of messages will be displayed.

Messages are automatically numbered, as can be seen in the following example:

    Mail version 8.1 6/6/93.  Type ? for help.
    "/var/mail/username": 3 messages 3 new
    >N  1 root@localhost        Mon Mar  8 14:05  14/510   "test"
     N  2 root@localhost        Mon Mar  8 14:05  14/509   "user account"
     N  3 root@localhost        Mon Mar  8 14:05  14/509   "sample"

Messages can now be read by typing `t` followed by the message number.

This example reads the first email:

    & t 1
    Message 1:
    From root@localhost  Mon Mar  8 14:05:52 2004
    X-Original-To: username@localhost
    Delivered-To: username@localhost
    To: username@localhost
    Subject: test
    Date: Mon,  8 Mar 2004 14:05:52 +0200 (SAST)
    From: root@localhost (Charlie Root)

    This is a test message, please reply if you receive it.

As seen in this example, the message will be displayed with full headers.

To display the list of messages again, press `h`.

If the email requires a reply, press either `R` or `r` mail(1) keys. `R` instructs mail(1) to reply only to the sender of the email, while `r` replies to all other recipients of the message. These commands can be suffixed with the mail number of the message to reply to. After typing the response, the end of the message should be marked by a single `.` on its own line.

An example can be seen below:

    & R 1
    To: root@localhost
    Subject: Re: test

    Thank you, I did get your email.
    .
    EOT

In order to send a new email, press `m`, followed by the recipient email address. Multiple recipients may be specified by separating each address with the `,` delimiter. The subject of the message may then be entered, followed by the message contents. The end of the message should be specified by putting a single `.` on its own line.

    & mail root@localhost
    Subject: I mastered mail

    Now I can send and receive email using mail ... :)
    .
    EOT

While using mail(1), press `?` to display help at any time. Refer to mail(1) for more help on how to use mail(1).

| mail(1) was not designed to handle attachments and thus deals with them poorly. Newer MUAs handle attachments in a more intelligent way.

### 32.6.2. Mutt

Mutt is a powerful MUA, with many features, including:

- The ability to thread messages.

- PGP support for digital signing and encryption of email.

- MIME support.

- Maildir support.

- Highly customizable.

Refer to http://www.mutt.org for more information on Mutt.

| A Mutt fork called NeoMutt is worth mentioning, which brings added features. See more on the NeoMutt website. If NeoMutt was chosen, replace the following command examples from `mutt` to `neomutt`.

Mutt may be installed using the mail/mutt port. After the port has been installed, Mutt can be started by issuing the following command:

    % mutt

Mutt will automatically read and display the contents of the user mailbox in /var/mail. If no mails are found, Mutt will wait for commands from the user. The example below shows Mutt displaying a list of messages:

To read an email, select it using the cursor keys and press `Enter`. An example of Mutt displaying email can be seen below:

Similar to mail(1), Mutt can be used to reply only to the sender of the message as well as to all recipients. To reply only to the sender of the email, press `r`. To send a group reply to the original sender as well as all the message recipients, press `g`.

| By default, Mutt uses the vi(1) editor for creating and replying to emails. Each user can customize this by creating or editing the .muttrc in their home directory and setting the `editor` variable or by setting the `EDITOR` environment variable. Refer to http://www.mutt.org/ for more information about configuring Mutt.

To compose a new mail message, press `m`. After a valid subject has been given, Mutt will start vi(1) so the email can be written. Once the contents of the email are complete, save and quit from `vi`. Mutt will resume, displaying a summary screen of the mail that is to be delivered. In order to send the mail, press `y`. An example of the summary screen can be seen below:

Mutt contains extensive help which can be accessed from most of the menus by pressing `?`. The top line also displays the keyboard shortcuts where appropriate.

### 32.6.3. alpine

alpine is aimed at a beginner user, but also includes some advanced features.

| alpine has had several remote vulnerabilities discovered in the past, which allowed remote attackers to execute arbitrary code as users on the local system, by the action of sending a specially-prepared email. While known problems have been fixed, alpine code is written in an insecure style and the FreeBSD Security Officer believes there are likely to be other undiscovered vulnerabilities. Users install alpine at their own risk.

The current version of alpine may be installed using the mail/alpine port. Once the port has installed, alpine can be started by issuing the following command:

    % alpine

The first time alpine runs, it displays a greeting page with a brief introduction, as well as a request from the alpine development team to send an anonymous email message allowing them to judge how many users are using their client. To send this anonymous message, press `Enter`. Alternatively, press `E` to exit the greeting without sending an anonymous message. An example of the greeting page is shown below:

The main menu is then presented, which can be navigated using the cursor keys. This main menu provides shortcuts for the composing new mails, browsing mail directories, and administering address book entries. Below the main menu, relevant keyboard shortcuts to perform functions specific to the task at hand are shown.

The default directory opened by alpine is inbox. To view the message index, press `I`, or select the MESSAGE INDEX option shown below:

The message index shows messages in the current directory and can be navigated by using the cursor keys. Highlighted messages can be read by pressing `Enter`.

In the screenshot below, a sample message is displayed by alpine. Contextual keyboard shortcuts are displayed at the bottom of the screen. An example of one of a shortcut is `r`, which tells the MUA to reply to the current message being displayed.

Replying to an email in alpine is done using the pico editor, which is installed by default with alpine. pico makes it easy to navigate the message and is easier for novice users to use than vi(1) or mail(1). Once the reply is complete, the message can be sent by pressing `Ctrl`+`X`. alpine will ask for confirmation before sending the message.

alpine can be customized using the SETUP option from the main menu.

## 32.7. Advanced Topics

This section covers more involved topics such as mail configuration and setting up mail for an entire domain.

### 32.7.1. Basic Configuration

Out of the box, one can send email to external hosts as long as /etc/resolv.conf is configured or the network has access to a configured DNS server. To have email delivered to the MTA on the FreeBSD host, do one of the following:

- Run a DNS server for the domain.

- Get mail delivered directly to the FQDN for the machine.

In order to have mail delivered directly to a host, it must have a permanent static IP address, not a dynamic IP address. If the system is behind a firewall, it must be configured to allow SMTP traffic. To receive mail directly at a host, one of these two must be configured:

- Make sure that the lowest-numbered MX record in DNS points to the host’s static IP address.

- Make sure there is no MX entry in the DNS for the host.

Either of the above will allow mail to be received directly at the host.

Try this:

    # hostname

The output should be similar to the following:

    example.FreeBSD.org

    # host example.FreeBSD.org

The output should be similar to the following:

    example.FreeBSD.org has address 204.216.27.XX

In this example, mail sent directly to yourlogin@example.FreeBSD.org should work without problems, assuming a full-featured MTA is running correctly on `example.FreeBSD.org`. Note that dma(8) does not listen on port 25 for incoming connections and cannot be used in this scenario.

For this example:

    # host example.FreeBSD.org

The output should be similar to the following:

    example.FreeBSD.org has address 204.216.27.XX
    example.FreeBSD.org mail is handled (pri=10) by nevdull.FreeBSD.org

All mail sent to `example.FreeBSD.org` will be collected on `nevdull` under the same username instead of being sent directly to the local host.

The above information is handled by the DNS server. The DNS record that carries mail routing information is the mail exchanger record (MX record). If no MX record exists, mail will be delivered directly to the host by way of its IP address.

The MX entry for `freefall.FreeBSD.org` at one time looked like this:

    freefall		MX	30	mail.crl.net
    freefall		MX	40	agora.rdrop.com
    freefall		MX	10	freefall.FreeBSD.org
    freefall		MX	20	who.cdrom.com

`freefall` had many MX entries. The lowest MX number is the host that receives mail directly, if available. If it is not accessible for some reason, the next lower-numbered host will accept messages temporarily, and pass it along when a lower-numbered host becomes available.

Alternate MX sites should have separate Internet connections in order to be most useful. The ISP can provide this service.

### 32.7.2. Mail for a Domain

When configuring an MTA for a network, any mail sent to hosts in its domain should be diverted to the MTA so that users can receive their mail on the master mail server.

To make life easiest, a user account with the same username should exist on both the MTA and the system with the MUA. Use adduser(8) to create the user accounts.

| In addition to adding local users to the host, there are alternative methods known as virtual users. Programs like Cyrus and Dovecot can be integrated into MTAs to handle users, mail storage, and also provide access via POP3 and IMAP.

The MTA must be the designated mail exchanger for each workstation on the network. This is done in the DNS configuration with an MX record:

    example.FreeBSD.org	A	204.216.27.XX		; Workstation
    			MX	10 nevdull.FreeBSD.org	; Mailhost

This will redirect mail for the workstation to the MTA no matter where the A record points. The mail is sent to the MX host.

This must be configured on a DNS server. If the network does not run its own DNS server, talk to the ISP or DNS provider.

The following is an example of virtual email hosting.

Consider a customer with the domain `customer1.org`, where all the mail for `customer1.org` should be sent to `mail.myhost.com`.

The DNS entry should look like this:

    customer1.org		MX	10	mail.myhost.com

An `A` record is not needed for `customer1.org` in order to only handle email for that domain. However, running `ping` against `customer1.org` will not work unless an `A` record exists for it.

Tell the MTA which domains and/or hostnames it should accept mail for. Either of the following will work for Sendmail:

- Add the hosts to /etc/mail/local-host-names when using the `FEATURE(use_cw_file)`.

- Add a `Cwyour.host.com` line to /etc/sendmail.cf.

### 32.7.3. Setting Up to Send Only

There are many instances where one may only want to send mail through a relay. Some examples are:

- The computer is a desktop machine that needs to use programs such as mail(1), using the ISP’s mail relay.

- The computer is a server that does not handle mail locally, but needs to pass off all mail to a relay for processing.

While any MTA is capable of filling this particular niche, it can be difficult to properly configure a full-featured MTA just to handle offloading mail. Programs such as Sendmail and Postfix are overkill for this use.

Additionally, a typical Internet access service agreement may forbid one from running a "mail server".

The easiest way to fulfill those needs is to use the dma(8) MTA included in the base system. For systems up to 13.2, need be to installed from ports.

In addition to dma(8), third-party software can be used to achieve the same, like mail/ssmtp.

    # cd /usr/ports/mail/ssmtp
    # make install replace clean

Once installed, mail/ssmtp can be configured with /usr/local/etc/ssmtp/ssmtp.conf:

    root=yourrealemail@example.com
    mailhub=mail.example.com
    rewriteDomain=example.com
    hostname=_HOSTNAME_

Use the real email address for `root`. Enter the ISP’s outgoing mail relay in place of `mail.example.com`. Some ISPs call this the "outgoing mail server" or "SMTP server".

Make sure to disable Sendmail, including the outgoing mail service.

mail/ssmtp has some other options available. Refer to the examples in /usr/local/etc/ssmtp or the manual page of ssmtp for more information.

Setting up ssmtp in this manner allows any software on the computer that needs to send mail to function properly, while not violating the ISP’s usage policy or allowing the computer to be hijacked for spamming.

### 32.7.4. SMTP Authentication in Sendmail

Configuring SMTP authentication on the MTA provides a number of benefits. SMTP authentication adds a layer of security to Sendmail, and provides mobile users who switch hosts the ability to use the same MTA without the need to reconfigure their mail client’s settings each time.

Install security/cyrus-sasl2 from the Ports Collection. This port supports a number of compile-time options. For the SMTP authentication method demonstrated in this example, make sure that `LOGIN` is not disabled.

After installing security/cyrus-sasl2, edit /usr/local/lib/sasl2/Sendmail.conf, or create it if it does not exist, and add the following line:

    pwcheck_method: saslauthd

Next, install security/cyrus-sasl2-saslauthd and add execute the following command:

    # sysrc saslauthd_enable="YES"

Finally, start the saslauthd daemon:

    # service saslauthd start

This daemon serves as a broker for Sendmail to authenticate against the FreeBSD passwd(5) database. This saves the trouble of creating a new set of usernames and passwords for each user that needs to use SMTP authentication, and keeps the login and mail password the same.

Next, edit /etc/make.conf and add the following lines:

    SENDMAIL_CFLAGS=-I/usr/local/include/sasl -DSASL
    SENDMAIL_LDADD=/usr/local/lib/libsasl2.so

These lines provide Sendmail the proper configuration options for linking to cyrus-sasl2 at compile time. Make sure that cyrus-sasl2 has been installed before recompiling Sendmail.

Recompile Sendmail by executing the following commands:

    # cd /usr/src/lib/libsmutil
    # make cleandir && make obj && make
    # cd /usr/src/lib/libsm
    # make cleandir && make obj && make
    # cd /usr/src/usr.sbin/sendmail
    # make cleandir && make obj && make && make install

This compile should not have any problems if /usr/src has not changed extensively and the shared libraries it needs are available.

After Sendmail has been compiled and reinstalled, edit /etc/mail/freebsd.mc or the local .mc. Many administrators choose to use the output from hostname(1) as the name of .mc for uniqueness.

Add these lines:

    dnl set SASL options
    TRUST_AUTH_MECH(`GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl
    define(`confAUTH_MECHANISMS', `GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl

These options configure the different methods available to Sendmail for authenticating users. To use a method other than pwcheck, refer to the Sendmail documentation.

Finally, run make(1) while in /etc/mail. That will run the new .mc and create a .cf named either freebsd.cf or the name used for the local .mc.

Then, run `make install restart`, which will copy the file to sendmail.cf, and properly restart Sendmail.

For more information about this process, refer to /etc/mail/Makefile.

To test the configuration, use a MUA to send a test message. For further investigation, set the `LogLevel` of Sendmail to `13` and watch /var/log/maillog for any errors.

For more information, refer to SMTP authentication.

Last modified on: June 20, 2026 by Dave Cottlehuber

Prev
Home
Next