From murray@freebsdmall.com  Wed Apr  3 22:29:54 2002
Return-Path: <murray@freebsdmall.com>
Received: from mail.freebsdmall.com (www.freebsdmall.com [66.220.2.194])
	by hub.freebsd.org (Postfix) with ESMTP id 8570737B417
	for <FreeBSD-gnats-submit@freebsd.org>; Wed,  3 Apr 2002 22:29:54 -0800 (PST)
Received: by mail.freebsdmall.com (Postfix, from userid 2074)
	id 6607E2E827; Wed,  3 Apr 2002 22:29:54 -0800 (PST)
Message-Id: <20020404062954.6607E2E827@mail.freebsdmall.com>
Date: Wed,  3 Apr 2002 22:29:54 -0800 (PST)
From: Murray Stokely <murray@FreeBSD.org>
Reply-To: Murray Stokely <murray@FreeBSD.org>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: Mail chapter of Handbook is incomplete
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         36727
>Category:       docs
>Synopsis:       Mail chapter of Handbook is incomplete
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Apr 03 22:30:01 PST 2002
>Closed-Date:    Mon Mar 15 23:30:44 PST 2004
>Last-Modified:  Mon Mar 15 23:30:44 PST 2004
>Originator:     Murray Stokely
>Release:        FreeBSD 4.5-RC i386
>Organization:
FreeBSD Project
>Environment:
any

>Description:

We only include 1 paragraph on MUAs in the mail chapter of the FreeBSD
Handbook.  This is very valuable information that new users need.  We
should add at least 5 pages talking about installation and usage of
Mutt, Pine, fetchmail, the concepts of local Unix mailboxes vs POP3 /
IMAP.  Available IMAP clients for FreeBSD.  Pointer to the SSH
tunnelling section for these insecure protocols, etc.. 

>How-To-Repeat:

Point a new user at FreeBSD.

>Fix:

Many beginning Unix / Linux books do a good job at documenting this.
We do not.

For now, we should focus on adding more information about MUAs to
section 18.2.1.

Eventually, we may end up with one chapter on reading electronic mail
with FreeBSD. (in Part I of the Handbook), and another chapter on
using various MTAs with FreeBSD (Postfix, sendmail, etc..) in Part II
of the Handbook.

>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Sun Apr 14 23:14:36 PDT 2002 
Responsible-Changed-Why:  
I'll close this sometime this week. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=36727 

From: Ceri Davies <setantae@submonkey.net>
To: throdes@FreeBSD.org
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/36727: Mail chapter of Handbook is incomplete
Date: Sun, 9 Jun 2002 15:10:38 +0100

 Tom, while you're working on this, could you please see that the
 daily_status_include_submit_mailq periodic.conf knob gets mentioned somewhere ?
 
 Thanks,
 
 Ceri
 
 -- 
 you can't see when light's so strong
 you can't see when light is gone

From: Tom Rhodes <darklogik@pittgoth.com>
To: Ceri Davies <setantae@submonkey.net>
Cc: trhodes@FreeBSD.org, FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/36727: Mail chapter of Handbook is incomplete
Date: Sun, 09 Jun 2002 21:01:53 -0700

 Ceri Davies wrote:
 
 >The following reply was made to PR docs/36727; it has been noted by GNATS.
 >
 >From: Ceri Davies <setantae@submonkey.net>
 >To: throdes@FreeBSD.org
 >Cc: FreeBSD-gnats-submit@freebsd.org
 >Subject: Re: docs/36727: Mail chapter of Handbook is incomplete
 >Date: Sun, 9 Jun 2002 15:10:38 +0100
 >
 > Tom, while you're working on this, could you please see that the
 > daily_status_include_submit_mailq periodic.conf knob gets mentioned somewhere ?
 > 
 > Thanks,
 > 
 > Ceri
 > 
 > -- 
 > you can't see when light's so strong
 > you can't see when light is gone
 >
 >
 Sure!  Let me get another laptop first, I'm kinda 
 computer/workstation-less at the
 moment.  But I'll get to this ;)
 
 
 Thanks for the content idea!
 
 --
 Tom Rhodes
 
 

