SMTP addresses are of the form userID@domain.name, where domain.name refers to a valid DNS domain. Mail exchange (MX) records point electronic mail to a particular address (host and account) in that domain.

14.1.5 How SMTP Routes Mail

To find a destination address, SMTP routing looks up addresses in this order:

1. Local MX database
2. Remote MX database
3. BIND database
4. Local hosts database

MX routing first checks the local preference but tries it only once in the lookup process.

14.1.5.1 Using MX Records

SMTP uses the information stored in MX records to route mail. Each MX record contains a list of hosts that can accept mail for the specified destination. The list is in order of routing preference. Each MX record contains the following fields:

Destination domain	Indicates the mail destination. Multiple MX records for the same destination are allowed.
Gateway host name	The name of the host through which mail is routed.
Preference	Prioritizes multiple MX records for the same destination domain. The lower the preference value, the higher the priority for the MX record.

Creating multiple MX records for the same destination domain provides the following advantages:

• Enables load balancing between mail routers.
• Mail continues to be routed even if one mail router is unavailable (that is, down).
• Provides MX-based routes for mail internal and external to a firewall.

Use the SET MX_RECORDS command to enter routing information to the MX database. For example, the following example command assigns MERLIN as the gateway for CROW with a preference 100:

TCPIP> SET MX_RECORDS CROW /GATEWAY=MERLIN /PREFERENCE=100

See the DIGITAL TCP/IP Services for OpenVMS Management Command Reference for a detailed desciption of the SET MX_RECORDS command.

14.1.5.2 Using SMTP Zone and Alternate Gateway

When configuring SMTP, you supply the name of the domain for your environment with the /ZONE qualifier to the SET CONFIGURATION SMTP command. If you do not supply a domain name, the zone defaults to one level higher than your local domain. For example, if your local domain is a.b.com, the default value of /ZONE is b.com (assuming that, because TCPIP has been started, the domain is known).

Mail for delivery outside of your zone is sent to its destination by the alternate gateway, as defined by the /GATEWAY qualifier. This is an alternate route through which SMTP sends mail if delivery fails. If you define an alternate gateway, SMTP checks if the gateway is part of or outside of your local domain and relays the mail accordingly. (If you do not specify an alternate gateway, SMTP uses the MX records to determine which host should relay mail.)

In the following example commands defines the alternative gateway MY.ALT.MYZONE.COM and the zone MYZONE.COM.

TCPIP> SET CONFIGURATION SMTP/GATEWAY=ALTERNATE=MY.ALT.MYZONE.COM TCPIP> SET CONFIGURATION SMTP/ZONE=MYZONE.COM

See the DIGITAL TCP/IP Services for OpenVMS Management Command Reference for a detailed desciption of the SET CONFIGURATION SMTP command.

14.2 Starting and Stopping SMTP

SMTP consists of two components: the sender (the queuing mechanism) and the receiver. You must start the sender before enabling the receiver. The receiver is activated by the auxiliary server.

To start the SMTP sender, enter:

$ @SYS$MANAGER:TCPIP$SMTP_STARTUP

To enable the receiver, enter:

$ TCPIP ENABLE SERVICE SMTP

To stop SMTP, enter:

$ @SYS$MANAGER:TCPIP$SMTP_SHUTDOWN

14.3 Configuring SMTP

Use the configuration procedure TCPIP$CONFIG to set up SMTP on your host. If you need to reconfigure or further refine your SMTP environment, use the SET CONFIGURATION SMTP command. With this command, you can change the way SMTP:

• Relays messages
• Determines the route
• Determines how many times it will retry a relay and the length of time between delivery attempts
• Sends and receives timeouts

For a complete description of this command, its qualifiers, and options, see DIGITAL TCP/IP Services for OpenVMS Management Command Reference.

14.3.1 Mail Utility Files

Outgoing mail files are stored in the user profile default directory. Incoming mail files are temporarily stored by the receiving process in the SYS$SPECIFIC:[TCPIP$SMTP] directory. These files have names such as:

92022509472729_USERNAME.TCPIP_HOSTNAME

or

92022509472729_SYSTEM.TCPIP_HOSTNAME

Table 14-2 lists the utility files created during the SMTP configuration.

Table 14-2 Default SMTP Utility Files

File Name	Description
LOGIN.COM	Used by the auxiliary server
TCPIP$SMTP_RECV_RUN.COM	Used by the auxiliary server
TCPIP$SMTP_LOGFILE.LOG	Log of mail queue and symbiont activities
TCPIP$SMTP_RECV_LOGFILE.LOG	Log of incoming mail

