This manual provides installation and setup instructions for Message Exchange, electronic mail software for VMS systems.

Revision/Update Information: This is a revised manual.

Operating System and Version: OpenVMS Alpha [tbd] or later

OpenVMS Industry Standard 64 [tbd] or later

Software Version: Message Exchange V6.0

Copyright ©2008 Matthew Madison.

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of the copyright owner nor the names of any other contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Portions of the software were adapted from other open source projects. Refer to the Release Notes for copyright and license information.

Contents



This guide describes how to install Message Exchange (MX).

Intended Audience

This manual is intended for use by the system manager or any individual responsible for installing and maintaining MX.

Document Structure

This guide consists of three chapters and two appendices.

Chapter 1	Contains pre-installation information.
Chapter 2	Describes the MX installation procedure.
Chapter 3	Contains post-installation information.
Appendix A	Describes the contents of the MX distribution kit.
Appendix B	Contains a list of the files created by an installation.

Related Documents

You can find additional information in the following documents:

• Message Exchange Management Guide describes the management of the MX software.
• Message Exchange User's Guide describes MX features available to general users.
• Message Exchange Programmer's Guide describes the various programming interfaces for customizing MX.
• Message Exchange Mailing List/File Server Guide describes the MX Mailing List and File Server.
• Message Exchange Release Notes contain information and updates not included in this manual. The release notes are part of the software distribution kit. Release notes are also included in the distribution kit for NETLIB, the TCP/IP interface library.
• VMS Mail Utility Manual, part of the VMS documentation set, contains information about the VMS Mail utility.

This chapter describes the steps that should be taken prior to installing the Message Exchange software.

1.1 Prerequisite Software

MX requires OpenVMS Alpha [version tbd] or later, and/or OpenVMS Industry Standard 64 [version tbd] or later. The SMTP support option requires a NETLIB-supported TCP/IP package (refer to the NETLIB release notes for further information). SMTP-over-DECnet requires DECnet, but does not require either NETLIB or any TCP/IP package.

1.2 Upgrading from Previous Versions of MX

Starting with MX V6.0, upgrades from versions of MX prior to V6.0 are not supported.

1.3 VMScluster Support and MX Clusters

MX fully supports VMScluster systems in both homogeneous and heterogeneous configurations.

An "MX cluster" consists of one or more VMScluster nodes that meet the following criteria:

1. All nodes in the MX cluster share one User Authorization File (SYSUAF.DAT) and one VMS Mail profile (VMSMAIL_PROFILE.DATA).
2. All nodes have mounted the disk that contains the MX images and directories.
3. All nodes have mounted the disk that contains the message queue.
4. If MX is to be used for network mail, at least one node in the MX cluster is running the networking software required for each type of network link desired.
5. The logical name MAIL$SYSTEM_FLAGS is defined to a value of at least 3. (Refer to VMS Mail Utility Manual for further information on MAIL$SYSTEM_FLAGS.)

For homogeneous VMScluster systems, the MX cluster will usually include all nodes in the VMScluster.

1.3.1 Answering VMScluster-related Installation Questions

The MX installation procedure automatically detects that you are in a VMScluster and will ask additional questions during installation about where in the cluster each installed MX processing agent should run. The processing agents are programs which are run as detached processes. They can be run on any or all nodes in the cluster (following the MX Cluster guidelines outlined above), and will automatically cooperate in providing their respective services.

When asked to provide a cluster node name for running the processing agents, be sure to specify the SCSNODE name (or use an asterisk ("*") to have an agent run on all nodes in the cluster).

1.3.2 Mixed-Architecture VMSclusters

Mixed-architecture VMSclusters (those containing a combination of VAX, Alpha, and/or IA64 systems) are fully supported by MX. The MX directory tree can be shared by all three systems if it resides on a common disk. When systems share a common MX directory, agents may be run on any or all types of systems.

When MX is first installed, and the installation procedure determines that the node is part of a cluster, it will record installation information in the MX directory tree. A subsequent installation of the same version of MX in the same directory tree, but on a system of a different architecture, will cause the installation procedure to ask whether or not just architecture-specific files should be installed.

The MX_ROOT: directory tree contains architecture-specific directories for executables: MX_ROOT:[EXE] for VAX executables, MX_ROOT:[ALPHA_EXE] for Alpha executables, and MX_ROOT:[IA64_EXE] for IA64 executables. The logical MX_EXE:, which is used in all examples below, will automatically be defined appropriately on each system in the cluster.

1.4 Determining Your Node Name

MX requires two node names for its operation. The first, the MX cluster name, is used by MX to coordinate access to the message queue.

• For a stand-alone (non-clustered) system, the MX cluster name usually corresponds to your DECnet node name. If you are not running DECnet, you can use any 1-to-6 character name.
• For a VMScluster system, the MX cluster name should correspond to your DECnet cluster alias node name. If do not have a cluster alias, you should use the DECnet node name of one of the nodes in the MX cluster.

The second node name is the MX network node name. This is the name that is used by the MX software to identify mail originating locally. You should decide on a node name for your system before installing the MX software. If your host has a registered Internet domain name, you should use that name. If you are on a UUCP network and do not have a registered Internet domain name, you should use your UUCP host name. Otherwise, you should use a host name that fits with the naming conventions at your site.

In an MX cluster environment, MX will use a single network name to identify the entire cluster. If you have several nodes with their own network node names, and your networking software does not support the use of a cluster-wide alias, you could either pick one node to be the "master" for E-mail purposes or use the MX_VMSMAIL_FROM_FORMAT logical name (described in Message Exchange Management Guide) to have each node insert its own host name in return addresses on outgoing messages. What you do will depend on your network software and setup.

1.5 Accessing the Online Release Notes

