Skip Ribbon Commands
Skip to main content
Navigate Up
Sign In
Launch the Developer Dashboard

IT Help

:

KB: PineUnixEmailClientforIMAP

Pine: A UNIX email client supporting IMAP and SSL

Pine is a full-featured UNIX email and news client that runs in any character-cell terminal. The UNIX version of Pine does not have a graphical user interface but it is "screen-oriented", i.e., it uses the full terminal screen rather than just the command line. Most commands consist of a single keystroke or sometimes a CTRL key combination. The commands available at any time are displayed on the bottom two lines of the screen; if there are more than will fit, one of the commands will cycle through the other available commands. There is a UNIX man page for the pine(1) command, plus extensive, context-sensitive, built-in help once you have started a Pine session. Pine can handle some types of attachments itself, and can be configured to hand-off others to separate applications (typically a Web browser).

By default, Pine assumes your INBOX is the local UNIX mail spool and that your other mail folders are in your UNIX home directory, normally in a subdirectory named mail; however, it can also be configured to use IMAP (or POP) to access mail from one or more servers. As of version 4.21 (as installed at SLAC in June 2000), IMAP connections can be configured to use Secure Sockets Layer (SSL) to prevent passwords from appearing on the network in the clear. This means that it can now be used to connect to SLAC's Exchange mail service. This version also includes support for the Light Weight Directory Access Protocol (LDAP) and is configured to access SLAC's LDAP server to search for information about SLAC personnel. 




Configuring Pine for a new UNIX user

Pine is configured by default to read your incoming UNIX mail spool file as its primary INBOX, and to put your saved mail folders in $HOME/mail. New accounts at SLAC are created with a mail subdirectory with appropriate AFS permissions, so if you are a new SLAC user and only need to read your SLAC mail when logged into a SLAC UNIX host, you should be able to start using Pine immediately with no configuration necessary. If you sometimes need to read your SLAC mail from other systems (e.g., when logged into a CERN computer or from a Web browser) you may wish to obtain an account on SLAC's Exchange mail service and then follow the directions below to configure Pine as an Exchange client.


Converting to Pine from Elm or other mail programs

Converting to Pine from Elm and certain other email programs which save multiple mail messages to single UNIX files (e.g., the VM Emacs subsystem) is fairly straightforward, since Pine uses the same format for its "mail folders". Converting from programs like MH that save each mail message as a separate file is more difficult and is beyond the scope of this document.

In converting from another UNIX email program, there are three main issues to address: the location of the saved mail folders; INBOX management; and converting mail aliases. The remainder of this section will assume you are converting from Elm unless otherwise noted. 


Location of saved mail folders

