Netware Super Library

home *** CD-ROM | disk | FTP | other *** search

/ Netware Super Library / Netware Super Library.iso / mhs_mail / xgate3 / xgate.doc < prev next >

Wrap

Text File | 1993-12-15 | 170.4 KB | 4,262 lines

XGATEXGATE High PerformanceHigh Performance MHS to SMTP GatewayMHS to SMTP Gateway Version 3.0Version 3.0 Copyright (c) 1993, Dave Frailey andCopyright (c) 1993, Dave Frailey and DAC Micro SystemsDAC Micro Systems XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- FeaturesFeatures Automatic handling of inbound and outbound file attachments. Supports a variety of return receipt options. Returns delivery errors in both directions with optional copies to the MHS administrator. Separate log file options for errors, inbound, and outbound message traffic. Complies with RFC-821, and RFC-822 for SMTP message handling. An exhaustive amount of testing with a wide variety of different SMTP mailers assures the highest level of compatibility. Low administration. The rules-based conversion engine does not use alias or look-up tables. Addressing syntax from both sides is easy to use. Supports MHS 1.1 through 2.0 (SMF-64, SMF-70, and SMF-71) The integrated SMTP module can multitask up to 100 inbound or outbound SMTP sessions concurrently, and is complimented with an extensive debug monitor that provides troubleshooting functions such as PING, NSLookup (name server lookup), Telnet/25 (telnet to another SMTP host), and more.... Configurable scroll back buffers for both the MHS Gateway Activity screen and the SMTP Monitor screen. Internal TCP/IP is provided by the high-performance Mach 2 TCP/IP protocol stack that runs directly (without shims) on either a Novell ODI driver or a Clarkson Packet Driver. Can also function as a high-performance (shotgun style) name server as an additional service to local nodes. Written 100% in assembly language for high performance and efficient memory usage. And, a vast array of other features and options.... i XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- IntroductionIntroduction XGATE is the most powerful MHS to SMTP gateway available today. It provides a completely integrated solution for bridging MHS-based electronic mail directly and seamlessly with SMTP-based electronic mail. XGATE runs as a single, uninterrupted program on a dedicated PC. It doesn't use any complex batch files, nor does it use any techniques that involve running another program and trying to process what that program left behind. Its ability to always receive a new SMTP connection is never interrupted. XGATE is a completely integrated solution that extensively uses the NetWare Queue Services API for all message handling, and it contains its own high-performance Mach 2 TCP/IP protocol stack that runs directly on either Novell ODI drivers, or Clarkson Packet Drivers. XGATE provides the best power-to-dollar ratio of any MHS to SMTP gateway available. Feature for feature, XGATE has more configurable options and capabilities than any other MHS to SMTP gateway. XGATE was developed 100% in assembly language for speed and memory efficiency. Its SMTP Server is capable of sending and/or receiving as many as 100 mail sessions simultaneously, and it provides the fastest throughput of any PC-based SMTP mailer, exceeding its competition by many orders of magnitude. The SMTP Server can be configured to run in a relay mode where it passes all outbound mail to a nearby UNIX host, or you can run it as a fully functional delivery agent which directly connects to any host it has outbound mail for. When run in direct delivery mode it returns comprehensive notifications at the 4 hour mark, and after each subsequent 24 hour period in which it can't deliver mail - up until it reaches the (configurable) number of hours at which to return mail as undeliverable. Both the MHS Gateway and SMTP Server modules include a full- featured scroll back capability. The SMTP Server also provides debugging tools such as a display filter (to screen out all but one active SMTP session), connection statistics, and NSLookup, Ping, and Telnet/25 options (for testing connectivity with other hosts). ii XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- XGATE's conversion engine was carefully designed using a rules-based philosophy. The last thing an E-Mail administrator needs is more recurring administration. In a minimal configuration, XGATE doesn't need any routing tables, user name tables, or alias tables. The addressing syntax from either side is easy to use. Once XGATE is installed, users on either side have immediate E-Mail access to users on the other side. And, with the scroll back capabilities, you'll always be able to easily tell what XGATE has been doing, what it is doing, and what its current status is. No other MHS to SMTP gateway lets you so easily monitor what's happening in real time. After you've used XGATE for a few days, we're confident you'll find that we didn't take any shortcuts, and that a lot of effort was used to ensure that all aspects, unusual circumstances, and exceptions were taken into account. AcknowledgmentsAcknowledgments Special thanks to Steve Glick of Dallas County Community College District, and Steve Knowles of Sir Sandford Fleming College, for plenty of valuable beta testing help. iii XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- 45 Day Trial Copy45 Day Trial Copy This is a 45 day trial copy of XGATE. It is provided so you can try XGATE before you buy it, for a period of 45 days in order to determine if it meets your needs. Continued usage after 45 days requires registration. Registering XGATE allows you to use this product after the trial period expires for an indefinite period of time. Registered XGATE users will also get mailed notifications when significant updates are available. More importantly though, registered users know they are helping to ensure that high quality software like XGATE can continue to be developed and distributed in this low cost manner. For more information on ordering, refer to the REGISTER.DOC text file included in this package. All DAC Micro Systems products are trademarks or registered trademarks of DAC Micro Systems. Other brand and product names are trademarks or registered trademarks of their respective holders. Copyright (c) 1993, Dave Frailey and DAC Micro Systems. All rights reserved. DAC Micro Systems 40941 176th St E Lancaster, CA 93535 Voice: 800-776-1322 Voice: 805-264-1700 BBS: 805-264-1219 FAX: 805-727-1603 iv XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- ContentsContents INTRODUCTION.........................................II REQUIREMENTS..........................................1 MHS................................................1 Memory.............................................1 LIMITATIONS...........................................2 OVERVIEW..............................................3 Program Modules....................................3 SMTP Queues........................................4 ADDRESSING............................................6 From SMTP to MHS...................................6 From MHS to SMTP...................................7 Static MHS Reply Address...........................8 The Default SMTP Host..............................8 FEATURES AND OPTIONS..................................9 Uuencoding.........................................9 Appending ASCII Attachments.......................10 Large Message Roll-off............................10 Return Receipts...................................10 Postmaster........................................12 Native Mode SMF-71................................12 Receiving SMTP Mail...............................14 Delivery Modes....................................14 RUNNING XGATE........................................16 Command Line Switches and Syntax..................17 USING XGATE..........................................19 Scroll Back.......................................19 MHS Gateway Activity..............................20 The SMTP Monitor..................................20 USING XGATE AS A NAME SERVER.........................23 The HOSTS File....................................23 PRE-INSTALLATION.....................................25 The MHS Gateway Name..............................25 The TCP/IP Host Name..............................25 INSTALLATION.........................................26 Copying XGATE's Files.............................26 Adding a gateway name under MHS...................27 Editing XGATE.CFG.................................28 Using SETUP.......................................29 v XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- Modifying NET.CFG.................................30 Installation Complete.............................31 INITIAL TESTING AND TROUBLESHOOTING..................32 TCP/IP HOST NAMES AND IP ADDRESSES...................33 Configuring DNS...................................33 Defining MX Records...............................34 Hiding XGATE Behind Another UNIX Host.............35 XGATE.CFG............................................37 Alphabetical Index................................37 Reference.........................................39 INDEX................................................59 vi XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- RequirementsRequirements IBM PC XT/AT Compatible 640 KB Conventional Memory Extended/Expanded (XMS/EMS) Memory is Helpful Network Interface Card Novell ODI driver or Clarkson Packet Driver MHSMHS XGATE works with MHS versions 1.1, 1.5, and 2.0 (SMF-64, SMF-70, and SMF-71), and automatically adjusts to each level's differences and/or capabilities. MemoryMemory XGATE was written 100% in efficient assembly language. But even as such, fitting the functionality of a MHS gateway, SMTP server, and TCP/IP protocol stack in memory concurrently can be a bit demanding on memory utilization. XGATE will automatically recognize and use UMB memory (upper memory blocks between the 640K and 1Meg boundary) either through MS-DOS 5 API calls, or through an XMS driver (like HIMEM.SYS when used with EMM386.EXE, or QEMM from Quarterdeck). XGATE also automatically recognizes and uses EMS (expanded) memory when present (if version 4.0 or higher) for some of its event-based buffering requirements, and also for scroll back buffers. If a choice is needed, allocating approx. 256K of extended memory as expanded memory should be sufficient (as long as nothing else uses it). 1 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- LimitationsLimitations XGATE's messaging limitations are more those of MHS than XGATE. XGATE can handle a message of unlimited length. MHS 1.5 has a limit of 64K for body text. MHS 2.0 has an unlimited length for body text. (Note that many MHS E-Mail applications have a smaller limit, sometimes 32K or less for body text. XGATE provides an option to roll body text off to a file attachment in these cases.) XGATE can handle an unlimited number of outgoing MHS file attachments and automatically uuencode them into the outgoing SMTP message. It can also do the inverse with inbound SMTP messages and automatically uudecodes multiple uuencoded files back into separate MHS file attachments. MHS 1.1 (SMF 64) however, can only handle one file attachment per message (in this case XGATE only decodes the first file and leaves the rest uuencoded in the message body). MHS 1.5 (SMF 70) can handle 64 file attachments, and XGATE will automatically uudecode and create attachments for as many uuencode blocks that exist in the message body text. 2 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- OverviewOverview How does it work? Its not really that complicated.... Program ModulesProgram Modules Although the appearance is that it is all integrated, XGATE is fundamentally divided into two different modules; the MHS Gateway module and the SMTP Server module, and it uses a third module for its TCP/IP driver. All modules are automatically loaded at startup (into UMB memory if possible). The MHS Gateway module and the SMTP Server module communicate with each other through an internal API and with the NetWare Queue Services API. To conserve memory, both modules also use a common set of library functions that are resident within the loader. The MHS Gateway module and the SMTP Server module are multitasked on a non-preemptive time-sharing basis and are both equipped with individual scroll back capability. The MHS Gateway ModuleThe MHS Gateway Module The MHS Gateway module handles the conversion of mail between MHS and SMTP formats, and it handles the inbound and outbound delivery of MHS mail. The SMTP Server ModuleThe SMTP Server Module The SMTP Server module (as its name implies) provides the SMTP server functionality, and it handles all of the TCP/IP related issues. The SMTP Server automatically uses the advanced capabilities provided by the NetWare Queue Services API to manage the order and scheduling of outbound SMTP mail. The Mach 2 TCP/IP Protocol StackThe Mach 2 TCP/IP Protocol Stack At an even lower level, the SMTP Server uses the Mach 2 TCP/IP protocol stack for all TCP/IP requirements. Like the other two modules, Mach 2 is also loaded automatically at startup, and is unloaded when you exit XGATE. Mach 2 is a high-performance TCP/IP protocol stack that unlike other TCP/IP drivers or applications, was not a 3 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- derivative of someone else's previous work (in C). Mach 2 was designed from scratch completely in assembly language, with strong priorities on long-term stability and high performance. The SMTP Server interacts with Mach 2 mostly on an asynchronous basis (at interrupt time when packets are received). The system never blocks waiting for Mach 2 to complete an API call. Mach 2 runs directly (without any shims) on either a Novell ODI driver, or a Clarkson Packet Driver (or both - it can support multiple interfaces). When run on ODI, Mach 2 is a fully compliant ODI protocol stack. The SMTP QueuesThe SMTP Queues XGATE uses two NetWare queues; SMTP_IN and SMTP_OUT, to handle all inbound and outbound SMTP mail. These two queues are job queues (like a print queue except that the queue object type is a different number), and are created with one of the options in XGATE's SETUP program. When XGATE initially starts up, it attaches to both the SMTP_IN and SMTP_OUT queues through the NetWare API as a queue server. Basically, anything in the SMTP_IN queue is considered inbound SMTP mail and likewise, anything in the SMTP_OUT queue is considered outbound SMTP mail. On a configurable basis the MHS Gateway module periodically scans the gateway OUT directory under MHS for outbound mail, converts anything it finds to SMTP format, and posts it in the SMTP_OUT queue for the SMTP Server module to deliver. In the same scan cycle the MHS Gateway module also checks the SMTP_IN queue, converts any messages found in it to MHS format, and posts them in the MHS inbound directory for MHS to route. Once every second the SMTP Server module scans the SMTP_OUT queue for new messages that are ready for servicing. If one is found, it launches an outbound process to deliver it. The SMTP Server module is always capable of receiving a new inbound SMTP (listen) connection (which is handled asynchronously at interrupt time by the Mach 2 TCP/IP protocol stack). When the SMTP Server finishes receiving an inbound SMTP message, it puts it in the SMTP_IN queue for the MHS Gateway module to process on its next cycle. Most of this is mentioned only to satisfy the technically curious. There's no real need to completely understand it. 4 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- Creating the SMTP job queues, and granting queue server rights to an existing user, are performed with a couple of easy steps from within XGATE's SETUP program. 5 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- AddressingAddressing There are two different names involved when addressing mail through XGATE. One is the TCP/IP host name that SMTP users know it by (defined as the "smtp_gateway_name" in XGATE.CFG), the other is the MHS gateway name that MHS users know it by (the "mhs_gateway_name" in XGATE.CFG). The trick to understanding how both names are used is mainly to look at it in the perspective of which way the mail is going. When MHS mail is going through XGATE to an SMTP user, the message is addressed to XGATE's MHS gateway name and the actual SMTP address is given in (what MHS calls) an extended address field. This is because you normally just can't fill in the "To:" address of an MHS message with only the SMTP address and expect MHS to know what to do with it (unless you're on MHS 2.0 or NGM and properly configure them - which is explained under "Using XGATE with SMF-71"). When SMTP mail is coming to XGATE destined for an MHS user, the message is addressed to the MHS user at XGATE's TCP/IP host name. (Sometimes the user's MHS hub name needs to be included after the user's name, if the user can't be found at the default MHS workgroup.) Addressing From SMTP to MHSAddressing From SMTP to MHS So how does a SMTP user send mail to a MHS user? If the TCP/IP host name for XGATE is "xgate.acme.com", and if you have an MHS user called "Joe", SMTP mail would be sent to Joe like this: joe@xgate.acme.com If you have multiple MHS hosts and don't use a workgroup- wide router, or Joe is on a different MHS hub - the name of Joe's MHS host may also be given in the SMTP address. For example: joe%mhs1@xgate.acme.com In this example a percent sign is used to separate Joe's user name from his MHS host name, which is the default syntax under SMF-71 conventions. XGATE also recognizes an alternate syntax of using a period instead, but the rules get a little complicated. For more information refer to the 6 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- "name_mapping_mode" option described under the XGATE.CFG reference. If a user has more than one application name under MHS, the MHS application name can also be specified (normally this is not necessary since MHS will deliver E-Mail to the user's default application), by enclosing the application name in square brackets. For example: joe[pmail]@xgate.acme.com If both the application name and the MHS hub name are given, the application name should precede the hub name. For example: joe[pmail]%mhs1@xgate.acme.com And lastly, extended addressing parameters can also be specified (which allows an SMTP user to send parameters to another gateway on your MHS system, such as a FAX gateway), by enclosing them in curly braces. For example: faxgate{801-555-9600}@xgate.acme.com Addressing From MHS to SMTPAddressing From MHS to SMTP Under MHS you define a gateway name for XGATE to use. The name of the gateway is akin to the name of another MHS hub. When MHS users send mail through XGATE, they have to address the message to XGATE's gateway name (so MHS will give it to XGATE) and enclose the destination SMTP address inside curly braces (which is what MHS calls an "extended" address). When XGATE then gets the message, it looks for the extended address and uses it as the destination address for the SMTP user. The syntax that your MHS E-Mail application uses to do this may vary (most use the native MHS format). The native MHS syntax is: user . application @ host {extended_address} When XGATE gets a message from MHS, it normally pays no attention to what "user" name was used unless the extended address isn't given. The "extended_address" is what XGATE looks for in order to address the SMTP user. For example, if XGATE's gateway name is called "SMTP", and an MHS user wanted to send mail to "joe@acme.com", he would address the message like this: email @ smtp {joe@acme.com} 7 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- Static MHS Reply AddressStatic MHS Reply Address The syntax just described previously under Addressing From MHS to SMTP is the conventional way to address mail through an MHS gateway. There is however, another method that XGATE supports called Static Reply Addressing. When this mode is enabled, XGATE builds reply addresses from inbound SMTP mail with an MHS format of: gateway_name @ workgroup {joe@acme.com} Which also works fine going through MHS - and in most cases is a matter of symantics (depending on whether you have a multi-host workgroup). For instance, if you had called XGATE's gateway name "SMTP" and your MHS workgroup name was "XYZ", the reply address that XGATE builds would look like this: SMTP @ XYZ {joe@acme.com} If you prefer the appearance of a reply address in this format (and/or finding it easier to tell MHS users how to address SMTP mail through XGATE), then enable the static_reply_address option in XGATE.CFG. The Default SMTP HostThe Default SMTP Host In XGATE's configuration file you can define a default SMTP host. When XGATE processes a message that doesn't specify the destination SMTP host, the message will be sent to the default SMTP host. For example, if the default SMTP host is set to "kirby.com", and an MHS user wanted to send a message to "joe@kirby.com", they could simply address the message as: email @ smtp {joe} Furthermore, if the extended address is not present at all, XGATE will send the message to the MHS user name at the default SMTP host. Since MHS user names can't exceed eight characters (except SMF-71), sending a message to a user at the default SMTP host can be reduced down to just a "user @ xgate" syntax if the recipient's name is eight characters or less. For example: joe @ smtp 8 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- Features and OptionsFeatures and Options UuencodingUuencoding If the "uuencode" option in XGATE.CFG is enabled (or not specified - the default is enabled), XGATE automatically uuencodes and decodes MHS file attachments. When enabled, each message received from SMTP is scanned for encoded blocks which are automatically decoded, and outbound MHS messages that contain file attachments are automatically uuencoded into the SMTP message body. The scanning algorithm of inbound SMTP messages is very picky about assuming the presence of a uuencoded block. If any part of the uuencoded block doesn't conform to the specification, scanning is abandoned and the message body is passed through untouched. If you are running on MHS 1.5 or greater, multiple uuencoded files can exist in an inbound SMTP message and will be decoded into separate file attachments in the resulting MHS message. If you are running a version of MHS older than 1.5, only the first uuencoded block is decoded to a file attachment. Any subsequent uuencoded blocks in the same message will remain in the body text of the message. When a block of uuencoded text is decoded from an inbound SMTP message, the uuencoded block is removed from the message text, but the lines preceding and following the block remain intact. XGATE has no internal limitations on the size of uuencoded files. Encode and decode are standard utilities in the UNIX operating system. But, its not so standard to automatically scan and decode a message containing a uuencoded file when received by a remote SMTP mailer, or other types of SMTP gateways. In some instances, the remote SMTP user may have to save the received message to a file and then run a decode program against it in order to extract the attached file. Public domain PC-based decode programs are available that run under both DOS and Windows, and can be found on Compuserve or on our BBS. 9 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- Appending ASCII AttachmentsAppending ASCII Attachments When an outbound MHS message has a file attachment that only contains ASCII text characters, it may be desirable to simply append the file attachment onto the body of the SMTP message rather than uuencode it (which saves the recipient from having to decode it if their SMTP mailer or gateway doesn't perform the service automatically). This feature is enabled with the following variable in XGATE.CFG: APPEND_ASCII_ATTACH = nn "nn" is the maximum size of an attached file (in K) that will be considered for appending. A value of zero disables this feature. Any file that contains characters other than the ASCII characters 9, 10, 12, 13, 32-127 (26 allowed at the end of file) is automatically disqualified and will be uuencoded instead (if enabled). Large Message Roll-offLarge Message Roll-off When an inbound SMTP message contains body text larger than what your MHS E-Mail application can handle, XGATE provides a configurable option that can move the body off to a MHS file attachment. For instance, Beyond Mail for Windows has a body text limit of 32K. If an inbound SMTP message contained body text larger than 32K, Beyond Mail for Windows simply truncates the message at the 32K boundary. This feature is enabled with the following variable in XGATE.CFG: CONV_BODY_TO_ATTACH = nn "nn" is the maximum body text size (in K) of an inbound SMTP message that will pass through without being rolled off. A value of zero disables this feature. When an inbound SMTP message body is moved to a file attachment, a small note is written in the message body indicating this occurred. Return ReceiptsReturn Receipts XGATE can be configured to always request a return receipt when incoming SMTP mail is read by the MHS user, by including the following statement in XGATE.CFG: SMTP_RECEIPTS = Y But this option can only be on or off globally for all inbound SMTP mail. If this option is disabled (which is 10 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- normal), two other methods of getting a return receipt are still available: 1) SMTP users can ask for a return receipt by embedding a flag in the address of the message, which produces the same affect on a case-by-case basis. Normally, a SMTP user addresses a MHS user as follows: user%mhshub@smtp_gateway_name However, if a "/r" is embedded after the MHS hub name (or after the user name if hub names aren't being used) XGATE will build the MHS message with a return receipt requested. For example: user%mhshub/r@smtp_gateway_name 2) XGATE will always request an MHS return receipt if the inbound SMTP message has a "Return-Receipt-To:" header field. For mail going from MHS to SMTP, return receipts are a little more convoluted. XGATE.CFG has an option called "use_mhs_ret_rcpts" that controls whether XGATE pays any attention to an MHS message that requests a return receipt. SMTP was never designed with return receipts in mind. Some SMTP mailers recognize a "Return-Receipt-To:" header field and some don't. If a mailer does recognize this field, it usually generates a delivery notification, not a time-of-reading return receipt. If the "use_mhs_ret_rcpts" option is enabled, XGATE will build the "Return-Receipt-To:" field in outgoing SMTP messages when a MHS message requests a return receipt. This option is disabled by default since the delivery notifications could be misleading to MHS users who would usually think it means the message had been read. MHS users still have another means of requesting a return receipt even if the "use_mhs_ret_rcpts" field is disabled in XGATE.CFG. A flag can be embedded in the SMTP address that also causes XGATE to build the same "Return-Receipt-To:" field in the SMTP header. Normally, a MHS user addresses a SMTP user as follows: user @ gateway {username@smtphost} If an additional "/r" is embedded after the "username" in the SMTP address, XGATE will generate the "Return- Receipt-To" field in the outgoing SMTP message (and remove the /r of course). For example: 11 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- user @ gateway {username/r@smtphost} PostmasterPostmaster XGATE automatically forwards received SMTP mail addressed for "Postmaster" to the MHS administrator. When XGATE returns a -Maiser- delivery error to an SMTP user that was generated by MHS, the sender of the message is automatically remapped from "-Maiser-" to "Postmaster". Native Mode SMF-71Native Mode SMF-71 XGATE can be used with SMF-71 (MHS 2.0 or NGM) just the same as with older versions of MHS and nothing changes. XGATE automatically detects when its running with NGM (or MHS 2.0) and writes SMF-71 style envelopes for outbound MHS messages, and it automatically handles SMF-71 style envelopes when processing inbound MHS mail. But it won't automatically assume native SMF-71 style addressing unless you tell it to. If you are using NGM (or MHS 2.0), you should configure XGATE as a version 71 gateway regardless. But all that does is tell NGM that XGATE knows how to read an SMF-71 envelope, which is what NGM will then use when it gives XGATE mail. Where the difference lies between what we are calling "native mode addressing", and old-style gateway addressing, is whether you want MHS users to be able to address SMTP users without having to use the extended address syntax. Until SMF-71 the only way to get mail through XGATE was to address it to XGATE's gateway name and then use an extended address (the stuff in curly braces) to actually define the destination SMTP address. For example: email @ smtp {joe@acme.com} But with the introduction of SMF-71, Novell added a new feature that allows a message to be delivered to XGATE without XGATE's gateway name having been explicitly given in the destination address. This is done by telling NGM that XGATE supports "additional address formats". What this basically does is let you define certain patterns in an address which influence where NGM routes a message. For example, you can tell NGM that any address ending with a ".com" goes to XGATE. This means Joe can be addressed simply by using his normal SMTP address without having to also give the "email @ smtp {" business in front of it. For example: joe@acme.com 12 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- When NGM is set up in this manner however, XGATE needs to be told not to bother looking for the extended address - and furthermore, not to build the reply address for inbound SMTP mail with the extended address format. You do this with the following statement in XGATE.CFG: NATIVE_SMF71 = Y When the "native_smf71" option is enabled, all possible SMTP root domains should be properly entered as "Additional Address Formats Supported" in XGATE's gateway configuration under NGMADMIN, or outbound SMTP messages will not be routed properly to XGATE, and will probably be returned to the sender. Whether you are going to use the "native_smf71" option or not, there is nothing different about the actual steps of adding XGATE as a gateway name under MHS 2.0 or NGM, it is performed in the same manner for both cases. The difference is that when you enable "native_smf71" in XGATE, you must also ensure that all address formats (SMTP root domains) are also defined as "Additional Address Formats Supported" by XGATE's gateway name in NGM because the dependence is now totally on NGM to route messages intended for SMTP users to XGATE when they are not explicitly addressed to XGATE. To add XGATE as a gateway under NGM, use the NGMADMIN NLM. From NGMADMIN's Main Menu, select "This Server" and then select "SMF Gateways". To add a new gateway, press the Insert key. Most of the options are self-explanatory. The "Command Line:" and "Execution Interval:" fields are not relevant for XGATE. The "SMF Version:" should be set to 71. When you are done, press the Escape key. If you are going to enable XGATE.CFG's "native_smf71" option, select XGATE's gateway name from under the "SMF Gateway's Menu" and press Return. A sub-menu describing configurable options for XGATE then appears. Select "Additional Address Formats Supported" and press Return. For each SMTP root domain that needs to be added, use the Insert key. Some of the additional formats you may want to enter are: **@**.com **@**.org **@**.edu **@**.gov **@**.mil When adding additional address formats, the menu also prompts you for a priority number. The priority number is 13 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- used to determine where a message should be routed if more than one host or gateway contains a qualifying format. If XGATE's gateway name is the only route for an SMTP root domain, the value used for the priority is purely subjective. Receiving SMTP MailReceiving SMTP Mail XGATE will NOT act as a relay host for other SMTP systems. Do not configure another SMTP mailer to relay its mail to XGATE! All mail received is accepted without question and considered destined for an MHS user. Since all mail received is considered destined for an MHS user, XGATE performs no validity checking of the recipient's name. It expects MHS to generate delivery errors for mis- addressed messages, and return them back through XGATE for delivery to the SMTP user. When receiving an SMTP message, if the host name for XGATE was given as a numerical IP address (i.e. Joe@134.23.45.1), it'll work fine. Likewise, outbound SMTP mail that originates from MHS can also be given as a numerical IP address (not normally recommended though). If you have XGATE configured to relay mail to another host, the relay host may not like it (along with any mail exchangers in between). Mail is normally addressed to an individual's host name not the IP address - all we're saying is that XGATE doesn't have any problems dealing with an IP address instead of a host name, should one pass through it. Delivery ModesDelivery Modes For outbound SMTP mail, XGATE can operate in a relay mode, a direct deliver mode, or a mixture of both. In relay only mode XGATE passes all outbound mail to another nearby SMTP host. In direct delivery mode XGATE resolves the recipient's host name either to a direct IP address or an MX record, and then initiates a connection to deliver the message. When attempting to directly deliver a message, XGATE first tries the actual IP address of the destination host. If a name lookup for the actual address fails, or a connection attempt directly to the IP address fails, XGATE then queries for an MX record. Note: This is actually backwards from RFC-821, but we felt the priority should be towards delivering mail as expeditiously as possible. In the world of PC-based E-Mail, users don't have a lot of patience and understanding for why 14 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- their message sat in a mail exchange host for 2 hours waiting for the next mail event to occur. What controls this is based on how you configure the XGATE.CFG file. In order to do direct delivery, XGATE needs to know the IP address of at least one name server. It can be configured to use as many as ten different name servers. If no name servers are given in XGATE.CFG, XGATE will work in relay mode only. Conversely, if the IP address for the relay host isn't given, XGATE will only work in direct delivery mode using the name servers specified. If the IP addresses of both the relay host and name servers are given, the order in which they are attempted is controlled by the "relay_mode" variable in XGATE.CFG. What are the pro's and con's? In direct delivery mode XGATE is usually more verbose (than most UNIX boxes) about reporting undeliverable status back to the sending MHS user. After 4 hours of not being able to deliver a message, XGATE will notify the MHS user that the message is having trouble, and indicates why. For each 24 hour period afterwards, another problem message is sent back to the sender until the undeliverable point is reached, at which time XGATE cancels the message and notifies the sender. In a direct delivery configuration, mail will also be delivered to a recipient's host significantly sooner. Depending on the type of connection though (i.e. to the Internet - whether its hidden behind an unreliable router, etc...), XGATE may not be as reliable in reaching all possible destination hosts in direct delivery mode, than another nearby UNIX box might be if it has a better or more direct access to the Internet. Usually the best way to first configure XGATE is using "relay_mode=0" where it tries direct delivery first (provided you have direct Internet access) using name servers, but also have a relay host defined in the event direct delivery doesn't work for a valid destination. Sometimes it takes a little experimentation to determine which is the best approach to use. 15 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- Running XGATERunning XGATE When you start XGATE, the current drive and directory must contain XGATE's overlays and configuration files. Also, when you start XGATE a user with the proper SMTP queue privileges must already be logged in to the file server (unless you want XGATE to perform the login by providing the user name on XGATE's command line). Normally you would have the AUTOEXEC.BAT file run XGATE. If you are using Novell ODI drivers, it might look something like this: @ECHO OFF PATH C:\DOS PROMPT $P$G CD \ODI LSL NE2000 IPXODI NETX CD \XGATE XGATE xgate,password If you installed XGATE on a network drive rather than on the C: drive, the AUTOEXEC.BAT file will also have to login to the file server and map a drive to the right server volume before XGATE is run. For example: @ECHO OFF PATH C:\DOS PROMPT $P$G CD \ODI LSL NE2000 IPXODI NETX CD \NETUTILS ATTACH fs/XGATE MAP F:=fs/VOL1:XGATE F: XGATE This example assumes that you've copied the ATTACH.EXE and MAP.EXE files from SYS:PUBLIC to C:\NETUTILS (on the computer that will run XGATE), and that a user name (without a password) called XGATE exists in the bindery and has been granted queue privileges to the SMTP queues (with XGATE's SETUP program), and that XGATE's overlays and configuration 16 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- files are installed in a subdirectory on VOL1: called "XGATE". If the computer running XGATE is a 386 or better with extended memory, using an extended memory manager that can provide some of it as expanded memory (LIM/EMS 4.0) is recommended. Also providing UMB memory (Upper Memory Blocks), and LOADHI as much of the network drivers as possible beforehand will prove helpful. But even if you didn't LOADHI any network drivers before running XGATE, if UMB memory is present when XGATE starts, it will automatically LOADHI its own overlays and will use as much of the free UMB memory as possible for a significant portion of its other memory requirements. Command Line Switches and SyntaxCommand Line Switches and Syntax XGATE has the following command line syntax: XGATE [login_name][,password] [switches] Whether you specify a login name on the command line usually depends on where you installed XGATE's files. If you installed XGATE's files on a file server volume, then before you run XGATE the computer must already have been logged in and the current drive and directory mapped to the drive where XGATE's files are located. In this case you probably wouldn't want XGATE to attempt another file server login (which is the same way in which you normally run MHS). But if you've installed XGATE's files on the local C:, it may be a lot easier to simply have XGATE do the login with the appropriate user name (and optional password). For the most part XGATE does not use command line switches to influence or control any feature or option related to the handling of mail, which is instead controlled by options in XGATE.CFG. Command line switches are mainly used to alter a cosmetic behavioral aspect of the program itself. (With the possible exception of the -Vnn switch.) -I-I When this switch is used, each ICMP message received is displayed in the SMTP Monitor. Without it, received ICMP messages are suppressed (with the exception of an ICMP echo reply from a PING request). In some situations the number of ICMP messages received can be rather verbose (i.e. redirects, or source quench) so this switch is provided primarily for debugging purposes. The screen output, with it enabled, can get a little convoluted and/or use up a lot of scroll back buffer. 17 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- -M-M MHS Gateway mode only. This switch causes XGATE not to load the SMTP Server module, effectively providing only the MHS conversion functions. For more information refer to the -S switch. -N-N This switch causes DNS (domain name server) lookups (along with queries received from local nodes) to be much more verbose than normal in the SMTP Monitor. This is primarily meant for debugging purposes. The screen output, with it enabled, can use up a lot of scroll back buffer very rapidly. -S-S SMTP Server mode only. This switch causes XGATE to directly enter the SMTP Server monitor on startup, and to exit completely when quit. Using this switch allows you to split the functionality of XGATE across two computers. One runs XGATE with a -S, the other runs XGATE with a -M. Use of the -M and -S switches is not normal. They are provided mainly for debugging situations. Should you choose to split XGATE between two computers in this fashion, your license allows you to do so. But your license does not allow you to run two fully functional copies of XGATE simultaneously. -Vnn-Vnn Overrides automatic detection of the MHS version number. For instance, if you are running MHS 2.0 (SMF-71) but you want XGATE to behave as if it were MHS 1.5 (SMF-70), use a -V70 command line switch. It is not recommended that you tell XGATE to use a higher version of MHS than is actually installed though! Valid switch options are -V64, -V70, and -V71. 18 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- Using XGATEUsing XGATE At startup, XGATE normally comes up in the MHS Gateway Activity screen (unless you run it with a -S switch). The 25th screen line is a status line that constantly displays some important status information (unless you're temporally using an interactive command). If at any time you need help on keyboard commands, pressing the <Esc> key will temporarily replace the status line with a list of active commands (which vary depending on whether you're in the MHS Gateway screen or the SMTP Monitor screen). To switch to the SMTP Monitor (server) screen, press the <M> key. To switch back to the MHS Gateway screen, press the <Q> key. Or, you can use the <Tab> key to quickly switch between the two screens. Scroll BackScroll Back You can activate the scroll back feature in both the MHS Gateway screen or the SMTP Monitor screen, by pressing either the <Up>, <PgUp>, or <Home> cursor keys. While scroll back is active, use the standard cursor keys (<Up>, <Dn>, <PgUp>, <PgDn>, <Home>, and <End>) to manipulate the screen within the scroll back buffer. To manually cancel scroll back, press the <Esc> key. Scroll back automatically self-cancels after 5 minutes of inactivity. When scroll back is active, an "SB" is displayed in the bottom right corner on the 25th screen line, and the screen is considered frozen - which means XGATE will not suddenly refresh it (or scroll it up on its own) if new activity has occurred. The size of the scroll back buffers depends on whether Expanded Memory (LIM/EMS 4.0) was present when XGATE started. If it was, XGATE will try allocate 64K from expanded memory for each scroll back buffer. If Expanded Memory isn't present, the scroll back buffers are allocated with x-number of lines from conventional memory as determined by the "mhs_scrollback_lines" and "smtp_scrollback_lines" variables in XGATE.CFG. 19 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- MHS Gateway ActivityMHS Gateway Activity The MHS Gateway Activity screen is a condensed list of activity that has passed through the gateway. Each line represents a message that was sent to a particular recipient. If a single message was addressed to more than one user, a separate line is used for each recipient. The following commands are active in the MHS Gateway screen: D - DebugD - Debug This is a command that does a small check to make sure XGATE hasn't lost any file handles (the default is 40 under NetWare), and how much of the MHS process stack has been consumed during MHS conversion activities. M - MonitorM - Monitor This command switches to the SMTP Monitor screen. S - ScanS - Scan This command terminates the time left before the MHS Gateway module will do another scan for mail that needs to be converted between MHS and SMTP. This was intended for situations where XGATE was configured with a high scan interval, and for one reason or another you're watching mail go through the gateway, and you know that MHS just delivered a message to the gateway, and you don't want to wait for the next scan interval to cycle of its own accord. Q - QuitQ - Quit This command exits XGATE. If an SMTP send or receive process is active, a warning message will prompt for confirmation first. The SMTP MonitorThe SMTP Monitor Each screen line displayed in the SMTP Monitor begins with a number that indicates which active process generated the line. When a system-type error or message is displayed (i.e. an asynchronous error, or the SMTP task dispatcher, the monitor's foreground handler, etc...), the process number is displayed as "$$:". If a domain name server ICMP 20 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- message is received asynchronously, a "NS:" is displayed for the process number. The SMTP Monitor provides a number of commands that can help test connectivity with other TCP/IP hosts: D - DriverD - Driver This command activates a sub-menu of additional options that display various elements of information regarding the current operating condition and status of the Mach 2 TCP/IP protocol stack. F - FilterF - Filter Normally the output from all active SMTP processes is displayed in chronological order, and will be intermixed if more than one process was active simultaneously. This command allows the monitor screen to be filtered to show only the output of one particular process. When a filter is active, a "F:nn" is displayed in the bottom right corner of the screen. Pressing the <Esc> key cancels an active filter. N - NSLookupN - NSLookup This command initiates a domain name service lookup for a particular host name. This can be useful for checking the proper operation of the name servers identified in XGATE.CFG, or for determining whether a particular host name is valid, and if so, what its IP address is, or MX records are. P - PingP - Ping This command initiates a series of ICMP echo requests with another TCP/IP host (one per second for 10 seconds). This is a good way to check if XGATE's basic TCP/IP connectivity is working properly, or to test if another TCP/IP host is alive (or reachable through your router). 21 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- Successfully receiving Ping replies from another host does not necessarily mean that its SMTP capability is working though. Occasionally an SMTP server daemon may stop accepting connections even though the host will respond fine to an ICMP Ping. The only way to fully test a remote host's current status of receiving mail is by using the Telnet/25 command. R - RouteR - Route This command simply displays what IP address and which interface (useful if more than one is present) that the Mach 2 TCP/IP protocol stack will use as the next hop destination for a particular IP address. This is basically a test of whether the ROUTE command in XGATE.CFG has been properly configured with the right default router. S - SMTP StatsS - SMTP Stats This command displays running statistics accumulated in the SMTP Server module. T - Telnet/25T - Telnet/25 This command initiates a Telnet session with another host using port 25, the port which the SMTP service runs on (port 23 is the normal Telnet port). This is a good way to check if another TCP/IP host is ready to receive inbound SMTP mail, or if it is for some reason refusing new connections. When a connection is established with this command, the remote host thinks you are an originating SMTP server. There are a number of text-based commands available that might prove useful, but explaining them all here is beyond the context of this documentation (refer to RFC- 821). Suffice it to say that most SMTP servers will respond to "HELP" and "QUIT" commands. Pressing <Esc> will also quit a connection. Q - QuitQ - Quit This command quits the SMTP Monitor and returns to the MHS Gateway Activity screen. 22 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- Using XGATE as a Name ServerUsing XGATE as a Name Server This doesn't have much to do with electronic mail, but what the heck.... If you have one or more name servers defined in XGATE.CFG (there isn't much of an advantage to doing this if you don't), you can configure local nodes to query XGATE as a name server. When XGATE receives a name server query, it immediately scans the cached image of the HOSTS file (described next) and sends a reply if the name is found. If the name isn't resolved by the HOSTS file, although this is unorthodox, XGATE immediately rebroadcasts the query to all name servers defined in XGATE.CFG and logs the request in a working table. As soon as one of the name servers provides a positive reply, XGATE relays the response back to the requesting station and closes out the active request. If a late reply comes in from one of the other name servers, it is discarded. XGATE will time out active requests if a positive response isn't received within 20 seconds. XGATE provides this service asynchronously as a background task. It is a very high performance solution to simplifying and expediting name server lookup's for client nodes. Workstation configurations can be reduced to sending just one query to XGATE and still have the benefit of being able to resolve names using all the name servers XGATE knows about, in a parallel fashion rather than one by one. The HOSTS FileThe HOSTS File Even though the HOSTS file will resolve names for outbound SMTP mail (and will do it before name servers are used), it is intended primarily as a mechanism to use nicknames or shorthand names for commonly accessed hosts when XGATE is queried as a name server. The format of the HOSTS file follows the somewhat conventional syntax; use one line for each host beginning with its IP address. Multiple host names can be given for the same IP address by appending them on the same line, separated with either spaces or tabs. For example: 129.194.30.5 ns-nic 129.9.0.107 isi a.isi.edu 23 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- The HOSTS file must reside in XGATE's home directory. Its contents are read at startup and held in memory, so don't get too carried away with adding a lot of names. Changes to the HOSTS file don't take effect until the next time XGATE is restarted. 24 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- Pre-InstallationPre-Installation Before you can install and configure XGATE, you will need to know and/or decide on two important names for XGATE, and obtain a dedicated IP address for XGATE's computer. The names you will need are: The MHS gateway name. The TCP/IP host name. The MHS Gateway NameThe MHS Gateway Name The MHS gateway name is what MHS users will use when they send mail through XGATE to an SMTP user. Chances are good that you're the MHS administrator and that you can decide on the MHS gateway name without much trouble. Give some consideration to keeping it short, simple, and easy to type. If your MHS E-Mail application doesn't have an easy-to-use template feature, your MHS users might end up typing it a lot. The TCP/IP Host NameThe TCP/IP Host Name The TCP/IP host name is what remote SMTP users use when they send mail to an MHS user through XGATE. Determining what XGATE's TCP/IP host name will be, and getting it properly configured within your TCP/IP network, is not as easy as picking the MHS gateway name. You may end up needing to consult with a local TCP/IP guru before its over. Basically, along with determining what the host name is, you also need a dedicated IP address assigned to the host name, and get both registered in an authoritative name server for your domain. The details of how TCP/IP host names and IP addresses work and interrelate can be a bit overwhelming for the uninitiated. If what we said makes sense and you know what XGATE's TCP/IP host name and IP address will be, or how to assign them - then you're all set. If not, you might want to refer to the section later on called "TCP/IP Host Names and IP Addresses". 25 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- InstallationInstallation Making a program that uses TCP/IP easy to install is almost impossible, but we try.... Programs that try to do too much of the installation and configuration process in an automated fashion usually end up handing you something you know absolutely nothing about. Where are all the pieces to the jigsaw puzzle? Just exactly what did this thing just do? Where are all the files that it just copied? What files contain configuration data? Etc.... XGATE's installation does include some automated help (in the SETUP program), but most of the pieces you'll put together yourself. Before starting the installation, you will need to know what XGATE's TCP/IP host name, IP Address, and MHS gateway name will be. The steps to installing XGATE are: 1. Copy XGATE's files. 2. Add a gateway name under MHS. 3. Edit XGATE's configuration file XGATE.CFG. 4. Use XGATE's SETUP program to create the SMTP queues, and to assign queue server rights to the user name that XGATE will use. 5. If using ODI drivers, modify the NET.CFG file. Copying XGATE's FilesCopying XGATE's Files There are two approaches you can take when deciding where to install XGATE. You can install it on the local hard drive of the PC that will run it, or you can install it on a network drive. The difference being that if you install XGATE on a network drive, you'll have to script the file server login and drive mappings in some type of batch file before you run XGATE (similar to how you might be running MHS). If XGATE is installed on the local hard drive, there's no technical reason why the computer needs to be logged in before running XGATE, so to make things easy XGATE provides 26 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- a means to do the user login for you if you give it a user name on the command line. If you install XGATE on a network drive, normal users do not need any disk privileges to XGATE's directory. After you've figured out where you want to install XGATE's files, just copy all of its files in there.... Adding a gateway name under MHSAdding a gateway name under MHS When MHS adds a new gateway, it automatically builds a directory structure for the gateway under its mv\MHS\MAIL\GATES subdirectory. XGATE does not use any INPOST or OUTPOST executables like other gateways, it only needs the directory structure. Other than telling MHS to add the gateway name for XGATE, there's nothing more to do (i.e. there are no files that need to be copied into the mv\MHS\MAIL\GATES subdirectory after MHS builds the gateway name). If you are using MHS 2.0 or NGM and want to setup XGATE as a native SMF-71 gateway, refer to the section called "Native Mode SMF-71" for detailed instructions. If you already know how to add a gateway under MHS, you can go ahead and do it (enter the gateway version as either 64, 70, or 71 depending on how high your MHS version is). There's nothing more that needs to be done regarding MHS, and you can skip ahead to the next section on XGATE.CFG. Adding the MHS gateway that XGATE uses is done from within the MHS program. These instructions describe the steps as they appear when using the user interface of MHS 1.1 or 1.5. If Novell ever releases the DOS version of MHS 2.0 (rumored to have been finished back in mid-1992, but being held captive for evil marketing reasons), the user interface will probably be different. Usually when you start MHS it will proceed a few moments later and run the "Connectivity Manager" (unless the host is not configured as a routing host). If you press the Escape key within the first few moments after launching MHS, instead of running the Connectivity Manger it'll come up with a prompt to log in. (If the Connectivity Manager has already started, pressing the Escape key two times should then produce the login prompt, unless its already been answered previously within this session). After you have logged into MHS by using the MHS administrator's password, and have found its Main Menu, select: 27 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- "Directory Manager" (Under MHS 1.5 its called "Manage Directories" instead). From the Directory Manager menu, select: "Routes to Workgroups, Hosts, and Gateways" Then select: "Add entry" And then pick: "Define a gateway" MHS will then display an entry form for adding a new gateway. What you enter for the "Host name:" is very significant. You might want to keep it short and easy to type. This is the name MHS users will type when they send mail through XGATE (you could of course define another hub which routes via this name if you want to alias it down to a shorter name). Whatever you enter for the "Host name:" - remember it and write it down. You will also need to enter it into XGATE's configuration file. What you enter for the "Description:" is purely discretionary, XGATE doesn't use it. Under "Gateway Version:" you can enter either 64, 70, or 71 (depending on which level your MHS can support). This tells MHS what level of the SMF language that XGATE understands. Under "Gateway Commands:", don't enter anything. A lot of MHS gateway programs are run directly within MHS and these are the commands that would be passed to the gateway program when executed. Since XGATE runs on a separate PC, gateway commands should be left blank. So all we've just done is told MHS to build a new gateway name in its host table and to create the corresponding MHS directory structure. Nothing more. The first time XGATE runs it will automatically build some additional directories under its gateway subdirectory in MHS. But you don't need to worry about doing it yourself. Editing XGATE.CFGEditing XGATE.CFG The sample XGATE.CFG configuration file included with XGATE is fully commented and you can probably configure XGATE properly just by using the comments. If you need more details on any of the options, refer to the reference section later on that gives a complete description of each option or variable. 28 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- XGATE.CFG is an ASCII text file. You can go ahead and edit it with any standard text editor. Using SETUPUsing SETUP After you've created the gateway name under MHS and edited XGATE's configuration file (XGATE.CFG), you're ready to use XGATE's SETUP program to create the SMTP queues and assign queue server rights to the user name that XGATE will run under. When using SETUP, you must be logged in as a supervisor equivalent (it'll warn you if you aren't). The normal 1st-time steps within SETUP are: 1. Create SMTP Inbound and Outbound Queues 2. Assign Queue Server Rights to a User Create SMTP Inbound and Outbound QueuesCreate SMTP Inbound and Outbound Queues This option creates the SMTP_IN and SMTP_OUT job queues that XGATE uses for inbound and outbound SMTP mail. If you are installing XGATE for the first time, this option also starts the 45 day evaluation timer. After using this option, there is normally no reason to ever repeat it (unless you have deleted the SMTP queues for some reason). Remove SMTP Inbound and Outbound QueuesRemove SMTP Inbound and Outbound Queues This option completely removes the SMTP job queues. Use this option with caution! If there is any undelivered mail in either queue it will be destroyed. The primary reason for providing this option is in the event that you've granted more than one user Queue Server rights and wish to retract them (in which case the only mechanism available is to remove the queues, re-create them, and then assign Queue Server rights again). Before using this option make sure there is no mail queued (usually outbound) that you would care about loosing. 29 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- Assign Queue Server Rights to a UserAssign Queue Server Rights to a User This option assigns Queue Server privileges to a user. Typically you will only need to assign queue server rights to just the one user name that XGATE will be logged in under. If you wish to run XGATE under your own login name for installation or troubleshooting purposes, you would also want to assign queue server rights to your own name. Note: NetWare does not consider a user with supervisor equivalence as blanket authorization to serve queues. A user with supervisor equivalence must also be assigned queue rights the same as any other user. To ensure proper privileges in the MHS directory structure, the user name picked with this option is also granted [SRWCEMF] trusteeship to the mv/MHS\MAIL directory structure. Serialize and Register XGATESerialize and Register XGATE After you have purchased a license to continue your use of XGATE, this option permanently serializes (registers) XGATE for your installation. When unregistered (during the evaluation period) XGATE runs as an unlimited host license. If you did not purchase an unlimited host license, you'll now have to create a file (with any text editor) called HUBLIC.DAT in XGATE's home directory that describes which MHS hosts are licensed to use XGATE. On separate lines, list the name of each MHS host that is authorized to send and receive mail through XGATE. Even if you're just running a single MHS host license, the first line of HUBLIC.DAT must contain your MHS host name. If you purchased an unlimited host license, there is no need to create or worry about the HUBLIC.DAT file. Modifying NET.CFGModifying NET.CFG The Mach 2 TCP/IP protocol stack built into XGATE directly supports either a Novell ODI driver, or a Clarkson Packet Driver (or both if the situation warrants). If you are using a Clarkson Packet Driver, the installation is now complete. If you are using a Novell ODI driver, you must make a small modification to the NET.CFG file to bind an "Ethernet_II" frame type to the board (network card) being used. (Ethernet_II is the frame type TCP/IP uses.) 30 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- For example: Link Driver NE2000 PORT 300 INT 5 MEM D000 FRAME Ethernet_802.3 FRAME Ethernet_II FRAME Ethernet_II After adding the Ethernet_II frame type, you'll need to reboot the computer before trying to run XGATE. Installation CompleteInstallation Complete After you have used SETUP to create the SMTP queues, and have granted queue server rights to the applicable user(s), you are now ready to try running XGATE. 31 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- Initial Testing and TroubleshootingInitial Testing and Troubleshooting The first thing you usually do when setting up a new TCP/IP host is to make sure it can "Ping" another TCP/IP host. The SMTP Monitor has a built-in Ping capability (pressing "S" or <Tab> from the MHS Gateway Activity screen will switch to the SMTP Monitor screen). For starters, try pinging another local TCP/IP host by using its IP address (not its host name). If that fails to work, check the netmask used with the bind statement in XGATE.CFG, and ensure its set to the right value for your subnet. If that seems fine, go to the machine you were trying to ping and see if it can ping another host (i.e. is it working ok?). If pinging another local TCP/IP host works, the network card is working OK, ARP is working OK, and the subnet mask is set correctly. The next thing to try is pinging a remote TCP/IP host using its IP address to see if network traffic through your router is working. If this doesn't work, check the ROUTE statement in XGATE.CFG and ensure that it contains a an entry with a valid IP address for the router that provides remote access to other networks. If the router's IP address is in question, try pinging the router itself with the same IP address. The last thing to try is using Ping with the host name of a remote host instead of its IP address. This ensures that the name server entries in XGATE.CFG are set right and responding. If there's a problem with name server lookups, try using the <N>SLookup option with a well known host name and watch what happens. The DNS interactions from a NSLookup are quite a bit more verbose than with a <P>ing or <T>elnet/25 command (unless you ran XGATE with a -N switch). If you experience a problem with the Ping or Telnet/25 commands and are wondering whether XGATE.CFG was configured correctly - the only options in XGATE.CFG that could have any affect are the bind and route statements. If all of this works OK, try sending a message through XGATE and watch how the message is handled on the SMTP Monitor's screen. Hopefully this is the beginning of a beautiful friendship! 32 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- TCP/IP Host Names and IP AddressesTCP/IP Host Names and IP Addresses There are basically two ways to set up XGATE so that remote SMTP hosts can send it mail. They will be listed shortly in order of desired preference. In all cases though, XGATE must be assigned a TCP/IP host name and an IP address. An IP address is a number comprised of 4 digits separated with dots (sometimes called "dotted notation"), which might look something like "131.46.23.5". If XGATE's IP address was 131.46.24.5, some remote SMTP hosts will allow users to send a message to an MHS user on XGATE just by using the IP address (i.e. "Joe@131.46.23.5", or "Joe@[131.46.23.5]"). But sending mail in this fashion is unconventional and can be difficult for the remote SMTP user to remember. It also makes it hard to change XGATE's IP address because doing so would invalidate the E-Mail addresses of all your MHS users. So the "normal" is to assign a host name to the IP address and use the host name instead. We will try to go slow and explain things thoroughly, but you may find it easier to take this section of the manual to your local TCP/IP expert, who should be able to help you with what steps you need to take, and who to talk to next. Note: Normally you can't just pick a TCP/IP host name or an IP address without first checking with the appropriate office or person that administers TCP/IP names and addresses for your network! Configuring DNSConfiguring DNS DNS means Domain Name Service. It is a protocol that runs on top of UDP (and in turn on top of IP) that provides the most popular mechanism for translating a host name into an IP address (using a host table is the other). The simple act of selecting a TCP/IP host name for XGATE won't in itself do much until you have the host name registered in some type of name server. An name server answers DNS queries in a hierarchical fashion, which allows remote hosts to resolve where they should send messages that are addressed to MHS users at XGATE's TCP/IP host name. 33 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- If all you'll be doing is exchanging mail locally, a simple entry in a local name server should suffice to get SMTP mail working with XGATE. If you'll be receiving mail from various locations all over the Internet, you'll probably need to get XGATE's TCP/IP host name registered with the authoritative name server for your domain. For example, if XGATE's TCP/IP host name was "xgate.acme.com", and XGATE's IP address was 125.26.10.1, the entry you would want entered in your authoritative name server's hosts database would look similar to this: Name ________________ Class _______ Type ______ Address ______________ xgate.acme.com IN A 125.26.10.1 Defining MX RecordsDefining MX Records MX records (which means Mail Exchange) are entries that can also be defined in your authoritative name server that are used by remote SMTP hosts to determine if there's an alternate host that will accept mail for XGATE (and then forward it). If the physical link to XGATE from the outside world is a little "shaky" or non-existent, but a nearby "UNIX box" has a good connection to the outside world, you can define the "UNIX Box" as an MX record for XGATE with your authoritative name server. More than one MX record can be used (and often is), to improve the likelihood that in one way or another a remote SMTP host will be able to forward mail destined for XGATE to another host. For example, if the host name of the nearby "UNIX box" was called "bigbro.acme.com", the entries needed in your domain name server's hosts database would look similar to this: Name ________________ Class _______ Type ______ Pri _____ Address _____________ xgate.acme.com IN A 125.26.10.1 IN MX 0 xgate.acme.com. IN MX 10 bigbro.acme.com. The secret here is that MX entries are used in order of priority, from lowest to highest. So when remote SMTP hosts have mail for XGATE and then query for MX records, they'll get two results. The lowest is the direct address to XGATE which may fail to connect. If so, they'll then use the next highest priority which is the "UNIX box" and give it your mail. The "UNIX box" will then try to forward the message to XGATE and would succeed using the first one with the 34 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- lowest priority. If the order of priorities were reversed, the "UNIX box" would try talking with itself first, which sometimes causes an internal error and cancellation of the delivery. Hiding XGATE Behind Another UNIX HostHiding XGATE Behind Another UNIX Host The most desirable way to use XGATE is by using DNS to resolve XGATE's TCP/IP host name when remote SMTP hosts have mail to send to it. If this isn't possible because you can't get XGATE's TCP/IP host name registered with an authoritative name server, there is still a way to work around the problem if a nearby "UNIX box" can be configured to forward mail to XGATE when the address contains a certain flag after the user's name. But its not easy.... There's no reason to bother reading this section, or trying to understand it, if you're going to register XGATE's host name with a name server! Normally XGATE has its own unique TCP/IP host name, and mail addressed to "Joe@xgate.acme.com" is clearly intended for an MHS user called Joe at the default MHS workgroup. But when XGATE shares the same TCP/IP host name with another "UNIX box", something more than just "Joe" has to be given for the user name so that the "UNIX box" will know the message gets forwarded to XGATE. The technique normally works like this. Some sort of flag text is used after the user name to indicate the message is to be forwarded to XGATE instead of going to a local user on the "UNIX box". For example, if the flag text was ".mhs", Joe would be addressed as: joe.mhs@bigbro.acme.com" So what the "UNIX box" has to do when it processes inbound mail is look for user names that end with ".mhs". If one comes through, it would strip off the ".mhs" and forward the message to "Joe@xgate.acme.com". In this situation, the only host that knows the name "xgate.acme.com" is the "UNIX box", you configure XGATE to use the same TCP/IP host name as the "UNIX box" (which is controlled by the SMTP_GATEWAY_NAME variable in XGATE.CFG). If its hard to get a host name mapped to an IP address for XGATE in the "UNIX box", forwarding the message to XGATE's IP address should work fine. 35 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- So how do you get XGATE to build reply addresses with a ".mhs" after the user's name? Use the following definition in XGATE.CFG: SMTP_USER_SUFFIX = .mhs How you get a "UNIX box" to do this type of black magic is beyond the scope of this documentation and varies with the type of SMTP daemon in use. It does take a darn sharp UNIX administrator willing to take on a small challenge. 36 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- XGATE.CFGXGATE.CFG XGATE.CFG is an ASCII text file that can be edited with any standard text editor. It describes and controls almost all of XGATE's configuration. The formatting syntax of XGATE.CFG is not very particular. Each option begins with a variable name followed by a value. Between the variable name and the value can be any number of space or tab characters (at least one must be present), along with an optional equals sign. When a semicolon is encountered, it, and the rest of the line (and any preceding white space) is considered a comment. XGATE.CFG Alphabetical IndexXGATE.CFG Alphabetical Index append_ascii_attach...............................41 bind..............................................56 black_and_white...................................50 connect_timeout...................................53 conv_body_to_attach...............................42 conv_time_to_local................................45 decode_header.....................................49 domain_timeout....................................55 error_log.........................................51 ignore_lwsp_after_fold............................42 inbound_log.......................................50 include_header....................................40 include_smtp_fields...............................40 ipforward.........................................58 max_xmit_processes................................52 mhs_admin_errors..................................40 mhs_administrator.................................39 mhs_default_host..................................39 mhs_gateway_name..................................39 mhs_path..........................................39 mhs_scrollback_lines..............................51 mute..............................................50 name_mapping_mode.................................47 name_server.......................................54 native_smf71......................................44 outbound_log......................................50 ping..............................................55 relay_host........................................53 relay_mode........................................52 reschedule_minutes................................53 resolve_minutes...................................54 37 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- route.............................................57 scan_frequency....................................50 scrap_mhs_attach..................................49 screen_save.......................................50 smtp_default_host.................................44 smtp_exclude_mhs_hub..............................45 smtp_gateway_name.................................44 smtp_include_mhs_app..............................46 smtp_receipts.....................................47 smtp_scrollback_lines.............................51 smtp_timezone.....................................44 smtp_user_suffix..................................48 static_reply_address..............................43 undeliverable_hours...............................53 use_mhs_ret_rcpt..................................47 use_mhs_total_fields..............................41 use_smtp_repto_as_from............................41 uuencode..........................................48 watch_dog.........................................51 38 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- XGATE.CFG ReferenceXGATE.CFG Reference The variables and options are listed in the order in which they appear in XGATE.CFG. mhs_pathmhs_path This variable tells XGATE what directory contains MHS. This path is normally entered using a volume name, not a DOS drive letter. For instance, if MHS is installed in the root directory of SYS: (i.e. the path to the MHS Mail directory is SYS:MHS\MAIL), you would enter "mhs_path=SYS:" (without the quotes). mhs_gateway_namemhs_gateway_name This variable tells XGATE what its gateway name is under MHS. XGATE uses this value to determine where MHS will put outbound messages, and also uses it to build the return address for outgoing SMTP mail. It should contain the same name that you used when you added the gateway name under MHS. mhs_default_hostmhs_default_host This variable controls what happens to inbound SMTP mail that does not specify the destination MHS hub. If this variable is omitted or left blank, XGATE sends the message to the hub name defined as the "workgroup" under MHS. If a value is given for this variable, the message is sent to the host name specified. This variable is not normally given a value since the workgroup name of the local MHS hub is normally where an inbound SMTP message should be sent if the MHS hub wasn't specified. But its provided as an option in case a different host or workgroup name should be used. mhs_administratormhs_administrator This variable overrides XGATE's automatic determination of the MHS administrator. Normally XGATE will determine who the MHS administrator is by reading the MHS NETDIR.TAB file. It can sometimes be convenient to override where XGATE's error messages go if a different person administers XGATE. 39 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- The value entered should be a fully qualified name expressed in native MHS syntax (i.e. mhs_administrator=joe@mhs1). mhs_admin_errorsmhs_admin_errors This option tells XGATE whether or not to send the MHS administrator copies of various errors (such as routing or non-delivery) as a message. The possible answers are either Yes or No. include_headerinclude_header This variable controls whether XGATE includes the header of received SMTP messages either at the start of the MHS body, or encapsulated in the MHS header. It has the following possible values: B....The SMTP header is written at the start of the MHS body. Y....Same as "B". H....The SMTP header is encapsulated in the MHS header. N....The SMTP header is not retained. Using the "H" option is useful only if your MHS E-Mail application provides a function that allows the header of inbound mail to be viewed as it was received. include_smtp_fieldsinclude_smtp_fields This variable allows some of the fields in a received SMTP message to be written into the beginning of the body text in a MHS message. Sometimes these fields can provide valuable information to the MHS user which might otherwise be hidden depending on the particular MHS E- Mail software in use. For instance, if a message had multiple recipients (specified by the SMTP To: header field), but the MHS E-Mail software displays the MHS "Send-To:" field instead, the MHS recipient won't see the complete list of recipients. This variable has the following format: include_smtp_fields=[T][F][C][R] (The brackets are meant to indicate each flag is optional. They are not part of the syntax.) 40 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- Each flag causes the following SMTP header fields to be included in the MHS body: T....To: F....From: C....Cc: R....Reply-To: use_mhs_total_fieldsuse_mhs_total_fields This option enables an effect similar to that of the "include_smtp_fields" option, except that it works a little more cleanly provided your MHS software recognizes the SMF-70 "Total-to:" and "Total-Copies-to:" header fields. If this option is enabled, XGATE builds the "Total-to:" and "Total-Copies-to:" MHS header fields with a complete list of their respective recipients. This keeps the information out of the body text and possibly allows replies to go to all recipients, but this only works if your MHS E-Mail application recognizes and reacts to these fields. Possible values are either Yes or No. You probably wouldn't want to enable this option, and "include_smtp_fields" at the same time. use_smtp_repto_as_fromuse_smtp_repto_as_from When processing an inbound SMTP message, this option tells XGATE to use the SMTP Reply-To: field for the MHS message's From: field. Prior to MHS 1.5, the SMF language did not provide for a Reply-To: field, which allows message replies to go to a different address than the message sender. If your MHS E-Mail application does not recognize the MHS Reply-To: field, turning this option on is one way to fix the problem. This option is not normally enabled if your MHS E-Mail application was written for SMF-70 (MHS 1.5) or greater. Possible values are either Yes or No. append_ascii_attachappend_ascii_attach This variable tells XGATE whether to automatically append MHS file attachments onto the end of the outbound SMTP message body, when the attachment only contains ASCII text characters. 41 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- It has the following format: append_ascii_attach=nn Where "nn" is the maximum size of an attached file (in K) that will be considered for appending. For more information, refer to "Appending ASCII Attachments" described under the Features section. conv_body_to_attachconv_body_to_attach This variable is used to protect an MHS E-Mail application from receiving a SMTP message with body text larger than it can handle. For instance, Beyond Mail for Windows has a body text limitation of 32,000 bytes. If an SMTP user sends a message to the Beyond user that has a body larger than 32K, Beyond Mail will callously truncate it at the 32K boundary. Setting this variable to a non-zero value causes XGATE to check the size of the SMTP body, and move the body to a file attachment if it exceeds the value. (When the body is moved, a small notice is written into the body text indicating this condition occurred.) The value given is in K (1000, not 1024). If its zero or undefined, this feature is not enabled. ignore_lwsp_after_foldignore_lwsp_after_fold This option controls whether XGATE considers linear white space characters (LWSP) after a folded header field in an MHS message as significant. This option is rather technical and is not normally enabled. The WPO MHS gateway is the only application known so far that needs it enabled. 42 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- According to the SMF-70 and 71 Programmer's References, folded lines are only permissible where LWSP characters are allowed (i.e. not in the middle of an SMTP address, unless there actually is a space in the SMTP address). Normally any application that processes an MHS message and encounters a folded line is to assume that LWSP characters starting the continuation line are logically equivalent to a space character if they occur in the middle of an active address. Enabling this option, disables this logic and any LWSP characters beginning a folded line are discarded. Normally this option is disabled. If you occasionally see an outbound MHS message produce a space character in the middle of the resulting SMTP message's To: or From: fields that wasn't entered that way inadvertently by the sender, you may need to turn this option on. Possible values are either Yes or No. static_reply_addressstatic_reply_address This option controls the format of reply addresses built for MHS users from inbound SMTP mail. With this option off, the MHS reply address for inbound SMTP mail is built using a combination of the first eight characters of the SMTP user's name @ XGATE's gateway name (plus the SMTP address in the MHS extended address), which is the conventional way to address mail through a gateway. MHS however, will also route mail fine to XGATE if an alternate syntax where the gateway name preceeds the MHS workgroup name is used. For example: SMTP @ ACME {smtp_address} (If SMTP is XGATE's gateway name and ACME is your MHS workgroup name.) Enable this option if you'd rather use this style of syntax. Possible values are either Yes or No. Note: If native_smf71 is enabled, this option has no effect. 43 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- native_smf71native_smf71 Enabling this option usually means you are running MHS 2.0 or NGM and have XGATE configured as a gateway that supports additional TCP/IP address formats. This option is recognized whether or not you have MHS 2.0 or NGM (SMF-71) installed, which allows native SMTP addressing from your MHS E-Mail application if you're using an MHS clone that can do hint routing but isn't SMF-71 capable. When enabled, native_smf71 significantly alters XGATE's addressing behavior. For a detailed explanation refer to "Using XGATE with SMF-71". Possible values are either Yes or No. smtp_gateway_namesmtp_gateway_name This variable should be set to the fully qualified TCP/IP host name that has been assigned to XGATE. XGATE uses this variable to build the reply address for outgoing SMTP mail, and the SMTP Server module uses it in some of its dialog when exchanging mail with other SMTP hosts. smtp_default_hostsmtp_default_host Using this variable is optional and is useful if a large percentage of outbound SMTP mail goes to a certain SMTP host. If an MHS user sends a message through XGATE without specifying the destination SMTP host, the message will be addressed to the host specified by this variable. If this variable isn't set and a MHS message is launched without specifying the destination SMTP host, it will almost certainly be returned with a delivery error. For example, if this variable is set to "acme1.com" and XGATE's MHS gateway name is "SMTP", an MHS user can send a message to "joe@acme1.com" by simply addressing it to "joe@smtp". smtp_timezonesmtp_timezone This variable is used when XGATE builds the "Date:" field in an outbound SMTP message, when the "Date:" field in the sender's MHS message did not contain a UTC (Universal Time Coordinate). 44 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- SMTP messages are expected to have a time zone in their date fields, but in MHS it was an after-thought. Even the most up-to-date versions of many MHS E-Mail applications still don't build it properly. So when XGATE converts an MHS message that doesn't specify the time zone in its "Date:" field, it needs to know what time zone should be used in the outbound SMTP message. Even if your MHS E-Mail application does correctly build its "Date:" fields with a UTC, its still a good idea to make sure this variable is set properly for XGATE. (If the "conv_time_to_local" option is enabled, this variable must contain a valid time zone.) Valid options are: PST, PDT, MST, MDT, CST, CDT, EST, EDT, or a UTC (i.e. -0800, -0500) Note: If a text-based time zone is entered for this variable (i.e. "PST"), it is internally converted to a UTC value, and the UTC value is then used for almost all of the time zone related functions within XGATE. conv_time_to_localconv_time_to_local This option controls whether XGATE will convert the date/time stamp of inbound SMTP mail to local time. Sometimes this is desirable for several reasons (since MHS doesn't want to do it for us). First, if your MHS E-Mail application displays messages received sorted by the date stamp, messages received from SMTP that were sent at an earlier hour won't show at the top of the inbox, where you would expect to see a new message (provided a user gets that many messages). Second, you might want the date and time of all messages in your inbox to be based on local time (since there's usually nothing that says the time of the message is not local). In order for this feature to work right, the "smtp_timezone" has to be set correctly. Possible values are either Yes or No. smtp_exclude_mhs_hubsmtp_exclude_mhs_hub This option controls whether the reply address built for outbound SMTP messages will include the name of the sender's MHS workgroup. 45 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- If there's only one MHS hub that XGATE will receive mail for, or if MHS is configured as a multi-host workgroup, you may find it desirable to not have the sender's MHS workgroup name expressed in the reply address of outbound SMTP messages, since replying to the MHS user at the default workgroup will work fine. This option should not be enabled if XGATE will handle any outbound MHS message that can't be replied to by using the sender's name at the default MHS workgroup. (This might be the case if XGATE handles mail that originates from another gateway on your MHS hub.) If XGATE will route mail to users on multiple MHS hubs and you don't use a workgroup-wide router, do not enable this option! For example; if the MHS workgroup name is "mhs1" and XGATE's smtp_gateway_name is "xgate.acme.com", and this option is disabled, the reply address will look like this: user%mhs1@xgate.acme.com If this option is enabled, reply addresses will look like this: user@xgate.acme.com Enabling this option might reduce some confusion if you want to tell SMTP users that your MHS users are addressed as user@smtp_gateway_name instead of user%mhshub@smtp_gateway_name, since they then won't get messages with a reply address that looks different. smtp_include_mhs_appsmtp_include_mhs_app This option controls whether XGATE includes the MHS application name in the reply address when building an outbound SMTP message (if it was given in the MHS message). This option is not normally enabled because MHS "manages" E-Mail applications. Which means that MHS will automatically route inbound messages to the user's primary E-Mail application when its not explicitly specified. Regardless of whether this option is enabled, XGATE always reacts to an MHS application name if its embedded in the address of an inbound SMTP message (inside square brackets). 46 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- This option is provided in the event that you have MHS users that use more than one E-Mail application, and embedding the application name in their reply address is the only way to assure that replies will come back to the right E-Mail application. Possible values are either Yes or No. smtp_receiptssmtp_receipts This option controls whether all received SMTP messages will request a return receipt when the MHS user reads the message (not normally used). Other options for requesting return receipts are described in a previous section called "Return Receipts". use_mhs_ret_rcptuse_mhs_ret_rcpt This option controls whether XGATE pays any attention to if an outbound MHS message has a return receipt requested. If this option is enabled and an MHS message requests a return receipt, a "Return-Receipt-To:" field is inserted in the SMTP header. In most cases however, this only produces a delivery notification from the SMTP mailer, not a time-of-reading notification. If most MHS users on your system default to having return receipts enabled, it may not be desirable to have this option enabled. It is off by default. name_mapping_modename_mapping_mode This variable controls whether the return address for outbound SMTP mail is built using a percent ("%") character as the MHS workgroup delimiter, or whether the old-style period is used. This variable has the following options: 0....A "%" is used for the workgroup separator 1....A "." is used for the workgroup separator 47 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- If "smtp_exclude_mhs_hub" is enabled, this option has no effect. This option only controls how the reply address of an outbound SMTP message is built. For inbound messages, XGATE will always respond to the percent sign as an MHS workgroup separator, or if a percent sign isn't found, the first period encountered is considered the end of the user name and the start of the MHS workgroup. Subsequent periods are then considered to be periods. In order to fully support SMF-71 long user names (that legally can contain a period), the mapping mode should be set to 0. Mapping mode 1 will still work with SMF-71 as long as all inbound SMTP messages use short names for the user name. smtp_user_suffixsmtp_user_suffix This is an optional variable that is NOT___ normally used. If for some reason additional text needs to be inserted in the reply address of outgoing SMTP mail, between the user's name and the smtp_gateway_name, this field will do that. Normally XGATE builds reply addresses of outgoing SMTP messages using a syntax of "user%mhshub@smtp_gateway_name". If a value is given for this variable, the text is inserted between %mhshub and @smtp_gateway_name. When you might consider using this option is in a situation where because for one reason or another you can't get XGATE's TCP/IP host name registered with a name server - but there's a nearby UNIX host willing to accept and forward mail to XGATE. The technique for doing this is described in a section called "Hiding XGATE Behind Another UNIX Box" earlier in this manual. This only time this variable is used is when building the reply address for an outbound SMTP message. uuencodeuuencode This option controls whether XGATE will automatically uuencode files attached to MHS messages, and whether it will automatically scan inbound SMTP messages for a block of uuencoded text. Possible answers are either Yes or No. 48 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- decode_headerdecode_header This variable is provided to help trigger automatic uudecoding of encoded MHS file attachments when they reach a remote SMTP user. A lot of SMTP user agents don't automatically scan for uuencode blocks unless they see a header field in the SMTP message that makes them think the message might have a block of uuencode text. When one or more of these variables are defined in XGATE.CFG, XGATE will automatically insert all of them in the header of the SMTP message when it uuencodes a MHS file attachment. The best way to determine whether this variable can help, and what text to use if so, is to scrutinize the header generated by the SMTP user agent in question when it sends a uuencoded file attachment. If the filename of the attached file is needed in the SMTP header, embedding a %FN in the variable's definition will expand into the real-time name of the file(s) when the message is built. For example: decode_header=Next-Attachment: %fn decode_header=Content-Type: x-uuencode-apple-single The first example is designed to trip automatic decoding on NEXT computers, and the second for Apple computers running Microsoft Mail. A little experimentation may be necessary to determine whether a remote SMTP user agent can be tricked into automatically decoding a uuencoded block, and what the proper values are. scrap_mhs_attachscrap_mhs_attach This variable allows you to have certain MHS file attachments ignored when a MHS message passes through XGATE (instead of sending the file as a uuencoded block in the message body). This is useful with some MHS E- Mail applications that like to add an attachment containing formatting information (such as Beyond Mail's Windows product) which has no useful purpose if sent to an SMTP user. This variable can be defined more than once. For example: scrap_mhs_attach=*BEYOND* ;Scrap Beyond's attachs 49 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- scan_frequencyscan_frequency This variable controls how often XGATE scans for new MHS mail in seconds. XGATE is very efficient about doing this. A value between 10 and 20 seconds is negligible in the amount of network traffic generated. black_and_whiteblack_and_white This option forces XGATE to operate in a black and white mode, which could be useful when you have a monitor that displays shades of green (or whatever) attached to a color video card. mutemute This option keeps XGATE from beeping when error messages are displayed. Possible answers are either Yes or No. screen_savescreen_save This variable sets the number of minutes after which XGATE will blank the screen if no activity has occurred. A value of zero disables the screen saver. If enabled, a blanked screen is automatically restored when new activity occurs. inbound_loginbound_log If this variable contains a value, a complete path and filename must be used. XGATE will then write a single- line entry in the file specified for each inbound SMTP message received. If the path points to a server volume (i.e. SYS:XGATE\INBOUND.LOG), make sure the user name XGATE is logged in with has sufficient disk privileges. outbound_logoutbound_log If this variable contains a value, a complete path and filename must be used. XGATE will then write a single- line entry in the file specified for each outbound SMTP message received. If the path points to a server volume (i.e. SYS:XGATE\INBOUND.LOG), make sure the user name XGATE is logged in with has sufficient disk privileges. 50 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- error_logerror_log If this variable contains a value, a complete path and filename must be used. XGATE will then write a single- line entry in the file specified for each error or warning message encountered. If the path points to a server volume (i.e. SYS:XGATE\INBOUND.LOG), make sure the user name XGATE is logged in with has sufficient disk privileges. mhs_scrollback_linesmhs_scrollback_lines This variable controls how much conventional memory can be allocated for the MHS Gateway Activity scroll back buffer. For more information refer to "smtp_scrollback_lines". smtp_scrollback_linessmtp_scrollback_lines This variable controls how much conventional memory can be allocated for the SMTP Monitor scroll back buffer. If expanded memory (LIM/EMM) version 4.0 isn't present, this variable controls how many lines of scroll-back buffer XGATE will attempt to allocate from conventional memory. XGATE will limit the total number to a value that uses less than 64k. (Each line consumes about 80 bytes.) If expanded memory is present, XGATE disregards this variable and first attempts to allocate two 16K pages. If it gets that, it'll try to expand it to a full 64k by allocating 2 more pages of 16K. (The minimum unit of issue in the world of expanded memory is a 16K page.) watch_dogwatch_dog This variable controls whether XGATE will try to watch from the hardware timer-tick whether something has gone awry and the computer is hung-up. If no activity has been detected either with XGATE's process time slicer, or the MS-DOS function dispatcher for the specified number of seconds, XGATE will reboot the computer. This feature will only work if hardware interrupts are still functioning at the point when the computer needs to be rebooted. Chances are slim that you'll need this feature, but with so many different elements involved it was thought to be a good thing to have around anyway. 51 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- A value of zero disables the watchdog. Otherwise, if the value given is not zero and less than 10 XGATE will automatically raise it to 10. If this value is set to 10, the computer will simply reboot after 10 seconds of apparent inactivity. If the value is set higher than 10 seconds, the watch dog will start beeping at the 10 second mark, and once again every two seconds, until the time out period expires. max_xmit_processesmax_xmit_processes This variable limits the maximum number of originate (transmit) processes that XGATE will start concurrently. Even though the SMTP Server is technically capable of supporting 100 concurrent SMTP sessions (memory providing), this is usually much more than most sites will ever have a realistic requirement for. But if so, this option is mainly used to prevent outbound sessions from saturating all of the sockets possible in the SMTP Server (which can happen if XGATE has been off-line for a while and has received a lot of outbound mail from MHS in the meantime) and thus leaving it incapable of receiving a listen connection. Since the SMTP Server uses the NetWare Queue Services API, each inbound or outbound session indirectly involves opening a file handle. Before raising the value of this variable higher than 40 (which is the default number of file handles under NetWare), you should also correspondingly raise the number of file handles that NETx is capable of supporting. Normally a value of 20 is more than adequate for most installations.... relay_moderelay_mode If both the relay host is defined and name servers are given, this variable controls whether XGATE first attempts to connect to the relay host, or directly to the destination host using the name servers (when processing outbound mail). These are the possible values: 0 Attempt direct delivery first using the list of domain name servers. If the host name can't be resolved or if XGATE can't connect to the host, pass the message to the relay host (if defined). 52 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- 1 Attempt to pass all messages to the relay host first. If the relay host isn't available and name servers have been defined, XGATE will then attempt direct delivery to the remote host. Note that the only instance in which XGATE will pass multiple recipient names in the same session (should it get a message that converted from MHS that way by XGATE) is if the relay_mode is set to 1. If the relay_mode is set to 0, XGATE will initiate separate connections for each recipient in a message. relay_hostrelay_host This is the fully qualified numeric IP address of the relay host. If the relay host isn't specified, at least one name server must be given. Whether the relay host is used first, or direct delivery to the recipient's host, is controlled by the "relay_mode" variable. connect_timeoutconnect_timeout This is the time XGATE will wait in seconds after initiating a connection, before considering the connection attempt failed for lack of any response. reschedule_minutesreschedule_minutes If this variable is set, XGATE will re-schedule outbound messages (queue jobs) that fail to connect by this many minutes. This is mainly useful when XGATE runs in direct deliver mode without a relay host, so that it won't tie up a lot of CPU time constantly trying to connect to a foreign host that is unavailable or doesn't exist. Even if this variable isn't set, XGATE always rotates jobs that fail to the end of the queue. undeliverable_hoursundeliverable_hours This variable tells XGATE how long to continue trying to send a message that it can't deliver (for any reason), before returning it to the sender as undeliverable. 53 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- If this variable is set higher than 24 hours (recommended because some systems go down over the weekend), XGATE will send an error status message back to the sender after the first 4 hours, and subsequently after each 24 hour period that a message is undeliverable. If a relay host is defined, chances are this time out will never be encountered since XGATE will subsequently pass a message that fails direct delivery to the relay host. resolve_minutesresolve_minutes This variable tells XGATE how long to continue trying to deliver a message when its host name can't be resolved using the name servers defined. You would normally set this value to at least twice the value of "reschedule_minutes" so that your name servers will have at least two attempts at resolving the destination host. Sometimes a caching name server won't know a host name when queried the first time, but will subsequently issue a recursive query back up its chain, and in the meantime XGATE has advanced to the next name server in the list - all of which may time out the first go around. On a second attempt, one of the caching name servers might have gotten a response back and be able to resolve the name. When this time out expires, the message is returned to the sender with an error that the host is unknown. If a relay host is defined, chances are this time out will never be encountered since XGATE will subsequently pass a message that fails direct delivery to the relay host. name_servername_server This variable identifies a name server. The value given must be a fully qualified numeric IP address. In order for XGATE to do direct delivery, at least one name server must be specified so destination host names can be resolved to a numeric IP addresses. 54 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- XGATE can also utilize a file-based host table (called HOSTS in XGATE's home directory), but its provided mainly for serving short-cut names to local hosts (if they are configured to query XGATE as a name server). The purpose of XGATE's HOSTS file isn't to resolve all of the possible host names that outbound SMTP mail might need to resolve. If all hosts were defined in the hosts file, the impact on XGATE's working memory would probably inhibit XGATE from loading at all - and you don't want that kind of administration anyway. Its much easier and better to define several name_server entries so XGATE can resolve outbound mail by querying another name server, when it attempts direct delivery. This variable can be given more than once, up to a maximum of 10 times. domain_timeoutdomain_timeout After sending a query to a name server to resolve a host name, this is the time (in seconds) that XGATE waits for a response before advancing to the next name server or timing out the attempt if no more name servers are left to query. When multiple name servers are given, a late response from a query to a previous name server is still recognized. pingping This statement allows a host to be Ping'd on a recurring basis. This could be useful if your access to the Internet is through a dial-up link that disconnects after a period of inactivity, and you want something to generate recurring traffic through the link so that the inactivity timeout won't occur. The format of the ping command is: ping <ipaddress> [minutes] The <ipaddressipaddress> is the host you want to ping (which should be on the other side of the router you want to keep awake). MinutesMinutes is an optional number of minutes in between ping's generated. If it isn't given, a value of 1 is assumed. Ping activity generated by this option won't show in the SMTP Monitor unless XGATE is started with the -I (verbose ICMP) command line switch. 55 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- Only one PING command can be active in XGATE.CFG. bindbind This variable essentially tells XGATE what its own IP address is. Although its not normal, XGATE can support more than one interface (network card) by using multiple bind commands. IP addresses are bound logically inside XGATE (actually in the Mach 2 TCP/IP protocol stack) to either an ODI driver, or a Packet Driver. As mentioned, more than one bind statement can be used to support multiple IP addresses and/or interfaces, but such usage is rare. At least one bind statement must be present in XGATE.CFG. The format of the bind command is: bind <ipaddress>, <netmask> [,<interface>] [,<bcast>] <ipaddressipaddress> is the local IP address being bound to a particular interface board (which will be XGATE's local IP address). <netmasknetmask> is the portion of the IP address that represents the network part (which is what XGATE uses to determine when a packet is destined to a remote network and has to be routed). For instance, the netmask of a class C subnet would be 255.255.255.0. Both the <ipaddress> and <netmask> parameters are expressed as fully qualified IP addresses in dotted notation. <interfaceinterface> is an optional parameter that explicitly tells XGATE what network interface (card) to bind the IP address to. In most cases this can be left out or set to zero and XGATE will automatically bind correctly to the next available interface driver that supports a TCP/IP frame type. Specifying which interface is needed if more than one network card is present, or more than one frame type is present that supports TCP/IP. If the interface is not specified and XGATE does a search for a compatible interface, an ODI driver is recognized before a Packet Driver, should both happen to be present. When specifying an explicit interface, the number can be expressed in either decimal or hex (hex values are given in C format by prefixing the number with a "0x"). 56 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- If the interface number is a value between 1 and 16 (decimal), it is considered to be a reference to a logical MLID "board ID" number that was bound to a suitable frame type in NET.CFG (usually ETHERNET_II). (An MLID is a card-specific ODI driver.) If the interface number is a value between 17 and 255 (decimal), it is considered to be a reference to a Clarkson Packet Driver configured to use that number for its software interrupt. Packet Driver interrupts are normally expressed in hexadecimal, so be sure to give the interface prefixed with a "0x" if so appropriate. <bcastbcast> is an optional parameter that overrides the normal use of 1's for broadcast bits in the host portion of an IP Address. If <bcast> is given, it can only be a value of 0 or 1. routeroute Route commands are used to initially seed the routing table with static routes, or to enable RIP, or a combination of both. When RIP is enabled, a broadcast query for RIP information is sent on all interfaces immediately upon startup. Normally the use of RIP is overkill (unless XGATE has more than one network interface), because all non-local packets will probably end up just needing to go to a default router (gateway), and using one simple static route to the default router will work just fine. If you enable RIP, and do not also specify a static route to the default gateway - XGATE may not be able to talk to all networks if the default gateway doesn't advertise itself through RIP as the default route for your network. The routing table can be examined from under the SMTP Monitor's "<D>river, <T>ables" command. The format of a route statement is: route <network>, <next_hop_gateway> [,metric] route RIP The first form adds a static route. The second form enables RIP, which is off by default. Up to 10 static routes can be given by using multiple route statements. A <networknetwork> given as all zeros is the equivalent of a default route (i.e. everything not destined for the local network qualifies, and those packets are then send to the <next_hop_gatewaynext_hop_gateway>). 57 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- When more than one IP address is bound, XGATE will automatically make the correct association of which interface they route through. If the <metricmetric> isn't specified, it is assumed to be 1. The metric is used as a means to prioritize routes when more than one qualifies. A default route is always assigned an internal metric of 17 (which is higher than the normal metrics of 1..15) because default routes are only supposed to be used if no other route qualifies. Both the <network> and <next_hop_gateway> parameters are expressed as fully qualified IP addresses in dotted notation. Normally, all that is needed is a single route command that specifies a default route to the default gateway. For example: route 0.0.0.0, 130.23.4.1 ipforwardipforward The Mach 2 TCP/IP protocol stack built into XGATE has the ability to forward (route) packets between multiple interfaces. If you have more than one interface card installed and want XGATE to route packets between them, this option can be enabled with the ipforward statement. 58 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- INDEXINDEX Addressing 6, 33 Command Line 17 Default SMTP Host 8, 44 Telnet/25 22 From MHS to SMTP 7 Troubleshooting 32 From SMTP to MHS 6 Using XGATE 19 Native SMF-71 12, 44 Gateway Activity 20 Static Reply Address 8, Name Server 23 43 SMTP Monitor 20 Attachments Uuencoding 9 Appending ASCII 10 XGATE.CFG 28, 37 Large SMTP Body 10 Alphabetical Index 37 Command Line Switches 17 append_ascii_attach 10, Configuration 28 41 DNS 33 bind 56 HOSTS 23 black_and_white 50 Name Serving 23 connect_timeout 53 NET.CFG 30 conv_body_to_attach 10, XGATE.CFG 37 42 Delivery Modes 14 conv_time_to_local 45 DNS 33 decode_header 49 Extended Address 7 domain_timeout 55 Gateway Activity 20 error_log 51 HOSTS 23 ignore_lwsp_after_fold HUBLIC.DAT 30 42 Installation 26 inbound_log 50 Limitations 2 include_header 40 Login Name 17 include_smtp_fields 40 Mach 2 TCP/IP Protocol ipforward 58 Stack 3 max_xmit_processes 52 Memory 1 mhs_admin_errors 40 MHS Gateway Module 3 mhs_administrator 39 MX Records 34 mhs_default_host 39 Name Serving 23, 33 mhs_gateway_name 6, 39 Native SMF-71 12, 44 mhs_path 39 NET.CFG 30 mhs_scrollback_lines 51 NSLookup 21 mute 50 Ping 21, 55 name_mapping_mode 7, 47 Postmaster 12 name_server 54 Registering XGATE 30 native_smf71 13, 44 Return Receipts 10 outbound_log 50 Route 22 ping 55 Scroll Back 19 Reference 39 Serializing XGATE 30 relay_host 53 Setup 29 relay_mode 52 SMTP Monitor 20 reschedule_minutes 53 SMTP Queues 4 resolve_minutes 54 SMTP Server Module 3 route 57 Static Reply Address 8, 43 scan_frequency 50 Switches scrap_mhs_attach 49 59 XGATE - MHS to SMTP Gateway ----------------------------------------------------------------- screen_save 50 smtp_default_host 44 smtp_exclude_mhs_hub 45 smtp_gateway_name 6, 44 smtp_include_mhs_app 46 smtp_receipts 10, 47 smtp_scrollback_lines 51 smtp_timezone 44 smtp_user_suffix 48 static_reply_address 8, 43 undeliverable_hours 53 use_mhs_ret_rcpt 47 use_mhs_ret_rcpts 11 use_mhs_total_fields 41 use_smtp_repto_as_from 41 uuencode 9, 48 watch_dog 51 60