To analyze the consistency of the SMTP queues against the directories containing the SMTP utility files, enter the ANALYZE MAIL command.

14.3.2 Creating a Postmaster Account

The Postmaster account is a required account that receives all undeliverable mail. The SMTP process account serves as the Postmaster account by default. You can change this by specifying a different account name with the /POSTMASTER qualifier to the SET CONFIGURATION SMTP command.

To set up a Postmaster account, follow these steps:

1. Check that the spooling directory is in a SYS$SPECIFIC directory.
2. Ensure that the Postmaster account can gain access to the spooling directory.
3. Define the same user name and Postmaster in the SMTP service's definition.

SMTP requires that the system be able to receive mail addressed to the user name POSTMASTER. To meet this requirement, do one of the following:

• Set OpenVMS mail to forward the mail addressed to POSTMASTER to the SYSTEM account. For example:

  $ SET PROC/PRIV=SYSPRV $ MAIL MAIL> SET FORWARD/USER=POSTMASTER SYSTEM MAIL> SET FORWARD/USER=TCPIP$SMTP SYSTEM MAIL> SET FORWARD/USER=UCX_SMTP SYSTEM

• Create a distribution file named POSTMASTER.DIS that contains the system manager's mailing address.

To define a list of domains that SMTP interprets as local:

1. Create the file TCPIP$SMTP_LOCAL_ALIASES.TXT.
2. Include a list of domain names that are to be recognized as local (maximum 64 characters), one line per name, up to a maximum of 255 names. For example:

   ! ! This is the local alias file. ! ourdomain.edu ourdomain1.edu ourdomain2.edu ourdomain3.edu

3. Copy the TCPIP$SMTP_LOCAL_ALIASES.TXT file to one of the following locations:
   • TCPIP$SMTP_COMMON, where each host listed in the TCPIP$SMTP_LOCAL_ALIASES.TXT file receives clusterwide messages
   • SYS$SPECIFIC:[TCPIP$SMTP] (local system use)
4. Stop and restart SMTP for the change to take effect.

If SMTP cannot locate the TCPIP$SMTP_LOCAL_ALIASES.TXT file, it looks for the file TCPIP$SMTP_COMMON:UCX$SMTP_LOCAL_ALIASES.TXT. This support is provided for mixed clusters (running TCP/IP Services V5.0 and earlier versions of the product (UCX)) where the TCPIP$SMTP_COMMON and UCX$SMTP_COMMON logicals point to the same directory. Note that when SMTP looks for UCX$SMTP_LOCAL_ALIASES.TXT it looks for it in the TCPIP$SMTP_COMMON: directory rather than the UCX$SMTP_COMMON: directory.

14.5 Managing the SMTP Symbiont Queues

Table 14-3 summarizes the commands you use to monitor and manage SMTP.

Table 14-3 SMTP Management Commands

Command	Function	Required Privilege
ANALYZE MAIL	Verifies the consistency of the SMTP queues against the SMTP working directory.	SYSPRV or BYPASS
DISABLE SERVICE SMTP	Stops SMTP service.	1
ENABLE SERVICE SMTP	Initializes communications for SMTP.	1
REMOVE MAIL	Deletes the specified mail entries from the SMTP queues.
SEND MAIL	SMTP requeues a mail message for delivery.	SYSPRV or BYPASS for messages other than yours.
SET CONFIGURATION SMTP	Modifies the characteristics of the SMTP sender and receiver.	SYSPRV or BYPASS
SHOW CONFIGURATION SMTP	Displays the system characteristics for SMTP.	1
SET SERVICE SMTP	Defines, modifies, or deletes the SMTP service in the services database.	SYSPRV or BYPASS
SHOW MAIL	Displays information about mail for the specified user.	SYSPRV or BYPASS
SHOW SERVICE SMTP	Displays statistical information about the SMTP server.	1
START MAIL	Starts the SMTP queuing mechanism.	SYSPRV or BYPASS
STOP MAIL	Stops the SMTP queuing mechanism.	SYSPRV or BYPASS

To monitor the mail queues, examine the TCPIP$SMTP_LOGFILE.LOG and the TCPIP$SMTP_RECV_RUN.LOG files.

14.5.2 Changing the Number of Queues

To change the number of SMTP queues, follow these steps:

