Table Of Contents
Simple Mail Transfer Protocol
This chapter describes the Simple Mail Transfer Protocol (SMTP). It includes these sections:
A brief description of the SMTP, including definitions of terms used in this chapter to describe SMTP.
Describes how to use the Cisco IOS for S/390 mail facilities for the transportation of electronic mail.
Describes the interfaces between the Cisco IOS for S/390 mail routines and the post office.
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:
The SMTP Server program receives SMTP mail and spools it into a JES SYSOUT file.
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.
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.
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
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.
Using the Mail Facilities
This section describes how to use the Cisco IOS for S/390 mail facilities for the transportation of electronic mail.
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
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.
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 formatX-From: CZQ14CD@MYHOST.ARPA
into this formatX-From: <CDoaks@MYHOST.ARPA>
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.
The Cisco IOS for S/390 SNDMSG program can interactively create mail data sets for USMTP to send.
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:
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:
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 RESTRICTEDPLEASE 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 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 ESTTo: email@example.com,firstname.lastname@example.org.CC: email@example.comSubject: new testEnter message text, followed by empty line. Use \x tocancel last line, or \t to display msg. ..message text ..-->firstname.lastname@example.org SPOOLED-->email@example.com SPOOLED-->firstname.lastname@example.org SPOOLED
Note To send an empty line, press the function key PF10 (XWNL) to transmit with a null line.
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:
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 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.
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 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.
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.
The following example shows a sample incoming mail file as created by SSMTP:X-FROM: abcdef@remotehostX-TO: CZQ14CD@local post office nameTo: CDoaks@OURHOST.ARPADate: Tue, 12 Jan 91 10:11:12 ESTFrom: abcdef@remotehostSubject: Status of SMTP DocumentationWhat is the current status?
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.
This example shows a sample outgoing mail file:X-FROM: CZQ14CD@OURHOST.ARPAX-TO: abcdef@remotehostTo: abcdef@remotehostDate: Tue, 12 Jan 91 10:11:12 ESTFrom: CZQ14CD@OURHOST.ARPASubject: Status of SMTP DocumentationThe documentation has been successfully completed
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:
Time of day in hours, minutes, and seconds
The nth data set processed during that second
Note SNDMSG creates data sets using this format:
The data set name prefix directory is a SPOOL#4/USMTP configuration parameter (the PATH parameter on the SMTP statement in the file APPCFGxx).
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.comx-to: email@example.comDate: Tue, 7 Nov 89 11:08:49 ESTFrom: firstname.lastname@example.org: email@example.comSubject: test mailWe test mail through iebgener batch job.test mail test mail test mail test mail test mail test mailThis is the last line./*//SYSUT2 DD SYSOUT=A,DCB=(LRECL=80,BLKSIZE=3120,RECFM=FB),// DEST=RMT21//SYSPRINT DD SYSOUT=*//SYSIN DD DUMMY//
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.
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: