Guest

Support

Simple Mail Transfer Protocol

Hierarchical Navigation

  • Viewing Options

  • PDF (108.4 KB)
  • Feedback
Simple Mail Transfer Protocol

Table Of Contents

Simple Mail Transfer Protocol

Introducing SMTP

Mail Transport Support Programs

Understanding Cisco IOS for S/390 Mail Services

Mail Service Components

Using the Mail Facilities

Getting Started

Receiving Mail

Sending Mail

Invoking SNDMSG

SNDMSG Session

SNDMSG Termination

Interface to a User Mail System

Receiving Mail

SSMTP

Sending Mail

SPOOL#4

Sample Jobs

USMTP


Simple Mail Transfer Protocol


This chapter describes the Simple Mail Transfer Protocol (SMTP). It includes these sections:

Introducing SMTP

A brief description of the SMTP, including definitions of terms used in this chapter to describe SMTP.

Using the Mail Facilities

Describes how to use the Cisco IOS for S/390 mail facilities for the transportation of electronic mail.

Interface to a User Mail System

Describes the interfaces between the Cisco IOS for S/390 mail routines and the post office.

Introducing SMTP

The SMTP is used as the common mechanism for transporting electronic mail among different hosts within the Department of Defense Internet protocol suite.

Under SMTP, a user SMTP process opens a TCP connection to a server SMTP process on a remote host and attempts to send mail across the connection. The server SMTP listens for a TCP connection on a well-known port (25), and the user SMTP process initiates a connection on that port. When the TCP connection is successful, the two processes execute a simple request/response dialogue, defined by the SMTP protocol, in which the user process transmits the mail addresses of the originator and the recipient(s) for a message. When the server process accepts these mail addresses, the user process transmits the message. The message must contain a message header and message text formatted in accordance with RFC 822.

Mail Transport Support Programs

Within Cisco IOS for S/390, these major programs support mail transport:

SSMTP

The SMTP Server program receives SMTP mail and spools it into a JES SYSOUT file.

USMTP