MX provides online release notes, which you can display or print by using VMSINSTAL with the OPTIONS N parameter. After the installation, you can read the release notes by printing the file SYS$HELP:MXvvn.RELEASE_NOTES, where "vvn" denotes the version number of the software. For example, for version V5.2 of MX, the file name would be MX052.

The release notes for NETLIB are provided in the file SYS$HELP:NETLIBvvn.RELEASE_NOTES, where "vvn" identifies the version of NETLIB shipped with the MX distribution kit. This file is created during NETLIB installation and is not accessible through VMSINSTAL OPTIONS N.

1.6 Mailer Accounts

You can run the detached processes MX uses under the SYSTEM account, or, if you prefer, under a separate "mailer" account.

Note, however, that using a mailer account may complicate the process for starting up MX on your system; see Section 3.4 for further information on MX startup procedures.

If you intend to use an account other than SYSTEM for running the MX detached processes, you should create the account before installing MX. The mailer account should have the following attributes:

• a username of eight characters or less.
• full batch access, no interactive access.
• network access, only if SMTP-over-DECnet is used and you do not wish to create a dedicated account for the SMTP-over-DECnet object.
• the INTERNET_ACCESS identifier, if needed for CMU-Tek TCP/IP access.
• the ARPANET_ACCESS identifier, if needed for CMU-Tek TCP/IP access.
• the following authorized and default privileges: CMKRNL, SYSNAM, DETACH, WORLD, PHY_IO, SYSPRV, SYSLCK, EXQUOTA, TMPMBX, and NETMBX. (BYPASS may also be required if using DECUS UUCP.)
• a subprocess limit (PRCLM) of at least 1.
• no detached process limit (MAXDETACH of 0).
• a login directory that is owned by the account.

Figure 1-1 shows the UAF entry for a typical Mailer account.

1.6.1 SMTP-over-DECnet Dedicated Account

If you intend to use the MX SMTP-over-DECnet support, you may want to establish a special server account to be used exclusively for the DECSMTP DECnet object. If so, you should ensure that the accounts have NETWORK access and the privileges TMPMBX, NETMBX, SYSPRV, and SYSLCK (both authorized and default). Figure 1-2 shows the UAF entry for a typical SMTP-over-DECnet server account. See Section 3.8 for more information on setting up the MX SMTP-over-DECnet support.

Figure 1-1 Mailer Account attributes

Username: MAILER Owner: MX Mailer account Account: NETSTUF UIC: [1076,76] ([MAILER]) CLI: DCL Tables: DCLTABLES Default: USER_DISK:[MAILER] LGICMD: NL: Login Flags: Disctly Defcli Primary days: Mon Tue Wed Thu Fri Secondary days: Sat Sun Primary 000000000011111111112222 Secondary 000000000011111111112222 Day Hours 012345678901234567890123 Day Hours 012345678901234567890123 Network: ----- No access ------ ----- No access ------ Batch: ##### Full access ###### ##### Full access ###### Local: ----- No access ------ ----- No access ------ Dialup: ----- No access ------ ----- No access ------ Remote: ----- No access ------ ----- No access ------ Expiration: (none) Pwdminimum: 3 Login Fails: 0 Pwdlifetime: (none) Pwdchange: (none) Last Login: (none) (interactive), 19-JAN-1990 14:38 (non-interactive) Maxjobs: 0 Fillm: 60 Bytlm: 36000 Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0 Maxdetach: 0 BIOlm: 20 JTquota: 1024 Prclm: 4 DIOlm: 18 WSdef: 512 Prio: 4 ASTlm: 325 WSquo: 512 Queprio: 100 TQElm: 10 WSextent: 2048 CPU: (none) Enqlm: 600 Pgflquo: 25600 Authorized Privileges: CMKRNL SYSNAM DETACH TMPMBX WORLD EXQUOTA NETMBX PHY_IO SYSPRV SYSLCK Default Privileges: CMKRNL SYSNAM DETACH TMPMBX WORLD EXQUOTA NETMBX PHY_IO SYSPRV SYSLCK Identifier Value Attributes ARPANET_ACCESS %X80010042 NORESOURCE NODYNAMIC INTERNET_ACCESS %X80010043 NORESOURCE NODYNAMIC

Figure 1-2 SMTP-over-DECnet server account attributes

Username: DNSMTP_SRV Owner: MX DECSMTP object account Account: NETSTUF UIC: [1076,77] ([DNSMTP_SRV]) CLI: DCL Tables: DCLTABLES Default: USER_DISK:[DNSMTP_SRV] LGICMD: NL: Login Flags: Disctly Defcli Primary days: Mon Tue Wed Thu Fri Secondary days: Sat Sun Primary 000000000011111111112222 Secondary 000000000011111111112222 Day Hours 012345678901234567890123 Day Hours 012345678901234567890123 Network: ##### Full access ###### ##### Full access ###### Batch: ----- No access ------ ----- No access ------ Local: ----- No access ------ ----- No access ------ Dialup: ----- No access ------ ----- No access ------ Remote: ----- No access ------ ----- No access ------ Expiration: (none) Pwdminimum: 3 Login Fails: 0 Pwdlifetime: (none) Pwdchange: (none) Last Login: (none) (interactive), 19-JAN-1990 14:38 (non-interactive) Maxjobs: 0 Fillm: 60 Bytlm: 36000 Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0 Maxdetach: 0 BIOlm: 20 JTquota: 1024 Prclm: 4 DIOlm: 18 WSdef: 512 Prio: 4 ASTlm: 325 WSquo: 512 Queprio: 100 TQElm: 10 WSextent: 2048 CPU: (none) Enqlm: 600 Pgflquo: 25600 Authorized Privileges: TMPMBX NETMBX SYSPRV SYSLCK Default Privileges: TMPMBX NETMBX SYSPRV SYSLCK

1.7 Installation Procedure Requirements

Before installing MX, ensure that the following privileges, resources, and requirements are met:

• Operating System Version
  MX V6.0 runs on OpenVMS Alpha [version tbd] and higher, and OpenVMS Industry Standard 64 [version tbd] and higher.
• Layered Product Versions
  Refer to the NETLIB release notes for details on TCP/IP requirements.
• all the normal privileges and quotas of the default SYSTEM account.
• approximately 5 minutes to 1 hour, depending on your system configuration, distribution medium, and options selected.
• On Alpha systems, 50 free global sections and 2000 free global pagelets. On VAX systems, 50 free global sections and 1000 free global pages. On Industry Standard 64 systems, 50 free global sections and 4000 free global pagelets.
• approximately 30,000 free blocks on a disk for use during the installation procedure; this can be the system disk or a disk specified with the VMSINSTAL AWD option.
• approximately 5 free blocks on the system disk for permanent files.
• approximately 5,000 free blocks on any disk for MX base software, and the following additional free disk blocks:
  • approximately 1,000 free blocks for each MX optional transport agent.
  • approximately 1,000 free blocks for mailing list/file server support.
  • approximately 8,500 free blocks for MX documentation.
  • approximately 600 free blocks for the MX example files.
  • approximately 2,700 free blocks for the MX contributed files and programs.
• a minimum of 5,000 free blocks on any disk for message queue space.
• if you are running CMU-Tek TCP/IP, the value of the SYSGEN parameter MAXBUF must be at least 2300.

If MX is already installed on your system, you should create an MCP command file from your current MX configuration database prior to installing a new version of MX. To do this, use the following commands:

$ MCP :== $MX_EXE:MCP $ MCP/FILE=MX_DIR:MX_CONFIG SHOW ALL/OUTPUT=MX_DIR:OLD_CONFIG.MCP/COMMAND

You can then use this MX command file to re-create your MX configuration database once the new version of MX is installed.

MX uses VMSINSTAL for installation. If you do not know how to use VMSINSTAL, you should first read the chapter on installing software in the VMS System Manager's Manual. For the installation, you should be logged into the SYSTEM account, or another suitably privileged account.

If any MX processes are currently running, you should stop them before installing a new version of MX. Unprocessed mail should remain queued until you start the new MX processes.

2.2 Invoking VMSINSTAL

Invoke VMSINSTAL to install MX.

$ @SYS$UPDATE:VMSINSTAL MXvvn ddcu:

Substitute the appropriate values for vvn and ddcu.

OpenVMS Alpha Software Product Installation Procedure V7.2 It is dd-Mmm-yyyy at hh:mm. Enter a question mark (?) at any time for help.

If there are any users logged into the system, you will see the message

%VMSINSTAL-W-ACTIVE, The following processes are still active: ...process names...

You can install MX while users are logged in, though it is safer to perform the installation while no one is logged in and while your network links are shut down.

* Do you want to continue anyway [NO]?

If you wish to continue, answer YES.

* Are you satisfied with the backup of your system disk [YES]?

If you feel comfortable with your system disk backup, answer YES. Otherwise, answer NO, perform the backup, then restart the installation procedure.

2.3 Preliminary Installation Checks

The installation procedure first checks to make sure that the version of VMS that you are running is compatible with the version of MX being installed, and does some preliminary checks on disk space. It then tries to determine the type of installation and the location of the MX directory tree.

2.3.1 Ensuring that MX is Currently Shut Down

If a version of MX is currently installed, the installation procedure will check to see if any MX delivery agents are currently running. If so, it will warn you of this and ask if you wish to continue with the installation:

%MX-I-NOTDOWN, MX delivery agents have not been shut down. * Do you wish to continue [NO]?

It is strongly recommended that you answer NO to this question, shut down MX, then restart the installation.

2.3.2 Determining the Installation Type

The installation procedure examines the system to determine if a version of MX is already installed. If there is a version of MX installed, it then determines whether this is an upgrade from an upgradable previous version of MX, or a reinstall of the current version. In either case, the installation procedure asks you if you wish to update the MX installation it found:

%MX-I-INSTALDET, An installation of MX Vv.u has been detected at dev:[dir]. * Do you wish to update the existing installation [YES]?

If you answer YES to this question, the installation procedure will skip the question about selecting a location for the MX directory tree.

If this is a fresh install, or you answer NO when asked about updating an existing installation, you are then asked:

* Where should the MX top directory be located [SYS$SYSDEVICE:[MX]]:

You may place the MX directories on any disk you like. If MX is already installed on the system and its logical names are defined, the default answer will be the definition of your existing MX root directory.

MX next determines if the system is part of a VMScluster, and if the version of MX currently being installed has already been installed once on a node in the cluster of a different architecture. If both of these are found to be true the installation procedure then asks:

* Do you wish to install only arch-specific files [YES]?

You should answer YES to this question unless you really want to re-install the architecture-independent files.

The last of the preliminary questions is

* Do you want to purge files replaced by this installation [YES]?

If this is the first time you have installed MX, answering NO to this question can save some time when the MX files are moved into their directories.

2.4 Component Selection

A menu of MX components appears next, and you are asked to enter your choices from the menu:

1. [ ] Base MX software 2. [ ] NETLIB network support 3. [ ] SMTP interface support 4. [ ] SMTP-over-DECnet support 5. [ ] Site-provided interface support 6. [ ] Mailing List/File Server support 7. [ ] Documentation 8. [ ] Example files and programs 9. Exit * Your choice [9]:

The exact contents of this menu may differ from the above display, depending on the system's architecture. In addition, if this is an architecture-specific-only installation (see Section 2.3.3), the last three choices in the menu will not be displayed.

Enter the number corresponding to the component you wish to install; multiple components may be selected by entering the numbers as a comma-separated list. The menu is displayed again after each selection, with asterisks appearing next to the items you have selected; selecting a component twice removes it from the selection list.