1. Stop SMTP and MAIL on the root node by entering the following commands:

   TCPIP> DISABLE SERVICE SMTP TCPIP> STOP MAIL

2. Change the SMTP configuration by entering the following command:

   TCPIP> SET CONFIGURATION SMTP/QUEUES=new_number

   
   The maximum number of queues set with this command is 10.

3. Restart SMTP and MAIL by entering the following commands:

   TCPIP> ENABLE SERVICE SMTP TCPIP> START MAIL

To display SMTP routing information, use the SHOW MX_RECORDS command.

• If you omit destination, you see the entries in the local MX database.
• If you specify destination, you see all the entries in all the databases that the product would look at, if necessary, to resolve the address. The local MX database and the BIND MX database are usually as far as the product needs to search.

Example 1:

This example displays, in order of preference, the routing hops to reach host SWAN if an attempt fails. The local host tries to route through:

1. WATER.PIPIT.WEBBED.FEET.COM
2. bd-gw.purple.martin.com
3. great.horned.owl.com
4. bird.food.seeds.worms.com

In the example:

• The Gate name field tells where to relay the mail.
• The Gate address field gives the gateway's IP address.
• The Preference field gives each MX record a precedence. A lower preference number means a higher precedence.

TCPIP> SHOW MX_RECORDS SWAN BIND MX database Server: 18.18.218.10 GREAT.HORNED.OWL.COM Gate address Preference Gate name 18.18.218.10 50 WATER.PIPIT.WEBBED.FEET.COM 18.1.218.16 100 bd-gw.purple.martin.com 188.88.206.2 200 great.horned.owl.com 199.9.214.1 300 bird.food.seeds.worms.com BIND database Server: 18.18.218.10 WATER.PIPIT.WEBBED.FEET.COM Host address Host name 18.18.100.10 SWAN.WEBBED.FEET.COM

Example 2:

The following example shows the MX records for destination host crow.com. In the example:

• The Gate name field tells where to relay the mail.
• The Gate address field gives the gateway's IP address.
• The Preference field gives each MX record a precedence. A lower preference number means a higher precedence.

The local host is WATER, the alternate gateway is scare.crow.com, and the zone is crow.com. The first preference for delivering mail to crow.com is to try to send to cawcaw.crow.com.

If you have not defined an alternate gateway, SMTP tries to relay the mail to scare.crow at IP address 158.228.12.253 in the zone, not the destination host name. Therefore, SMTP checks to see if cawcaw.crow is in the zone daw.com.

TCPIP> SHOW MX_RECORDS CROW.COM BIND MX database Server: 18.18.218.10 WATER.PIPIT.WEBBED.FEET.COM Gate address Preference Gate name 159.228.12.253 1 cawcaw.crow.com 159.228.12.254 2 scare.crow.com

Example 3:

The following example shows the local MX configuration for destinations JUNCO and ubird.edu. In the example:

• Messages from JUNCO are routed to TURKEY.
• If TURKEY fails, SMTP then routes them to HERON.
• Messages from ubird.edu are routed to owl.wise.mouser.edu.
• If owl.wise.mouser.edu fails, SMTP then routes them to tragopan.asian.pheasant.edu.

TCPIP> SHOW MX_RECORDS JUNO Local MX database Destination Preference Gateway JUNCO 8 HERON 2 TURKEY ubird.edu 100 tragopan.asian.pheasant.edu 50 owl.wise.mouser.edu

14.5.4 SMTP Logging

SMTP logs mail queue and mail symbiont events to the following files:

• TCPIP$SMTP_LOGFILE.LOG
• TCPIP$SMTP_RECV_RUN.LOG

The symbiont and receiver contain a feature called snapshot logging, which allows you to run with full diagnostics enabled but to write the diagnostics to the log file only if an error is signaled. This feature saves disk space and allows the receiver or the symbiont, or both, to run at a normal speed. As each line of diagnostic text is generated, it is saved in an internal snapshot buffer rather than to the disk. The buffer is circular in that once it fills up, new lines of text start to overwrite the old data already there. This functionality provides a snapshot of the last lines of diagnostic text.

Logical names are available to modify the way SMTP logs information and the type of information it reports.

14.6 Modifying Your SMTP Configuration

You can modify your SMTP configuration by defining logical names that are translated at queue startup time. Characteristics you can affect include:

• Event-and error-logging diagnostics
• How mail headers are displayed
• How mail is routed
• How SMTP interacts with OpenVMS mail

