<?xml version="1.0" encoding="iso-8859-1"?>
<!--
The FreeBSD Documentation Project
$FreeBSD$
-->
<chapter id="mail">
<chapterinfo>
<authorgroup>
<author>
<firstname>Bill</firstname>
<surname>Lloyd</surname>
<contrib>Original work by </contrib>
</author>
</authorgroup>
<authorgroup>
<author>
<firstname>Jim</firstname>
<surname>Mock</surname>
<contrib>Rewritten by </contrib>
<!-- 2 Dec 1999 -->
</author>
</authorgroup>
</chapterinfo>
<title>Electronic Mail</title>
<sect1 id="mail-synopsis">
<title>Synopsis</title>
<indexterm><primary>email</primary></indexterm>
<para><quote>Electronic Mail</quote>, 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 &os;, as well as an introduction to sending and
receiving email using &os;.
For more complete coverage of this subject,
refer to the books listed in
<xref linkend="bibliography"/>.</para>
<para>After reading this chapter, you will know:</para>
<itemizedlist>
<listitem>
<para>Which software components are involved in sending and
receiving electronic mail.</para>
</listitem>
<listitem>
<para>Where basic <application>sendmail</application>
configuration files are located in &os;.</para>
</listitem>
<listitem>
<para>The difference between remote and local
mailboxes.</para>
</listitem>
<listitem>
<para>How to block spammers from illegally using a mail
server as a relay.</para>
</listitem>
<listitem>
<para>How to install and configure an alternate Mail Transfer
Agent, replacing
<application>sendmail</application>.</para>
</listitem>
<listitem>
<para>How to troubleshoot common mail server problems.</para>
</listitem>
<listitem>
<para>How to set up the system to send mail only.</para>
</listitem>
<listitem>
<para>How to use mail with a dialup connection.</para>
</listitem>
<listitem>
<para>How to configure SMTP authentication for added
security.</para>
</listitem>
<listitem>
<para>How to install and use a Mail User Agent, such as
<application>mutt</application>, to send and receive
email.</para>
</listitem>
<listitem>
<para>How to download mail from a remote
<acronym>POP</acronym> or <acronym>IMAP</acronym>
server.</para>
</listitem>
<listitem>
<para>How to automatically apply filters and rules to incoming
email.</para>
</listitem>
</itemizedlist>
<para>Before reading this chapter, you should:</para>
<itemizedlist>
<listitem>
<para>Properly set up a network connection (<xref
linkend="advanced-networking"/>).</para>
</listitem>
<listitem>
<para>Properly set up the <acronym>DNS</acronym> information
for a mail host (<xref linkend="network-servers"/>).</para>
</listitem>
<listitem>
<para>Know how to install additional third-party software
(<xref linkend="ports"/>).</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="mail-using">
<title>Using Electronic Mail</title>
<indexterm><primary>POP</primary></indexterm>
<indexterm><primary>IMAP</primary></indexterm>
<indexterm><primary>DNS</primary></indexterm>
<para>There are five major parts involved in an email exchange:
<link linkend="mail-mua">the Mail User Agent
<acronym>MUA></acronym></link>, <link linkend="mail-mta">the
Mail Transfer Agent<acronym>MTA</acronym></link>, <link
linkend="mail-dns"><acronym>DNS</acronym></link>, <link
linkend="mail-receive">a remote or local mailbox</link>, and
<link linkend="mail-host">the mail host</link>.</para>
<sect2 id="mail-mua">
<title>The Mail User Agent</title>
<para>This includes command line programs such as
<application>mutt</application>,
<application>alpine</application>,
<application>elm</application>, and
<command>mail</command>, <acronym>GUI</acronym> programs such
as <application>balsa</application> or
<application>xfmail</application>, and web mail programs
which can be accessed from a web browser. User programs pass
the email transactions to the local <link
linkend="mail-host"><quote>mail host</quote></link>, either
by a <link
linkend="mail-mta"><acronym>MTA</acronym></link>, or by
delivering it over <acronym>TCP</acronym>.</para>
</sect2>
<sect2 id="mail-mta">
<title>The Mail Transfer Agent</title>
<indexterm>
<primary>mail server daemons</primary>
<secondary><application>Sendmail</application></secondary>
</indexterm>
<indexterm>
<primary>mail server daemons</primary>
<secondary><application>Postfix</application></secondary>
</indexterm>
<indexterm>
<primary>mail server daemons</primary>
<secondary><application>qmail</application></secondary>
</indexterm>
<indexterm>
<primary>mail server daemons</primary>
<secondary><application>Exim</application></secondary>
</indexterm>
<para>&os; ships with <application>Sendmail</application> as the
default <acronym>MTA</acronym>, but it also supports numerous
other mail server daemons, including:</para>
<itemizedlist>
<listitem>
<para><application>Exim</application>;</para>
</listitem>
<listitem>
<para><application>Postfix</application>;</para>
</listitem>
<listitem>
<para><application>qmail</application>.</para>
</listitem>
</itemizedlist>
<para>The <acronym>MTA</acronym> usually has two functions. It
is responsible for receiving incoming mail as well as
delivering outgoing mail. It is <emphasis>not</emphasis>
responsible for the collection of mail using protocols such as
<acronym>POP</acronym> or <acronym>IMAP</acronym>, nor does it
allow connecting to local <filename>mbox</filename> or Maildir
mailboxes. An additional <link
linkend="mail-receive">daemon</link> may be required for
these functions.</para>
<warning>
<para>Older versions of <application>Sendmail</application>
contain serious security issues which may result in an
attacker gaining local or remote access to the system.
Run a current version to &os; to avoid these problems.
Optionally, install an alternative <acronym>MTA</acronym>
from the <link linkend="ports">&os; Ports
Collection</link>.</para>
</warning>
</sect2>
<sect2 id="mail-dns">
<title>Email and DNS</title>
<para>The Domain Name System (<acronym>DNS</acronym>) and its
daemon <command>named</command> play a large role in the
delivery of email. In order to deliver mail from one site to
another, the <acronym>MTA</acronym> will look up the remote
site in <acronym>DNS</acronym> to determine which host will
receive mail for the destination. This process also occurs
when mail is sent from a remote host to the
<acronym>MTA</acronym>.</para>
<indexterm>
<primary>MX record</primary>
</indexterm>
<para><acronym>DNS</acronym> is responsible for mapping
hostnames to IP addresses, as well as for storing information
specific to mail delivery, known as Mail eXchanger
<acronym>MX</acronym> records. The <acronym>MX</acronym>
record specifies which host, or hosts, will receive mail for a
particular domain. If there is no <acronym>MX</acronym>
record for the hostname or domain, the mail will be delivered
directly to the host, provided there is an
<literal>A</literal> record pointing the hostname to the IP
address.</para>
<para>To view the <acronym>MX</acronym> records for a domain,
specify the type of record using &man.host.1;, as seen in the
example below:</para>
<screen>&prompt.user; <userinput>host -t mx FreeBSD.org</userinput>
FreeBSD.org mail is handled by 10 mx1.FreeBSD.org</screen>
</sect2>
<sect2 id="mail-receive">
<title>Receiving Mail</title>
<indexterm>
<primary>email</primary>
<secondary>receiving</secondary>
</indexterm>
<para>Receiving mail for a domain is done by the mail host.
It will collect all mail sent to the domain and store it
either in the default <filename>mbox</filename> or the
alternative Maildir format, depending on the configuration.
Once mail has been stored, it may either be read locally using
a <acronym>MUA</acronym>, or remotely accessed and collected
using protocols such as <acronym>POP</acronym> or
<acronym>IMAP</acronym>. In order to read mail locally,
a <acronym>POP</acronym> or <acronym>IMAP</acronym> server
does not need to be installed.</para>
<sect3 id="pop-and-imap">
<title>Accessing Remote Mailboxes Using <acronym>POP</acronym>
and <acronym>IMAP</acronym></title>
<indexterm><primary>POP</primary></indexterm>
<indexterm><primary>IMAP</primary></indexterm>
<para>To access mailboxes remotely, access to a
<acronym>POP</acronym> or <acronym>IMAP</acronym> server is
required. These protocols allow users to connect to their
mailboxes from remote locations. Though both
<acronym>POP</acronym> and <acronym>IMAP</acronym> allow
users to remotely access mailboxes, <acronym>IMAP</acronym>
offers many advantages, including:</para>
<itemizedlist>
<listitem>
<para><acronym>IMAP</acronym> can store messages on a
remote server as well as fetch them.</para>
</listitem>
<listitem>
<para><acronym>IMAP</acronym> supports concurrent
updates.</para>
</listitem>
<listitem>
<para><acronym>IMAP</acronym> can be useful over
low-speed links as it allows users to fetch the
structure of messages without downloading them. It can
also perform tasks such as searching on the server in
order to minimize data transfer between clients and
servers.</para>
</listitem>
</itemizedlist>
<para>In order to install a <acronym>POP</acronym> or
<acronym>IMAP</acronym> server, the following steps should
be performed:</para>
<procedure>
<step>
<para>Use the Ports Collection to install an
<acronym>IMAP</acronym> or <acronym>POP</acronym>
server. The following <acronym>POP</acronym> and
<acronym>IMAP</acronym> servers are well known:</para>
<itemizedlist>
<listitem>
<para><filename
role="package">mail/qpopper</filename></para>
</listitem>
<listitem>
<para><filename
role="package">mail/teapop</filename></para>
</listitem>
<listitem>
<para><filename
role="package">mail/imap-uw</filename></para>
</listitem>
<listitem>
<para><filename
role="package">mail/courier-imap</filename></para>
</listitem>
<listitem>
<para><filename
role="package">mail/dovecot2</filename></para>
</listitem>
</itemizedlist>
</step>
<step>
<para>Where required, use the startup script that came
with the application to load the <acronym>POP</acronym>
or <acronym>IMAP</acronym> server. Those programs will
also provide a variable which can be added to
<filename>/etc/rc.conf</filename> to automate the
startup of the application's daemon whenever the system
boots.</para>
</step>
</procedure>
<warning>
<para>It should be noted that both <acronym>POP</acronym>
and <acronym>IMAP</acronym> transmit information,
including username and password credentials, in
clear-text. To secure the transmission of information
across these protocols, consider tunneling sessions over
&man.ssh.1; (<xref linkend="security-ssh-tunneling"/>) or
using SSL (<xref linkend="openssl"/>).</para>
</warning>
</sect3>
<sect3 id="local">
<title>Accessing Local Mailboxes</title>
<para>Mailboxes may be accessed locally by directly using an
<acronym>MUA</acronym> on the server on which the mailbox
resides. This can be done using a built-in application
such as &man.mail.1; or by installing a
<acronym>MUA</acronym> from the Ports Collection..</para>
</sect3>
</sect2>
<sect2 id="mail-host">
<title>The Mail Host</title>
<indexterm><primary>mail host</primary></indexterm>
<para>The mail host is a server that is responsible for
delivering and receiving mail for a host, or a network.</para>
</sect2>
</sect1>
<sect1 id="sendmail">
<sect1info>
<authorgroup>
<author>
<firstname>Christopher</firstname>
<surname>Shumway</surname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
</sect1info>
<title><application>Sendmail</application> Configuration</title>
<indexterm>
<primary><application>Sendmail</application></primary>
</indexterm>
<para>&man.sendmail.8; is the default <acronym>MTA</acronym>
which is installed with &os;.
<application>Sendmail</application> accepts mail from
<acronym>MUA</acronym>s and delivers it to the appropriate
mailer as defined by its configuration file.
<application>Sendmail</application> can also accept network
connections and deliver mail to local mailboxes or to another
program.</para>
<para><application>Sendmail</application> uses the following
configuration files. This section describes these files in more
detail.</para>
<indexterm>
<primary><filename>/etc/mail/access</filename></primary>
</indexterm>
<indexterm>
<primary><filename>/etc/mail/aliases</filename></primary>
</indexterm>
<indexterm>
<primary><filename>/etc/mail/local-host-names</filename></primary>
</indexterm>
<indexterm>
<primary><filename>/etc/mail/mailer.conf</filename></primary>
</indexterm>
<indexterm>
<primary><filename>/etc/mail/mailertable</filename></primary>
</indexterm>
<indexterm>
<primary><filename>/etc/mail/sendmail.cf</filename></primary>
</indexterm>
<indexterm>
<primary><filename>/etc/mail/virtusertable</filename></primary>
</indexterm>
<informaltable frame="none" pgwide="1">
<tgroup cols="2">
<thead>
<row>
<entry>Filename</entry>
<entry>Function</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<filename>/etc/mail/access</filename></entry>
<entry><application>Sendmail</application> access database
file.</entry>
</row>
<row>
<entry>
<filename>/etc/mail/aliases</filename></entry>
<entry>Mailbox aliases</entry>
</row>
<row>
<entry>
<filename>/etc/mail/local-host-names</filename></entry>
<entry>Lists of hosts <application>Sendmail</application>
accepts mail for.</entry>
</row>
<row>
<entry>
<filename>/etc/mail/mailer.conf</filename></entry>
<entry>Mailer program configuration.</entry>
</row>
<row>
<entry>
<filename>/etc/mail/mailertable</filename></entry>
<entry>Mailer delivery table.</entry>
</row>
<row>
<entry>
<filename>/etc/mail/sendmail.cf</filename></entry>
<entry><application>Sendmail</application> master
configuration file.</entry>
</row>
<row>
<entry>
<filename>/etc/mail/virtusertable</filename></entry>
<entry>Virtual users and domain tables.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<sect2>
<title><filename>/etc/mail/access</filename></title>
<para>This database defines which host(s) or IP addresses
have access to the local mail server and what kind of access
they have. Hosts can be listed as <option>OK</option>,
<option>REJECT</option>, or <option>RELAY</option>, or can be
passed to <application>Sendmail</application>'s error
handling routine with a given mailer error. Hosts that
are listed as <option>OK</option>, 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 that are
listed as <option>REJECT</option> are rejected for all mail
connections. Hosts that are listed as <option>RELAY</option>
are allowed to send mail for any
destination using this mail server.</para>
<example>
<title>Configuring the <application>Sendmail</application>
Access Database</title>
<programlisting>cyberspammer.com 550 We do not accept mail from spammers
FREE.STEALTH.MAILER@ 550 We do not accept mail from spammers
another.source.of.spam REJECT
okay.cyberspammer.com OK
128.32 RELAY</programlisting>
</example>
<para>This example shows five entries. Mail senders that match
the left side of the table are affected by the action on the
right side of the table. The first two examples give an error
code to <application>Sendmail</application>'s error handling
routine. The message is sent to the remote host when a mail
matches the left side of the table. The third entry rejects
mail from a specific host on the Internet,
<hostid>another.source.of.spam</hostid>. The fourth entry
accepts mail connections from <hostid
role="fqdn">okay.cyberspammer.com</hostid>, which is
more specific than the <hostid
role="domainname">cyberspammer.com</hostid> line above.
More specific matches override less exact matches. The last
entry allows relaying of email from hosts with an IP address
that begins with <hostid>128.32</hostid>. These hosts can
send mail through this mail server that is destined for other
mail servers.</para>
<para>Whenever this file is updated, run
<command>make</command> in <filename
class="directory">/etc/mail/</filename> to update the
database.</para>
</sect2>
<sect2>
<title><filename>/etc/mail/aliases</filename></title>
<para>This database contains a list of virtual mailboxes that
are expanded to other user(s), files, programs, or other
aliases. Here are a few examples to illustrate the
file format:</para>
<example>
<title>Mail Aliases</title>
<programlisting>root: localuser
ftp-bugs: joe,eric,paul
bit.bucket: /dev/null
procmail: "|/usr/local/bin/procmail"</programlisting>
</example>
<para>The mailbox name on the left side of the colon is expanded
to the target(s) on the right. The first entry expands the
mailbox <username>root</username> to the mailbox
<username>localuser</username>, which is then looked up again
in the <filename>aliases</filename> database. If no match is
found, the message is delivered to
<username>localuser</username>. The second entry shows a
mail list. Mail to the mailbox <username>ftp-bugs</username>
is expanded to the three local mailboxes
<username>joe</username>, <username>eric</username>, and
<username>paul</username>. A remote mailbox could be
specified as <email>user@example.com</email>. The third
entry shows how to write mail to a file, in this case
<filename>/dev/null</filename>. The last entry demonstrates
how to send mail to a program,
<filename>/usr/local/bin/procmail</filename>, through a &unix;
pipe.</para>
<para>Whenever this file is updated, run
<command>make</command> in <filename
class="directory">/etc/mail/</filename> to update the
database.</para>
</sect2>
<sect2>
<title><filename>/etc/mail/local-host-names</filename></title>
<para>This is a list of hostnames &man.sendmail.8; is to accept
as the local host name. Place any domains or hosts that
<application>Sendmail</application> will receive mail
for. For example, to configure a mail server to accept mail
for the domain <hostid role="domainname">example.com</hostid>
and the host <hostid role="fqdn">mail.example.com</hostid>,
add these entries to
<filename>local-host-names</filename>:</para>
<programlisting>example.com
mail.example.com</programlisting>
<para>Whenever this file is updated, &man.sendmail.8; needs to be
restarted so that it will read the changes.</para>
</sect2>
<sect2>
<title><filename>/etc/mail/sendmail.cf</filename></title>
<para>This is the master configuration file for
<application>Sendmail</application>. It controls the overall
behavior of <application>Sendmail</application>, 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.</para>
<para>The master <application>Sendmail</application> configuration
file can be built from &man.m4.1; macros that define the
features and behavior of <application>Sendmail</application>.
Refer to
<filename>/usr/src/contrib/sendmail/cf/README</filename> for
some of the details.</para>
<para>Whenever changes to this file are made,
<application>Sendmail</application> needs to be restarted for
the changes to take effect.</para>
</sect2>
<sect2>
<title><filename>/etc/mail/virtusertable</filename></title>
<para>The <filename>virtusertable</filename> maps mail addresses
for virtual domains and mailboxes to real mailboxes. These
mailboxes can be local, remote, aliases defined in
<filename>/etc/mail/aliases</filename>, or files.</para>
<example>
<title>Example Virtual Domain Mail Map</title>
<programlisting>root@example.com root
postmaster@example.com postmaster@noc.example.net
@example.com joe</programlisting>
</example>
<para>The above example contains a mapping for the domain
<hostid role="domainname">example.com</hostid>. This file
is processed in a first match order. The first item maps
<email>root@example.com</email> to the local mailbox
<username>root</username>. The second entry maps
<email>postmaster@example.com</email> to the mailbox
<username>postmaster</username> on the host <hostid
role="fqdn">noc.example.net</hostid>. Finally, if
nothing from <hostid role="domainname">example.com</hostid>
has matched so far, it will match the last mapping, which
matches every other mail message addressed to someone at
<hostid role="domainname">example.com</hostid> to the local
mailbox <username>joe</username>.</para>
</sect2>
</sect1>
<sect1 id="mail-changingmta">
<sect1info>
<authorgroup>
<author>
<firstname>Andrew</firstname>
<surname>Boothman</surname>
<contrib>Written by </contrib>
</author>
</authorgroup>
<authorgroup>
<author>
<firstname>Gregory</firstname>
<surname>Neil Shapiro</surname>
<contrib>Information taken from emails written
by</contrib>
</author>
</authorgroup>
</sect1info>
<title>Changing the Mail Transfer Agent</title>
<indexterm>
<primary>email</primary>
<secondary>change mta</secondary>
</indexterm>
<para>&os; comes with <application>Sendmail</application> already
installed as the <acronym>MTA</acronym> which is in charge of
outgoing and incoming mail.</para>
<para>However, the system administrator can change the system's
<acronym>MTA</acronym>. The reasons for doing so range from
wanting to try out another <acronym>MTA</acronym> to needing a
specific feature or package which relies on another
<acronym>MTA</acronym>. Whatever the reason, &os; makes it
easy to make the change.</para>
<sect2>
<title>Install a New <acronym>MTA</acronym></title>
<para>A wide choice of <acronym>MTA</acronym>s is available
from the <literal>mail</literal> category of the <link
linkend="ports">&os; Ports Collection</link>.</para>
<para>Once a new <acronym>MTA</acronym> is installed, configure
the new software and decide if it really fulfills your needs
before replacing <application>Sendmail</application>.</para>
<para>Refer to the new chosen <acronym>MTA</acronym>'s
documentation for information on how to configure the
software.</para>
</sect2>
<sect2 id="mail-disable-sendmail">
<title>Disable <application>Sendmail</application></title>
<warning>
<para>If <application>Sendmail</application>'s outgoing mail
service is disabled, it is important that it is replaced
with an alternative mail delivery system. Otherwise, system
functions such as &man.periodic.8; will be unable to deliver
their results by email. Many parts of the system expect a
functional <acronym>MTA</acronym>. If applications continue
to use <application>Sendmail</application>'s binaries to try
to send email they are disabled, mail could go into an
inactive <application>Sendmail</application> queue, and
never be delivered.</para>
</warning>
<para>In order to completely disable
<application>Sendmail</application>, including the outgoing
mail service, add or edit the following lines in
<filename>/etc/rc.conf</filename>:</para>
<programlisting>sendmail_enable="NO"
sendmail_submit_enable="NO"
sendmail_outbound_enable="NO"
sendmail_msp_queue_enable="NO"</programlisting>
<para>To only disable <application>Sendmail</application>'s
incoming mail service, set</para>
<programlisting>sendmail_enable="NO"</programlisting>
<para>in <filename>/etc/rc.conf</filename>. More information
on <application>Sendmail</application>'s startup options
is available in &man.rc.sendmail.8;.</para>
</sect2>
<sect2>
<title>Running the New <acronym>MTA</acronym> on Boot</title>
<para>The new <acronym>MTA</acronym> can be started during
boot by adding a configuration line to
<filename>/etc/rc.conf</filename>. This example enables the
Postfix <acronym>MTA</acronym>:</para>
<screen>&prompt.root; echo
'<replaceable>postfix</replaceable>_enable=<quote>YES</quote>'
>> /etc/rc.conf</screen>
<para>The specified <acronym>MTA</acronym> will now be
automatically started during boot.</para>
</sect2>
<sect2>
<title>Replacing <application>Sendmail</application> as
the System's Default Mailer</title>
<para><application>Sendmail</application> is so ubiquitous as
standard software on &unix; systems that some software assumes
it is already installed and configured. For this reason, many
alternative <acronym>MTA</acronym>s provide their own
compatible implementations of the
<application>Sendmail</application> command-line interface in
order to facilitate using them as <quote>drop-in</quote>
replacements for <application>Sendmail</application>.</para>
<para>When using an alternative <acronym>MTA</acronym>,
make sure that software trying to execute standard
<application>Sendmail</application> binaries, such as
<filename>/usr/bin/sendmail</filename>, actually execute
the chosen mailer instead. Fortunately, &os; provides a
system called &man.mailwrapper.8; for this purpose.</para>
<para>When <application>Sendmail</application> is operating
as installed,
<filename>/etc/mail/mailer.conf</filename> will look like
this:</para>
<programlisting>sendmail /usr/libexec/sendmail/sendmail
send-mail /usr/libexec/sendmail/sendmail
mailq /usr/libexec/sendmail/sendmail
newaliases /usr/libexec/sendmail/sendmail
hoststat /usr/libexec/sendmail/sendmail
purgestat /usr/libexec/sendmail/sendmail</programlisting>
<para>When any of the commands listed on the left are run,
the system actually executes the associated command shown on
the right instead. This system makes it easy to change what
binaries are executed when these default
<filename>Sendmail</filename> functions are invoked.</para>
<para>As an example, to run
<filename>/usr/local/supermailer/bin/sendmail-compat</filename>
instead of <application>Sendmail</application>, specify the
paths to the installed applications in
<filename>/etc/mail/mailer.conf</filename>:</para>
<programlisting>sendmail /usr/local/supermailer/bin/sendmail-compat
send-mail /usr/local/supermailer/bin/sendmail-compat
mailq /usr/local/supermailer/bin/mailq-compat
newaliases /usr/local/supermailer/bin/newaliases-compat
hoststat /usr/local/supermailer/bin/hoststat-compat
purgestat /usr/local/supermailer/bin/purgestat-compat</programlisting>
</sect2>
<sect2>
<title>Finishing</title>
<para>Once everything is configured, either kill the
unneeded <application>sendmail</application> processes and
start the processes belonging to the new software, or
reboot. Rebooting provides the opportunity to ensure that
the system is correctly configured to start the new
<acronym>MTA</acronym> automatically on boot.</para>
</sect2>
</sect1>
<sect1 id="mail-trouble">
<title>Troubleshooting</title>
<indexterm>
<primary>email</primary>
<secondary>troubleshooting</secondary>
</indexterm>
<qandaset>
<qandaentry>
<question>
<para>Why do I have to use the FQDN for hosts on my
site?</para>
</question>
<answer>
<para>The host may actually be in a different domain.
For example, in order for a host in <hostid
role="fqdn">foo.bar.edu</hostid> to reach a host
called <hostid>mumble</hostid> in the <hostid
role="domainname">bar.edu</hostid> domain, refer to
it by the Fully-Qualified Domain Name
<acronym>FQDN</acronym>, <hostid
role="fqdn">mumble.bar.edu</hostid>, instead of just
<hostid>mumble</hostid>.</para>
<indexterm><primary>BIND</primary></indexterm>
<para>This is because the version of
<application>BIND</application> which ships with
&os; no longer provides default abbreviations
for non-FQDNs other than the local domain. An
unqualified host such as
<hostid>mumble</hostid> must either be found as
<hostid role="fqdn">mumble.foo.bar.edu</hostid>,
or it will be searched for in the root domain.</para>
<para>In older versions of
<application>BIND</application>,
the search continued across <hostid
role="domainname">mumble.bar.edu</hostid>, and
<hostid role="domainname">mumble.edu</hostid>. RFC
1535 details why this is considered bad practice or
even a security hole.</para>
<para>As a good workaround, place the line:</para>
<programlisting>search foo.bar.edu bar.edu</programlisting>
<para>instead of the previous:</para>
<programlisting>domain foo.bar.edu</programlisting>
<para>into <filename>/etc/resolv.conf</filename>.
However, make sure that the search order does not go
beyond the <quote>boundary between local and public
administration</quote>, as RFC 1535 calls it.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para><application>Sendmail</application> says
<errorname>mail loops back to myself</errorname>.</para>
</question>
<answer>
<para>This is answered in the <ulink
url="http://www.sendmail.org/faq/">Sendmail
FAQ</ulink> as follows. This FAQ is recommended reading
when <quote>tweaking</quote> the mail setup.</para>
<programlisting>I'm getting these error messages:
553 MX list for domain.net points back to relay.domain.net
554 <user@domain.net>... Local configuration error
How can I solve this problem?
You have asked mail to the domain (e.g., domain.net) to be
forwarded to a specific host (in this case, relay.domain.net)
by using an MX record, but the relay machine does not recognize
itself as domain.net. Add domain.net to /etc/mail/local-host-names
[known as /etc/sendmail.cw prior to version 8.10]
(if you are using FEATURE(use_cw_file)) or add <quote>Cw domain.net</quote>
to /etc/mail/sendmail.cf.</programlisting>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>How can I run a mail server on a dial-up PPP
host?</para>
</question>
<answer>
<para>Connect to a &os; mail gateway on the LAN. The PPP
connection is non-dedicated.</para>
<indexterm>
<primary>MX record</primary>
</indexterm>
<para>One way to do this is to get a full-time Internet server
to provide secondary <acronym>MX</acronym> services for the
domain. In this example, the domain is <hostid
role="domainname">example.com</hostid> and the ISP has
configured <hostid
role="domainname">example.net</hostid> to provide
secondary <acronym>MX</acronym> services to the
domain:</para>
<programlisting>example.com. MX 10 example.com.
MX 20 example.net.</programlisting>
<para>Only one host should be specified as the final
recipient. For <application>Sendmail</application>, add
<literal>Cw example.com</literal> in
<filename>/etc/mail/sendmail.cf</filename> on
<hostid role="domainname">example.com</hostid>.</para>
<para>When the sending <acronym>MTA</acronym> attempts
to deliver mail, it will try to connect to the system,
<hostid role="domainname">example.com</hostid>, over the PPP
link. This will time out if the destination is offline.
The <acronym>MTA</acronym> will automatically deliver it to
the secondary <acronym>MX</acronym> site at the Internet
Service Provider (<acronym>ISP</acronym>), <hostid
role="domainname">example.net</hostid>. The secondary
<acronym>MX</acronym> site will periodically try to connect
to the primary <acronym>MX</acronym> host, <hostid
role="domainname">example.com</hostid>.</para>
<para>Use something like this as a login
script:</para>
<programlisting>#!/bin/sh
# Put me in /usr/local/bin/pppmyisp
( sleep 60 ; /usr/sbin/sendmail -q ) &
/usr/sbin/ppp -direct pppmyisp</programlisting>
<para>When creating a separate login script for users, instead
use <command>sendmail -qRexample.com</command> in the script
above. This will force all mail in the queue for <hostid
role="domainname">example.com</hostid> to be processed
immediately.</para>
<para>A further refinement of the situation can be seen from
this example from the &a.isp;:</para>
<programlisting>> we provide the secondary MX for a customer. The customer connects to
> our services several times a day automatically to get the mails to
> his primary MX (We do not call his site when a mail for his domains
> arrived). Our sendmail sends the mailqueue every 30 minutes. At the
> moment he has to stay 30 minutes online to be sure that all mail is
> gone to the primary MX.
>
> Is there a command that would initiate sendmail to send all the mails
> now? The user has not root-privileges on our machine of course.
In the <quote>privacy flags</quote> section of sendmail.cf, there is a
definition Opgoaway,restrictqrun
Remove restrictqrun to allow non-root users to start the queue processing.
You might also like to rearrange the MXs. We are the 1st MX for our
customers like this, and we have defined:
# If we are the best MX for a host, try directly instead of generating
# local config error.
OwTrue
That way a remote site will deliver straight to you, without trying
the customer connection. You then send to your customer. Only works for
<quote>hosts</quote>, so you need to get your customer to name their mail
machine <quote>customer.com</quote> as well as
<quote>hostname.customer.com</quote> in the DNS. Just put an A record in
the DNS for <quote>customer.com</quote>.</programlisting>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Why do I keep getting <errorname>Relaying
Denied</errorname> errors when sending mail from other
hosts?</para>
</question>
<answer>
<para>In a default &os; installation,
<application>Sendmail</application> is configured to only
send mail from the host it is running on. For example,
if a <acronym>POP</acronym> 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 <literal>MAILER-DAEMON</literal>
with a <errorname>5.7 Relaying Denied</errorname>.</para>
<para>The most straightforward solution is to add the ISP's
FQDN to <filename>/etc/mail/relay-domains</filename>, as
seen in this example:</para>
<screen>&prompt.root; <userinput>echo "your.isp.example.com" > /etc/mail/relay-domains</userinput></screen>
<para>After creating or editing this file, restart
<application>Sendmail</application>. This works great if
the server administrator does not wish to send mail
locally, would like to use a <acronym>MUA</acronym> on a
remote machine, or would like to use another
<acronym>ISP</acronym> for remote connections. It is also
useful when there is only one or two email accounts. If
there are a large number of addresses, add them one per
line:</para>
<programlisting>your.isp.example.com
other.isp.example.net
users-isp.example.org
www.example.org</programlisting>
<para>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.</para>
</answer>
</qandaentry>
</qandaset>
</sect1>
<sect1 id="mail-advanced">
<title>Advanced Topics</title>
<para>This section covers more involved topics such as mail
configuration and setting up mail for an entire domain.</para>
<sect2 id="mail-config">
<title>Basic Configuration</title>
<indexterm>
<primary>email</primary>
<secondary>configuration</secondary>
</indexterm>
<para>Out of the box, one can send email to external hosts as
long as <filename>/etc/resolv.conf</filename> is configured or
the network has access to a configured
<acronym>DNS</acronym> server. If order to have mail
delivered to the <acronym>MTA</acronym> on the &os; host,
do one of the following:</para>
<itemizedlist>
<listitem>
<para>Run a <acronym>DNS</acronym> server for the
domain.</para>
</listitem>
<listitem>
<para>Get mail delivered directly to to the
<acronym>FQDN</acronym> for the machine.</para>
</listitem>
</itemizedlist>
<indexterm><primary>SMTP</primary></indexterm>
<para>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:</para>
<itemizedlist>
<indexterm><primary>MX record</primary></indexterm>
<listitem>
<para>Make sure that the lowest-numbered
<acronym>MX</acronym> record in
<acronym>DNS</acronym> points to the host's static IP
address.</para>
</listitem>
<listitem>
<para>Make sure there is no <acronym>MX</acronym> entry in
the <acronym>DNS</acronym> for the host.</para>
</listitem>
</itemizedlist>
<para>Either of the above will allow mail to be received
directly at the host.</para>
<para>Try this:</para>
<screen>&prompt.root; <userinput>hostname</userinput>
example.FreeBSD.org
&prompt.root; <userinput>host example.FreeBSD.org</userinput>
example.FreeBSD.org has address 204.216.27.XX</screen>
<para>In this example, mail sent directly to <email
role="nolink">yourlogin@example.FreeBSD.org</email>
should work without problems, assuming
<application>Sendmail</application> is running correctly on
<hostid role="fqdn">example.FreeBSD.org</hostid>.</para>
<para>For this example:</para>
<screen>&prompt.root; <userinput>host example.FreeBSD.org</userinput>
example.FreeBSD.org has address 204.216.27.XX
example.FreeBSD.org mail is handled (pri=10) by hub.FreeBSD.org</screen>
<para>All mail sent to <hostid
role="fqdn">example.FreeBSD.org</hostid> will be
collected on <hostid>hub</hostid> under the same username
instead of being sent directly to your host.</para>
<para>The above information is handled by the
<acronym>DNS</acronym> server. The <acronym>DNS</acronym>
record that carries mail routing information is the
<acronym>MX</acronym> entry. If no <acronym>MX</acronym>
record exists, mail will be delivered directly to the host by
way of its IP address.</para>
<para>The <acronym>MX</acronym> entry for <hostid
role="fqdn">freefall.FreeBSD.org</hostid> at one time looked
like this:</para>
<programlisting>freefall MX 30 mail.crl.net
freefall MX 40 agora.rdrop.com
freefall MX 10 freefall.FreeBSD.org
freefall MX 20 who.cdrom.com</programlisting>
<para><hostid>freefall</hostid> had many <acronym>MX</acronym>
entries. The lowest <acronym>MX</acronym> 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.</para>
<para>Alternate <acronym>MX</acronym> sites should have separate
Internet connections in order to be most useful. Your
<acronym>ISP</acronym> can provide this service.</para>
</sect2>
<sect2 id="mail-domain">
<title>Mail for a Domain</title>
<para>When configuring a <acronym>MTA</acronym> for a network,
any mail sent to hosts in its domain should be diverted to the
<acronym>MTA</acronym> so that users can receive their mail on
the master mail server.</para>
<indexterm><primary>DNS</primary></indexterm>
<para>To make life easiest, a user account with the same
<emphasis>username</emphasis> should exist on both the
<acronym>MTA</acronym> and the system with the
<acronym>MUA</acronym>. Use &man.adduser.8; to create the
user accounts.</para>
<para>The <acronym>MTA</acronym> must be the designated mail
exchanger for each workstation on the network. This is done
in the<acronym>DNS</acronym> configuration with an
<acronym>MX</acronym> record:</para>
<programlisting>example.FreeBSD.org A 204.216.27.XX ; Workstation
MX 10 hub.FreeBSD.org ; Mailhost</programlisting>
<para>This will redirect mail for the workstation to the
<acronym>MTA</acronym> no matter where the A record points.
The mail is sent to the <acronym>MX</acronym> host.</para>
<para>This must be configured on a <acronym>DNS</acronym>
server. If the network does not run its own
<acronym>DNS</acronym> server, talk to the
<acronym>ISP</acronym> or <acronym>DNS</acronym>
provider.</para>
<para>The following is an example of virtual email hosting.
Consider a customer with the domain <hostid
role="domainname">customer1.org</hostid>, where all the mail
for <hostid role="domainname">customer1.org</hostid> should be
sent to <hostid role="fqdn">mail.myhost.com</hostid>. The
<acronym>DNS</acronym> entry should look like this:</para>
<programlisting>customer1.org MX 10 mail.myhost.com</programlisting>
<para>An <literal>A</literal>> record is
<emphasis>not</emphasis> needed for <hostid
role="domainname">customer1.org</hostid> in order to only
handle email for that domain. However, running
<command>ping</command> against <hostid
role="domainname">customer1.org</hostid> will not work
unless an <literal>A</literal> record exists for it.</para>
<para>Tell the <acronym>MTA</acronym> which domains and/or
hostnames it should accept mail for. Either of the following
will work for <application>Sendmail</application>:</para>
<itemizedlist>
<listitem>
<para>Add the hosts to
<filename>/etc/mail/local-host-names</filename> when
using the <literal>FEATURE(use_cw_file)</literal>.
For versions of
<application>Sendmail</application> earlier than 8.10,
edit <filename>/etc/sendmail.cw</filename> instead.</para>
</listitem>
<listitem>
<para>Add a <literal>Cwyour.host.com</literal> line to
<filename>/etc/sendmail.cf</filename>. For
<application>Sendmail</application> 8.10 or higher, add
that line to
<filename>/etc/mail/sendmail.cf</filename>.</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="outgoing-only">
<sect1info>
<authorgroup>
<author>
<firstname>Bill</firstname>
<surname>Moran</surname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
</sect1info>
<title>Setting Up to Send Only</title>
<para>There are many instances where one may only want to send
mail through a relay. Some examples are:</para>
<itemizedlist>
<listitem>
<para>The computer is a desktop machine that needs to use
programs such as &man.send-pr.1;, using the
<acronym>ISP</acronym>'s mail relay.</para>
</listitem>
<listitem>
<para>The computer is a server that does not handle mail
locally, but needs to pass off all mail to a relay for
processing.</para>
</listitem>
</itemizedlist>
<para>While any <acronym>MTA</acronym> is capable of filling
this particular niche, it can be difficult to properly configure
a full-featured <acronym>MTA</acronym> just to handle offloading
mail. Programs such as <application>Sendmail</application> and
<application>Postfix</application> are overkill for this
use.</para>
<para>Additionally, a typical Internet access service agreement
may forbid one from running a <quote>mail server</quote>.</para>
<para>The easiest way to fulfill those needs is to install the
<filename role="package">mail/ssmtp</filename> port:</para>
<screen>&prompt.root; <userinput>cd /usr/ports/mail/ssmtp</userinput>
&prompt.root; <userinput>make install replace clean</userinput></screen>
<para>Once installed, <filename
role="package">mail/ssmtp</filename> can be configured with
<filename>/usr/local/etc/ssmtp/ssmtp.conf</filename>:</para>
<programlisting>root=yourrealemail@example.com
mailhub=mail.example.com
rewriteDomain=example.com
hostname=_HOSTNAME_</programlisting>
<para>Use the real email address for <username>root</username>.
Enter the <acronym>ISP</acronym>'s outgoing mail relay in place
of <hostid role="fqdn">mail.example.com</hostid>. Some
<acronym>ISP</acronym>s call this the <quote>outgoing mail
server</quote> or <quote>SMTP server</quote>).</para>
<para>Make sure to disable
<application>Sendmail</application>, including the outgoing mail
service. See <xref linkend="mail-disable-sendmail"/> for
details.</para>
<para><filename role="package">mail/ssmtp</filename> has some
other options available. Refer to the examples in
<filename>/usr/local/etc/ssmtp</filename> or the manual page
of <application>ssmtp</application> for more information.</para>
<para>Setting up <application>ssmtp</application> in this manner
allows any software on the computer that needs to send mail to
function properly, while not violating the
<acronym>ISP</acronym>'s usage policy or allowing the computer
to be hijacked for spamming.</para>
</sect1>
<sect1 id="SMTP-dialup">
<title>Using Mail with a Dialup Connection</title>
<para>When using a static IP address, one should not need to
adjust the default configuration. Set the hostname to the
assigned Internet name and <application>Sendmail</application>
will do the rest.</para>
<para>When using a dynamically assigned IP address and a dialup
PPP connection to the Internet, one usually has a mailbox on the
<acronym>ISP</acronym>'s mail server. In this example, the
<acronym>ISP</acronym>'s domain is <hostid
role="domainname">example.net</hostid>, the user name is
<username>user</username>, the hostname is <hostid
role="fqdn">bsd.home</hostid>, and the <acronym>ISP</acronym>
has allowed <hostid
role="fqdn">relay.example.net</hostid> as a mail relay.</para>
<para>In order to retrieve mail from the <acronym>ISP</acronym>'s
mailbox, install a retrieval agent from the Ports Collection.
<filename role="package">mail/fetchmail</filename> is a good
choice as it supports many different protocols. Usually, the
<acronym>ISP</acronym> will provide <acronym>POP</acronym>.
When using user <acronym>PPP</acronym>, email can be
automatically fetched when an Internet connection is established
with the following entry in
<filename>/etc/ppp/ppp.linkup</filename>:</para>
<programlisting>MYADDR:
!bg su user -c fetchmail</programlisting>
<para>When using <application>Sendmail</application> to deliver
mail to non-local accounts, configure
<application>Sendmail</application> to process the mail queue as
soon as the Internet connection is established. To do this, add
this line after the above <command>fetchmail</command> entry in
<filename>/etc/ppp/ppp.linkup</filename>:</para>
<programlisting> !bg su user -c "sendmail -q"</programlisting>
<para>In this example, there is an account for
<username>user</username> on <hostid
role="fqdn">bsd.home</hostid>. In the home directory of
<username>user</username> on <hostid
role="fqdn">bsd.home</hostid>, create a
<filename>.fetchmailrc</filename> which contains this
line:</para>
<programlisting>poll example.net protocol pop3 fetchall pass MySecret</programlisting>
<para>This file should not be readable by anyone except
<username>user</username> as it contains the password
<literal>MySecret</literal>.</para>
<para>In order to send mail with the correct
<literal>from:</literal> header, configure
<application>Sendmail</application> to use
<email>user@example.net</email> rather than <email
role="nolink">user@bsd.home</email> and to send all mail
via <hostid role="fqdn">relay.example.net</hostid>, allowing
quicker mail transmission.</para>
<para>The following <filename>.mc</filename> file should
suffice:</para>
<programlisting>VERSIONID(`bsd.home.mc version 1.0')
OSTYPE(bsd4.4)dnl
FEATURE(nouucp)dnl
MAILER(local)dnl
MAILER(smtp)dnl
Cwlocalhost
Cwbsd.home
MASQUERADE_AS(`example.net')dnl
FEATURE(allmasquerade)dnl
FEATURE(masquerade_envelope)dnl
FEATURE(nocanonify)dnl
FEATURE(nodns)dnl
define(`SMART_HOST', `relay.example.net')
Dmbsd.home
define(`confDOMAIN_NAME',`bsd.home')dnl
define(`confDELIVERY_MODE',`deferred')dnl</programlisting>
<para>Refer to the previous section for details of how to convert
this file into the
<filename>sendmail.cf</filename> format. Do not forget to
restart <application>Sendmail</application> after updating
<filename>sendmail.cf</filename>.</para>
</sect1>
<sect1 id="SMTP-Auth">
<sect1info>
<authorgroup>
<author>
<firstname>James</firstname>
<surname>Gorham</surname>
<contrib>Written by </contrib>
</author>
</authorgroup>
</sect1info>
<title>SMTP Authentication</title>
<para>Configuring <acronym>SMTP</acronym> authentication on the
<acronym>MTA</acronym> provides a number of benefits.
<acronym>SMTP</acronym> authentication adds a layer
of security to <application>Sendmail</application>, and provides
mobile users who switch hosts the ability to use the same
<acronym>MTA</acronym> without the need to reconfigure their
mail client's settings each time.</para>
<procedure>
<step>
<para>Install <filename
role="package">security/cyrus-sasl2</filename>
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
<option>LOGIN</option> is not disabled.</para>
</step>
<step>
<para>After installing <filename
role="package">security/cyrus-sasl2</filename>,
edit
<filename>/usr/local/lib/sasl2/Sendmail.conf</filename>,
or create it if it does not exist, and add the following
line:</para>
<programlisting>pwcheck_method: saslauthd</programlisting>
</step>
<step>
<para>Next, install <filename
role="package">security/cyrus-sasl2-saslauthd</filename>
and add the following line to
<filename>/etc/rc.conf</filename>:</para>
<programlisting>saslauthd_enable="YES"</programlisting>
<para>Finally, start the saslauthd daemon:</para>
<screen>&prompt.root; <userinput>service saslauthd start</userinput></screen>
<para>This daemon serves as a broker for
<application>sendmail</application> to authenticate against
the &os; &man.passwd.5; database. This
saves the trouble of creating a new set of usernames and
passwords for each user that needs to use
<acronym>SMTP</acronym> authentication, and keeps the login
and mail password the same.</para>
</step>
<step>
<para>Next, edit <filename>/etc/make.conf</filename> and add
the following lines:</para>
<programlisting>SENDMAIL_CFLAGS=-I/usr/local/include/sasl -DSASL
SENDMAIL_LDFLAGS=-L/usr/local/lib
SENDMAIL_LDADD=-lsasl2</programlisting>
<para>These lines provide
<application>Sendmail</application> the proper configuration
options for linking to <filename
role="package">cyrus-sasl2</filename> at compile time.
Make sure that <filename
role="package">cyrus-sasl2</filename> has been installed
before recompiling
<application>Sendmail</application>.</para>
</step>
<step>
<para>Recompile <application>Sendmail</application> by
executing the following commands:</para>
<screen>&prompt.root; <userinput>cd /usr/src/lib/libsmutil</userinput>
&prompt.root; <userinput>make cleandir && make obj && make</userinput>
&prompt.root; <userinput>cd /usr/src/lib/libsm</userinput>
&prompt.root; <userinput>make cleandir && make obj && make</userinput>
&prompt.root; <userinput>cd /usr/src/usr.sbin/sendmail</userinput>
&prompt.root; <userinput>make cleandir && make obj && make && make install</userinput></screen>
<para>This compile should not have any problems if
<filename class="directory">/usr/src</filename> has not
changed extensively and the shared libraries it needs are
available.</para>
</step>
<step>
<para>After <application>Sendmail</application> has been
compiled and reinstalled, edit
<filename>/etc/mail/freebsd.mc</filename> or the local
<filename>.mc</filename> file. Many administrators choose
to use the output from &man.hostname.1; as the name of the
<filename>.mc</filename> file for uniqueness. Add these
lines:</para>
<programlisting>dnl set SASL options
TRUST_AUTH_MECH(`GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl
define(`confAUTH_MECHANISMS', `GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl</programlisting>
<para>These options configure the different methods available
to <application>Sendmail</application> for authenticating
users. To use a method other than
<application>pwcheck</application>, refer to the
<application>Sendmail</application> documentation.</para>
</step>
<step>
<para>Finally, run &man.make.1; while in <filename
class="directory">/etc/mail</filename>. That will run the
new <filename>.mc</filename> and create a
<filename>.cf</filename> named either
<filename>freebsd.cf</filename> or the name used for the
local <filename>.mc</filename>. Then, run <command>make
install restart</command>, which will copy the file to
<filename>sendmail.cf</filename>, and properly restart
<application>Sendmail</application>. For more information
about this process, refer to
<filename>/etc/mail/Makefile</filename>.</para>
</step>
</procedure>
<para>To test the configuration, use a <acronym>MUA</acronym> to
send a test message. For further investigation, set the
<option>LogLevel</option> of <application>Sendmail</application>
to <literal>13</literal> and watch
<filename>/var/log/maillog</filename> for any errors.</para>
<para>For more information, refer to <ulink
url="http://www.sendmail.org/~ca/email/auth.html">
<acronym>SMTP</acronym> authentication</ulink>.</para>
</sect1>
<sect1 id="mail-agents">
<sect1info>
<authorgroup>
<author>
<firstname>Marc</firstname>
<surname>Silver</surname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
</sect1info>
<title>Mail User Agents</title>
<indexterm>
<primary>Mail User Agents</primary>
</indexterm>
<para>A <acronym>MUA</acronym> is an application that is used to
send and receive email. As email <quote>evolves</quote> and
becomes more complex, <acronym>MUA</acronym>s are becoming
increasingly powerful and provide users increased functionality
and flexibility. The <literal>mail</literal> category of the
&os; Ports Collection contains numerous <acronym>MUA</acronym>s.
These include graphical email clients such as
<application>Evolution</application> or
<application>Balsa</application> and console based clients such
as <application>mutt</application> or
<application>alpine</application>.</para>
<sect2 id="mail-command">
<title><command>mail</command></title>
<para>&man.mail.1; is the default
<acronym>MUA</acronym> installed with &os;. It is a console
based <acronym>MUA</acronym> that offers the basic
functionality required to send and receive text-based email.
It provides limited attachment support and can only access
local mailboxes.</para>
<para>Although <command>mail</command> does not natively support
interaction with <acronym>POP</acronym> or
<acronym>IMAP</acronym> servers, these mailboxes may be
downloaded to a local <filename>mbox</filename> using an
application such as
<application>fetchmail</application>.</para>
<para>In order to send and receive email, run
<command>mail</command>:</para>
<screen>&prompt.user; <userinput>mail</userinput></screen>
<para>The contents of the user's mailbox in <filename
class="directory">/var/mail</filename> are automatically
read by <command>mail</command>. 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:</para>
<screen>Mail version 8.1 6/6/93. Type ? for help.
"/var/mail/marcs": 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"</screen>
<para>Messages can now be read by typing <keycap>t</keycap>
followed by the message number. This example reads the first
email:</para>
<screen>& <userinput>t 1</userinput>
Message 1:
From root@localhost Mon Mar 8 14:05:52 2004
X-Original-To: marcs@localhost
Delivered-To: marcs@localhost
To: marcs@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.</screen>
<para>As seen in this example, the message will be displayed
with full headers. To display the list of messages again,
press <keycap>h</keycap>.</para>
<para>If the email requires a reply, press either
<keycap>R</keycap> or <keycap>r</keycap>
<command>mail</command> keys. <keycap>R</keycap> instructs
<command>mail</command> to reply only to the sender of the
email, while <keycap>r</keycap> 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 <keycap>.</keycap> on its own line. An example can be
seen below:</para>
<screen>& <userinput>R 1</userinput>
To: root@localhost
Subject: Re: test
<userinput>Thank you, I did get your email.
.</userinput>
EOT</screen>
<para>In order to send a new email, press <keycap>m</keycap>,
followed by the recipient email address. Multiple recipients
may be specified by separating each address with the
<keycap>,</keycap> 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
<keycap>.</keycap> on its own line.</para>
<screen>& <userinput>mail root@localhost</userinput>
Subject: <userinput>I mastered mail
Now I can send and receive email using mail ... :)
.</userinput>
EOT</screen>
<para>While using <command>mail</command>, press
<keycap>?</keycap> to display help at any time. Refer to
&man.mail.1; for more help on how to use
<command>mail</command>.</para>
<note>
<para>&man.mail.1; was not designed to handle attachments and
thus deals with them poorly. Newer <acronym>MUA</acronym>s
handle attachments in a more intelligent way. Users who
prefer to use <command>mail</command> may find the <filename
role="package">converters/mpack</filename> port to be of
considerable use.</para>
</note>
</sect2>
<sect2 id="mutt-command">
<title><application>mutt</application></title>
<para><application>mutt</application> is a powerful
<acronym>MUA</acronym>, with many features, including:</para>
<itemizedlist>
<listitem>
<para>The ability to thread messages.</para>
</listitem>
<listitem>
<para>PGP support for digital signing and encryption of
email.</para>
</listitem>
<listitem>
<para>MIME support.</para>
</listitem>
<listitem>
<para>Maildir support.</para>
</listitem>
<listitem>
<para>Highly customizable.</para>
</listitem>
</itemizedlist>
<para>Refer to <ulink
url="http://www.mutt.org"></ulink> for more
information on <application>mutt</application>.</para>
<para><application>mutt</application>
may be installed using the <filename
role="package">mail/mutt</filename> port. After the
port has been installed, <application>mutt</application> can
be started by issuing the following command:</para>
<screen>&prompt.user; <userinput>mutt</userinput></screen>
<para><application>mutt</application> will automatically read
and display the contents of the user mailbox in <filename
class="directory">/var/mail</filename>. If no mails are
found, <application>mutt</application> will wait for commands
from the user. The example below shows
<application>mutt</application> displaying a list of
messages:</para>
<mediaobject>
<imageobject>
<imagedata fileref="mail/mutt1"/>
</imageobject>
</mediaobject>
<para>To read an email, select it using the cursor keys and
press <keycap>Enter</keycap>. An example of
<application>mutt</application> displaying email can be seen
below:</para>
<mediaobject>
<imageobject>
<imagedata fileref="mail/mutt2"/>
</imageobject>
</mediaobject>
<para>Similar to &man.mail.1;, <application>mutt</application>
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 <keycap>r</keycap>. To send a group reply
to the original sender as well as all the message recipients,
press <keycap>g</keycap>.</para>
<note>
<para>By default, <application>mutt</application> uses the
&man.vi.1; editor for creating and replying to emails. Each
user can customize this by creating or editing the
<filename>.muttrc</filename> in their home directory and
setting the <literal>editor</literal> variable or by setting
the <envar>EDITOR</envar> environment variable. Refer to
<ulink url="http://www.mutt.org/"></ulink> for more
information about configuring
<application>mutt</application>.</para>
</note>
<para>To compose a new mail message, press
<keycap>m</keycap>. After a valid subject has been given,
<application>mutt</application> will start &man.vi.1; so the
email can be written. Once the contents of the email are
complete, save and quit from <command>vi</command>.
<application>mutt</application> will resume, displaying a
summary screen of the mail that is to be delivered. In
order to send the mail, press <keycap>y</keycap>. An example
of the summary screen can be seen below:</para>
<mediaobject>
<imageobject>
<imagedata fileref="mail/mutt3"/>
</imageobject>
</mediaobject>
<para><application>mutt</application> contains extensive help
which can be accessed from most of the menus by pressing
<keycap>?</keycap>. The top line also displays the keyboard
shortcuts where appropriate.</para>
</sect2>
<sect2 id="alpine-command">
<title><application>alpine</application></title>
<para><application>alpine</application> is aimed at a beginner
user, but also includes some advanced features.</para>
<warning>
<para><application>alpine</application> 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 <emphasis>known</emphasis> problems have been fixed,
<application>alpine</application> code is written in an
insecure style and the &os; Security Officer believes there
are likely to be other undiscovered vulnerabilities. Users
install <application>alpine</application> at their own
risk.</para>
</warning>
<para>The current version of <application>alpine</application>
may be installed using the <filename
role="package">mail/alpine</filename> port. Once the port
has installed, <application>alpine</application> can be
started by issuing the following command:</para>
<screen>&prompt.user; <userinput>alpine</userinput></screen>
<para>The first time <application>alpine</application>
runs, it displays a greeting page with a brief introduction,
as well as a request from the
<application>alpine</application> 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 <keycap>Enter</keycap>. Alternatively, press
<keycap>E</keycap> to exit the greeting without sending an
anonymous message. An example of the greeting page is
shown below:</para>
<mediaobject>
<imageobject>
<imagedata fileref="mail/pine1"/>
</imageobject>
</mediaobject>
<para>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.</para>
<para>The default directory opened by
<application>alpine</application> is <filename
class="directory">inbox</filename>. To view the message
index, press <keycap>I</keycap>, or select the
<guimenuitem>MESSAGE INDEX</guimenuitem> option shown
below:</para>
<mediaobject>
<imageobject>
<imagedata fileref="mail/pine2"/>
</imageobject>
</mediaobject>
<para>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
<keycap>Enter</keycap>.</para>
<mediaobject>
<imageobject>
<imagedata fileref="mail/pine3"/>
</imageobject>
</mediaobject>
<para>In the screenshot below, a sample message is displayed by
<application>alpine</application>. Contextual keyboard
shortcuts are displayed at the bottom of the screen. An
example of one of a shortcut is <keycap>r</keycap>, which
tells the <acronym>MUA</acronym> to reply to the current
message being displayed.</para>
<mediaobject>
<imageobject>
<imagedata fileref="mail/pine4"/>
</imageobject>
</mediaobject>
<para>Replying to an email in <application>alpine</application>
is done using the <application>pico</application> editor,
which is installed by default with
<application>alpine</application>.
<application>pico</application> makes it easy to navigate the
message and is easier for novice users to use than &man.vi.1;
or &man.mail.1;. Once the reply is complete, the message can
be sent by pressing <keycombo
action="simul"><keycap>Ctrl</keycap><keycap>X</keycap>
</keycombo>. <application>alpine</application>
will ask for confirmation before sending the message.</para>
<mediaobject>
<imageobject>
<imagedata fileref="mail/pine5"/>
</imageobject>
</mediaobject>
<para><application>alpine</application> can be customized using
the <guimenuitem>SETUP</guimenuitem> option from the main
menu. Consult <ulink
url="http://www.washington.edu/alpine/"></ulink>
for more information.</para>
</sect2>
</sect1>
<sect1 id="mail-fetchmail">
<sect1info>
<authorgroup>
<author>
<firstname>Marc</firstname>
<surname>Silver</surname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
</sect1info>
<title>Using <application>fetchmail</application></title>
<indexterm>
<primary>fetchmail</primary>
</indexterm>
<para><application>fetchmail</application> is a full-featured
<acronym>IMAP</acronym> and <acronym>POP</acronym> client. It
allows users to automatically download mail from remote
<acronym>IMAP</acronym> and <acronym>POP</acronym> servers and
save it into local mailboxes where it can be accessed more
easily. <application>fetchmail</application> can be installed
using the <filename role="package">mail/fetchmail</filename>
port, and offers various features, including:</para>
<itemizedlist>
<listitem>
<para>Support for the <acronym>POP3</acronym>,
<acronym>APOP</acronym>, <acronym>KPOP</acronym>,
<acronym>IMAP</acronym>, <acronym>ETRN</acronym> and
<acronym>ODMR</acronym> protocols.</para>
</listitem>
<listitem>
<para>Ability to forward mail using <acronym>SMTP</acronym>,
which allows filtering, forwarding, and aliasing to function
normally.</para>
</listitem>
<listitem>
<para>May be run in daemon mode to check periodically for new
messages.</para>
</listitem>
<listitem>
<para>Can retrieve multiple mailboxes and forward them, based
on configuration, to different local users.</para>
</listitem>
</itemizedlist>
<para>This section explains some of the basic features of
<application>fetchmail</application>. This utility requires a
<filename>.fetchmailrc</filename> configuration in the user's
home directory in order to run correctly. This file includes
server information as well as login credentials. Due to the
sensitive nature of the contents of this file, it is advisable
to make it readable only by the user, with the following
command:</para>
<screen>&prompt.user; <userinput>chmod 600 .fetchmailrc</userinput></screen>
<para>The following <filename>.fetchmailrc</filename> serves as an
example for downloading a single user mailbox using
<acronym>POP</acronym>. It tells
<application>fetchmail</application> to connect to <hostid
role="fqdn">example.com</hostid> using a username of
<username>joesoap</username> and a password of
<literal>XXX</literal>. This example assumes that the user
<username>joesoap</username> exists on the local system.</para>
<programlisting>poll example.com protocol pop3 username "joesoap" password "XXX"</programlisting>
<para>The next example connects to multiple <acronym>POP</acronym>
and <acronym>IMAP</acronym> servers and redirects to different
local usernames where applicable:</para>
<programlisting>poll example.com proto pop3:
user "joesoap", with password "XXX", is "jsoap" here;
user "andrea", with password "XXXX";
poll example2.net proto imap:
user "john", with password "XXXXX", is "myth" here;</programlisting>
<para><application>fetchmail</application> can be run in daemon
mode by running it with <option>-d</option>, followed by the
interval (in seconds) that <application>fetchmail</application>
should poll servers listed in <filename>.fetchmailrc</filename>.
The following example configures
<application>fetchmail</application> to poll every 600
seconds:</para>
<screen>&prompt.user; <userinput>fetchmail -d 600</userinput></screen>
<para>More information on <application>fetchmail</application> can
be found at <ulink
url="http://fetchmail.berlios.de/"></ulink>.</para>
</sect1>
<sect1 id="mail-procmail">
<sect1info>
<authorgroup>
<author>
<firstname>Marc</firstname>
<surname>Silver</surname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
</sect1info>
<title>Using <application>procmail</application></title>
<indexterm>
<primary>procmail</primary>
</indexterm>
<para><application>procmail</application> is a powerful
application used to filter incoming mail. It allows users to
define <quote>rules</quote> which can be matched to incoming
mails to perform specific functions or to reroute mail to
alternative mailboxes or email addresses.
<application>procmail</application> can be installed using the
<filename role="package">mail/procmail</filename> port. Once
installed, it can be directly integrated into most
<acronym>MTA</acronym>s. Consult the <acronym>MTA</acronym>
documentation for more information. Alternatively,
<application>procmail</application> can be integrated by adding
the following line to a <filename>.forward</filename> in the
home directory of the user:</para>
<programlisting>"|exec /usr/local/bin/procmail || exit 75"</programlisting>
<para>The following section displays some basic
<application>procmail</application> rules, as well as brief
descriptions of what they do. Rules must be inserted into a
<filename>.procmailrc</filename>, which must reside in the
user's home directory.</para>
<para>The majority of these rules can be found in
&man.procmailex.5;.</para>
<para>To forward all mail from <email>user@example.com</email> to
an external address of <email
role="nolink">goodmail@example2.com</email>:</para>
<programlisting>:0
* ^From.*user@example.com
! goodmail@example2.com</programlisting>
<para>To forward all mails shorter than 1000 bytes to an external
address of <email
role="nolink">goodmail@example2.com</email>:</para>
<programlisting>:0
* < 1000
! goodmail@example2.com</programlisting>
<para>To send all mail sent to
<email>alternate@example.com</email> to a mailbox called
<filename>alternate</filename>:</para>
<programlisting>:0
* ^TOalternate@example.com
alternate</programlisting>
<para>To send all mail with a subject of <quote>Spam</quote> to
<devicename>/dev/null</devicename>:</para>
<programlisting>:0
^Subject:.*Spam
/dev/null</programlisting>
<para>A useful recipe that parses incoming <hostid
role="domainname">&os;.org</hostid> mailing lists and places
each list in its own mailbox:</para>
<programlisting>:0
* ^Sender:.owner-freebsd-\/[^@]+@FreeBSD.ORG
{
LISTNAME=${MATCH}
:0
* LISTNAME??^\/[^@]+
FreeBSD-${MATCH}
}</programlisting>
</sect1>
</chapter>