PINE-EMSD

Contents

Chapter 1
MAIL User Agent

1.1 MAIL User Agent - PINE

PINE is a publicly available user agent. It has been slightly modified to send messages to disk to be picked up by the LSM-User-Daemon and to receive messages from disk written by the LSM-User-Daemon.

1.2 MAIL User Agent - PC-Pine

PINE is a publicly available user agent. It has been slightly modified to send messages to disk to be picked up by the LSM-User-Daemon and to receive messages from disk written by the LSM-User-Daemon.

1.2.1 PC-Pine for Microsoft Windows

In order to facilitate basic testing, or simply to use the standard version of PC-Pine, users may wish to obtain the PC-Pine binary distribution. Connect to ftp.neda.com and download the file /pine/pcpine/pcpine_w.zip. Then, uncompress the file and follow the instructions contained therein for installation on your system. Technical notes, source code, and man pages are also contained in this download. The following sections are intended to further illuminate some of the crucial details in the installation process.

Network Driver Installation

Neda Communications has tested PC-Pine for Windows with FTP Software, Inc’s. PC/TCP network stack and the NDIS driver. We recommend that PC-Pine users install the identical network software at their sites.

IMAP Server Setup

PC-Pine requires the presence of an imap host on the user’s mail server in order to successfully retrieve mail from the server. Your Unix system administrator must perform this installation.

PINERC Configuration File

The following sample PINERC file indicates the crucial Pine configuration parameters and their syntax.

See the Pine installation notes for further details and for information on where to install the PINERC file.

1.2.2 PC-Pine for MS-DOS Using FTP Software Inc’s. PC/TCP

Four different PC-Pine executables for MS-DOS also exist, each compiled to run with a different TCP/IP network stack. This section outlines the steps required to install the version that is compatible with FTP Software, Inc’s. PC/TCP stack.

The DOS binary may be downloaded from the same FTP site as the Windows version. Connect to ftp.neda.com, get the file /pine/pcpine/pcpine_f.zip, and uncompress it.

All of the information in the section on installing PC-Pine for Microsoft Windows applies to the MS-DOS version as well. However, there are a number of additional steps required for proper MS-DOS installation. These are described below.

PC/TCP Configuration

The file pctcp.ini is created on the user’s PC as part of the normal PC/TCP installation process. Depending on your network configuration, it may be necessary to add the following line under the [pctcp kernel] section:

kernel-does-dns=yes

See the PC/TCP documentation for further details on this.

PC Memory Availability

PC-Pine is very unforgiving of memory shortages. In order to run PC-Pine you should have at least 490K of free memory.

1.2.3 Building PC-Pine

In order to implement the LSM modifications to Pine, it is necessary to rebuild Pine from the publicly available source, incorporating a number of proprietary changes to some of the source files. This section outlines the steps required to first build the standard version of PC-Pine, as a check on the user’s build environment, and then the LSM version.

Source Code

The source code may be downloaded from the Neda Communications FTP site. Connect to ftp.neda.com. and download the file /pine/pine3.91.tar.Z. Move the file to a working directory, uncompress, and then un-tar the file. A number of subdirectories will be copied from the tar file to the working directory. We are interested only in the following:

In order to build PC-Pine the c-client directory must be moved so that it is at the same level as the pine and pico directories.

Of course, this discussion assumes that you are using Unix to download, uncompress, and un-tar the source. Once the source is expanded to clear text you must copy the pine, pico, and c-client directories to a PC (or to a PC mounted network drive) for compilation.

Development Environment

Microsoft C++ Compiler

PC-Pine is compiled using Microsoft’s C++ compiler, version 8.0. This compiler is shipped as part of the Visual C++ 2.0 release, however, the compilation is performed from the DOS command line under nmake. Follow the usual compiler installation procedures.

FTP Software, Inc. Software Developer’s Kit

PC-Pine for Windows requires the presence of a Winsock network interface. (See the Network Driver Installation section for further details on this.) Neda Communications uses FTP Software, Inc’s. Software Developers Kit version 2.3 for Microsoft C to implement this interface. Copy the files winsock.lib and winsock.h from the SDK distribution to the lib and include directories, respectively, associated with the Microsoft C compiler.

Building the Standard PC-Pine for Windows

PC-Pine has three major components: pico, the screen editor; c-client, which contains the imap interface; and pine, which contains the top-level functions. The pico and c-client object files, compiled in their respective directories, are merged into libraries which are then used to build the pine executable. Therefore, pico and c-client must be built first, and then pine.

The general procedure for building is the same for all three components:

• Change directory to the appropriate path.
• Run nmake with no arguments.

However, several minor changes must be made prior to running nmake. These changes are detailed below.

Pico Source Modifications

