If an SMTP substitute domain is defined, the POP server appends it to the user name, followed by a commercial at sign (@). Otherwise, POP uses the local host name.

For example, with a substitute domain defined as acme.widgets.com , the message header From: Smith becomes:

From: smith@acme.widgets.com

18.1.6.1.4 DECnet Address That Contains Quotation Marks

The values assigned to the TCPIP$POP_QUOTED_DECNET_REWRITE logical name define how the POP server rebuilds a DECnet address that contains quotation marks. The values are:

• GENERIC
  The address is changed to the SMTP format. For example, on host widgets.xyzcorp.com , the message header From: ORDERS::"j_smith@acme.com" becomes:

  From: "ORDER::\"j_smith@acme.com\""@widgets.xyzcorp.com

• NONE
  The From: line is passed to the POP client without being modified. For example:

  From: ORDERS::"j_smith@acme.com"

  
  You cannot reply to this type of mail message because the SMTP server does not accept an address of this form.

• TRANSFORM
  The POP server uses the text inside the quotation marks. For example, the message header From: ORDERS::"j.smith@acme.com" becomes:

  From: j.smith@acme.com

With a cluster-forwarding SMTP address, the POP server uses the SMTP address within the quotation marks. For example, the message header From: ABCDEF::SMTP%"james.jones@federation.gov" becomes:

From: james.jones@federation.gov

18.1.6.1.6 All Other Addresses

For all other address formats, the POP server changes the entire address to the SMTP format:

• Quotation marks in the address are prefixed with the backslash (\) escape character.
• The entire address is placed within quotation marks.
• A commercial at sign (@) is appended.
• If the SMTP substitute domain is configured, it is appended. Otherwise, the name of the local host is appended.

For example, if the substitute domain is xyz.org , the message header From: ABCMTS::MRGATE::"ORDERS::SPECIAL" becomes:

From: "ABCMTS::MRGATE::\"ORDERS::SPECIAL\""@xyz.org

If the logical name TCPIP$POP_IGNORE_MAIL11_HEADERS is defined and the address is an SMTP address, the rebuilt From: field is not displayed to the user. In this case, the POP server sends the actual headers from the body of the mail as the mail headers.

18.2 POP Server Startup and Shutdown

The POP server process starts automatically if you specified automatic startup during the configuration procedure (TCPIP$CONFIG.COM).

The POP server can be shut down and started independently of TCP/IP Services. This is useful when you change parameters or logical names that require the service to be restarted.

The following files are provided:

• SYS$STARTUP:TCPIP$POP_STARTUP.COM allows you to start up the POP server independently.
• SYS$STARTUP:TCPIP$POP_SHUTDOWN.COM allows you to shut down the POP server independently.

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

• SYS$STARTUP:TCPIP$POP_SYSTARTUP.COM can be used as a repository for site-specific definitions and parameters to be invoked when the POP server is started.
• SYS$STARTUP:TCPIP$POP_SYSHUTDOWN.COM can be used as a repository for site-specific definitions and parameters to be invoked when the POP server is shut down.

To modify the default POP server settings and configure additional characteristics, define TCPIP$POP logical names in the POP_SYSTARTUP.COM file. If you modify the POP startup file, restart the POP server to make the changes take effect.

You can modify the following POP server characteristics:

• Security levels
• Error-message logging
• Maximum number of mail messages downloaded per connection
• Link idle time
• Mail header options
• Ability to set the size of the TCP flow control buffer
• Ability to disable the USER and PASS commands
• Ability to purge mail messages

Table 18-2 outlines the POP logical names, default settings, and characteristic options.

Table 18-2 POP Logical Names