You will need to determine the top-level directory where your saved mail folders are currently stored. In the case of Elm, the default is $HOME/Mail (note the capital 'M' in contrast to Pine's default of $HOME/mail); however, this default may have been overridden, so you might need to verify the actual location using non-mail-related commands like more(1).

Once you have found the correct directory, you can update your Pine configuration to point to it, if necessary (note that some UNIX mail programs use the same default location as Pine). However, it may be easier and less confusing in the long run to rename the existing folder to Pine's default. You might also want to leave a symbolic link from the old name, so that if you have problems during the transition you can temporarily switch back to your old mail program. Here's an annotated example of doing this, starting from a home directory containing both a Mail (Elm) and mail (Pine) subdirectory (both of these directories are automatically created for new user accounts at SLAC):

   ljm@flora01 > cd                <-- Get to your home directory
   ljm@flora01 > ls -A mail        <-- Verify that Pine directory
                                       has not yet been used
   ljm@flora01 > rmdir mail        <-- Remove empty Pine directory
   ljm@flora01 > mv Mail mail      <-- Rename Elm directory to Pine default
   ljm@flora01 > ln -s mail Mail   <-- Create symlink to Pine directory for Elm
   ljm@flora01 > ls -ld mail Mail  <-- Check result:
   lrwxr-xr-x   1 ljm      sf             4 Jun 15 13:51 Mail -> mail
   drwx------   2 ljm      sf          2048 Jun 15 13:49 mail
Note the second step: if your $HOME/mail directory is not empty you will have to decide what to do with its contents before proceeding.


INBOX management

Incoming UNIX mail is normally delivered by SLAC's mail infrastructure to your mail spool file (/var/spool/mail/$USER), and most UNIX mail programs, including Pine and Elm, know how to find and read this file. However, there are a variety of different methods for managing it, so sometimes when alternating between different email programs your incoming mail may seem to disappear. If you are careful to run only one email program at a time, you'll probably find that it has not really been deleted but has simply been copied from your mail spool into a private mail folder; a couple of likely places to look are $HOME/mbox and $HOME/Mail/received. It is probably not a good idea, however, to run two different mail programs (or even two instances of the same program, especially if they are running on different machines) at the same time.

If you do somehow manage to lose or corrupt your mail spool, hope is not lost! The file server on which the mail spool is stored keeps several recent snapshots of all mail spool files. To get a time-ordered list of the available copies of your mail spool, issue the command,

ls -lt /var/spool/mail/.snapshot/*/$USER

Select the most recent one before the problem occurred (the size of the file might help you determine this if you don't recall when you went wrong) and copy it back to someplace in your mail directory as a new mail folder (if you copy it over your current mail spool you may destroy more recently received mail). You should do this as soon as possible after you discover the problem, of course, since the good version will age out of the snapshots after a couple of days if you continue to receive new mail. If the worst happens and you discover the problem too late to retrieve a good snapshot, send mail to unix-admin@slac.stanford.edu to request restoration from a backup tape, specifying as nearly as you can when the problem occurred.

The remainder of this section gives an overview of how Pine and Elm manage the INBOX, but may be skipped if you are not interested in the details.

Pine normally attempts to lock your mail spool file and leaves your incoming messages there until you explicitly delete them or save them to a different folder; however, it also can be configured to automatically copy incoming messages elsewhere under certain conditions. Getting different programs to agree on a robust and reliable file locking protocol in a networked environment can be difficult, however, so for extra insurance Pine can also be configured to reduce the window for lock contention by periodically copying new incoming messages from your mail spool file to a private file, mbox, in your home directory; it then treats this file as the INBOX. This feature is enabled by simply creating an empty $HOME/mbox file.

Elm makes a private copy of your mail spool in a temporary location (/tmp/mbox.$USER) while it's running and updates it periodically during your session. When you're ready to exit Elm, it asks "Keep unread messages in incoming mailbox?" If you respond 'y', it resynchronizes the temporary and spool copies and puts the result back into you mail spool. If you instead respond 'n', it appends everything left in the temporary file to your "received" mail box and clears your mail spool.


Converting Elm Mail Aliases

There is a small utility that can convert your Elm mail aliases to a Pine addressbook. It can be found at /afs/slac/package/pine/elm-to-pine; you can get help with the syntax via the -h option:

ljm@flora06 > /afs/slac/package/pine/elm-to-pine -h
Usage e.g.
elm-to-pine ~/.elm/aliases.text >~/.addressbook

Option:
-s Create a single address for multiple nicknames by making
additional nicknames point back to the first one.

Note that you must enter the full path name of the command and that the output goes to STDOUT and must be redirected to a file via the '>' shell metacharacter. 


Configuring Pine as a SLAC Exchange client

This section assumes you have previously used Pine (or another UNIX mail program like Elm) and so you already have some mail saved in mail folders in your UNIX home directory. We will therefore add your Exchange folders as a second folder collection rather than immediately replacing your UNIX folders with Exchange folders. If you eventually import all your existing mail folders into Exchange (or simply discard them once they've become obsolete), you can delete your UNIX folder collection at that time. If you've never used UNIX mail before and have no existing folder, you can still follow this procedure and then immediately delete the UNIX folder collection afterwards.

We will also assume that your UNIX INBOX is currently empty and that you have created a .forward file and updated your mailrouter entry to direct all future email to your Exchange account. If you need continuing access to your old UNIX INBOX, you should continue with the section, Configuring Additional INBOXes or Folder Collections, when you have finished here.

  • Before beginning, you'll need an account on SLAC's Exchange mail service. If you don't already have one, follow the Instructions for SLAC Computer Account Requests or pick up a form at the SCS Help Desk in the Computer Building.
  • SLAC's Exchange IMAP mail service is now served from a single front-end server called: email.slac.stanford.edu You will need to substitute email for exchange in the examples below.
  • Go to Pine's MAIN MENU. If this is the first time you've used Pine, you may want to spend a few minutes familiarizing yourself with the Pine environment by reading the initial greeting message and some of the built-in help screens. When you are ready to proceed, you should be able to get to the MAIN MENU from most Pine screens by pressing 'M'. You should see something like this: 


pine_main.gif


First, we will add a folder collection on your Exchange server. From the MAIN MENU, press 'S' (Setup) followed by 'L' to get to the SETUP COLLECTION LIST:



pine_colllist.gif


A new pine user will see two collections, one for mail and one for news. Press 'A' to add a new collection: 


pine_colladd1.gif


You can move between the four fields of this screen using the up and down arrow keys, and obtain help for the current field by typing CTRL-G while it is highlighted. Enter a NickName, perhaps "ExchangeMail", to identify this folder collection in the list of collections. Set the Server field to

email.slac.stanford.edu/ssl/user=<your-userid>

substituting your own userid for "<your-userid>". A few users have Exchange mailbox names that are different from their Windows userid. If you're in this group, you will need to enter something like "slac\<your-userid>\<your-mailbox-name>" following the "user=".

You can leave the Path and View fields empty. Press CTRL-X to exit and save your changes. Before exiting, Pine will attempt to login to the Exchange server and prompt you for your password:


pine_colladd2.gif



(NB: We sometimes use aliases to simplify management of the various Exchange servers and when we do, the login prompt message may display a different host name for the server. However, you should always use the front-end server name email.slac.stanford.edu when configuring Pine.) Enter your password (which should not be displayed). If the login is successful, you will then be prompted, 'Exit and save changes?' Press 'Y' and you will be returned to the SETUP COLLECTION LIST. 


pine_colllist2.gif


With the new collection selected, you can use the '$' (Shuffle) command to move it to the top of the list. Press '$' followed by 'U' to move your new ExchangeMail folder collection above the News collection; then repeat to move it above your Mail collection.

To avoid confusion, you might want to change the NickName for your local folder collection, e.g., to 'UnixMail'. Select the 'Mail' collection and press 'C' (Change), then modify the NickName field. Type CTRL-X to exit and save: 



pine_colledit1.gif


Respond 'Y' and you will return to the SETUP COLLECTION LIST screen. 


pine_colllist3.gif


Next, you must change your default INBOX to the Exchange server (if you still need access to your old UNIX INBOX, you may want to continue with the section, Configuring Additional INBOXes or Folder Collections, when you have finished here). Press 'E' to exit the SETUP COLLECTION LIST screen and return to the MAIN MENU, then press 'S' (Setup) followed by 'C' to get to the SETUP CONFIGURATION screen:



pine_config1.gif


  • Use the arrow keys to select the inbox-path field and press 'C' (Change) to edit it. Type in,

    {email.slac.stanford.edu/ssl/user=<your-userid>}INBOX

    again changing "<your-userid>" to your own userid (or to "slac\<your-userid>\<your-mailbox-name>"). Note that the braces ("{}") are required.

    Check also that the user-domain field is set properly so that the Mailrouter database is checked to resolve the email address:

    user-domain=slac.stanford.edu

  • Press 'E' to exit the SETUP CONFIGURATION screen and answer 'Y' (Yes) to the 'Commit changes?' prompt: 


pine_config2.gif


  • You will then be returned to the MAIN MENU.

  • For the INBOX change to take effect, you must quit and then restart Pine. Press 'Q' to quit and respond to the 'Y' to the 'Really quit Pine?' prompt. When you restart Pine, you will be immediately prompted for your password to login to the Exchange server:


pine_main.gif



Once you are logged in, you can press 'L' to view your COLLECTION LIST which should now look something like this: 



pine_colllist4.gif


Press '>' ([View Cltn]) to view the current collection, which should look something like this:

pine_mailcoll.gif


Tips for Exchange users

Here are some additional suggestions for using Pine as an Exchange client.


    Error Messages

    Unexpected disconnections may occur from the IMAP server with the following message: Server Unavailable, 15. The possible workarounds are: Reduce the number of messages in your Inbox to less than 2000 items; Avoid using multiple IMAP clients connecting to the server at the same time; and Disable any client-side filters.


    Folders and directories in Exchange

    In Pine terminology, a folder collection consists of mail folders, containing individual mail messages, and mail directories, containing mail folders and other mail directories. Pine normally distinguishes these two kinds of mail storage nodes by appending a slash, "/", to directory names. However, some mail servers, including Exchange, allow the user to store mail messages in intermediate, or directory, nodes as well as in the end-point, or folder, nodes. Pine handles such servers by associating with each directory a folder of the same name.

    There are two configuration options which control how you interact with these folder/directory pairs. When set, the separate-folder-and-directory-entries option causes the name of each such pair to appear twice in a FOLDER LIST screen, once with a trailing "/" (for the directory) and once without (for the folder). When this option is not set, Pine appends "[/]" to each name, to indicate that it may be interpreted either as a directory or as a folder, depending on the command used. For example, to see the directories and folders at the next level of the hierarchy, you would use the ">" (View Dir) command, while to see any messages stored in the associated folder, you would use the "V" (View Folder) command.

    With separate-folder-and-directory-entries set, Pine's behavior is essentially the same for both UNIX and Exchange folder collections, except that virtually all of the entries in the latter will be doubled. The second option, quell-empty-directories, can help reduce this clutter: enabling this option will suppress the empty directories corresponding to (non-empty) folders. Unfortunately, there is no corresponding option to suppress empty folders corresponding to non-empty directories, so you will still see a number of folder/directory pairs in the FOLDER LIST screens.

    Most Pine/Exchange users will probably find it more natural to keep the folder and directory entries separate, despite the duplicate entries in the FOLDER LIST screen. Moreover, there appear to be some glitches in Pine's behavior that can be avoided by enabling this option. For example, several people have noticed that Pine has trouble creating a sent-mail folder the first time they try to send mail after switching to the Exchange service unless this option is set.

    Enabling the quell-empty-directories option has one somewhat surprising side effect. In a FOLDER LIST screen, the 'A' (Add) command will still offer the option of adding a directory instead of a folder; however, the directory will be immediately removed, leaving only the folder. The work-around is to specify both a new directory and a new folder within that directory. For example, to add a directory named "foo/" to your current FOLDER LIST and also create a folder named "bar" within that directory, press 'A' (Add) and then type "foo/bar" at the "Folder name to add :" prompt. 


      [Beginning on 25 Oct 2000, the separate-folder-and-directory-entries
      and quell-empty-directories options will be enabled by default at SLAC.


        Default folders

        Pine makes use of several default mail folders, such as sent-mail , postponed-msgs, etc. These folders are located by default at the top level of your first folder collection; however, you can also configure Pine to put them somewhere else. For example, to tell Pine to always store your postponed messages in your UnixMail collection, go to the SETUP CONFIGURATION screen and set your postponed-folder to ~/mail/postponed-msgs.

        Arrival Order

        In Pine, sorting messages by "Arrival" (or "Reverse Arrival") really means no sorting at all (note that "Arrival" is Pine's default sort order). This makes sense in UNIX mail folders which are actually flat files with new messages appended at the end. However, Exchange stores messages in a database and, apparently, does not guarantee the order in which individual messages are returned to a client program. Thus, if you use Pine as an Exchange client, you may want to change the sort-key to something other than "Arrival" or "Reverse Arrival" to get a consistent index of messages in your folders (for example, you might want to try "Date" or "Reverse Date").

      Configuring additional INBOXes or folder collections

      If you have additional email accounts on other servers (for example, a Leland account on campus or a POP account from a commercial Internet Service Provider), you can configure Pine to access them as well. If you have not yet moved all your email from your UNIX INBOX into other folders, you may want to add it as an additional INBOX as well.
      • Pine handles the case of multiple INBOXes somewhat differently: it collects all the INBOXes into a special "Incoming-Folders" collection. To enable this, go to the MAIN MENU and press 'S' followed by 'C' to get to the SETUP CONFIGURATION screen. Scroll down a page or two to the "[ Folder Preferences ]" section and select the "enable-incoming-folders" option, then use the 'X' key to toggle this option on: 


      pine_folder_prefs.gif

      • Press 'E' to exit this screen, respond 'Y' to the 'Commit changes?' prompt and then press 'Q' to quit Pine so that the change can take effect.

      • Restart Pine, login to your Exchange server again, and go to the Incoming-folders collection to add the INBOX for an additional mail server: 



      pine_incoming1.gif


      Press 'A' to add an Incoming Message Folder (or INBOX) and answer the prompts for the name of the server, the name of the specific folder on that server (INBOX will usually select the correct default) and, optionally, a nickname for this INBOX. You will be prompted for the userid and password and an attempt will be made to login . If it succeeds, the additional INBOX will be added to your Incoming-Folder collection.

      If you want to add your UNIX INBOX to your "Incoming-Folders" collection, press ENTER when prompted for the server and then type in "/var/spool/mail/$USER" when prompted for the folder name. The nickname for your primary INBOX is always "INBOX", so you should choose something distinct, e.g., "OLD_INBOX".

      If the additional server supports IMAP rather than POP, you may also want to add an additional collection of stored mail folders. From the MAIN MENU, press 'S' followed by 'L' to get to the SETUP COLLECTION LIST screen and then press 'A' to add a new collection. The process is similar to that described above for adding the Exchange collection.


      Other Configuration Options

        If you receive annoying "spam" (unsolicited bulk email) you may want the SLAC postmasters to try to block it. To request this, you should forward a copy of the spam to postmaster@slac.stanford.edu with the mail headers fully expanded. In Pine, this require enabling the "enable-full-header-cmd" option. From the MAIN MENU, press 'S' followed by 'C' and scroll down to the "[Advanced Command Preferences ]" section of the SETUP CONFIGURATION screen. Select the "enable-full-header-cmd" option, use the 'X' key to toggle it on and press 'E' to exit:



      pine_fullhdr.gif


      Respond 'Y'. If you now go to a mail folder, look at a mail item and use the 'O' command to cycle through the command menus at the bottom of the screen, you'll see that an 'H HdrMode' command has been added: 

       


      pine_hdrmode0.gif

      Pressing 'H' will now toggle between the above minimal headers view and the full headers view needed by the postmaster to trace back to the source of a spam mail item: 


      pine_hdrmode1.gif