• Delete osdep.c and osdep.h if they already exist.
• Copy makefile.win to makefile

C-client Source Modifications

• Copy makefile.dos to makefile
• Edit makefile, setting the OS variable to wsk, i.e. OS=wsk
• Convert all batch files in the directory from Unix format to DOS format, i.e. unix2dos file1.bat file1.bat

Pine Source Modification

• Copy makefile.win to makefile
• Create the file ./osdep/coredump with the following contents:
  #include <stdlib.h>  
  void coredump( void )  
  {abort();}

Building the LSM Version of PC-Pine for Windows

The changes required to build the LSM version of PC-Pine for Windows are isolated to a small number of files in the pine and c-client directories.

To build the LSM version, first create a new directory at the same level as the pine directory called pine_lsm. Then, copy all of the files from pine to pine_lsm.

The actual code changes themselves are too numerous to describe in detail here. Instead the user should download the affected files, overwriting the previously existing ones. To download, connect to ftp.neda.com and download the file /pine/pcpine/pine_lsm.zip. into the pine3.91 directory. Then unzip the file.

Force a rebuild of c-client and then pine by deleting all of the object files (*.obj) and running nmake in both of the directories. The final executable will have the same name as the standard version, pine.exe.
Description of LSM Pine Modifications

The difference between the standard PC-Pine and the LSM version has to do with the location to which Pine delivers outgoing messages. The standard Pine delivers outgoing messages to a remote SMTP server. The LSM version writes messages to local disk files, which are subsequently processed by the LSM-User-Daemon.

The source files that were modified in order to implement this change in functionality are pine/send.c, pine/makefile, and c-client/mail.h.

In order to enable the LSM functionality, the pinerc file must contain the following:

smtp-server=¿lsm_directory

Note the use of the right-angle-bracket (¿) preceding lsm_directory. This tells the Pine message-send routine that outbound messages are to be written to disk rather than to the remote SMTP server stream. lsm_directory specifies the directory to which the files are written and may be any valid DOS directory name, for example c:/pine.tmp. Pine assigns the actual send-file names and two distinct files are created for every sent message - a control file and a message file.

Chapter 2
Administration

2.1 Starting EMSD-Pine

To start EMSD-Pine, double-click on the EMSD-Pine icon. EMSD-Pine behaves like the standard version of Pine. For information on using the Pine user interface, refer to the Pine on-line help, or see the chapter titled Mail User Interface. Once the User Agent and EMSD-Pine started, you can send and receive EMSD email messages.

2.1.1 Sending Email Messages

You can send an email message to any valid Internet address. When you send a message using EMSD-Pine, your return mail address will be your User Agent ID at the Message Center domain.

2.1.2 Receiving Email Messages

To receive email messages using EMSD-Pine, the messages must be sent to your EMSD address. Your address is your User Agent ID at the EMSD MTS domain as assigned by the EMSD MTS administrator at setup time. For example, if your User Agent ID is 301.001, and if you are using the Neda EMSD MTS, your EMSD email address is 301.001@emsd.neda.com. Email messages sent to this address will be forwarded by the Message Center to your workstation.

2.2 pinerc.

The Setup program prompts for the information required in the pinrc. configuration file. You can modify this file manually to change the information specified during setup. An icon for pinerc. is located in the Windows UA program group.

Chapter 3
Unix User Agent

This chapter describes in detail the steps required to install, configure, run, and troubleshoot the EMSD User Agent Daemon and EMSD Mail User Interface on a Unix system.

3.1 The User Agent Daemon (UAD)

3.1.1 Installing the UAD

To begin installation of the software, type:
tar -xvf emsdUserAgentDaemon.tar

The complete list of files that are extracted from this tar file can be found in the Appendix entitled Complete List of Files. You will need to be concerned with the files in the following directories:

• ./results/systems/*/config/
• ./results/systems/*/bin/
• ./results/systems/*/log

where the asterisk (*) represents the hostname of the machine on which the software is installed.

3.1.2 Configuring the UAD

There are three steps involved in configuring the Unix UAD - modifying the initialization file, creating user mailbox files, and setting spool directory permissions.

Edit the UAD Initialization File

The configuration file ./results/systems/*/config/emsd-ua.ini contains information that is used by the UAD when it first starts. The general syntax of an INI file is described in Appendix D. The following excerpt from a working configuration file illustrates the specific grammar of the parts of the file that a system administrator will typically have to modify.

Create the subscriber mailboxes.

You can use the touch(1) utility to do this. In Figure three mailboxes were named, one for each ‘User n’. So in this case you would need to create the files 201.001, 201.002, and test3 in ./results/systems/*/spool/emsd-ua/mbox/.

Set the spool directory permissions.

Execute the command, chmod -R 777 ./results/systems/*/spool

