path: root/en_US.ISO8859-1/books/handbook/mail/chapter.xml

<?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>'
&gt;&gt; /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>

	      <para>This is because the version of
		<application>BIND</application><indexterm>
		<primary>BIND</primary></indexterm> 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 &lt;user@domain.net&gt;... 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>

	<para>One way to do this is to get a full-time Internet server
	  to provide secondary <acronym>MX</acronym><indexterm>
	  <primary>MX record</primary></indexterm> 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 ) &amp;
/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>&gt; we provide the secondary MX for a customer. The customer connects to
&gt; our services several times a day automatically to get the mails to
&gt; his primary MX (We do not call his site when a mail for his domains
&gt; arrived). Our sendmail sends the mailqueue every 30 minutes. At the
&gt; moment he has to stay 30 minutes online to be sure that all mail is
&gt; gone to the primary MX.
&gt;
&gt; Is there a command that would initiate sendmail to send all the mails
&gt; 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" &gt; /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>
	<listitem>
	  <para>Make sure that the lowest-numbered
	    <acronym>MX</acronym><indexterm><primary>MX record</primary></indexterm> 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 &amp;&amp; make obj &amp;&amp; make</userinput>
&prompt.root; <userinput>cd /usr/src/lib/libsm</userinput>
&prompt.root; <userinput>make cleandir &amp;&amp; make obj &amp;&amp; make</userinput>
&prompt.root; <userinput>cd /usr/src/usr.sbin/sendmail</userinput>
&prompt.root; <userinput>make cleandir &amp;&amp; make obj &amp;&amp; make &amp;&amp; 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>&amp; <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>&amp; <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>&amp; <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
* &lt; 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>