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
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
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).
This manual is intended for use by the system manager or any individual responsible for installing and maintaining MX.
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. |
You can find additional information in the following documents:
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:
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.
MX must be installed multiple times on a mixed-architecture VMScluster: once for each architecture. Only the first installation needs to include all of the architecture-independent files. |
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.
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:
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 |
Before installing MX, ensure that the following privileges, resources, and requirements are met:
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.
MX must be installed multiple times on a mixed-architecture VMScluster: once per architecture. The first installation will also provide the architecture-independent files. When installing on a mixed VMScluster, be sure to specify a device name for the MX installation directory that is valid for all systems in the cluster, and refers to the same device in all cases. Using a platform-specific logical name, such as SYS$SYSDEVICE, will cause subsequent installations to fail. |
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]? |
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 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.
If you are installing MX on a mixed VMScluster where systems of different architectures will share a common directory, be sure you specify a disk that is common to all types of systems. The default device (SYS$SYSDEVICE:) may not be appropriate, especially if you do not cross-mount your system disks between systems of different architectures. |
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.
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 |
Warning: MX may temporarily exceed the reserved free space setting while a message is being entered into the queue. Configuring the reserved free space setting to too low a value may cause the disk containing the message queue to become 100% full at times; this may have undesirable side-effects, especially if the message queue resides on your system disk. |
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:
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.
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.
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 |
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 |
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 |
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 |
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 |
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.
The instructions provided below were valid for various versions of each vendor's software. Please consult your TCP/IP documentation for more accurate instructions. |
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 |
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:
$ UCX DISABLE SERVICE SMTP |
$ STOP/QUEUE UCX_node_00 $ STOP/QUEUE UCX_node_01 |
$ @SYS$MANAGER:UCX$CONFIG.COM |
To disable the SMTP server for Wollongong's PathWay, follow these steps:
$ @TWG$TCP:[NETDIST.MISC]INETSERV.COM |
$ netstat -a |
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.
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.
Using proxies allows the remote system access to all files the server account can access (by using regular DECnet file transfers with FAL). If you do not manage the remote system, it is recommended that you use DECnet objects instead of proxies. |
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.
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:
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 |