Logical Name	Description
TCPIP$POP_SECURITY value	Defines a level of security for the POP server. Determines the timing and text of error messages sent from the POP server to the POP client when authorization errors occur (for example, when an invalid user name or password is sent): FRIENDLY (default) The error messages provide information about a particular error. For example, if a password is incorrect, the client receives the following error message: -ERR password supplied for "jones" is incorrect SECURE One error message is sent in response to all authorization errors except when an invalid user name is specified. For example: Access to user account "jones" denied When the POP server receives an invalid user name, it replies to the POP client with a +OK message. After the POP client sends the password, the POP server sends the -ERR access denied message. This method prevents an unauthorized user from knowing whether the access was denied because of an incorrect user name or password.
TCPIP$POP_TRACE	If defined, the POP server records all messages sent to and received from the POP client in a log file.
TCPIP$POP_LOG_LEVEL value	Defines the type of messages logged by the POP server: ERROR Logs only error messages. INFORMATIONAL (default) Logs informational messages and error messages. THREAD Logs information about client and server interactions as well as informational and error messages. DEBUG Logs full diagnostic information. This is used for problem diagnosis.
TCPIP$POP_POSTMASTER value	Defines a person or persons to receive a failure mail message from the POP server startup procedure (TCPIP$POP_STARTUP.COM) when the POP server exits with an error. For example, to have the failure mail message sent to users JONES and SMITH, define the logical name as follows: $ DEFINE/SYSTEM TCPIP$POP_POSTMASTER "JONES, SMITH"
TCPIP$POP_MESSAGE_MAXIMUM n	Defines the maximum number of mail messages that a single client can download per connection, where n is a number from 0 to 65,535. If not defined, the POP server uses the default value of 0 (no maximum).
TCPIP$POP_LINK_IDLE_TIMEOUT n	Determines the length of time the server allows a link to a POP client to remain idle, where n is a number specified in OpenVMS delta time delimited by quotation marks. A POP link remains active until it is released by the POP client. If not defined, the POP server does not set a link idle value (0 00:00:00.00).
TCPIP$POP_PERSONAL_NAME	If defined, the POP server provides the POP clients with the message header From: fields that include the sender's personal name, if one appeared in the sender's From: field.
TCPIP$POP_LEAVE_IN_NEWMAIL	If defined, mail that has been read by the PC client but not deleted remains in the NEWMAIL folder. Allows users to access mail from different systems and determine when to move or delete the mail from the POP server. If not defined, mail that has been read but not deleted is moved to the MAIL folder.
TCPIP$POP_USE_MAIL_FOLDER	If defined, moves all mail to the MAIL folder and displays this folder instead of the NEWMAIL folder.
TCPIP$POP_FAST_SCAN	If defined, the POP server estimates the number of bytes for the size of the mail message based on the number of lines in the message instead of counting the exact number of bytes. Setting this logical may improve performance.
TCPIP$POP_MAXIMUM_THREADS	Allows you to define the number of process threads that POP can activate. The default is 15. If you set this logical to 1, the POP server becomes single threaded. This logical is recommended only as a temporary solution to system resource problems.
TCPIP$POP_IGNORE_MAIL11_HEADERS	If defined, the POP server ignores the OpenVMS message headers when mail is sent from SMTP, which contains an SMTP address in the From: field. For information about how POP forms message headers, see Section 18.1.6.
TCPIP$POP_SEND_ID_HEADERS	If defined, the POP server sends X-POP3-Server and X-POP3-ID headers for each mail message. If not defined, the ID headers are not sent for any mail from an SMTP address. For information about how POP handles message headers, see Section 18.1.6.
TCPIP$POP_DECNET_REWRITE value	Determines how the POP server rebuilds a simple DECnet address (of the form node::user) in the OpenVMS message From: field when it sends the mail to the POP client; value is one of the following: GENERIC Simple DECnet addresses are changed to the SMTP address format. NONE Simple DECnet addresses are sent unmodified to the POP client. TRANSFORM (default) The POP server attempts to transform the DECnet address into an SMTP address by translating the DECnet node name to a TCP/IP host name. For more information about how POP rebuilds the message headers, see Section 18.1.6.1.2.
TCPIP$POP_QUOTED_DECNET_REWRITE value	Determines how the POP server rebuilds a DECnet address that contains quotation marks (an address of the form node::"user@host") in the OpenVMS Mail From: field when it sends the message to the POP client; value is one of the following: GENERIC DECnet addresses that contain quotation marks are changed to the SMTP address format. NONE DECnet addresses that contain quotation marks are sent unmodified to the POP client. TRANSFORM (default) The POP server uses the text within the quotation marks in the From: field it sends to the POP server. For more information about how POP rebuilds the message headers, see Section 18.1.6.1.4.
TCPIP$POP_SNDBUF n	Allows you to increase or decrease the size of the TCP flow control buffer. Sets the SO_SNDBUF socket option to a specific number; n is the number 512 or greater. If not defined, the POP server uses the value specified in the SHOW PROTOCOL/PARAMETERS command.
TCPIP$POP_DISUSERPASS	Disables the client USER and PASS commands and sends a failure message to the POP client on receipt of either command. For more information about POP user authorization methods, see Section 18.1.5.
TCPIP$POP_PURGE_RECLAIM	If defined, the POP server performs a PURGE/RECLAIM command action after it deletes messages.