Some SMTP logical names are used to either enable or disable a configuration option and do not require a value. If you define the logical name, the option is considered to be enabled. If not defined, the option is disabled. To disable an option, remove the logical name.

For example, to enable message logging for messages received from and transmitted to remote SMTP clients, define the TCPIP$SMTP_RECV_TRACE as follows:

$ DEFINE/SYSTEM TCPIP$SMTP_RECV_TRACE

Other logical names require that you supply a value. For example, to enable logging that provides information about symbiont activity during control file processing, define the logical name TCPIP$SMTP_LOG_LEVEL with a value of 3. For example:

$ DEFINE/SYSTEM TCPIP$SMTP_LOG_LEVEL 3

The following descriptions indicate where a value is required.

• TCPIP$SMTP_LOG_LEVEL value
  Writes diagnostic information to the log file. Valid numeric values are:

  Value 2	Enables logging of all information when the symbiont starts up. The Next Open File message is printed, giving the name of each control file before processing begins. All mail headers and mail recipients in a control file are logged after control file processing is complete.
  Value 3	Provides additional information to the above about symbiont initialization and activity during control file processing.
  Value 5	Enables full symbiont diagnostics. For use only under the advice of Compaq's customer support.

• TCPIP$SMTP_NOSEY
  Used with TCPIP$SMTP_LOG_LEVEL to print the full subject RFC headers information. If not defined, the header is logged only as SUBJECT:.
• TCPIP$SMTP_LOG_LINE_NUMBERS
  Writes line numbers to SMTP logs. Includes the symbiont, receiver, and MAIL$PROTOCOL (DEBUG.TXT) logs.
• TCPIP$SMTP_SYMB_TRACE
  Logs all messages received from and transmitted to remote SMTP servers. Used to trace the SMTP application layer protocol. Any not printable or control characters that are sent or received are printed as \n where n is the hexadecimal value of the character. For example, command lines and replies are terminated with a <CR><LF> that appear in the log as follows:

  send buf=MAIL FROM:<jones@acme.com>\d\a recv buf=250 <jones@acme.com>... Sender OK\d\a

  
  where \d\a is the <CR><LF>

• TCPIP$SMTP_RECV_TRACE
  Logs all messages received from and transmitted to remote SMTP clients. The same conventions for logging unprintable or control characters are used. Obsoletes the logical name TCPIP$SMTP_PROTO_TRACE.
• TCPIP$SMTP_RECV_DEBUG
  Logs full diagnostics, similar to the TCPIP$SMTP_LOG_LEVEL 5 logical name. Obsoletes the logical name TCPIP$SMTP_PROTO_DEBUG.
• TCPIP$SMTP_VMSMAIL_SEND
  Instructs MAIL$PROTOCOL to log diagnostics to a file named DEBUG.TXT in the default directory. (Used primarily by Compaq.)
• TCPIP$SMTP_VMSMAIL_PARSE
  Causes the SMTP address parsing code to log diagnostics. The symbiont, receiver, and MAIL$PROTOCOL code are sensitive to this logical name, which is used primarily by DIGITAL.
• TCPIP$SMTP_SYMB_SNAPSHOT_BLOCKS numeric value
  Enables snapshot logging for the symbiont. The value you assign is the desired size of the snapshot buffer in OpenVMS blocks (1 block being 512 bytes). Use with TCPIP$SMTP_LOG_LEVEL. Note that when you enable snapshot buffering for the symbiont, it takes some time for the symbiont process to stop when you enter a TCPIP STOP MAIL command or you stop the queue depends on the size of the snapshot buffer and the speed of the system and its disks.
  For example, the following command lines set the log level to 5 and enable snapshot logging for the SMTP symbiont with a snapshot buffer of 200 blocks:

  $ DEFINE/SYSTEM TCPIP$SMTP_LOG_LEVEL 5 $ DEFINE/SYSTEM TCPIP$SMTP_SYMB_SNAPSHOT_BLOCKS 200

• TCPIP$SMTP_RECV_SNAPSHOT_BLOCKS numeric value
  Enables snapshot logging for the receiver. The value you assign is the desired size of the snapshot buffer in OpenVMS blocks (1 block being 512 bytes). Use with TCPIP$SMTP_LOG_LEVEL.
  For example, the following command line sets all of the receiver diagnostics on and enables snapshot logging for the receiver with a snapshot buffer of 200 blocks:

  $ DEFINE/SYSTEM TCPIP$SMTP_RECV_DEBUG 1 $ DEFINE/SYSTEM TCPIP$SMTP_RECV_TRACE 1 $ DEFINE/SYSTEM TCPIP$SMTP_RECV_SNAPSHOT_BLOCKS 200