From: Marc Silver <marcs@draenor.org>
To: freebsd-gnats-submit@FreeBSD.org, murray@FreeBSD.org
Cc:  
Subject: Re: docs/36727: Mail chapter of Handbook is incomplete
Date: Thu, 11 Mar 2004 09:04:56 +0000

 --fUYQa+Pmc3FrFX/N
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 
 Hi guys,
 
 I've done some work on adding MUA information to the handbook, as well
 as some minor additions regarding local and remote mailboxes, and
 information on procmail and fetchmail.
 
 This patch consists of three parts:
 
  1) chapter.sgnml-patch
     This file contains the patch to the mail chapter itself.
 
  2) handbook_Makefile-patch
     This file contains patches that are required to the handbook
     Makefile in order to change the .scr files to .png files.
 
  3) scr_files.tar.bz2 
     This file contains the .scr files (which may need to change)
     required to build the .png images.  Since I'm not sure if binary
     files can be submitted to GNATS, I'm going to leave this up at
     http://draenor.org/marcs/FreeBSD/scr_files.tar.bz2 instead.
 
 The rendered document may also be viewed online at
 http://draenor.org/marcs/FreeBSD/html/mail.html
 
 The only technical problem with this document seems to be that <keycap>
 is not displaying properly, but Tom Rhodes is helping me solve this
 problem.
 
 - Marc
 
 -- 
 Success is never final. Failure is never fatal. It is courage that
 counts.  
   -- Winston Churchill
 
 --fUYQa+Pmc3FrFX/N
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: attachment; filename="chapter.sgml-patch"
 
 --- chapter.sgml.orig	Mon Mar  8 20:04:59 2004
 +++ chapter.sgml	Thu Mar 11 09:54:01 2004
 @@ -32,11 +32,12 @@
  
      <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 FreeBSD.
 -      However, it is not a complete reference and in fact many
 -      important considerations are omitted.  For more complete
 -      coverage of the subject, the reader is referred to the many
 -      excellent books listed in <xref linkend="bibliography">.</para>
 +      a basic introduction to running a mail server on &os;, as well as an
 +      introduction to sending and receiving email using &os;; however,
 +      it is not a complete reference and in fact many important
 +      considerations are omitted.  For more complete coverage of the
 +      subject, the reader is referred to the many excellent books listed
 +      in <xref linkend="bibliography">.</para>
  
      <para>After reading this chapter, you will know:</para>
  
 @@ -52,6 +53,11 @@
        </listitem>
  
        <listitem>
 +        <para>An understanding of the difference between remote and
 +	  local mailboxes.</para>
 +      </listitem>
 +
 +      <listitem>
  	<para>How to block spammers from illegally using your mail server as a
  	  relay.</para>
        </listitem>
 @@ -80,6 +86,22 @@
        <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 your 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>
 @@ -110,25 +132,25 @@
      <para>There are five major parts involved in an email exchange.  They
        are: <link linkend="mail-mua">the user program</link>, <link
        linkend="mail-mta">the server daemon</link>, <link
 -      linkend="mail-dns">DNS</link>, <link linkend="mail-receive">a POP or
 -      IMAP daemon</link>, and of course, <link linkend="mail-host">the
 +      linkend="mail-dns">DNS</link>, <link linkend="mail-receive">a
 +      remote or local mailbox</link>, and of course, <link linkend="mail-host">the
        mailhost itself</link>.</para>
  
      <sect2 id="mail-mua">
        <title>The User Program</title>
  
        <para>This includes command line programs such as
 -        <application>mutt</application>, <application>pine</application>,
 -	<application>elm</application>, and
 -	<application>mail</application>, and GUI programs such as
 +	<application>mutt</application>,
 +	<application>pine</application>, <application>elm</application>,
 +	and <command>mail</command>, and GUI programs such as
  	<application>balsa</application>,
  	<application>xfmail</application> to name a few, and something
  	more <quote>sophisticated</quote> like a WWW browser.  These
 -	programs simply pass off the email transactions to the local <link
 -	linkend="mail-host"><quote>mailhost</quote></link>, either by
 -	calling one of the <link linkend="mail-mta">server daemons</link>
 -	available or delivering it over TCP.</para>
 -    </sect2>
 +	programs simply pass off the email transactions to the local
 +	<link linkend="mail-host"><quote>mailhost</quote></link>, either
 +	by calling one of the <link linkend="mail-mta">server
 +	daemons</link> available or delivering it over TCP.</para>
 +	</sect2>
  
      <sect2 id="mail-mta">
        <title>Mailhost Server Daemon</title>
 @@ -157,10 +179,13 @@
  	the most widely used.</para>
  
        <para>The server daemon usually has two functions&mdash;it looks
 -        after receiving incoming mail and delivers outgoing mail.  It does
 -	not allow you to connect to it via POP or IMAP to read your mail.
 -	You need an additional <link linkend="mail-receive">daemon</link>
 -	for that.</para>
 +	after receiving incoming mail and delivers outgoing mail.  It is
 +	not responsible for allowing you to collect mail using protocols
 +	such as <acronym>POP</acronym> or <acronym>IMAP</acronym> to
 +	read your email, nor does it allow connecting to local
 +	<filename>mbox</filename> or Maildir mailboxes.  You may require
 +	an additional <link linkend="mail-receive">daemon</link> for
 +	that.</para>
  
        <para>Be aware that some older versions of
          <application>sendmail</application> have some serious security
 @@ -194,29 +219,117 @@
        </indexterm>
  
        <para>Receiving mail for your domain is done by the mail host.  It
 -        will collect mail sent to you and store it for reading or pickup.
 -	In order to pick the stored mail up, you will need to connect to
 -	the mail host.  This is done by either using POP or IMAP.  If you
 -	want to read mail directly on the mail host, then a POP or IMAP
 -	server is not needed.</para>
 -
 -      <indexterm><primary>POP</primary></indexterm>
 -      <indexterm><primary>IMAP</primary></indexterm>
 -      <para>If you want to run a POP or IMAP server, there are two things
 -        you need to do:</para>
 -
 -      <procedure>
 -        <step>
 -	  <para>Get a POP or IMAP daemon from the <ulink
 -	    url="../../../../ports/mail.html">ports collection</ulink> and install
 -	    it on your system.</para>
 -	</step>
 -
 -	<step>
 -	  <para>Modify <filename>/etc/inetd.conf</filename> to load the
 -	    POP or IMAP server.</para>
 -	</step>
 -      </procedure>
 +	will collect mail sent to you and store it for reading or pickup
 +	in either <filename>mbox</filename> or Maildir format, depending
 +	on your configuration.  Mail can then be remotely accessed using
 +	either <acronym>POP</acronym> or <acronym>IMAP</acronym>, or
 +	alternatively by using a mail user agent that is locally
 +	installed on the mail host itself which will directly
 +	communicate with the mailbox.  This means that should you only
 +	wish to read mail locally, you are not required to install a
 +	<acronym>POP</acronym> or <acronym>IMAP</acronym> server.</para>
 +
 +      <sect3 id="pop-and-imap">
 +        <title>Accessing remote mailboxes using POP and IMAP</title>
 +
 +        <indexterm><primary>POP</primary></indexterm>
 +        <indexterm><primary>IMAP</primary></indexterm>
 +	<para>In order to access mailboxes remotely, you are required to
 +	  run a <acronym>POP</acronym> or <acronym>IMAP</acronym>
 +	  server.  This allows users to connect to their mailboxes from
 +	  remote locations with ease.  Though both
 +	  <acronym>POP</acronym> and <acronym>IMAP</acronym> allow users
 +	  to remotely access mailboxes, <acronym>IMAP</acronym> offers
 +	  many advantages, some of which are:</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 extremely useful over 
 +	      low-speed links, as it allows users to fetch the structure
 +	      of messages without downloading them, as well as
 +	      performing 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>Decide on an <acronym>IMAP</acronym> or 
 +	      <acronym>POP</acronym> server that best suits your needs.
 +	      The following <acronym>POP</acronym> and
 +	      <acronym>IMAP</acronym> servers are well known and serve
 +	      as some good examples:</para>
 +
 +	      <itemizedlist>
 +	        <listitem>
 +		  <para>qpopper</para>
 +	        </listitem>
 +
 +	        <listitem>
 +		  <para>teapop</para>
 +	        </listitem>
 +
 +	        <listitem>
 +		  <para>imap-uw</para>
 +	        </listitem>
 +
 +	        <listitem>
 +		  <para>courier-imap</para>
 +	        </listitem>
 +	      </itemizedlist>
 +
 +	  </step>
 +
 +          <step>
 +	    <para>Install the <acronym>POP</acronym> or
 +	      <acronym>IMAP</acronym> daemon of your choosing from the
 +	      <ulink url="../../../../ports/mail.html">ports
 +	      collection</ulink>.</para>
 +	  </step>
 +
 +	  <step>
 +	    <para>Where required, modify <filename>/etc/inetd.conf</filename> 
 +	      to load the <acronym>POP</acronym> or
 +	      <acronym>IMAP</acronym> server.</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.  This means
 +	    that if you wish to secure the transmission of information
 +	    across these protocols, you should consider tunnelling
 +	    sessions over &man.ssh.1;. See the <ulink
 +	    url="../handbook/openssh.html#AEN13610">&os;
 +	    handbook</ulink> for more information.</para> 
 +        </warning>
 +      </sect3>
 +
 +      <sect3 id="local">
 +        <title>Accessing local mailboxes</title>
 +
 +	<para>Mailboxes may be accessed locally by directly utilizing
 +	  <acronym>MUA</acronym>'s on the server on which the mailbox
 +	  resides.  This can be done using applications such as
 +	  <application>mutt</application> or <command>mail</command>.
 +	</para>
 +      </sect3>
      </sect2>
  
      <sect2 id="mail-host">
 @@ -247,8 +360,8 @@
  
      <para>&man.sendmail.8; is the default Mail Transfer Agent (MTA) in
        FreeBSD.  <application>sendmail</application>'s job is to accept
 -      mail from Mail User Agents (MUA) and deliver it to the
 -      appropriate mailer as defined by its configuration file.
 +      mail from Mail User Agents (<acronym>MUA</acronym>) and deliver 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 deliver it to
        another program.</para>
 @@ -914,14 +1027,14 @@
  	  <para>In default FreeBSD installations,
   	    <application>sendmail</application> is configured to only
   	    send mail from the host it is running on.  For example, if
 - 	    a POP3 server is installed, then users will be able to
 - 	    check mail from school, work, or other remote locations
 - 	    but they still will not be able to send outgoing emails
 - 	    from outside locations.  Typically, a few moments after
 - 	    the attempt, an email will be sent from
 - 	    <application>MAILER-DAEMON</application> with a
 - 	    <errorname>5.7 Relaying Denied</errorname> error
 - 	    message.</para>
 +	    a <acronym>POP</acronym> server is installed, then users
 +	    will be able to check mail from school, work, or other
 +	    remote locations but they still will not be able to send
 +	    outgoing emails from outside locations.  Typically, a few
 +	    moments after the attempt, an email will be sent from
 +	    <application>MAILER-DAEMON</application> with a
 +	    <errorname>5.7 Relaying Denied</errorname> error
 +	    message.</para>
  
  	  <para>There are several ways to get around this.  The most
   	    straightforward solution is to put your ISP's address in
 @@ -1380,13 +1493,14 @@
        role="fqdn">relay.example.net</hostid> as a mail relay.</para>
  
      <para>In order to retrieve mail from your mailbox, you must
 -      install a retrieval agent. The <application>fetchmail</application> utility
 -      is a good choice as it supports many different protocols.
 -      This program is available as a package or from the ports
 -      collection (<filename role="package">mail/fetchmail</filename>).
 -      Usually, your ISP will provide POP3. If you are using user PPP,
 -      you can automatically fetch your mail when an Internet
 -      connection is established with the following entry in
 +      install a retrieval agent. The
 +      <application>fetchmail</application> utility is a good choice as
 +      it supports many different protocols.  This program is available
 +      as a package or from the ports collection (<filename
 +      role="package">mail/fetchmail</filename>).  Usually, your ISP will
 +      provide <acronym>POP</acronym>. If you are using user PPP, you can
 +      automatically fetch your mail when an Internet connection is
 +      established with the following entry in
        <filename>/etc/ppp/ppp.linkup</filename>:</para>
  
      <programlisting>MYADDR:
 @@ -1574,6 +1688,542 @@
  
    </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 Mail User Agent (<acronym>MUA</acronym>) is an application
 +      that is used to send and receive email.  Furthermore, as email
 +      <quote>evolves</quote> and becomes more complex,
 +      <acronym>MUA</acronym>'s are becoming increasingly powerful in the
 +      way they interact with email, giving users increased functionality
 +      and flexibility.  &os; contains support for numerous mail user
 +      agents, all of which can be easily installed using the <link
 +      linkend="ports">FreeBSD Ports Collection</link>.  Users may choose
 +      between graphical email clients such as
 +      <application>evolution</application> or
 +      <application>balsa</application>, or console based clients such as
 +      <application>mutt</application>, <application>pine</application>
 +      or <command>mail</command>.</para>
 +
 +    <sect2 id="mail-command">
 +      <title>mail</title>
 +
 +      <para>&man.mail.1; is the default Mail User Agent 
 +	(<acronym>MUA</acronym>) in &os;.  <command>mail</command> is a
 +	console based <acronym>MUA</acronym> that offers all the basic
 +	functionality required to send and receive text-based email,
 +	though it is limited in its interaction with email attachments
 +	and only support 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 local <filename>mbox</filename> files using an
 +	application such as <application>fetchmail</application> which
 +	will be discussed later in this chapter.</para>
 +      
 +      <para>In order to send and receive email, simply invoke the
 +	<command>mail</command> command as per the following
 +	example:</para>
 +
 +      <screen>&prompt.user; <userinput>mail</userinput></screen>
 +
 +      <para>The contents of the user mailbox in
 +	<filename role="directory">/var/mail/</filename> are
 +	automatically read by the <command>mail</command> application.
 +	Should the mailbox be empty, the application exits with a
 +	message indicating that no mails could be found.  Once the
 +	mailbox has been read, the application interface is started, and
 +	a list of messages is 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 using the <keycap>t</keycap>
 +	<command>mail</command> command, suffixed by the message number
 +	that should be displayed.  In this example, we will read the
 +	first email:</para>
 +
 +      <screen>& t 1
 +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 receieve it.</screen>
 +
 +      <para>As can be seen in the example above, the <keycap>t</keycap>
 +	command causes the message to be displayed with full headers.
 +	To display the list of messages again, the <keycap>h</keycap>
 +	<command>mail</command> command should be used.</para>
 +
 +      <para>If the email requires a response, you may use
 +	<command>mail</command> to reply, by using either the
 +	<keycap>R</keycap> or <keycap>r</keycap> <command>mail</command>
 +	commands.  The <keycap>R</keycap> command instructs
 +	<command>mail</command> to reply only to the sender of the
 +	email, while <keycap>r</keycap> replies not only to the sender,
 +	but also to other recipients of the message.  You may also
 +	suffix these commands with the mail number which you would like
 +	to reply to.  Once this has been done, the response should be
 +	entered, and the end of the message should be marked by a single
 +	<keycap>.</keycap> on a new line.  An example can be seen
 +	below:</para>
 +      
 +      <screen>& R 1 To: root@localhost Subject: Re: test
 +
 +Thank you, I did get your email.
 +.
 +EOT</screen>
 +
 +      <para>In order to send new email, the <keycap>m</keycap>
 +	<command>mail</command> command should be used, followed by the
 +	recipient email address.  Multiple recipients may also be
 +	specified by seperating 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 a new
 +	line.</para>
 +
 +      <screen>& mail root@localhost
 +Subject: I mastered mail
 +
 +Now I can send and recieve email using mail... :)
 +.
 +EOT</screen>
 +
 +      <para>While inside the <command>mail</command> application, the 
 +	<keycap>?</keycap> command may be used to display help at any
 +	time.  The &man.mail.1; manual page should also be consulted for
 +	more help with <command>mail</command>.</para>
 +
 +      <note>
 +        <para>As previously mentioned, the &man.mail.1; command was not
 +	  originally designed to handle attachments, and thus deals with
 +	  them very poorly.  Newer <acronym>MUA</acronym>'s, such as
 +	  <application>mutt</application> handle attachments in a much
 +	  more intelligent way, but should you still wish to use the
 +	  <command>mail</command> command, the <filename
 +	  role="package">converters/mpack</filename> port may be of
 +	  considerable use.</para>
 +      </note>
 +    </sect2>
 +
 +    <sect2 id="mutt-command">
 +      <title>mutt</title>
 +
 +      <para><application>mutt</application> is a small, but very
 +        powerful Mail User Agent, with excellent features,
 +	just some of which include:</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>All of these features, and more, help to make mutt one of
 +	the most advanced mail user agents available.  See <ulink
 +	url="http://www.mutt.org">http://www.mutt.org</ulink> for more
 +	information on mutt.</para>
 +
 +      <para>The stable version of <application>mutt</application> may be 
 +	installed using the <filename
 +	role="package">mail/mutt</filename> port, while the current
 +	development verion may be installed via the <filename
 +	role="package">mail/mutt-devel</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 the
 +	contents of the user mailbox in <filename
 +	role="directory">/var/mail </filename> and display the contents
 +	if applicable.  If no mails are found in the user mailbox, then
 +	<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" format="PNG">
 +        </imageobject>
 +      </mediaobject>
 +
 +      <para>In order to read an email, simply select it using the cursor
 +	keys, and press the <keycap>Enter</keycap> key.  An example of
 +	<application>mutt</application> displaying email can be seen
 +	below:</para>
 +
 +      <mediaobject>
 +        <imageobject>
 +	  <imagedata fileref="mail/mutt2" format="PNG">
 +        </imageobject>
 +      </mediaobject>
 +
 +      <para>As with the &man.mail.1; command,
 +	<application>mutt</application> allows users to reply only to
 +	the sender of the message, as well as to all recipients.  To
 +	reply only to the sender of the email, use the
 +	<keycap>r</keycap> keyboard shortcut.  To send a group reply,
 +	which will be sent to the original sender as well as all the
 +	message recipients, use the <keycap>g</keycap> shortcut.</para>
 +
 +      <note>
 +        <para><application>mutt</application> makes use of the
 +	  &man.vi.1; command as an editor for creating and replying to
 +	  emails.  This may be customized by the user by creating or
 +	  editing their own <filename>.muttrc</filename> and setting the
 +	  <option>editor</option> variable.</para>
 +      </note>
 +
 +      <para>In order 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; and the
 +	mail can be written.  Once the contents of the mail are
 +	complete, save and quit from <command>vi</command> at which
 +	point <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" format="PNG">
 +        </imageobject>
 +      </mediaobject>
 +
 +      <para><application>mutt</application> also contains extensive
 +	help, which can be accessed from most of the menus by pressing
 +	the <keycap>?</keycap> key.  The top line also displays the
 +	keyboard shortcuts where appropriate.</para>
 +    </sect2>
 +
 +    <sect2 id="pine-command">
 +      <title>pine</title>
 +
 +      <para><application>pine</application> is aimed at beginner
 +        users, but also includes some advanced features.</para>
 +      <warning>
 +	<para>The pine software 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. All such KNOWN
 +	  problems have been fixed, but the pine code is written in a
 +	  very insecure style and the FreeBSD Security Officer believes
 +	  there are likely to be other undiscovered vulnerabilities.  
 +	  You install pine at your own risk.</para>
 +      </warning>
 +
 +      <para>The current version of <application>pine</application> may 
 +        be installed using the <filename
 +	role="package">mail/pine4</filename> port.  Once the port has
 +	installed, <application>pine</application> can be started by
 +	issuing the following command:</para>
 +
 +      <screen>&prompt.user; <userinput>pine</userinput></screen>
 +
 +      <para>The first time that <application>pine</application> is run
 +	it displays a greeting page with a brief introduction, as well
 +	as a request from the <application>pine</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>, or
 +	alternatively press <keycap>E</keycap> to exit the greeting
 +	without sending an anonymous message.  An example of the
 +	greeting page can be seen below:</para>
 +
 +      <mediaobject>
 +        <imageobject>
 +	  <imagedata fileref="mail/pine1" format="PNG">
 +        </imageobject>
 +      </mediaobject>
 +
 +      <para>Users are then presented with the main menu, which can be
 +	easily navigated using the cursor keys.  The main menu provides
 +	shortcuts for the composing new mails, browsing of mail folders,
 +	and even the administration of 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 folder opened by <application>pine</application> 
 +	is the inbox.  To view the message index, press
 +	<keycap>I</keycap>, or select the <quote>MESSAGE INDEX</quote>
 +	option as seen below:</para>
 +
 +      <mediaobject>
 +        <imageobject>
 +	  <imagedata fileref="mail/pine2" format="PNG">
 +        </imageobject>
 +      </mediaobject>
 +
 +      <para>The message index shows messages in the current folder, and
 +        can be navigated by using the cursor keys.  Highlighted messages
 +	can be read by pressing the <keycap>Enter</keycap> key.</para>
 +
 +      <mediaobject>
 +        <imageobject>
 +	  <imagedata fileref="mail/pine3" format="PNG">
 +        </imageobject>
 +      </mediaobject>
 +
 +      <para>In the screenshot below, a sample message is displayed by
 +        <application>pine</application>.  Keyboard shortcuts are
 +	displayed as a reference at the bottom of the screen.  An
 +	example of one of these shortcuts is the <keycap>r</keycap> key,
 +	which tells the <acronym>MUA</acronym> to reply to the current
 +	message being displayed.</para>
 +
 +      <mediaobject>
 +        <imageobject>
 +	  <imagedata fileref="mail/pine4" format="PNG">
 +        </imageobject>
 +      </mediaobject>
 +
 +      <para>Replying to email in <application>pine</application> is done
 +	using the <application>pico</application> editor, which is
 +	installed by default with <application>pine</application>.
 +	<application>pico</application> makes it easy to navigate around
 +	the message and is slightly more forgiving on novice users 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>pine</application> will ask for
 +	confirmation.</para>
 +
 +      <mediaobject>
 +        <imageobject>
 +	  <imagedata fileref="mail/pine5" format="PNG">
 +        </imageobject>
 +      </mediaobject>
 +
 +      <para><application>pine</application> can be customized using the
 +	<quote>SETUP</quote> option from the main menu.  Consult <ulink
 +	url="http://www.washington.edu/pine/">http://www.washington.edu/pine/</ulink>
 +	for more information on pine.</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 fetchmail</title>
 +
 +    <indexterm>
 +      <primary>Using fetchmail</primary>
 +    </indexterm>
 +
 +    <para><application>fetchmail</application> is a full-featured
 +      <acronym>IMAP</acronym> and <acronym>POP</acronym> client which
 +      allows users to automatically download mail from remote
 +      <acronym>IMAP</acronym> and <acronym>POP</acronym> servers to
 +      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, some of which include:</para>
 +
 +      <itemizedlist>
 +        <listitem>
 +	  <para>Supports <acronym>POP3</acronym>,
 +	    <acronym>APOP</acronym>, <acronym>KPOP</acronym>,
 +	    <acronym>IMAP</acronym> and even <acronym>ETRN</acronym> and
 +	    <acronym>ODMR</acronym>.</para>
 +        </listitem>
 +
 +        <listitem>
 +	  <para>Forwards 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>While it is outside the scope of this document to explain
 +	all of <application>fetchmail</application>'s features, some
 +	basic features will be explained.
 +	<application>fetchmail</application> requires a configuration
 +	file, <filename>.fetchmailrc</filename>, 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 read-only, by issuing
 +	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">my.isp.com</hostid> using a username of
 +	<username>joesoap</username> and a password of
 +	<quote>badpassword</quote>.  This example assumes that the user
 +	<username>joesoap</username> is also a user on the local
 +	system.</para>
 +
 +      <programlisting>poll my.isp.com protocol pop3 username "joesoap" password "badpassword"
 +      </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 my.isp.com proto pop3:
 +    user "joesoap", with password "badpassword", is "jsoap" here;
 +    user "andrea", with password "amliejPo";
 +poll other.provider.net proto imap:
 +    user "john", with password "tedVenturd", is "myth" here;
 +      </programlisting>
 +
 +      <para><application>fetchmail</application> can be run in daemon
 +	mode by running it with the <option>-d</option> flag, followed
 +	by the interval (in seconds) that
 +	<application>fetchmail</application> should poll servers listed
 +	in the <filename>.fetchmailrc</filename> file.  The following
 +	example would cause <application>fetchmail</application> to poll
 +	every 60 seconds:</para>
 +
 +      <screen>&prompt.user; <userinput>fetchmail -d 60</userinput></screen>
 +
 +      <para>More information on <application>fetchmail</application> can
 +	be found at <ulink
 +	url="http://www.catb.org/~esr/fetchmail/">http://www.catb.org/~esr/fetchmail/</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 procmail</title>
 +
 +    <indexterm>
 +      <primary>Using procmail</primary>
 +    </indexterm>
 +
 +    <para><application>procmail</application> is an incredibly 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 and/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 your <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 utilizing
 +      <application>procmail</application>.</para>
 +
 +      <programlisting>"|exec /usr/local/bin/procmail || exit 75"</programlisting>
 +      <para>The following section will display some basic
 +	<application>procmail</application> rules, as well as brief
 +	descriptions on what they do.  These rules, and others must be
 +	inserted into a <filename>.procmailrc</filename> file, which
 +	must reside in the home directory of the user.<para>  
 +	
 +      <para>The majority of these rules can also be found in the
 +        <quote>procmailex</quote> manual page.</para>
 +
 +      <para>Forward all mail from <quote>user@goodhost.com</quote> to an
 +        external address of <quote>goodmail@my.isp.com</quote>:</para>
 +
 +      <programlisting>:0
 +* ^From.*user@goodhost.com
 +! goodmail@my.isp.com</programlisting>
 +
 +      <para>Forward all mails shorter than 1000 bytes to an external
 +        address of <quote>goodmail@my.isp.com</quote>:</para>
 +
 +      <programlisting>:0
 +* < 1000
 +! goodmail@my.isp.com</programlisting>
 +
 +      <para>Send all mail sent to <quote>alternate@my.isp.com</quote> 
 +        into a mailbox called <filename>alternate</filename>.</para>
 +
 +      <programlisting>:0
 +* ^TOalternate@my.isp.com
 +alternate</programlisting>
 +
 +      <para>Send all mail with a subject of <quote>Spam</quote> to
 +        <filename>/dev/null</filename>.</para>
 +
 +      <programlisting>:0
 +^Subject:.*Spam
 +/dev/null</programlisting>
 +
 +      <para>A useful recipe that parses incoming &os;.org mailing lists
 +        and places each list in it's own mailbox.</para>
 +
 +      <programlisting>:0
 +* ^Sender:.owner-freebsd-\/[^@]+@FreeBSD.ORG
 +{
 +	LISTNAME=${MATCH}
 +	:0
 +	* LISTNAME??^\/[^@]+
 +	FreeBSD-${MATCH}
 +}</programlisting>
 +  </sect1>
  </chapter>
  
  <!--
 
 --fUYQa+Pmc3FrFX/N
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: attachment; filename=handbook_Makefile-patch
 
 --- Makefile.orig	Tue Mar  9 15:32:14 2004
 +++ Makefile	Tue Mar  9 15:30:44 2004
 @@ -104,6 +104,14 @@
  IMAGES_EN+= install/userconfig.scr
  IMAGES_EN+= install/userconfig2.scr
  IMAGES_EN+= install/xf86setup.scr
 +IMAGES_EN+= mail/mutt1.scr
 +IMAGES_EN+= mail/mutt2.scr
 +IMAGES_EN+= mail/mutt3.scr
 +IMAGES_EN+= mail/pine1.scr
 +IMAGES_EN+= mail/pine2.scr
 +IMAGES_EN+= mail/pine3.scr
 +IMAGES_EN+= mail/pine4.scr
 +IMAGES_EN+= mail/pine5.scr
  
  IMAGES_EN+= install/example-dir1.eps
  IMAGES_EN+= install/example-dir2.eps
 
 --fUYQa+Pmc3FrFX/N--
State-Changed-From-To: open->closed 
State-Changed-By: trhodes 
State-Changed-When: Mon Mar 15 23:30:18 PST 2004 
State-Changed-Why:  
Committed with minor alterations, thanks for the submission Marc! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=36727 
>Unformatted:
