.\" README.POP -  -*- Indented-Text -*-
.\" Last Edited: Mon Feb 17 18:40:50 1997 by fuku (FUKUSHIMA Osamu) on psyche

How to configure cmail to use Post Office Protocol (POP)

-----------------------------------------------------------------------
* Abstract
-----------------------------------------------------------------------

This document explains required cmail configuration in order to read
email messages from a mail server using POP (Post Office Protocol).

    * Required environment
    * Checking POP account
    * Configuring cmail
    * Trouble shooting
    * Compiling movemail

-----------------------------------------------------------------------
* Required environment
-----------------------------------------------------------------------

In order to read Email message via POP, a movemail configured
for POP must be installed.

[ GNU Emacs 19.29 and later ]

For GNU Emacs 19.29 and later version and Mule based on these Emacs
version, the movemail program should be POP capable if emacs is
configured with --with-pop when compilation.

[ GNU Emacs version before 19.29 ]

For GNU Emacs version before 19.29 or Mule-2.3 based on 19.28, the
following is mandatory.

  * Your mail server is RPOP compliant.
  * The movemail program is compiled with -DMAIL_USE_POP option.
  * The movemail program is a SUID program.

If these conditions are not met, either change the environment
to satisfy the conditions, or obtain the source code of emacs 19.3x
or later and compile/install the movemail attached with it. Please
refer to the later section, "Compiling movemail."

-----------------------------------------------------------------------
* Checking POP account
-----------------------------------------------------------------------

First, make sure you can log onto your mail server with your POP
account using POP3 port (110) via telnet.

Depending on your POP server, response messages the server returns may
be slightly different, however, you should be able to confirm your POP
conenectivity by the following procedure.

>   (example) % telnet pop.your.host.name 110
    Trying 100.100.100.1..
    Connected to mailhost.somedomain.
    Escape character is '^]'.
    +OK QPOP (version 2.2) at mailhost.somedomain starting.
>   user fuku                   <-- your POP account
    +OK Password required for fuku.
    pass XXXXXXXX               <-- POP POP password
>   +OK fuku has 10 messages (41420 octets).
>   quit
    (example) %

-----------------------------------------------------------------------
* Configuring cmail
-----------------------------------------------------------------------

In addition to typical cmail configuration, please add the following.

  (setenv "MAILHOST" "your.pop.host.name")
  (setq cmail-spool-directory "po:youraccount")

As described in the previous section, if the movemail program is
properly installed, by just invoking cmail, movemail will connect to
the mail server via POP.

It will prompt for password in the mini-buffer, so enter your
password.  After your account and password are authenticated, movemail
will retrieve email messages, and cmail receives and displays them.

Multiple POP servers can be accessed, by specifying a list to
cmail-mail-spools.

The following is the format of the list.

	(setq cmail-mail-spools
	      '(("po:account" "pop-server-name" "movemail-options" "password")
	        ...))

Environment variables MAILHOST and MOVEMAIL are set to pop-server-name
and move-mail-options respectively. In order for this to work
properly, your movemail program is required to understand the
environment variables.


-----------------------------------------------------------------------
* trouble shooting
-----------------------------------------------------------------------

(Q1) Messages seem to be received by the POP server, they cannot
     be retrieved when cmail is started.

(A1) There are several possible causes.

1. movemail does not support POP.

       -> [Solution 1] Install POP supported movemail program.
                   (Please refer to "Compiling movemail")

2. movemail only supports RPOP (e.g. one comes with Mule-2.3)
   and it is not setuid'ed as root.

       -> [Solution 1] Set movemail setuid bit.
                   (You have to be able to become root)
       or

       -> [Solution 2] Install movemail comes with emacs-19.3x or later.
                   (You do not need be root. Please refer to
                   "Compiling movemail")

3. movemail olny supports RPOP (e.g. one comes with Mule-2.3)
   and your server does not support RPOP.

       -> [Solution 2] Install movemail comes with emacs-19.3x or later.
                   (You do not need be root. Please refer to
                   "Compiling movemail")

Since you can workaround any of these cases by installing movemail
come with emacs-19.3x or later, it is recommended to try this way
first.

(Q2) The above workaround has been done, but still doesn't work.

(A2) It is possilbe that an old movemail program is left somewhere
     in your system and your new version of movemail is not executed.
     Use which command to check which movemail program was used.

-----------------------------------------------------------------------
* Compiling movemail
-----------------------------------------------------------------------

In case you need to recompile movemail program, the following
illustrates the compilation procedure. First, obtain source
distribution of emacs 19.3x or later, and unarchive it.


    (example) % gzip -d < emacs-19.3x.tar.gz | tar xvf -
    (example) % cd ./emacs-19.3x

In the directory where you unarchived, read etc/MACHINES and confirm
the machine name of the OS you use, execute the following:

    (example) % ./configure "machine" --with-pop

(If you want to compile emacs as well, add necessary options at this
point.) Then, move to lib-src directory, and type:

    (example) % cd ./lib-src
    (example) % make movemail

to compile the movemail compile program. After successfully compiled,
copy the new movemail program to somewhere in your executable search
paths, and check if the movemail is the one executed.

    (example) % which movemail

If you are the administrator of your system, you can install movemail
to directly the emacs exec-path.
