Attachment 20856 Details for Bug 36727 – chapter.sgml-patch

chapter.sgml-patch

chapter.sgml-patch (text/plain; charset=us-ascii), 33.56 KB, created by Marc Silver on 2004-03-11 09:04:56 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Marc Silver

Created: 2004-03-11 09:04:56 UTC

Size: 33.56 KB

patch

obsolete

>--- 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>
> 
> <!--

Actions: View

Attachments on bug 36727: 20856 | 20857