HP TCP/IP Services for OpenVMS

Previous Contents Index

18.2 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:

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

18.2.1 Mail Utility Files

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

Table 18-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, and stored in the TCPIP$SYSTEM directory.
TCPIP$SMTP_LOGFILE.LOG Log of mail queue and symbiont activities.
TCPIP$SMTP_RECV_RUN.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.

18.2.2 Creating a Postmaster Account

SMTP requires that the system be able to receive mail addressed to the user name POSTMASTER. This user name is the destination for bounced mail messages.

A bounced mail message is a mail message that has been returned by a remote server because neither the recipient specified in the original mail message, nor the original sender can be found by the local SMTP server.

By default, bounced mail is delivered to the following SMTP address:


To ensure that the POSTMASTER account is set up to receive SMTP mail, use OpenVMS Mail to specify forwarding of mail addressed to POSTMASTER to the SYSTEM account. For example:


This ensures that bounced mail messages are sent to the SYSTEM user (usually the system manager).

You can modify the user name associated with POSTMASTER by defining the following logical name:


In this example, user-name is the user name. For more information, see Section 18.5.

18.3 Creating a Local Alias File

You can used a local alias to define a list of domains that SMTP will interpret as local. If SMTP receives mail for any of the domains specified as local aliases, it will deliver the mail on the local system using OpenVMS Mail rather than forward it on to another system.

This is useful in an OpenVMS Cluster environment, where you want mail sent to any of the cluster hosts to be delivered locally rather than take the extra step of relaying it from one cluster node to another. It is also useful if you want to set up your OpenVMS host to receive inbound mail either for different domains unrelated to the actual domain of your host or for alias names of your host.

For example, if your host was a.b.com and you had entries for x.y.com and y.z.com in your local alias file, any mail to x.y.com and y.z.com would be delivered locally on your host. (To implement this fully, set up DNS MX records so that mail to the x.y.com and y.z.com domains is routed to your host.) For more information about setting up DNS records, see Chapter 6.

To define a list of domains that SMTP interprets as local, create the file TCPIP$SMTP_LOCAL_ALIASES.TXT containing a list of domain names that are to be recognized as local. The domain names should have a maximum of 64 characters with one line per name, up to a maximum of 255 names. For example:

! This is the local alias file. 

Copy the TCPIP$SMTP_LOCAL_ALIASES.TXT file to one of the following locations:

Stop and then 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 ensures functionality for mixed clusters (that is, clusters running the current version of TCP/IP Services 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 in the UCX$SMTP_COMMON: directory.

18.4 Managing SMTP

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

Table 18-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. Follows OpenVMS file protection rules.
ENABLE SERVICE SMTP Initializes communications for SMTP. Follows OpenVMS file protection rules.
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. Follows OpenVMS file protection rules.
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. Follows OpenVMS file protection rules.
START MAIL Starts the SMTP queuing mechanism. SYSPRV or BYPASS.
STOP MAIL Stops the SMTP queuing mechanism. SYSPRV or BYPASS.

18.4.1 Displaying Mail Queues

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

18.4.2 Changing the Number of Mail 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:


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


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

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


18.4.3 Displaying SMTP Routing Information

To display SMTP routing information, use the SHOW MX_RECORDS command. If you omit destination from the command line, you see the entries in the local MX database.

If you specify destination, you see all the entries in all the databases that the SMTP mailer would look at, if necessary, to route mail to the destination. The local MX database and the DNS MX database are usually as far as TCP/IP Services needs to search.

18.4.4 SMTP Logging

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

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. These are described in Section 18.5.

18.4.5 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.

The SMTP can be shut down and started independently. This is useful when you change parameters or logical names that require the service to be restarted.

The following files are provided:

To preserve site-specific parameter settings and commands, create the following files. These files are not overwritten when you reinstall TCP/IP Services:

The SMTP services can be started automatically using the TCPIP$CONFIG configuration procedure, or manually using the following command:


To stop SMTP, enter:


18.5 Modifying the SMTP Configuration

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

To store the settings of logical names, include the DEFINE command in one of the following command procedures:

When you redefine the value of a logical, you must restart SMTP. Use the following command procedures to shut down and restart SMTP:

For more information, see Section 18.4.5.

18.5.1 Defining SMTP Logical Names

Each SMTP logical name changes a configuration setting for handling SMTP mail operations. Some SMTP logical names enable or disable configuration options. If you define the logical name, the option is considered to be enabled. If the logical name is not defined, the option is disabled.

To disable this type of configuration option, simply remove the logical name.

To define this type of logical, set its value to 1.

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


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:



Always use the /SYSTEM qualifier when you define an SMTP logical name, except where noted in Table 18-4.

SMTP consists of three main components:

Each logical name can be used by one or more of the SMTP components.

18.5.2 SMTP Logical Names

Table 18-4 lists the SMTP logical names and, for each, describes the purpose, valid settings, and components that use it.

Table 18-4 SMTP Logical Names
Name Component Explanation
TCPIP$SMTP_LOG_LEVEL Symbiont Sets the log level, according to the value you supply:
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.
3---Provides additional information about symbiont initialization and activity during control file processing.
5---Enables full symbiont diagnostics. For use only under the advice of HP customer support.
TCPIP$SMTP_NOSEY Symbiont Used with TCPIP$SMTP_LOG_LEVEL to print the full subject RFC headers information. If not defined, the header is logged as SUBJECT:<omitted> .
Writes line numbers to SMTP logs.
TCPIP$SMTP_SYMB_TRACE Symbiont Logs all messages received from and transmitted to remote SMTP servers. Used to trace the SMTP application layer protocol. Any nonprinting characters 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 file as follows:
send buf=MAIL FROM:<jones@acme.com>\d\a

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

In this message, \d\a is the <CR><LF> .

TCPIP$SMTP_RECV_TRACE Receiver Logs all messages received from and transmitted to remote SMTP clients. Used to trace the SMTP application layer protocol. The same conventions for logging nonprinting characters or control characters are used.
TCPIP$SMTP_RECV_DEBUG Receiver Logs full diagnostics, similar to the TCPIP$SMTP_LOG_LEVEL 5 logical name.
TCPIP$SMTP_VMSMAIL_SEND MAIL$PROTOCOL Logs diagnostic messages to a file named DEBUG.TXT in the default directory. This logical name is reserved for use by HP.
Causes the SMTP address parsing code to log diagnostics. This logical name is reserved for use by HP.
TCPIP$SMTP_SYMB_SNAPSHOT_BLOCKS Symbiont Enables snapshot logging for the symbiont. The value you assign to this logical specifies the size of the snapshot buffer in OpenVMS blocks (1 block = 512 bytes).

In addition to enabling snapshot logging, you must also specify the type of logging using the TCPIP$SMTP_LOG_LEVEL logical name.

When you enable snapshot buffering for the symbiont, it takes some time for the symbiont process to stop when you enter the STOP MAIL command or when you stop the queue. The delay 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:


TCPIP$SMTP_RECV_SNAPSHOT_BLOCKS Receiver Enables snapshot logging for the receiver. The value you assign to this logical name specifies the size of the snapshot buffer in OpenVMS blocks (1 block = 512 bytes). When you enable snapshot buffering, you must also specify the type of logging, using the TCPIP$SMTP_RECV_DEBUG and TCPIP$SMTP_RECV_TRACE logical names.

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:


Instructs SMTP not to consider mail that is sent to the substitute domain as local mail.

By default, SMTP recognizes mail that is addressed to the substitute domain as local mail. To change this default, define the logical name TCPIP$SMTP_NO_SUBS_DOMAIN_INBOUND.

Specifies the default SMTP common directory for an OpenVMS Cluster. By default, the SMTP common directory is SYS$SPECIFIC:[TCPIP$SMTP]. This directory is used to store bounced mail control files, receiver control files, symbiont log files, distribution lists, and the local aliases (TCPIP$SMTP_LOCAL_ALIASES.TXT).

If you define a different directory to be used as the SMTP common directory, make sure the directory you specify allows read (R) and write (W) access. Copy the distribution lists and the local aliases files to the directory you specify.

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.

TCPIP$SMTP_JACKET_LOCAL Symbiont Puts the SMTP jacket on local mail to provide sufficient information to the POP server.
TCPIP$SMTP_INBOUND_NOXVMS Symbiont Disables use of the the RFC X-VMS-To header as the text of the OpenVMS Mail To: header and the X-VMS-CC header as the text of the CC: line. Instead, the RFC To: and CC: headers are used.

If the TCPIP$SMTP_INBOUND_NOXVMS option is not defined, the X-VMS-To and X-VMS-CC headers (if present) are used for the mail header lines.

TCPIP$SMTP_VMSDEF_TO Symbiont Causes OpenVMS callable mail to use the default text for the To: field (the user name). Overrides the TCPIP$SMTP_INBOUND_NOXVMS option for the To: field.
TCPIP$SMTP_MTS_ALLIN1 Symbiont Used for compatibility with older versions of MR/MRGATE. 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 Version 3.3A.
TCPIP$SMTP_POSTMASTER_ALIAS Symbiont Enables mail bounced by the local host to appear to be from a user name other than TCPIP$SMTP@ node.domain.

Specify the user name portion of the address, not including the host name. For example:


    In this example, bounced mail sent from the local host appears to be from Postmaster@ node.domain rather than from TCPIP$SMTP@ node.domain.

Be sure to set up a forwarding entry for the user name you specify. (For more information, see Section 18.2.2.)

TCPIP$SMTP_REWRITE_MTS_FROM Symbiont 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 Symbiont Sends all mail that is destined for another system (nonlocal mail) to the alternate gateway. A zone check is not performed.
TCPIP$SMTP_MX_IF_NOALTGATE Symbiont Use MX records to connect to a host if the alternate gateway cannot be reached.
TCPIP$SMTP_NO_MX Symbiont Does not 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 Symbiont Uses only the contents of the local alias file for determining whether a mail message is local.
TCPIP$SMTP_PROHIBIT_USER_HEADERS MAIL$PROTOCOL Disables outbound alias processing. This prevents the use of the TCPIP$SMTP_FROM logical.
TCPIP$SMTP_SFF_REQUIRES_PRIV MAIL$PROTOCOL Requires users to set either SYSPRV, BYPASS or OPER privileges before using the Send From File (SFF) feature. For more information about this feature, see Section 18.7.
TCPIP$SMTP_8BITMIME_HACK Receiver Enables SMTP to accept 8BITMIME requests from SMTP clients, preventing remote clients from converting the message into a 7-bit format before sending the mail message to the SMTP server. On some displays, such as that used by OpenVMS Mail (a character-cell based mailer), certain 8-bit strings, such as accented characters, are converted and displayed in coded sequences.

To prevent this behavior, set the following logical:


    When this logical is set, the SMTP receiver tells remote SMTP clients that 8-bit characters are supported. In this case, the client does not convert them to 7-bit format.
Prevents SMTP from revealing TCP/IP Services version information.
Requires users to set either SYSPRV, BYPASS or OPER privileges before using SFF.

Previous Next Contents Index