3.1.3 Running the UAD

1. Initialize the EMSD Environment - If you haven’t done so already, go to the root EMSD directory and execute the command source sourceme.csh
2. Running the UAD - From the directory ./results/systems/*/bin, run the script runUaEmsd.sh. This script redirects UAD trace data to a file whose name is displayed just before the script completes.
3. Displaying the Trace - Use the tail(1) utility to display the trace file indicated by the shell script above. See the following section for a more detailed discussion of tracing.
4. Stopping the UAD - The shell script killAll.sh will terminate the UAD (as well as LSROS and the Message Center (MTS) if it is also running on the same machine as the UAD). Alternatively, use the showProcs.sh script to obtain the process ID of the UAD and then use the kill(1) utility to terminate the UAD.

3.1.4 Troubleshooting the UAD.

System administrators can use the UAD tracing features to help troubleshoot configuration problems. Tracing is enabled by commands in the [Trace] section of the UAD initialization file. When tracing is enabled, trace messages are logged by the UAD to stdout, which is normally redirected to a file. See ”Displaying the Trace” in the previous section for further instructions.

Table 7.1 shows the UAD trace features available and their associated mask bits. These features may be enabled from within the UAD initialization file. In the case of the above example the line
Module 1 = UA,3

commands the UAD to enable the tracing features controlled by bit zero and bit one. Referring to the appendix we see that bit zero controls the display of message flow, while bit one controls the display of initialization operations. Also note that the line
Module 2 = IMQ_,0

Explicitly turns off any Inter-module Queue (IMQ_) tracing.

3.2 The Mail User Interface - EMSD Pine

The Unix EMSD Mail User Interface is a specially modified version of the Pine mail utility found at many Unix sites. In many respects the EMSD version, named EMSD Pine, behaves in an identical manner to the standard PINE. Thus, the following sections address only the differences between the two. For all other information you should see the pine man page or the on-line help.

3.2.1 Installing the MUI

To begin installation of the software, type:

tar -xvf emsdPine.tar

This will create the following files:

• emsdpine - the executable
• dot.pinerc.emsd - a template configuration file

Set the permission bits on emsdpine to allow execution by the appropriate users, i.e. chmod 777 emsdpine

3.2.2 Configuring the MUI

Copy the template configuration file dot.pinerc.emsd from the distribution directory created above to a user’s home directory and rename it .pinerc.emsd. Edit this file. The following excerpt from a working EMSD Pine configuration file illustrates those fields that EMSD Pine users need to concern themselves with. All of the other fields behave as described in the man page or in the self-contained comments.

There is also a method of automatically generating Pine configuration files. These files can be created with the shell script ‘pine_rc.sh’. For details on how to use this script, invoke it with no arguments. A usage message will be displayed.

The purpose of this script is to make using emsdpine easier, especially when submitting to varied UAD queues. It also frees up the default .pinerc file for use with plain pine.

Using this script, the resulting ‘pinerc’ file used is named pinerc.$SUBSCRIBER and is located in $CURENVBASE/results/systems/$SYSTEM/pinerc.

3.2.3 Running the MUI

To start EMSD Pine execute the command

emsdpine -p ¡my_config_file¿

Where ¡my_config_file¿ is the name of the EMSD Pine configuration file described in the previous section, i.e. .pinerc.emsd.

In all other aspects EMSD Pine behaves identically to the standard version. For further information on the Pine user interface refer to the pine man pages installed on your system or to the on-line help.

If you generated the pinerc file using the automated method, you could also invoke EMSD Pine using the following script which selects the proper ‘pinerc’ file. For example:

emsdpine.sh 201.020 jamshid

invokes emsdpine with a ‘pinerc’ file which submits the message into the queue of the UAD on the specified machine.

For details on how to use this script, invoke it with no arguments. A usage message will be displayed.

3.3 Verification of the User Agent

This section assumes that the Message Center associated with the User Agent is up and running.

Once the MUI and UAD are started you should be able to send and receive email messages to/from any Internet address.

3.3.1 Send a Message

To send a message from the MUI select Compose from the Pine main menu. Enter any valid internet email address on the ”To” line of the message header. Fill in the other fields as you choose. The ctrl-X key sequence will send the message. Verify that the message was submitted by checking for mail at the destination email address.

3.3.2 Receive a Message

To receive a message at the MUI send email from any Internet email account to ¡emsd_user¿@¡emsd_domain¿ where

• ¡emsd_user¿ is the subscriber ID of the test account, for instance 201.001
• ¡emsd_domain¿ is the domain name of the EMSD Message Center that serves the test account, for instance emsd.neda.com.

If all is well, the message will appear in the Pine INBOX after half a minute or so. You can force Pine to poll its INBOX by using the ctrl-L key sequence.