From murray@freebsdmall.com Wed Apr 3 22:29:54 2002 Return-Path: Received: from mail.freebsdmall.com (www.freebsdmall.com [66.220.2.194]) by hub.freebsd.org (Postfix) with ESMTP id 8570737B417 for ; 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 Reply-To: Murray Stokely 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 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 To: Ceri Davies 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 >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 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 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 @@ Electronic Mail, better known as email, is one of the most widely used forms of communication today. This chapter provides - a basic introduction to running a mail server on FreeBSD. - 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 . + 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 . After reading this chapter, you will know: @@ -52,6 +53,11 @@ + An understanding of the difference between remote and + local mailboxes. + + + How to block spammers from illegally using your mail server as a relay. @@ -80,6 +86,22 @@ How to configure SMTP Authentication for added security. + + + How to install and use a Mail User Agent, such as + mutt to send and receive email. + + + + + How to download your mail from a remote POP + or IMAP server. + + + + How to automatically apply filters and rules to incoming + email. + Before reading this chapter, you should: @@ -110,25 +132,25 @@ There are five major parts involved in an email exchange. They are: the user program, the server daemon, DNS, a POP or - IMAP daemon, and of course, the + linkend="mail-dns">DNS, a + remote or local mailbox, and of course, the mailhost itself. The User Program This includes command line programs such as - mutt, pine, - elm, and - mail, and GUI programs such as + mutt, + pine, elm, + and mail, and GUI programs such as balsa, xfmail to name a few, and something more sophisticated like a WWW browser. These - programs simply pass off the email transactions to the local mailhost, either by - calling one of the server daemons - available or delivering it over TCP. - + programs simply pass off the email transactions to the local + mailhost, either + by calling one of the server + daemons available or delivering it over TCP. + Mailhost Server Daemon @@ -157,10 +179,13 @@ the most widely used. The server daemon usually has two functions—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 daemon - for that. + after receiving incoming mail and delivers outgoing mail. It is + not responsible for allowing you to collect mail using protocols + such as POP or IMAP to + read your email, nor does it allow connecting to local + mbox or Maildir mailboxes. You may require + an additional daemon for + that. Be aware that some older versions of sendmail have some serious security @@ -194,29 +219,117 @@ 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. - - POP - IMAP - If you want to run a POP or IMAP server, there are two things - you need to do: - - - - Get a POP or IMAP daemon from the ports collection and install - it on your system. - - - - Modify /etc/inetd.conf to load the - POP or IMAP server. - - + will collect mail sent to you and store it for reading or pickup + in either mbox or Maildir format, depending + on your configuration. Mail can then be remotely accessed using + either POP or IMAP, 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 + POP or IMAP server. + + + Accessing remote mailboxes using POP and IMAP + + POP + IMAP + In order to access mailboxes remotely, you are required to + run a POP or IMAP + server. This allows users to connect to their mailboxes from + remote locations with ease. Though both + POP and IMAP allow users + to remotely access mailboxes, IMAP offers + many advantages, some of which are: + + + + IMAP can store messages on a remote + server as well as fetch them. + + + + IMAP supports concurrent updates. + + + + IMAP 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. + + + + + In order to install a POP or + IMAP server, the following steps should be + performed: + + + + Decide on an IMAP or + POP server that best suits your needs. + The following POP and + IMAP servers are well known and serve + as some good examples: + + + + qpopper + + + + teapop + + + + imap-uw + + + + courier-imap + + + + + + + Install the POP or + IMAP daemon of your choosing from the + ports + collection. + + + + Where required, modify /etc/inetd.conf + to load the POP or + IMAP server. + + + + + It should be noted that both POP and + IMAP 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 &os; + handbook for more information. + + + + + Accessing local mailboxes + + Mailboxes may be accessed locally by directly utilizing + MUA's on the server on which the mailbox + resides. This can be done using applications such as + mutt or mail. + + @@ -247,8 +360,8 @@ &man.sendmail.8; is the default Mail Transfer Agent (MTA) in FreeBSD. sendmail'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 (MUA) and deliver it + to the appropriate mailer as defined by its configuration file. sendmail can also accept network connections and deliver mail to local mailboxes or deliver it to another program. @@ -914,14 +1027,14 @@ In default FreeBSD installations, sendmail 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 - MAILER-DAEMON with a - 5.7 Relaying Denied error - message. + a POP 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 + MAILER-DAEMON with a + 5.7 Relaying Denied error + message. 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 as a mail relay. In order to retrieve mail from your mailbox, you must - install a retrieval agent. The fetchmail utility - is a good choice as it supports many different protocols. - This program is available as a package or from the ports - collection (mail/fetchmail). - 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 + fetchmail utility is a good choice as + it supports many different protocols. This program is available + as a package or from the ports collection (mail/fetchmail). Usually, your ISP will + provide POP. If you are using user PPP, you can + automatically fetch your mail when an Internet connection is + established with the following entry in /etc/ppp/ppp.linkup: MYADDR: @@ -1574,6 +1688,542 @@ + + + + + Marc + Silver + Contributed by + + + + Mail User Agents + + + Mail User Agents + + + A Mail User Agent (MUA) is an application + that is used to send and receive email. Furthermore, as email + evolves and becomes more complex, + MUA'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 FreeBSD Ports Collection. Users may choose + between graphical email clients such as + evolution or + balsa, or console based clients such as + mutt, pine + or mail. + + + mail + + &man.mail.1; is the default Mail User Agent + (MUA) in &os;. mail is a + console based MUA 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. + + Although mail does not natively support + interaction with POP or + IMAP servers, these mailboxes may be + downloaded to local mbox files using an + application such as fetchmail which + will be discussed later in this chapter. + + In order to send and receive email, simply invoke the + mail command as per the following + example: + + &prompt.user; mail + + The contents of the user mailbox in + /var/mail/ are + automatically read by the mail 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: + + 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" + + Messages can now be read by using the t + mail command, suffixed by the message number + that should be displayed. In this example, we will read the + first email: + + & 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. + + As can be seen in the example above, the t + command causes the message to be displayed with full headers. + To display the list of messages again, the h + mail command should be used. + + If the email requires a response, you may use + mail to reply, by using either the + R or r mail + commands. The R command instructs + mail to reply only to the sender of the + email, while r 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 + . on a new line. An example can be seen + below: + + & R 1 To: root@localhost Subject: Re: test + +Thank you, I did get your email. +. +EOT + + In order to send new email, the m + mail command should be used, followed by the + recipient email address. Multiple recipients may also be + specified by seperating each address with the , + delimiter. The subject of the message may then be entered, + followed by the message contents. The end of the message should + be specified by putting a single . on a new + line. + + & mail root@localhost +Subject: I mastered mail + +Now I can send and recieve email using mail... :) +. +EOT + + While inside the mail application, the + ? command may be used to display help at any + time. The &man.mail.1; manual page should also be consulted for + more help with mail. + + + As previously mentioned, the &man.mail.1; command was not + originally designed to handle attachments, and thus deals with + them very poorly. Newer MUA's, such as + mutt handle attachments in a much + more intelligent way, but should you still wish to use the + mail command, the converters/mpack port may be of + considerable use. + + + + + mutt + + mutt is a small, but very + powerful Mail User Agent, with excellent features, + just some of which include: + + + + The ability to thread messages. + + + + PGP support for digital signing and encryption of email. + + + + MIME Support. + + + + Maildir Support. + + + + Highly customizable. + + + + All of these features, and more, help to make mutt one of + the most advanced mail user agents available. See http://www.mutt.org for more + information on mutt. + + The stable version of mutt may be + installed using the mail/mutt port, while the current + development verion may be installed via the mail/mutt-devel port. After the port + has been installed, mutt can be + started by issuing the following command: + + &prompt.user; mutt + + mutt will automatically read the + contents of the user mailbox in /var/mail and display the contents + if applicable. If no mails are found in the user mailbox, then + mutt will wait for commands from the + user. The example below shows mutt + displaying a list of messages. + + + + + + + + In order to read an email, simply select it using the cursor + keys, and press the Enter key. An example of + mutt displaying email can be seen + below: + + + + + + + + As with the &man.mail.1; command, + mutt 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 + r keyboard shortcut. To send a group reply, + which will be sent to the original sender as well as all the + message recipients, use the g shortcut. + + + mutt 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 .muttrc and setting the + variable. + + + In order to compose a new mail message, press + m. After a valid subject has been given, + mutt will start &man.vi.1; and the + mail can be written. Once the contents of the mail are + complete, save and quit from vi at which + point mutt will resume, displaying a + summary screen of the mail that is to be delivered. In order to + send the mail, press y. An example of the + summary screen can be seen below: + + + + + + + + mutt also contains extensive + help, which can be accessed from most of the menus by pressing + the ? key. The top line also displays the + keyboard shortcuts where appropriate. + + + + pine + + pine is aimed at beginner + users, but also includes some advanced features. + + 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. + + + The current version of pine may + be installed using the mail/pine4 port. Once the port has + installed, pine can be started by + issuing the following command: + + &prompt.user; pine + + The first time that pine is run + it displays a greeting page with a brief introduction, as well + as a request from the pine + development team to send an anonymous email message allowing + them to judge how many users are using their client. To send + this anonymous message, press Enter, or + alternatively press E to exit the greeting + without sending an anonymous message. An example of the + greeting page can be seen below: + + + + + + + + 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. + + The default folder opened by pine + is the inbox. To view the message index, press + I, or select the MESSAGE INDEX + option as seen below: + + + + + + + + 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 Enter key. + + + + + + + + In the screenshot below, a sample message is displayed by + pine. Keyboard shortcuts are + displayed as a reference at the bottom of the screen. An + example of one of these shortcuts is the r key, + which tells the MUA to reply to the current + message being displayed. + + + + + + + + Replying to email in pine is done + using the pico editor, which is + installed by default with pine. + pico 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 CtrlX. + pine will ask for + confirmation. + + + + + + + + pine can be customized using the + SETUP option from the main menu. Consult http://www.washington.edu/pine/ + for more information on pine. + + + + + + + + + Marc + Silver + Contributed by + + + + Using fetchmail + + + Using fetchmail + + + fetchmail is a full-featured + IMAP and POP client which + allows users to automatically download mail from remote + IMAP and POP servers to + local mailboxes, where it can be accessed more easily. + fetchmail can be installed using the + mail/fetchmail port, and + offers various features, some of which include: + + + + Supports POP3, + APOP, KPOP, + IMAP and even ETRN and + ODMR. + + + + Forwards mail using SMTP, which + allows filtering, forwarding and aliasing to function + normally. + + + + May be run in daemon mode to check periodically for new + messages. + + + + Can retrieve multiple mailboxes and forward them, based + on configuration, to different local users. + + + + While it is outside the scope of this document to explain + all of fetchmail's features, some + basic features will be explained. + fetchmail requires a configuration + file, .fetchmailrc, 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: + + &prompt.user; chmod 600 .fetchmailrc + The following .fetchmailrc serves as an + example for downloading a single user mailbox using + POP. It tells + fetchmail to connect to my.isp.com using a username of + joesoap and a password of + badpassword. This example assumes that the user + joesoap is also a user on the local + system. + + poll my.isp.com protocol pop3 username "joesoap" password "badpassword" + + + The next example connects to multiple POP + and IMAP servers and redirects to different + local usernames where applicable. + + 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; + + + fetchmail can be run in daemon + mode by running it with the flag, followed + by the interval (in seconds) that + fetchmail should poll servers listed + in the .fetchmailrc file. The following + example would cause fetchmail to poll + every 60 seconds: + + &prompt.user; fetchmail -d 60 + + More information on fetchmail can + be found at http://www.catb.org/~esr/fetchmail/. + + + + + + + Marc + Silver + Contributed by + + + + Using procmail + + + Using procmail + + + procmail is an incredibly powerful + application used to filter incoming mail. It allows users to + define rules which can be matched to incoming mails + to perform specific functions or to reroute mail to alternative + mailboxes and/or email addresses. + procmail can be installed using the + mail/procmail port. Once + installed, it can be directly integrated into most + MTA's; consult your MTA + documentation for more information. Alternatively, + procmail can be integrated by adding + the following line to a .forward in the home + directory of the user utilizing + procmail. + + "|exec /usr/local/bin/procmail || exit 75" + The following section will display some basic + procmail rules, as well as brief + descriptions on what they do. These rules, and others must be + inserted into a .procmailrc file, which + must reside in the home directory of the user. + + The majority of these rules can also be found in the + procmailex manual page. + + Forward all mail from user@goodhost.com to an + external address of goodmail@my.isp.com: + + :0 +* ^From.*user@goodhost.com +! goodmail@my.isp.com + + Forward all mails shorter than 1000 bytes to an external + address of goodmail@my.isp.com: + + :0 +* < 1000 +! goodmail@my.isp.com + + Send all mail sent to alternate@my.isp.com + into a mailbox called alternate. + + :0 +* ^TOalternate@my.isp.com +alternate + + Send all mail with a subject of Spam to + /dev/null. + + :0 +^Subject:.*Spam +/dev/null + + A useful recipe that parses incoming &os;.org mailing lists + and places each list in it's own mailbox. + + :0 +* ^Sender:.owner-freebsd-\/[^@]+@FreeBSD.ORG +{ + LISTNAME=${MATCH} + :0 + * LISTNAME??^\/[^@]+ + FreeBSD-${MATCH} +} +