When you are upgrading to a new version of MX, the installation procedure will look at your current configuration to automatically determine the components that should be installed. If you wish to omit any of those components that were selected, simply select them again to remove it from the list.

When you have selected the components you want to install, enter 9 to exit the menu. Your selections are displayed again and you are asked to confirm your selections:

You have selected the following optional components: (selected components listed here) * Is this correct [YES]?

Press RETURN to continue the installation, or enter NO to return to the components menu.

Component Notes

You must install the Base software component if this is your first installation of MX, or if you are upgrading from a previous version of MX. The other components are optional and may be installed at any time after the Base component is installed. If you re-install the Base component, you must also re-install all desired optional components as well, except for documentation, examples and contributed files.

If you elect to install SMTP support, NETLIB support will automatically be installed as well. If you have already installed the NETLIB support component, you can disable the NETLIB re-installation by re-selecting it on the menu.

2.5 NETLIB Component Installation

If you are installing the NETLIB component (required for SMTP support using TCP/IP), the saveset containing the NETLIB support files will be loaded and you will be asked some questions regarding the configuration of NETLIB.

The NETLIB installation procedure asks where the NETLIB shareable libraries should be placed:

* Where should the NETLIB libraries be placed [device:[directory]]:

If this is your first installation of NETLIB, the default answer for this question will be the directory where the MX executables are located. However, you may specify any valid location for these files.

2.6 The Installation Completes

After the configuration questions and NETLIB component installations, which always require input from the installer, all selected components are installed. Files are copied from the each save set of the installation kit, then all installed files are copied to their destination directories. Informational messages about the individual components are displayed as needed.

This chapter contains important information about setting up MX configuration and startup options.

3.1 Configuring MX

When installing MX for the first time, or upgrading from a previous version, the installation procedure automatically invokes the MXCONFIG command procedure to assist in creating or updating your MX configuration files. If you are adding options to an existing MX installation, and have already created a configuration database, this step is skipped. If you want to create a new MX configuration from scratch, you may use the MXCONFIG command procedure to create an MX configuration database after the installation completes:

$ @SYS$STARTUP:MX_STARTUP LOGICALS $ @MX_DIR:MXCONFIG

MXCONFIG prompts you for some basic information about the MX message queue, your local host name, and MX processing agents. This information is used to create logical names used by MX and control the parts of MX that are started during the system startup procedure. The prompts for these configuration elements contain detailed descriptions for each of these configuration options.

If MXCONFIG is invoked as part of an initial installation, it will also ask about your network connectivity, and create an MCP command file to create an MX configuration database. You can use MXCONFIG to define all routing information and Postmaster aliases for a typical Internet-connected system. Once the basic configuration is created with MXCONFIG, you can tailor it as you wish using the MCP commands described in Message Exchange Management Guide.

3.2 Message Queue Location and Limits

The first step of the MXCONFIG procedure (option 1 on the menu when invoked outside the installation procedure) asks questions about configuring the MX message queue. The first question asks for the directory where the queue should be located. If you are configuring MX for the first time, the default location will be MX_ROOT:[QUEUE]; however, the queue may be located on any accessible disk on the system or cluster. If you are re-configuring MX, the default answer to this question will be your current MX message queue directory. You may use this procedure to move the message queue to a new location, if needed.

After other questions about the cluster name and whether completed messages should be deleted from the queue immediately, MXCONFIG prompts for configuration information regarding the maximum allowable size for messages and minimum amount of space that should be kept free on the disk device containing the message queue.

3.2.1 Maximum Message Size

You may specify a maximum size for any message that enters your system. By default, the maximum size is set to zero, indicating that there is no fixed maximum. This default setting is adequate for most systems; users sometimes send very large files through e-mail, and if sufficient space is available, this is not a problem. However, if your system has limited disk space available, restricting messages to a reasonable maximum size may help prevent mailboxes from consuming too much disk space.

3.2.2 Message Queue Limits

To prevent system failures or other undesirable behavior from occurring due to disk devices becoming too full, MX checks the amount of free space available on the disk containing the message queue before accepting a message for delivery. MXCONFIG prompts you for a value that represents, as a percentage value, the amount of free space that should be reserved on the queue disk. If a message is entered (via SMTP, VMS MAIL, or any other source) that would cause the amount of free space to drop below this value, the message is automatically refused and deleted from the system.

MXCONFIG sets the reserved free space to a default value of 10%, which will ensure that MX never causes the disk to become more than 90% full. If you elected during installation to place the message queue on a very large disk (larger than 1GB), you may wish to configure the reserved free space to a smaller value; the minimum allowed value is 1% (which allows the disk to become 99% full before MX refuses to accept messages). If your message queue is on a very small disk (smaller than 500MB), you may wish to configure the reserved free space to a larger value.

At some sites, the message queue disk may be located on a very large disk that is also very full, and even the 1% minimum that is settable through MXCONFIG may not be low enough to allow MX to operate consistently. MX provides a means for configuring the minimum reserved free space as an absolute number of disk blocks, rather than a percentage. This is not settable through MXCONFIG; to configure the reserved free space in disk blocks, you must add the following logical name definition to your system startup procedure:

$DEFINE/SYSTEM/EXEC MX_FLQ_DISK_FREE_ABSOLUTE n

where n is the minimum allowed free space on the disk, in disk blocks. This logical name overrides the percentage setting that is configured through MXCONFIG. The minimum allowed value for n is 1024.

All Internet sites that use electronic mail must be able to accept mail to the username Postmaster. If you do not have a real username called POSTMASTER on your system, you should either establish aliases with the MCP DEFINE ALIAS command:

MCP> DEFINE ALIAS Postmaster "user@host"

(substituting appropriate values for user and host), or use the SET FORWARD command in VMS Mail to forward mail from Postmaster to a real user:

MAIL> SET FORWARD/USER=POSTMASTER user

