HP TCP/IP Services for OpenVMS

Previous Contents Index

19.5.4 Specifying Certificate and Key Files

You can use logical names to specify the location of certificate and key files. The values assigned to these logical names may be full or partial file specifications. That is, you may specify the directory, the file name, or both. The parts of the file specification that you do not specify are supplied from the defaults.

The following examples show how to use these logical names. Each example shows the logical name, its value, and the full file specification that the secure POP server uses for the associated file.

  1. This example allows you to keep the files in the SSL directories but make them unique for the exclusive use of the secure POP server.
    Logical Name Defined To File Specification

  2. This example allows you to move the files to the TCPIP$POP account's home directory for exclusive use by the secure POP server.
    Logical Name Defined To File Specification
  3. This example assumes that CLUSTERDEV points to a device that is visible across the OpenVMS Cluster and allows you to have single copies of the files. Make sure the device is mounted before starting the POP server.
    Logical Name Defined To File Specification

If you use the full defaults for the POP certificate and key files, any use of the SSL certificate tool to create a new certificate or key file might affect Secure POP because the POP server and certificate tool use the same default file names.

19.5.5 Security Recommendations for the SSL Key File

To maximize security, you should restrict access to the .KEY file to users who need to use it. You can use a combination of file protections, file ownership, and ACLs to accomplish this. For the POP server to access the .KEY file, read access to the file must be granted to the TCPIP$POP account. If you are sharing the .KEY file between different SSL-enabled applications, those applications must also have access to the .KEY file.

Because the information in the certificate file is public, it does not require the same security restrictions.

19.5.6 Encrypted Private Keys

Secure POP does not support encrypted private keys. When you generate a private key, you can choose to have the key encrypted in a passphrase that you provide. This requires all users of the private key to have access to the passphrase. The Secure POP server cannot access the passphrase.

19.6 Solving POP Problems

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

19.6.1 POP Server Messages

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:


19.6.2 Using POP Extension Commands

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

Table 19-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-I-TRYING, Trying ... 
%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 
 +OK logging level changed to debug 
 +OK TCPIP  POP server at ucxsys.acme.com signing off. 

Chapter 20
Configuring and Managing the IMAP Server

The IMAP server for OpenVMS Mail and the Simple Mail Transfer Protocol (SMTP) server software work together to provide reliable mail management in a client/server environment.

The IMAP server allows users to access their OpenVMS Mail mailboxes by clients such as Microsoft Outlook so that they can view, move, copy and delete messages. The SMTP server provides the extra functionality of allowing the clients to create and send mail messages.

After the IMAP server is enabled on your system, you can modify the default characteristics by editing the configuration file (described in Section 20.2.3).

This chapter reviews key IMAP concepts and describes:

For information about setting up your client PC and using IMAP, refer to the HP TCP/IP Services for OpenVMS User's Guide.

20.1 Key Concepts

IMAP stands for Internet Message Access Protocol. The IMAP server allows users to access their OpenVMS Mail mailboxes by clients communicating with the IMAP4 protocol as defined in RFC 2060. The supported clients used to access email are PC clients running Microsoft Outlook or Netscape Communicator.

The IMAP server is by default assigned port number 143, and all IMAP client connections are made to this port.

The following sections review the IMAP process and describe how the TCP/IP Services software implements IMAP. If you are not familiar with IMAP, refer to RFC 2060 or introductory IMAP documentation for more information.

20.1.1 IMAP Server Process

The IMAP server is installed with SYSPRV, BYPASS, DETACH, SYSLCK, SYSNAM, NETMBX, and TMPMBX privileges. It runs in the TCPIP$IMAP account, which receives the correct quotas from the TCPIP$CONFIG procedure. The IMAP server is invoked by the auxiliary server.

The IMAP server uses security features provided in the protocol and in the OpenVMS operating system, as well as additional security measures. These methods provide a secure process that minimizes the possibility of inappropriate access to a user's mail file on the served system.

