HP OpenVMS Systems Documentation

Content starts here HP TCP/IP Services for OpenVMS

HP TCP/IP Services for OpenVMS

Previous Contents Index

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:

  • Starting and stopping the server
  • Viewing event logs for each server
  • Modifying options that control server behavior
  • Tuning the server

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:

  • SYS$STARTUP:TCPIP$IMAP_STARTUP.COM allows you to start the IMAP server.
  • SYS$STARTUP:TCPIP$IMAP_SHUTDOWN.COM allows you to shut down the IMAP server.

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

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

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:

  • Server port number
  • Mail header options
  • Number of live connections per server process

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:

  • Give more dynamic memory to an IMAP server process
    If sufficient memory is available, increase the PGFLQUO of the TCPIP$IMAP account (adjusting any SYSGEN parameters that limit PGFLQUO). Take into account that multiple server processes might need to run concurrently on a heavily loaded system when assigning a high PGFLQUO.
    The amount of memory an IMAP server can use at peak is the sum of the following elements:
    • Memory required at start-up: 10000 blocks
    • Memory per connection: 1500 blocks. The number of connections per Server is limited by the Max-Connections configuration option, default 25. Thus in a default configuration the amount required is 37500 blocks.
    • Memory per message: If a user lists a large folder, then the Server requires an extra 3 blocks per message. If you estimate that your users are opening, at peak, folders with an average of 1000 messages, then the amount of memory required is the following:
      Max-Connections * 3 * 1000
      This is 75,000 blocks in a default configuration. The Message-Cap configuration option can be used to limit the maximum number of messages in a folder that can be viewed. If Message-Cap is defined, then the formula is:
      Max-Connections * 3 * Message-Cap

    For more information about these configuration options, see Table 20-1.
  • Reduce IMAP server demand for memory
    There are two IMAP configuration options that can be used to reduce each IMAP server process's consumption of dynamic memory: Max-Connections and Message-Cap.
    Because Max-Connections limits the number of connections that can be served simultaneously, it implicitly limits the quantity of VM consumed by each IMAP server process. Note that while reducing Max-Connections reduces the dynamic memory consumption of each IMAP server process it results in more IMAP server processes; there will be more processes each using less dynamic memory.
    Message-Cap limits the number of messages passed back to the client when a folder is selected.

20.3 Enabling MIME Mail

The MIME (Multipurpose Internet Mail Extensions) specification provides a set of additional headers you can use so that 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 IMAP server with the option Ignore-Mail11-Headers set to True, or leave this option undefined, since True is the default value. Otherwise, MIME headers are not parsed as message headers.
  • The OpenVMS message From: field must be recognized as an SMTP address. Otherwise, the IMAP server sends the headers it creates from OpenVMS message headers as the headers of the mail message. For information about IMAP message headers, see Section 19.1.6.
    Define the logical name TCPIP$SMTP_JACKET_LOCAL to 1 for all SMTP cluster systems. This ensures that the mail is delivered if the domain in the From: or To: field appears local. For example:


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. Note that the headers of messages forwarded over OpenVMS Mail are mapped only if there is no cover note (that is, if the headers of a forwarded message are at the top of the message immediately following the headers of the forwarding message).

Chapter 21
Configuring XDMCP-Compatible X Displays

The X Window System, developed by the Massachusetts Institute of Technology, is a network-based graphics window system based on the client/server application model. The X protocol, through which the client and server communicate, runs on TCP/IP Services or DECnet. This means that an X display on one system can display information output from an application running on another system in the network.

An X display is a graphic output device that is known by The X Display Manager (XDM), such as:

  • An X terminal
  • A workstation that has the X Window System software installed and configured
  • A PC running Windows or Windows NT and some X Window System software, such as eXcursion or Exceed

This chapter reviews key concepts, discusses how to configure an XDMCP-compatible X display using the TCP/IP Services XDM server, and covers the following topics:

21.1 Key Concepts

The X Display Manager (XDM) is an X client that manages the login process of a user's X window session. XDM is responsible for displaying a login screen on a display specified by an X server, establishing an X window session, and running scripts that start other X clients. When the user logs out of the X session, XDM is responsible for closing all connections and resetting the terminal for the next user session.

An earlier version of XDM had limitations that were resolved with the introduction of the XDM Control Protocol (XDMCP). Before XDMCP, XDM used the XSERVERS file to keep track of the X terminals for which it managed the login process. At startup, XDM initialized all X terminals listed in the XSERVERS file. If the X terminal was turned off and then on again, XDM had no way of knowing that a new login process should be initiated at the X terminal. To reinitialize the X terminal, the XDM process had to be restarted. This problem was solved through the development of the XDM Control Protocol.

Now, because of XDMCP, XDM can listen for management requests from X terminals as well as use the XSERVERS file for the X terminals that were not XDMCP compatible. Most X terminals today are XDMCP compatible.

The TCP/IP Services implementation of XDM is based on the X11R6.1 release from X Consortium.

21.2 XDMCP Queries

XDMCP provides the following methods to query XDM for service:

  • Direct
    X terminals, configured for the direct request method, send a connection request to a specific host.
  • Broadcast
    X terminals, configured for a broadcast request, send out a general query to ask for service from all nodes running XDM. A list of the responding nodes is then presented to the user for selection by the client software.
  • Indirect
    An indirect request is used to relay a request for service from one XDM node to another.

The TCP/IP Services implementation of XDM does not support the indirect query with a chooser box supported by some other XDM servers.

An authentication protocol is supported for all three types of requests.

21.3 XDM Configuration Files

If the files are present, XDM uses the following files to configure the X display environment:

  • Master configuration (XDM_CONFIG.CONF)
  • Servers (XSERVERS.TXT)
  • Access (XACCESS.TXT)
  • Keys (XDM_KEYS.TXT)
  • Session (XDM_XSESSION.COM)

After installing XDM, you can use the TCP/IP Services-supplied configuration templates located in SYS$SPECIFIC:[TCPIP$XDM] to create the configuration files. The default directory location of the configuration and template files is the SYS$SPECIFIC:[TCPIP$XDM] directory.

21.3.1 Master Configuration File

The master configuration file, which is an optional file, specifies the location and file names of the other configuration files used to control the operation of XDM.

Example 21-1 shows the contents of the default configuration template file ([TCPIP$XDM]XDM_CONFIG.TEMPLATE) supplied with XDM:


! File name:      XDM_CONFIG.CONF
! Product:        HP TCP/IP Services for OpenVMS
! Version:        V5.4
! © Copyright 1976, 2003 Hewlett-Packard Development Company, L.P.

! XDM master configuration file

DisplayManager.keyFile:            SYS$SPECIFIC:[TCPIP$XDM]XDM_KEYS.TXT
DisplayManager.servers:            SYS$SPECIFIC:[TCPIP$XDM]XSERVERS.TXT
DisplayManager.accessFile:         SYS$SPECIFIC:[TCPIP$XDM]XACCESS.TXT
DisplayManager*RemoveDomainname:   true

The file specification for the master configuration file is:


XDM uses the DisplayManager*RemoveDomainname: value when computing the display name for XDMCP clients. BIND, when performing a host name lookup creates a fully qualified host name for the X terminal. When this keyword is set to TRUE, XDM removes the domain name portion of the host name if it is the same as the local host domain. The default value of DisplayManager*RemoveDomainname: is TRUE.

Previous Next Contents Index