18.4 Enabling MIME Mail

The MIME (Multipurpose Internet Mail Extensions) specification provides a set of additional headers you can use so users can send mail messages composed of more than simple ASCII text. MIME is an enhancement to RFC 822.

For MIME mail to be decoded correctly, follow these guidelines:

• Configure the SMTP server with the /OPTION=TOP_HEADERS qualifier, because the first lines of mail text after the four OpenVMS message header lines and the initial separating line must be the MIME headers.
• Configure the POP server with the TCPIP$POP_IGNORE_MAIL11_HEADERS logical name. Otherwise, MIME headers are not parsed as message headers.
• The OpenVMS message From: field must be recognized as an SMTP address. Otherwise, the POP server sends the headers it creates from OpenVMS message headers as the headers of the mail message. For information about POP message headers, see Section 18.1.6.
  Define the logical name TCPIP$SMTP_JACKET_LOCAL to 1 for all SMTP cluster systems, which ensures that the mail will be delivered if the domain in the From: or To: fields appears local. For example:

  $ DEFINE/SYSTEM TCPIP$SMTP_JACKET_LOCAL 1

If MIME mail does not decode, check the mail headers on the client system. If you see multiple blocks of headers and the MIME version header is not in the first block, confirm that you have followed these guidelines.

18.5 Solving POP Problems

The following sections describe ways to troubleshoot problems associated with using the POP server. Some of these include:

• Reviewing error and OPCOM messages sent to the log file
• Simulating a POP client and entering XTND commands

Many of the problems encountered using POP pertain to failed or misinterpreted commands or authorization errors. As the first step toward solving problems, you should review the messages provided by the POP server.

The POP server logs command error and OPCOM (authorization) messages in the file SYS$SYSDEVICE:[TCPIP$POP]POP_RUN.LOG. By default, the POP server sends informative error messages to the client about specific errors.

If the SERVICE database log option REJECT is set, the POP server sends OPCOM messages when it rejects POP client commands because of authorization failures. These errors include the receipt of a client's USER command with an invalid user name, or a PASS command with an invalid password.

By default, OPCOM messages are displayed on the client system and are listed in the log file. To disable OPCOM messages, disable the REJECT logging option for the POP service, as follows:

$ TCPIP SET SERVICE POP/LOG=NOREJECT

18.5.2 Using POP Extension Commands

For troubleshooting purposes, you can simulate a POP client and enter the XTND commands listed in Table 18-3 to obtain information.

Table 18-3 POP Extension (XTND) Commands

Command	Action
XTND CLIENT	Logs POP client information (if the client supplies it). Helpful for troubleshooting if you use POP with a variety of POP clients that identify themselves.
XTND LOGLEVEL	Dynamically adjusts POP logging level. Supported levels are INFORMATIONAL (default), ERROR, THREAD, and DEBUG.
XTND STATS	Displays POP statistics in the following format: +OK Statistics follow Version Number : TCPIP X5.0, OpenVMS V7.1 Alpha Logging Level : DEBUG Current Time : 1999-04-06 06:13:46 Start Time : 1999-04-04 06:42:17 CPU Seconds : 7.89 (0 mins, 7 secs) Current Threads : 1 Total Threads : 6 Max Threads : 1 Too Many Threads : 0 Normal Disconnects : 5 Abnormal Disconnects : 0 Client Timeouts : 0 Blocked Socket Count : 0 Retrieved Messages : 4 Retrieved Octets : 1102 Average Octets : 275 Minimum Octets : 222 Maximum Octets : 319 Auth Failures : 1 Current Users : 0. smith
XTND SHUTDOWN	Performs an orderly shutdown of POP. Waits for current client connections to disconnect. Recommended over the DCL command STOP.

To simulate a POP client and obtain information:

1. Enter the TELNET command to the POP port (110).
2. Using the USER and PASS command, enter your user name and password.
3. Enter an XTND command.

For example:

$ TELNET UCXSYS 110 %TELNET-I-TRYING, Trying ... 16.20.208.53 %TELNET-I-SESSION, Session 01, host ucxsys, port 110 +OK POP server TCPIP Version 5.0, OpenVMS V7.1 Alpha at ucxsys.acme.com, up since 1999-04-04 06:42:17 <24A00E61._6_APR_1999_06_02_31_15@ucxsys.acme.com> USER username +OK Password required for "username" PASS password +OK Username/password combination ok XTND LOGLEVEL DEBUG +OK logging level changed to debug QUIT +OK TCPIP POP server at ucxsys.acme.com signing off.