You can modify the IMAP server default characteristics and implement new characteristics by defining the configuration options described in Section 20.2.3.

20.2 IMAP Server Control

The system manager controls the management functions of the IMAP server. These functions include:

The following sections describe these management functions.

20.2.1 Starting Up and Shutting Down the Server

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

The IMAP server can be shut down and started independently of TCP/IP Services. This is useful if you change configuration options that require the service to be restarted.

The following files are provided:

To preserve site-specific parameter settings and commands, create the following files:

Note that these files are not overwritten when you reinstall TCP/IP Services.

20.2.2 Viewing Server Event Log Files

The IMAP server records start and stop server events in an event log file. Other events, such as failed user authentication events, are also recorded in this log file. The file is called TCPIP$IMAP_HOME:TCPIP$IMAP_EVENT$node.LOG, where node is the name of the node on which the server is running.

20.2.3 Modifying IMAP Server Characteristics

To modify the default IMAP server settings and to configure additional characteristics, edit the configuration file TCPIP$IMAP_HOME:TCPIP$IMAP.CONF. If you modify the IMAP server configuration file, restart the IMAP server to make the changes take effect.

You can modify the following IMAP server characteristics:

For guidelines about specifying configuration options in the IMAP.CONF configuration file, see Section 1.1.5.

Table 20-1 describes the IMAP option names, default settings, and characteristics that you can modify.

Table 20-1 IMAP Configuration Options
Option Name Description
Server-Port TCP/IP port number for connection between IMAP clients and the IMAP Server. The default value is 143.
Ignore-Mail11-Headers If set to True, the default, the IMAP server ignores the OpenVMS message headers when mail is sent via SMTP, which contains an SMTP address in the From: field. For information about how IMAP forms message headers, see Section 19.1.6.
Send-ID-Headers If set to True, the IMAP server sends X-IMAP4-Server and X-IMAP4-ID headers for each mail message. If not defined or if set to False (the default), the ID headers are not sent for any mail from an SMTP address. For information about how IMAP handles message headers, see Section 19.1.6.
Decnet-Rewrite Determines how the IMAP server rebuilds a simple DECnet address (of the form node:: user) when it sends the mail to the IMAP client The value of this option can be one of the following:

    Simple DECnet addresses are changed to the SMTP address format.

  • NONE

    Simple DECnet addresses are sent unmodified to the IMAP client.

  • TRANSFORM (default)

    The IMAP 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 IMAP rebuilds the message headers, see the HP TCP/IP Services for OpenVMS User's Guide.

Quoted-Decnet-Rewrite Determines how the IMAP server rebuilds a DECnet address that contains quotation marks (of the form node:: "user@host") in the OpenVMS Mail From: field when it sends the message to the IMAP client. The value of this option may be one of the following:

    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 IMAP client.

  • TRANSFORM (default)

    The IMAP server uses the text within the quotation marks in the From: field it sends to the IMAP server.

For more information about how IMAP rebuilds the message headers, see Section

Personal-Name If defined, the IMAP server provides the IMAP clients with the message header From: fields that include the sender's personal name, if one appeared in the sender's From: field.

Some IMAP client systems are confused by the use of personal names when you attempt to reply to a mail message or when the name contains commas or other special characters. If you define the configuration option Personal-Name described in the HP TCP/IP Services for OpenVMS Management guide, then before going live make sure you test the configuration carefully with your IMAP client systems to ensure that message replies work successfully.

Gateway-Node If defined, the local node or cluster name is superseded by the value of this configuration option, when supplying a route from SMTP into DECnet as part of an address. The Gateway-Node value should be an Internet address of a TCP/IP Services SMTP server node.

For example, suppose a Decnet node name of ORDERS cannot be mapped, and the address is ORDERS::J_SMITH and Gateway-Node is defined to be widgets.xyzcorp.com, then the resulting address will be "ORDERS::J_SMITH"@widgets.xyzcorp.com.