The SMTP User program assumes that mail to be sent is available in cataloged data sets with a specific DSNAME prefix. It awakens periodically (or in response to a signal from SPOOL#4 or SNDMSG) to try to send pending mail data sets.

SPOOL#4

The outgoing mail spooler copies output from a JES print queue into cataloged data sets that are the outgoing mail data sets for USMTP. SPOOL#4 then awakens USMTP to send the messages.

SNDMSG

This interactive program lets local users create outgoing mail files. Using data entered from a local user terminal, SNDMSG creates mail data sets in the same format as SPOOL#4. SNDMSG then awakens USMTP to send the messages.

Cisco IOS for S/390 contains no mechanism to read the JES queue containing received mail (the queue written by SSMTP) nor to write the JES queue with mail to be transported (the queue read by SPOOL#4). To provide these mail services, an installation needs an appropriate user mail system. USMTP, SSMTP, and SPOOL#4 interface through JES2/NJE with a user mail system such as UCLAMAIL. However, since the interfaces are quite general, some other mail system can be substituted.

In this chapter, the user mail system is referred to as the post office, meaning either UCLAMAIL or some other mail system. Read Interface to a User Mail System for a description of the interfaces between the Cisco IOS for S/390 mail routines and the post office.

Understanding Cisco IOS for S/390 Mail Services

shows the relationship of Cisco IOS for S/390 programs with one another and with the post office:

Figure 7-1 Cisco IOS for S/390 Mail Services

You can use the Cisco IOS for S/390 mail routines even without a post office. You can configure SSMTP to send received mail to a local printer for hard copy, and the SNDMSG program creates mail data sets for USMTP to send. Read Using the Mail Facilities for information about direct use of the Cisco IOS for S/390 mail programs.

Mail Service Components

These terms are used throughout this chapter.

Mail Addresses

Mail addresses identify both the originator and recipient of a mail message. They generally take this form

X@Y

where X is a string, often a user or account, and Y is a string, often a host. In this chapter, X represents the local part of the mail address and Y represents the global part of the mail address. Mail addresses appear in the To: and From: fields of the message header and in the X-from: and X-to: fields of the envelope.

Envelope

The envelope is a header containing the originator and recipient mail addresses. It is prepended to each mail message by the post office, SNDMSG, or SSMTP, and it is used by all the Cisco IOS for S/390 SMTP routines as the message travels through the system. The envelope consists of the internally-defined (in other words, to the SMTP routines) header fields, X-from: and X-to: that let the SMTP routines convey mail addresses to one another.

Message Header

An RFC 822 message consists of any number of header fields, optionally followed by message text. Typical header fields include: Date:, From:, To:, CC: (carbon copy), and Subject:. The RFC 822 message header refers to the collection of these header fields.

Domain Literal

As defined in RFC 822, a domain literal is a dotted-decimal host number enclosed in square brackets. This is an example of a mail address using a domain literal:

CZQ14CD@[10.10.0.1]

Multi-homed Host

Multi-homed hosts are connected to more than one network and therefore have multiple network addresses.

Host Names

These are mnemonic name strings by which hosts are known on the network. Each host has one official host name and can have optional nicknames. Although nicknames are allowed, their use is discouraged as discussed in RFC 952.

Domain Name Resolver

Cisco IOS for S/390 uses the Domain Name Resolver to map host names into the appropriate network addresses.


Using the Mail Facilities

This section describes how to use the Cisco IOS for S/390 mail facilities for the transportation of electronic mail.

Getting Started

Have your Cisco IOS for S/390 site administrator place an entry in the SMTP User Table for you. This table defines a mapping between TSO user IDs and user names. Each entry in the table contains these parameters:

TSO user ID

Mailbox name

A name by which the TSO user is known at other hosts on your network. When SSMTP sends a message, it attempts to match the local part of the recipient mail address against this field to map it into a TSO user ID.

Signature

This optional parameter is used by USMTP in the creation of an originating mail address (the X-From: header field in the message header). For example, suppose the User Table had this entry:

USMTP transforms the header field (created by either the post office or SNDMSG) from this format

X-From: CZQ14CD@MYHOST.ARPA

into this format

X-From: <CDoaks@MYHOST.ARPA> 

Receiving Mail

To receive mail, the SSMTP program can be configured to send mail to a local printer for hard copy output. The Cisco IOS for S/390 Customization Guide provides information on configuring SSMTP to send mail to the local printer.

Sending Mail

The Cisco IOS for S/390 SNDMSG program can interactively create mail data sets for USMTP to send.

Invoking SNDMSG

You can invoke SNDMSG directly from a local VTAM terminal or indirectly from a TSO Telnet session.

To invoke SNDMSG directly from a local VTAM terminal, enter this command (in one of two forms) on the system logon invitation screen in place of the LOGON command:

ACCES ;SNDMSG

or

LOGON APPLID(ACCES) DATA(;SNDMSG)

Consult with your Cisco IOS for S/390 site administrator to find which of the two command forms to use.

To invoke SNDMSG indirectly from a TSO Telnet session, enter the following command after the Telnet input prompt:

;SNDMSG

After the appropriate command is entered, the terminal is connected to Cisco IOS for S/390 and prompts you for a user ID and password:

REQUESTED SERVICE IS RESTRICTED 
PLEASE ENTER USERID: 
AND PASSWORD:

Consult with your Cisco IOS for S/390 site administrator for password and ID information. After permission is granted, control is passed to SNDMSG.

SNDMSG Session

SNDMSG first displays a herald message and then prompts you for recipient mail address(es), carbon copy mail address(es), subject, and message text. A sample SNDMSG session is shown here.

Using the data you entered, SNDMSG creates a mail data set containing an envelope, a message header, and message text in the same format that SPOOL#4 would create. Read SPOOL#4 for more information.

**SNDMSG ** WED, 13 JAN 91 16:40:47 EST 
To:  abc@unix.md.company.com,xyz@unix.md.company.com.
CC:  mno@unix.md.company.com 
Subject:  new test 
Enter message text, followed by empty line. Use \x to
cancel last line, or \t to display msg. .
.
message text .
.
-->abc@unix.md.company.com SPOOLED 
-->xyz@unix.md.company.com SPOOLED 
-->mno@unix.md.company.com SPOOLED 

Note   To send an empty line, press the function key PF10 (XWNL) to transmit with a null line.


Usage Guidelines

You can enter multiple recipient or carbon copy mail addresses (To: or CC: address fields), separated by commas. SNDMSG creates a separate mail data set for each recipient and carbon copy mail address. Each contains a single X-to: field in the envelope.

File inclusion is a message line beginning with the three characters ..f= followed by a data set name that causes the contents of that data set to be included in the outgoing message.

Do not enclose the data set name in quotes; it must be fully qualified. This is an example:

.f=OTAPXYZ.MYMESSGE.TEXT

The user and the Cisco IOS for S/390 user ID must have access authority to read the file. Also, if the file is not in the catalog, it is not sent.

The file is expanded into the mail message immediately. This may affect virtual storage requirements if the file is large.

SNDMSG Termination

SNDMSG terminates automatically when you have completed entering your message. If SNDMSG is invoked directly from VTAM, control returns to VTAM and the terminal again displays the login invitation. If SNDMSG is invoked from a TSO Telnet session, control returns there.

Interface to a User Mail System

This section describes the interfaces between the Cisco IOS for S/390 mail routines and the post office in more detail.

Receiving Mail

The post office receives a message from the network by retrieving it from a JES SYSOUT file where it was previously spooled by SSMTP (described in the following section). The post office can retrieve these JES SYSOUT files using one of the following:

The MVS-provided or a user-written external writer

The JES Sub-System Interface (SSI)

SSMTP

SSMTP begins execution when it receives a request to connect to the well-known mail port. SSMTP completes the opening of the TCP connection and performs the receiver end of the SMTP protocol. When a message is received, SSMTP spools it into a JES SYSOUT file from which the post office retrieves it. A secondary copy of the message text is also spooled into a SYSOUT file destined for the local printer. Normally, this copy is deleted at deallocation time. However, if the received message exceeds a configuration-specified size, the primary copy (destined for the post office) is deleted and the secondary copy queued for printing. This is called diversion of the mail to the printer. (In the case where no post office is implemented, all received mail is diverted to the printer.) Both of the JES SYSOUT files have RECFM=VB (in other words, no carriage control).

SSMTP prepends an envelope to the messages it spools to JES. The envelope consists of a single X-from: field of the form:

X-from: remote user@remote host

followed by one or more X-to: fields of the form:

X-to: TSO userid@local post office name

The X-from: field contents are taken directly from the SMTP MAIL FROM: command. The X-to: field contents are derived from a single RCPT TO: SMTP command. The local part of the mail address from the RCPT TO: command is mapped into a TSO user ID using the SMTP User Table. If the local part of the mail address is not in the SMTP User Table, SSMTP rejects the recipient mail address. The local post office name is an SSMTP configuration parameter that represents the name of the local post office. It need not be the same as the local network host name.

Usage Guidelines

The MAIL FROM: command received by SSMTP generates the X-FROM: line. The RCPT TO: commands received by SSMTP generate the X-TO: lines. The rest of the text of the file is placed into the file as received after the DATA command.

ASCII format effectors in the input stream are generally handled as follows:

Horizontal tabs (HT) are expanded to blanks assuming tab stops in every 8th column: 8, 16, 24, 32, etc.

Other format effectors (FF, a LF not following a CR, a CR not preceding a LF>, a BS) appear in the spooled file as the corresponding EBCDIC control characters.

SSMTP supports the following SMTP commands: HELP O, MAIL, RCPT, DATA, VRFY, QUIT, RSET, NOOP, HELP. This is the minimum implementation set.

SSMTP does not support expanding mailing lists.

Example

The following example shows a sample incoming mail file as created by SSMTP:

X-FROM: abcdef@remotehost 
X-TO: CZQ14CD@local post office name
To: CDoaks@OURHOST.ARPA 
Date: Tue, 12 Jan 91 10:11:12 EST 
From: abcdef@remotehost 
Subject: Status of SMTP Documentation 
What is the current status? 

Sending Mail

The post office originates a message destined for your network by formatting it with an envelope, message header, and message text and then spooling the message to a JES queue.

The MAIL FROM: command sent by USMTP comes from the X-FROM: line. The RCPT TO: commands sent by USMTP comes from the X-TO: lines. The rest of the text of the file is sent by USMTP after the DATA command.

Example

This example shows a sample outgoing mail file:

X-FROM: CZQ14CD@OURHOST.ARPA 
X-TO: abcdef@remotehost 
To: abcdef@remotehost 
Date: Tue, 12 Jan 91 10:11:12 EST 
From: CZQ14CD@OURHOST.ARPA 
Subject: Status of SMTP Documentation 
The documentation has been successfully completed

SPOOL#4

SPOOL#4 uses the JES subsystem interface. SPOOL#4 reads messages from a JES queue and creates cataloged data sets. SPOOL#4 signals USMTP. The data sets created by either have RECFM=VBA and data set names in this form:

`directory.Djjjjj.Thhmmss0.Nxxxx'

Syntax Description

jjjjj

Julian date

hhmmss

Time of day in hours, minutes, and seconds

xxxx

The nth data set processed during that second



Note   SNDMSG creates data sets using this format:
`directory.Djjjjj.Thhmmss0'


The data set name prefix directory is a SPOOL#4/USMTP configuration parameter (the PATH parameter on the SMTP statement in the file APPCFGxx).

Sample Jobs

The following sample jobs can be used to send a mail file to RMT21 (the REMOTE parameter on statement SMTP in the APPCFGxx member) for SPOOL#4 to pick up and convert into a mail data set:

This first sample reads from a file (T01TCP.ACCES.EMAIL(NEWMAILD):

//ICSGENER JOB (TSO00,,,99),'WRITE TO SPOOL#4',
//MSGCLASS=X,CLASS=A 
//* 
//STEP1    EXEC PGM=IEBGENER 
//SYSUT1 DD DISP=SHR,DSN=T01TCP.ACCES.EMAIL(NEWMAILD) 
//SYSUT2 DD SYSOUT=A,DCB=*.SYSUT1, 
//          DEST=RMT21 
//SYSPRINT DD   SYSOUT=* 
//SYSIN    DD   DUMMY 
//

Or, you may use the following to include the mail message in your job:

//ICSGENRM JOB (TSO00,,,999),'WRITE TO SPOOL#4',
//MSGCLASS=Z,CLASS=A
//*
//STEP1    EXEC PGM=IEBGENER
//SYSUT1   DD *
 X-From: t01tcp@host1.HQ.company.com
 x-to: t01tcp@host2.md.company.com
 Date: Tue, 7 Nov 89 11:08:49 EST
 From: t01tcp@host1.md.company.com
 to: t01tcp@host2.md.company.com
 Subject: test mail

 We test mail through iebgener batch job.
 test mail  test mail  test mail  test mail  test mail  test mail 
 This is the last line.
/*
//SYSUT2 DD SYSOUT=A,DCB=(LRECL=80,BLKSIZE=3120,RECFM=FB),
//          DEST=RMT21 
//SYSPRINT DD   SYSOUT=*
//SYSIN    DD   DUMMY
//

USMTP

USMTP awakens periodically (or when signaled by SPOOL#4 or SNDMSG) to try to send pending mail data sets. It tries to send each data set that is either new or whose retry timeout has expired. Any data sets successfully sent are deleted and uncataloged. The others are kept for later attempts. USMTP expects the mail data sets to be in the format shown in the example in the section on Sending Mail. USMTP assumes only a single X-TO: line (in other words, recipient mail address) per data set. For multiple network recipients, the post office (or SNDMSG) must create multiple data sets.

USMTP generally handles arbitrary carriage control characters in the mail data set translating them to corresponding sequences of ASCII format effectors.

If transmission of a particular message is unsuccessful because of a temporary error (for example, the remote host is down), USMTP retries periodically for a limited number of times. If this number is exceeded, or there is a permanent error (for example, the remote SMTP receiver refused the message because the target local part of the mail address was unknown), USMTP redelivers the message to the local user. For this redelivery, USMTP issues a message from the Mailer Daemon saying that the message was undeliverable and why. USMTP appends the Daemon message to the original message and spools it into the JES queue used by SSMTP (see the section of this chapter describing SSMTP) to deliver messages to the post office.

USMTP configuration parameters determine the frequency of retries and the maximum retry time.

USMTP has the following general features:

Multi-homed Host Logic

To provide robust delivery, USMTP tries each address in turn of a multi-homed host before deciding that the mail cannot be delivered.

Host Name Mapping

USMTP scans the fields in the message header and envelope that contain host names and, if necessary, maps nicknames into official host names.

MX record support

USMTP uses this feature to resolve mail routes for a host. (similar to a DNRGET ROUTE BYNAME host_name).

TSO User ID Mapping

As mentioned, USMTP scans the mail addresses in the envelope and message header and, if possible, uses the SMTP User Table to map local TSO user IDs into a mailbox name string before sending the message.


Note   To use Host name mapping and MX record support, USMTP must be able to parse RFC 822 message headers.


File Inclusion

A message line beginning with the three characters ..f= followed by a data set name causes USMTP to include the contents of that data set in the outgoing message. Do not enclose the data set name in quotes; it must be fully qualified. This is an example:

.f=OTAPXYZ.MYMESSGE.TEXT

The user and the TCP user ID must have access authority to read the file. If the file is not in the catalog, it is not sent.


Note   There is a potential access-control problem with this facility. Since USMTP does not have a password for the given user account, it cannot do a secondary login to assume the user's authority by any access control mechanism. Consequently, you must ensure that Cisco IOS for S/390 has read-access to the specified data set. Otherwise, the file is not sent.


Because included files are now expanded by SNDMSG, USMTP normally does not see ..f= commands. Such commands may have been entered by some other mailer via SPOOL#4.

Support for Domain Literals

You can send a message using a domain literal in place of a host name. However, since it is difficult to enter square brackets on an IBM system, USMTP accepts IP address domain literals without brackets:

CZQ14CD@10.1.0.1