Even if you are not connected to the Internet, it is still a good idea to create a Postmaster username or forwarding address.

3.4 Adding MX Startup to System Startup

The startup procedure for MX may vary depending on:

• you are running in a cluster environment
• you are running MX processes under a separate mailer account

In either case, remember that if you are running the MX SMTP-over-TCP/IP support, you should start MX after you start your TCP/IP software.

Standalone Systems

If you intend to run MX under the SYSTEM account, all you need to add to your system startup procedure is the command:

$ @SYS$STARTUP:MX_STARTUP

If you are using a separate mailer account, you would use the following commands instead:

$ @SYS$STARTUP:MX_STARTUP LOGICALS $ SUBMIT/NOPRINT/USER=mailer SYS$STARTUP:MX_STARTUP

For mailer substitute the username you assigned to your mailer account.

Clustered Systems

In a cluster environment, as long as you are running MX under the SYSTEM account, the startup command is as easy as for standalone systems:

$ @SYS$STARTUP:MX_STARTUP

However, if you are running MX under a separate mailer account, how each node in the cluster starts MX depends on whether or not it will run one or more of the MX processes (as selected during MX installation).

If the node will not run one or more of the MX processing agents, such as a satellite node in a Local-Area or Mixed-Interconnect VMScluster, all it needs to start up MX is the command:

$ @SYS$STARTUP:MX_STARTUP

which just defines the necessary logical names and install the necessary images for interfacing VMS Mail with MX.

If the node will run one or more MX processes, those processes need to be started up under the mailer account's username, so you would use the commands:

$ @SYS$STARTUP:MX_STARTUP LOGICALS $ SUBMIT/NOPRINT/USER=mailer/QUEUE=nodeque SYS$STARTUP:MX_STARTUP

substituting the mailer account name for mailer and the name of a batch queue that runs on the local system for nodeque.

3.4.1 Example

As an example, take a homogeneous VMScluster with two nodes, NODE1 and NODE2, each with a TCP/IP connection, and several satellite nodes that will just be used for sending and receiving mail by users (i.e., no MX processes will run on them).

Both NODE1 and NODE2 have batch queues, called NODE1_BATCH and NODE2_BATCH, respectively. The mailer account username is MAILER.

The commands to be added to SYS$MANAGER:SYSTARTUP_V5.COM, after TCP/IP startup, would be:

$ NODE = F$GETSYI ("NODENAME") $ IF NODE .NES. "NODE1" .AND. NODE .NES. "NODE2" $ THEN $ @SYS$STARTUP:MX_STARTUP $ ELSE $ SUBMIT/NOPRINT/USER=MAILER/QUEUE='NODE'_BATCH SYS$STARTUP:MX_STARTUP $ ENDIF

3.5 Adding MX Shutdown to System Shutdown

To ensure that MX agent processes are shut down cleanly when the system is shut down, add the following lines to SYS$MANAGER:SYSHUTDWN.COM:

$ MCP := $MX_EXE:MCP $ MCP SHUTDOWN/WAIT

This will notify any agent processes on the system that they should shut down without affecting the agent processes on other nodes in the cluster. The /WAIT qualifier will cause MCP to wait until the agent processes exit before continuing. This may take several seconds, but ensures that agents shut down cleanly to maintain the integrity of the MX message queue.

3.6 Establishing Your Time Zone

If you are not in the US Eastern time zone, or you are not following US standard daylight savings time, or you do not like "EST" and "EDT" as time zone names, you must make sure that at least one of several time zone logicals is defined in SYSTARTUP_V5.COM.

3.6.1 The Product-Specific Time Zone Logicals

MX checks for the existence of one of several time zone logicals that specify the timezone string to be used when generated RFC822 mail message headers. Because most of the delivery transports (DECUS UUCP, the TCP/IP implementations, etc.) already define time zone logicals compatible with MX, it is not necessary to define MX-specific logicals.

On OpenVMS V6.0 and later, MX automatically uses the logical name SYS$TIMEZONE_DIFFERENTIAL as the basis for its time zone strings. If you have not correctly set that logical name, use the command

$ @SYS$MANAGER:UTC$CONFIGURE_TDF

to set the timezone differential. If your site observes Daylight Savings Time, you may need to adjust the timezone differential each time you adjust your system clock.

On systems where SYS$TIMEZONE_DIFFERENTIAL is not defined (typically pre-V6.0 VMS), the value of the first logical defined in the following ordered list is used with no time-zone calculations.

MX_TIMEZONE	MX
MULTINET_TIMEZONE	MultiNet
UUCP_TIME_ZONE	DECUS UUCP
WIN$TIME_ZONE	WIN/TCP and PathWay

3.6.2 The MX Timezone Logicals

If you wish to define a specific timezone logical name for use by MX, you should define it as follows:

$ DEFINE/SYS/EXEC MX_TIMEZONE "tzstr"

where tzstr is a valid (RFC822-compliant) time zone designation, such as "-0500". No validity checking is performed on this string. Note that the string you specify with MX_TIMEZONE is used verbatim. If you use MX_TIMEZONE and you observe daylight savings time in your area, it is your responsibility for modifying the definition of MX_TIMEZONE as needed. You do not need to shut down MX to do this.

3.7 Interfacing with TCP/IP

The SMTP interface uses the NETLIB transport-independent library to interface with the TCP/IP package or packages you have installed on the system.

3.7.1 Disabling Vendor SMTP Support

If your TCP/IP vendor provides SMTP support as part of its package, you should disable that support before starting MX.

For CMU-OpenVMS/IP (aka CMU-Tek TCP/IP), edit your INTERNET.CONFIG file and comment out the line that begins with "WKS:25", then restart TCP/IP. In addition, you may wish to deassign the system logical name TCP$SMTPSV.

3.7.1.2 Disabling MultiNet SMTP

For MultiNet, use the Server Configuration Utility to disable MultiNet's SMTP service:

$ MULTINET CONFIGURE/SERVER MultiNet Server Configuration Utility 2.2(25) [Reading in symbols from SERVER image MULTINET:SERVER.EXE] [Reading in configuration from MULTINET:SERVICES.MASTER_SERVER] SERVER-CONFIG>DISABLE SMTP SERVER-CONFIG>RESTART SERVER-CONFIG>EXIT

If the SMTP was previously enabled, you will also need to stop the MultiNet SMTP batch queue. For example:

$ STOP/QUEUE MULTINET_SMTP_QUEUE

3.7.1.3 Disabling TCPware SMTP

For TCPware, use the TCPware configuration utility to disable TCPware's SMTP server, if you installed TCPware-SMTP. For TCPware v3.0, type:

$ @TCPWARE:CNFNET FULL SMTP

For versions of TCPware prior to v3.0, type:

$ @TCPIP_ROOT:CNFNET FULL SMTP

When asked

Enter the number of listening SMTP-VMS servers [1]:

enter 0. When asked whether to restart SMTP, answer YES.

3.7.1.4 Disabling UCX SMTP

VMS/ULTRIX Connection (in versions 1.0 through 1.3B) does not include any native SMTP support.

DEC TCP/IP Services for VMS V2.x does include native SMTP support. To disable the UCX SMTP server under V2.x, perform the following:

• Disable the currently running SMTP service:

  $ UCX DISABLE SERVICE SMTP

• Stop the UCX SMTP queues. For example:

  $ STOP/QUEUE UCX_node_00 $ STOP/QUEUE UCX_node_01

• Modify the system startup (SYSTARTUP*.COM in SYS$MANAGER:) procedure to not invoke UCX$SMTP_STARTUP.COM.

• Run the UCX configuration procedure:

  $ @SYS$MANAGER:UCX$CONFIG.COM

• Select "Client components".
• Select "SMTP".
• Answer YES to reconfigure SMTP.
• Answer NO to disable SMTP.

To disable the SMTP server for Wollongong's PathWay, follow these steps:

• Edit the file TWG$TCP:[NETDIST.ETC]SERVERS.DAT.
• Find the server description for the SMTP service and place pound signs (#) in front of each line, including the blank lines preceding and following the SMTP server description. This marks those lines as comments and they will be ignored by INET_SERVERS during its startup.
• If the INET_SERVERS process is running, kill it.
• Restart INET_SERVER by executing the following command:

  $ @TWG$TCP:[NETDIST.MISC]INETSERV.COM

• List the registered TCP/UDP services to make sure the SMTP service is not listed:

  $ netstat -a

• You can now start the MX SMTP_SERVER process.

To prevent the PathWay SMTP server from restarting on the next system boot, comment out the SMTP_INIT line in the PathWay startup file, TWG$TCP:[NETDIST.MISC]STARTINET.COM.

This procedure should permanently disable the PathWay SMTP server. To reenable the PathWay SMTP server, undo all the edit changes, kill the MX SMTP_SERVER, kill the INET_SERVER, and restart the INET_SERVER.

3.7.2 Ensuring SMTP Server Restarts

The MX SMTP Server process automatically exits when it detects the shutdown of the TCP/IP software. If you want to ensure that it starts back up again after restarting your TCP/IP software, you should create a command procedure for starting up TCP/IP:

$ @vendor-supplied-startup $ IF F$TRNLNM ("MX_EXE") .NES. "" THEN @SYS$STARTUP:MX_STARTUP SMTP_SERVER

Substitute the name of the vendor-supplied startup procedure for your TCP/IP package in the first line.

3.8 SMTP Support for DECnet

If you elected to install support for SMTP-over-DECnet, you must take some additional steps to configure DECnet and MX.

3.8.1 Creating a DECnet Object for DECnet-SMTP

You must create a DECnet object called DECSMTP for establishing SMTP-over-DECnet connections, both incoming and outgoing.

If you intend to accept incoming SMTP-over-DECnet connections, you should establish an account (either your mailer account or a dedicated server account) for use with each DECnet object. See Section 1.6.1 for more information on the requirements for the DECnet object account.

A DECnet object needs to be created to handle the incoming SMTP-over-DECnet connections and to map the DECSMTP object name to a DECnet object number. Choose an unused DECnet object number. To see what object numbers are currently in use, use the command:

$ MCR NCP SHOW KNOWN OBJECT

Assign the object name DECSMTP to an unused object number; the number used must be identical on all nodes on your network that use SMTP-over-DECnet (this example uses 254). In NCP, use these commands:

NCP> PURGE OBJECT DECSMTP ALL NCP> DEFINE OBJECT DECSMTP NUMBER 254 PROXY NONE FILE - _NCP> MX_EXE:DNSMTP_SERVER.EXE USER server-acct PASSWORD some-password NCP> SET OBJECT DECSMTP ALL

You do not need to specify the FILE, USER, or PASSWORD parameters if you do not intend to accept incoming SMTP connections over DECnet. Be sure that the password in the DECnet database matches the password you set for the server account in AUTHORIZE.

Using Proxies

Instead of storing the username and password for the server account in the DECnet database, you could grant access using DECnet proxies. Proxies give you more control over who on the network has access to the object, and eliminate the need for storing the password to the server account in the DECnet object database.

To enable proxy access to the DECSMTP object, use the following commands in NCP:

NCP> PURGE OBJECT DECSMTP ALL NCP> DEFINE OBJECT DECSMTP NUMBER 254 PROXY INCOMING FILE - _NCP> MX_EXE:DNSMTP_SERVER.EXE NCP> SET OBJECT DECSMTP ALL

Then in AUTHORIZE, create proxy entries for the mailer accounts on the other systems on the network that will be sending you mail via SMTP-over-DECnet:

UAF> ADD/PROXY remote::mailer server-acct/DEFAULT

For remote::mailer substitute the DECnet node of the remote system and the username of the mailer account on that system. For server-acct substitute the name of the server account you set up for use with the DECnet-SMTP object.

3.9 Customizing Mailing List and File Server Files

The MX installation procedure provides three files, MLIST_ADD_MESSAGE.TXT, MLIST_REMOVE_MESSAGE.TXT, and MLIST_FORWARD_MESSAGE.TXT, for use with the mailing list processor, and a help file called FILESERV_HELP.TXT for use with a file server. If you intend to use the mailing list or file server features of MX, you should modify the contents of these files to reflect site dependencies. If you already had customized versions of these files, they are not purged; you should delete the new versions created by the installation procedure.

Refer to Message Exchange Mailing List/File Server Guide for more information on setting up mailing lists.

3.10 Setting Up MXALIAS

MX includes a utility called MXALIAS which users can execute to define personal MX aliases for e-mail addresses. MXALIAS is fully documented in the Message Exchange User's Guide.

In order to make MXALIAS accessible to users on the system, you should add a symbol like the following to your system login procedure (SYS$SYLOGIN) or to the user's LOGIN.COM:

$ mxalias :== $mx_exe:mxalias.exe

Alternatively, you can add a command to the DCLTABLES on your system that will invoke MXALIAS. In order to do so, create a file called MXALIAS.CLD containing the following lines:

! ! CLD file for defining MXALIAS command as DCL command ! ! To install for all users, modify the dev:[dir] strings below and ! execute the following commands: ! ! $ SET COMMAND MXALIAS.CLD/TABLE=SYS$LIBRARY:DCLTABLES.EXE- ! /OUTPUT=SYS$COMMON:[SYSLIB]DCLTABLES.EXE ! $ INSTALL :== $INSTALL/COMMAND ! $ INSTALL REPLACE SYS$LIBRARY:DCLTABLES.EXE ! DEFINE VERB MXALIAS IMAGE MX_EXE:MXALIAS.EXE CLIFLAGS(FOREIGN)

The instructions in the file show you would enter the command in the system-wide DCLTABLES. This undocumented technique can be used for any program that must be run with a foreign symbol.

MXALIAS includes its own on-line help. A brief description of MXALIAS that can be placed in the system help library can be found in MX_DIR: as MXALIAS_MAIN.HLP. To install it in the system-wide help library, execute the following command:

$ LIBRARY/HELP/REPLACE SYS$HELP:HELPLIB.HLB MX_DIR:MXALIAS_MAIN

Of course, any local help library may be specified instead of SYS$HELP:HELPLIB.HLB.

3.11 Starting MX

Once you have created an MX configuration database and added the appropriate startup commands to your system startup, you are ready to start up the MX software. From the SYSTEM account, or other suitably privileged account, enter the command:

$ @SYS$STARTUP:MX_STARTUP

If you are using a separate mailer account, you instead use the command:

$ SUBMIT/NOPRINT/USER=mailer/QUEUE=batchque SYS$STARTUP:MX_STARTUP

In a VMScluster environment, you should execute MX_STARTUP on each node in the cluster.

MX is provided in a VMSINSTALlable distribution kit consisting of 14 save sets. Each save set is briefly described in Table A-1.

Table A-1 MX installation kit save sets

Save Set	Contents
MX054.A	Kit files and common base installation files.
MX054.B	NETLIB installation files (for Alpha and IA64).
MX054.C	Base installation files (Alpha).
MX054.D	Base installation files (IA64).
MX054.E	MX SMTP (TCP/IP, DECnet) files (Alpha).
MX054.F	MX SMTP (TCP/IP, DECnet) files (IA64).
MX054.G	MX SITE, and MLF files (Alpha).
MX054.H	MX SITE and MLF files (IA64).
MX054.I	Mailing List/File Server (MLF) common files.
MX054.J	Documentation files, in PostScript, HTML, and plain ASCII formats.
MX054.K	Examples.

The files in Table B-1 are created during the installation of the MX software.

The following notes are referenced in Table B-1:

1. Only if Mailing List/File Server support is installed.
2. Only if Documentation is installed.
3. Only if Examples are installed.
4. Only if SMTP-over-DECnet is installed.
5. Only if SMTP support is installed.
6. Only if SITE support is installed.
7. Only if NETLIB support is installed.

Table B-1 Message Exchange files created during installation

File name	Description
Files in MX_FLQ_DIR:
MX_SYSTEM_QUEUE.FLQ_CTL	System queue sequential file
Files in MX_ROOT:[000000]
MGLICENSE_DATABASE.MGLICDB	License key database
MXALIAS_MAIN.HLP	Top-level MXALIAS help file for HELPLIB.HLB
MX_ALIAS_HELPLIB.HLB	Help library for MXALIAS
MX_MCP_HELPLIB.HLB	Help library for MCP
MX_REJMAN_HELPLIB.HLB	Help library for REJMAN utility
MLF_CONFIG.COM	ML/FS configuration procedure (Note 1)
MX_LICENSE.COM	Command procedure for license management
MXCONFIG.COM	MX configuration creation procedure
MX_CREATE_CONFIG_DATABASE.COM	MX configuration database creation procedure
MX_LOGICALS.DAT	Logical name definitions used by MX___STARTUP.COM
MX_STARTUP_INFO.DAT	Describes which MX processes get started
Files in MX_ROOT:[DOC] (Note 2)
INDEX.HTML	Index of HTML documentation (HTML)
MX_INSTALL_GUIDE.HTML	Installation guide (HTML)
MX_INSTALL_GUIDE.PS	Installation guide (PostScript)
MX_INSTALL_GUIDE.TXT	Installation guide (ASCII)
MX_MGMT_GUIDE.HTML	Management guide (HTML)
MX_MGMT_GUIDE.PS	Management guide (PostScript)
MX_MGMT_GUIDE.TXT	Management guide (ASCII)
MX_MLF_GUIDE.HTML	Mailing List/File Server guide (HTML)
MX_MLF_GUIDE.PS	Mailing List/File Server guide (PostScript)
MX_MLF_GUIDE.TXT	Mailing List/File Server guide (ASCII)
MX_PROG_GUIDE.HTML	Programmer's guide (HTML)
MX_PROG_GUIDE.PS	Programmer's guide (PostScript)
MX_PROG_GUIDE.TXT	Programmer's guide (ASCII)
MX_USER_GUIDE.HTML	User guide (HTML)
MX_USER_GUIDE.PS	User guide (PostScript)
MX_USER_GUIDE.TXT	User guide (ASCII)
Files in MX_ROOT:[EXAMPLES] (Note 3)
00README.ADDRESS_REWRITER	README file for address rewriter.
00README.NAME_CONVERSION	README file for name conversion module.
ACCESS_CHECK.ZIP	Sample callout for SMTP client access checks.
ACCESS_CHECK_EXAMPLE.C	Sample callout for SMTP client access checks.
ADDRESS_REWRITER.B32	BLISS source for address rewriter.
ADDRESS_REWRITER.C	C source for address rewriter.
ADDRESS_REWRITER.MMS	Makefile for address rewriter.
AUTH_CALLOUT_EXAMPLE.C	Sample callout for SMTP authentication.
CHARCONV_EXAMPLE.C	Sample character set conversion callout.
CHARCONV_EXAMPLE_README.TXT	Documentation for the sample character set conversion callout.
DOM_EXPANSION_CMU.B32	Sample domain name expander for CMU TCP/IP.
DOM_EXPANSION_UCX.B32	Sample domain name expander for DEC TCP/IP.
FILTER.C	Sample message filter callout.
MX_FILTERDEF.H	Header file for sample message filter callout.
MX_FILTERDEF.R32	BLISS REQUIRE file for creating a message filter.
MX_HDR.H	C header file with MX header definitions.
NAME_CONVERSION.B32	BLISS source for name conversion module.
NAME_CONVERSION.MAR	MACRO source for name conversion module.
NAME_CONVERSION.C	C source for name conversion module.
VIRTDOM.ZIP	ZIP file containing a sample address-rewriter callout that implements "virtual domains".
Files in MX executables directories
DNSMTP_SERVER.EXE	SMTP-over-DECnet receiver module (Note 4)
DOMAIN_EXPANSION.EXE	Domain name expander (Note 5)
MAILQUEUE.EXE	Program for listing delayed messages in queue
MCP.EXE	MX Control Program
MLFAKE.EXE	Utility for faking messages to mailing list servers
MXALIAS.EXE	Utility for defining MX aliases
MX_DECODE.EXE	Utility to decode BASE64 mail messages
MX_DNSMTP.COM	SMTP-over-DECnet command procedure (Note 4)
MX_DNSMTP.EXE	SMTP-over-DECnet delivery module (Note 4)
MX_FLQ_MGR.COM	MX FLQ Manager command procedure
MX_FLQ_MGR.EXE	MX FLQ Manager
MX_FLQ_SHR.EXE	Shareable image implementing file queues
MX_LOCAL.EXE	MX Local delivery module
MX_MAILSHR.EXE	VMS MAIL foreign protocol interface
MX_MAILSHRP.EXE	Service routines for foreign protocol interface
MX_MLF.COM	Mailing list/file server command procedure (Note 1)
MX_MLF.EXE	Mailing list/file server module (Note 1)
MX_MSG.EXE	Messages file
MX_ROUTER.COM	MX Router command procedure
MX_ROUTER.EXE	MX Router module
MX_SHR.EXE	MX common routines shareable library
MX_SITE.COM	Command procedure used by site-spec interface (Note 6)
MX_SITE.EXE	Site-spec delivery agent (Note 6)
MX_SITE_IN.COM	Site-spec message entry program (Note 6)
MX_SMTP.COM	SMTP outbound delivery command procedure (Note 5)
MX_SMTP.EXE	SMTP outbound delivery module (Note 5)
MX_SMTP_MSG.EXE	Message file for delivery status and SMTP messages
MX_START.COM	Command procedure for starting MX components
MX___STARTUP.COM	Master startup procedure for MX.
REJMAN.EXE	REJMAN utility
SMTP_SERVER.COM	SMTP inbound receiver command procedure (Note 5)
SMTP_SERVER.EXE	SMTP inbound receiver module (Note 5)
Files in MX_ROOT:[MLF] (Note 1)
FILESERV_HELP.TXT	Help text for use with file server
Files in MX_ROOT:[MLF.MAILING_LISTS] (Note 1)
MLIST_ADD_MESSAGE.TEMPLATE	Template for mailing list add message
MLIST_ADD_MESSAGE.TXT	Template for mailing list add message
MLIST_FORWARD_MESSAGE.TEMPLATE	Template for forwarded-to-list-owner message
MLIST_FORWARD_MESSAGE.TXT	Template for forwarded-to-list-owner message
MLIST_HELP.TXT	Help file for mailing list processor
MLIST_REMOVE_MESSAGE.TEMPLATE	Template for mailing list removal message
MLIST_REMOVE_MESSAGE.TXT	Template for mailing list removal message
Files in NETLIB_DIR: (Note 7)
NETLIB_SHR.EXE	NETLIB shareable library
Files in SYS$COMMON:[SYSHLP]
MXvvn.RELEASE_NOTES	Release notes for MX
NETLIBvvn.RELEASE_NOTES	Release notes for NETLIB
Files in SYS$COMMON:[SYS$STARTUP]
MX_STARTUP.COM	Startup procedure for MX
NETLIB_STARTUP.COM	Startup procedure for NETLIB (Note 7)

Contents