Max-Connections Each time the number of live connections to the server reaches the Max-Connections parameter (default = 25), a new process is started. The old server does not accept new connections and will shut down as soon as all existing connections are closed by the client or after 20 minutes, whichever comes first. Service may be interrupted for up to 5 seconds while one process takes over from the other.

The service limit default value (currently 16) should not be less than the application limit of 25. Use the TCP/IP management command SET SERVICE IMAP/LIMIT to increase the server limit to a large number, such as 1600.

You should avoid changing the value of this option unless instructed by HP support personnel. Too low a setting will result in unnecessary delays, and too high a setting will result in too many connections contesting per-process-limited OpenVMS Mail resources.

Message-Cap The IMAP server has a configurable limit on the number of messages displayed in a folder, defined by the Message-Cap parameter. If this parameter is not defined, or if it is set to the default of 0, then no limit is applied.

If a user tries to list a folder containing more messages than the limit, then only the first n messages will be displayed, where n is the value of the Message-Cap parameter. To display more messages, delete or move mail messages, and purge the folder of deleted messages.

Server-Trace The default for this setting is False. If set to True, a trace file is created as TCPIP$IMAP_HOME:TCPIP$IMAP_ node_ mmddhhmmssTRACE.LOG, where node is the node name where the IMAP server is running and mmddhhmmss is the time that the trace log is created. All communication between IMAP clients and the IMAP server is logged, with the exception of passwords. Since a large amount of data is recorded on a busy system, it is recommended that tracing be turned on only for short periods. To turn tracing on or off, it is necessary to restart the IMAP server.
Trace-Synch This setting only applies when the setting Server-Trace is set to True. Trace-Synch governs the frequency with which the trace log is flushed.

Trace-Synch is a non-negative integer value which specifies the number of trace log writes between each full flush of the trace log output to disk. Flushing the log more frequently lowers the number of log writes that could be lost at the end of the log in the event of a server process crash but it also means slower performance. Conversely less frequent flushing means better performance but more lines possibly lost at the end of the log on a server crash.

A value of 0, which is the default, means not to flush to disk until the server process exits, though OpenVMS Record Management Services (RMS) will flush to disk periodically anyway. This is the highest performance option but in the event of a server crash many lines of trace log information might be lost.

If you want the server to flush on each log write set Trace-Synch to 1. This is the slowest performer but safest regarding potential loss of trace log data in the event of a server crash.

Benchmark testing has proven that a value of 100 strikes a good balance between performance and data loss.

20.2.4 Tuning the Server

This section is intended for system managers who want to know more detailed information about the IMAP server. Tuning Issues

The only tuning issue pertains to the server's use of Virtual Memory (VM). The IMAP server can use large amounts of VM and might require some tuning to get dependable performance.

The exhaustion of virtual memory can be manifested in different ways including the server process crashing with error messages that could appear to be caused by different problems such as access violations, ROPRAND as well as INSVIRMEM errors. Some crashes produce PTHREAD_DUMP.LOG files in TCPIP$IMAP_HOME.

Although the process crashes might appear to be from different causes, memory exhaustion can be confirmed by examining the job termination information at the end of the TCPIP$IMAP_RUN.LOG. If the "Peak virtual size" value is at or above the TCPIP$IMAP account's PGFLQUO value, then the process probably terminated due to insufficient virtual memory.

The IMAP server process sometimes hangs rather than exits when it consumes all of its dynamic memory. Use the following commands to examine the PAGFILCNT of the IMAP server process. If the value is at or near zero then the hang is caused by insufficient virtual memory.

    $! This shows the PID(s) of the IMAP process(es)... 
    $! To show the process's PAGFILCNT do 
    $ WRITE SYS$OUTPUT "''F$GETJPI("insert-pid-here","PAGFILCNT")'" Tuning Options

The use of virtual memory by the IMAP server can be controlled by one or both of the following actions:

Previous Next Contents Index