• TCPIP$SMTP_NO_SUBS_DOMAIN_INBOUND
  Instructs SMTP not to consider mail that is sent to the substitute domain as local mail.
• TCPIP$SMTP_COMMON string
  By default, SMTP looks for distribution list (.DIS) and local alias (TCPIP$SMTP_LOCAL_ALIASES.TXT) files in the SYS$SPECIFIC:[TCPIP$SMTP]. Use this logical name to change the default cluster common directory. You must:
  • Define this logical name before SMTP startup.
  • Create the directory with read (R) and write (W) access. If the directory is shared between a system running a previous version of the product (UCX) and this version, granting G:RWE privilege is sufficient, because the UCX_SMTP and TCPIP$SMTP accounts are in the same group.
  • Move the .DIS or .TXT files, or both, to the directory.
  
  You can also use this logical name as a search list. For example, you might want SMTP to look at the clusterwide directory and then the SYS$SPECIFIC:[TCPIP$SMTP] directory, as follows:

  $ DEFINE/SYSTEM TCPIP$SMTP_COMMON WORKDISK:[SMTP_DIS], - _$ SYS$SPECIFIC:[TCPIP$SMTP]

  
  Note that other files such as control files and log files reside in the SYS$SPECIFIC:[TCPIP$SMTP] directory.

• TCPIP$SMTP_JACKET_LOCAL
  Instructs the symbiont to put the SMTP jacket on local-to-local mail to provide sufficient information to the POP server.
• TCPIP$SMTP_INBOUND_NOXVMS
  Instructs the symbiont not to use the RFC X-VMS-To header as the text of the OpenVMS mail To: line and the X-VMS-CC header as the text of the CC: line. Instead, the RFC To: and CC: lines are used. If the TCPIP$SMTP_INBOUND_NOXVMS option is not defined, the SMTP symbiont uses the text of the X-VMS-To and X-VMS-CC lines for the mail header lines.
• TCPIP$SMTP_VMSDEF_TO
  Instructs the symbiont not to pass any text for the To: line to OpenVMS callable mail when delivering local mail. This option causes OpenVMS callable mail to use the default text for the To: line (the user name). Overrides the TCPIP$SMTP_INBOUND_NOXVMS option for the To: field.
• TCPIP$SMTP_MTS_ALLIN1
  Used in older versions of the product. When relaying mail from the SMTP environment to MTS (the message router), the symbiont puts TCPIP$SMTP into the From: field. Otherwise, older versions of MR/MRGATE send the mail back with a Return path too complicated error. No longer needed if you are running MR and MRGATE Versions 3.3A.
• TCPIP$SMTP_POSTMASTER_ALIAS value
  Enables undelivered mail to appear to be from a user name other than TCPIP$SMTP@your.localhostname. The value you assign is the user name portion of the address and should not include the host name. For example:

  $ DEFINE/SYSTEM TCPIP$SMTP_POSTMASTER_ALIAS "Postmaster"

  
  In this example, mail sent from the node appears to be from Postmaster@node.domain rather than from TCPIP$SMTP@node.domain.
  Be sure to set up a forwarding entry for the value you assign (see Section 14.3.2).

• TCPIP$SMTP_REWRITE_MTS_FROM
  If you have most or all of your users' mail forwarded to ALL-IN-1, use this logical name to instruct the symbiont to parse the user name out of the complex MTS address and append the local host name instead. As a result, only a simple address is sent to the Internet and any replies are relayed correctly to MTS.
• TCPIP$SMTP_ALTGATE_ALWAYS
  Instructs the symbiont to send all mail that is destined for another system (nonlocal mail) to the alternate gateway. Zone check is not performed.
• TCPIP$SMTP_MX_IF_NOALTGATE
  Instructs the symbiont to use MX records to connect to a host if the alternate gateway cannot be reached.
• TCPIP$SMTP_NO_MX
  Instructs the SMTP symbiont not to use MX records to route mail. Attempts to translate the domain part of each SMTP address into a host name and send the mail directly to that address. If the host name does not translate to an address, the mail is returned. If the host is not available, the mail is queued again.
• TCPIP$SMTP_LOCAL_ALIAS_ONLY
  Instructs the SMTP symbiont to use only the contents of the local alias file when routing mail.