"Installing and Administering an IPX Gateway for MacIPX-Based Applications" Copyright (c) 1993 by Novell, Inc. All rights reserved worldwide. WELCOME Welcome to the IPX(tm) gateway software, which Novell(R) provides to support networked applications that use the MacIPX(tm) transports. This README file includes information about the IPX gateway software. The IPX gateway is LAN driver software, and the IPX gateway can be used on computers running the Novell NetWare(R) operating system, version 3.11 or later, or the NetWare Multiprotocol Router(tm) software (MPR), version 2.0 or later. You may want to print this file for future reference. You need the IPX gateway software *only* under specific circumstances: you are using a MacIPX-based application on network segments that use only the AppleTalk(R) transport protocol to connect Macintosh(R) workstations to the network. Such "AppleTalk-only" segments result from technological or administrative conditions; the segment may use LocalTalk or another cable served by a third-party AppleTalk router, or a network administrator may want to designate a segment for AppleTalk traffic only. If you use Ethernet or Token Ring segments to connect your Macintosh workstations to an IPX network and if you permit IPX traffic on those segments, then you do *not* need this README file or the IPX gateway software. INTRODUCTION Because Macintosh users in your organization use networked applications that rely on MacIPX transports, you may possibly need to use this IPX gateway software to support your Macintosh users. This README file explains these topics: (1) MacIPX driver software and the IPX gateway software (2) How to install the IPX gateway on a NetWare server or NetWare MPR (3) How to load (run) the IPX gateway on a NetWare server or NetWare MPR (4) How to bind the IPX gateway to a specific interface (5) How to configure the IPX gateway to serve specific networks (6) How to advertise the IPX gateway service on the network (7) How to access and use IPX gateway statistics (8) How to interpret IPX gateway error messages (9) Some fine points about administering an IPX gateway Of these nine topics, the most fundamental are the second, third, fourth, and fifth. The initial topic provides background information, and the remaining topics enable you to make more sophisticated use of the IPX gateway software. MacIPX AND THE IPX GATEWAY ******************************************************************* * PLEASE NOTE: MacIPX software provides support for IPX transport * * protocols. It does not enable Macintosh users connected to the * * IPX network to log in to a NetWare server or to print documents * * on NetWare printers. Users and developers must rely on other * * software to support NetWare file and print services. * ******************************************************************* The MacIPX driver software from Novell enables a Macintosh workstation to use the IPX transport protocols to send and receive data on any network cable. Because IPX is the native transport protocol for NetWare LANs, MacIPX enables a Macintosh workstation to partake of a NetWare LAN's many resources. Figure 1 below illustrates what MacIPX does. Figure 1: MacIPX applications send IPX data from Macintosh workstations onto an IPX network. ----------- --------- ----------- / Macintosh \ IPX Data / NetWare \ IPX Data / Macintosh \ |system with| <--------------> | server | <--------------> |system with| \ MacIPX / on cable \ or MPR / on cable \ MacIPX / ----------- (Enet/TRing) --------- (Enet/TRing) ----------- (No AppleTalk Protocol on either segment) If *all* the Macintosh workstations running MacIPX-based applications are connected to an Ethernet or Token Ring cable, then you have no need for the IPX gateway. You need the IPX gateway software *only* if some or all Macintosh workstations are connected to an IPX network by means of an AppleTalk-only cable, such as a LocalTalk cable or other cable served by a third-party AppleTalk routing device, as shown in Figure 2. Figure 2: IPX gateway accepts IPX data (with AppleTalk encapsulation) from Macintosh workstations on an AppleTalk-only network cable and decapsulates the IPX data for routing in an IPX network. ----------- Encapsulated ---------------- ----------- / Macintosh \ IPX Data / NetWare server \ IPX Data / Macintosh \ |system with| <--------------> | or MPR with | <----------> |system with| \ MacIPX / on cable | IPX gateway | on cable \ MacIPX / ----------- (AppleTalk-only) \ software / (Enet/TRing) ----------- ---------------- (No AppleTalk on this segment) In this case, each Macintosh user connected to an AppleTalk-only cable must configure the MacIPX Control Panel to use the AppleTalk interface. Accordingly, you must install the IPX gateway on the NetWare server or NetWare Multiprotocol Router, as indicated in Figure 2. Once you have installed the IPX gateway, the MacIPX driver can discover the IPX gateway on the network, or the Macintosh user can specify the IPX gateway explicitly as part of his or her MacIPX configuration. When the IPX gateway is installed on a NetWare server or NetWare Multiprotocol Router, the IPX data destined for and transmitted by a Macintosh system connected to an AppleTalk-only cable has the proper AppleTalk encapsulation; the MacIPX driver software at the Macintosh supplies this encapsulation. When the IPX data is destined for or transmitted by a Macintosh system connected to Ethernet or Token Ring, the MacIPX driver adds no AppleTalk encapsulation. The AppleTalk encapsulation and decapsulation occurs automatically when the IPX gateway and the Macintosh workstations on an AppleTalk-only network cable are properly configured. The process is not complex and assures smooth operations for your network. NOTE: In situations where the IPX gateway software is required, you also need the APPLETLK.NLM software running on the NetWare server or NetWare Multiprotocol Router. The APPLETLK.NLM module is provided in the following ways: 1. With NetWare 4.0 network operating system 2. With NetWare 3.11 UpDate software and later versions of NetWare 3.x 3. With NetWare for Macintosh software 4. With NetWare Multiprotocol Router 2.0 or later 5. Via downloading from various online services, including Novell's NetWire(sm) forum on CompuServe(R) The APPLETLK.NLM module must be installed and configured according to instructions that accompany any of the Novell products in which it is included. INSTALLING THE IPX GATEWAY To install the IPX gateway on the NetWare server or NetWare Multiprotocol Router, copy the file MACIPXGW.LAN from the distribution diskette to the SYS:SYSTEM directory of the system. For example, if you have mapped the SYS volume of your server or router to drive F of a DR-DOS or MS_DOS PC, place the distribution diskette into drive A of the PC, and execute this command: COPY A:MACIPXGW.LAN F:\SYSTEM Make sure that the SYSTEM directory is in the server's or router's search path. In addition, the MACIPXGW.MSG and MACIPXGW.MDB files provided with the IPX gateway must be copied over to the SYS:SYSTEM directory on NetWare 4.0 servers. These files are *not* required for NetWare 3.x. LOADING THE IPX GATEWAY MODULE After installing the IPX gateway LAN driver, execute the following LOAD command at the server or router prompt to launch the IPX gateway software: LOAD MACIPXGW To specify a distinctive name for the IPX gateway when you load it, you can execute a command like this: LOAD MACIPXGW GATEWAY_NAME="AppleTalk-IPX Gateway" Macintosh users will see this name when they configure MacIPX at their workstations. You can also include this command in the NetWare server's or NetWare Multiprotocol Router's AUTOEXEC.NCF file. General information about the LOAD command can be found in the "Utilities Reference" manual for the NetWare operating system or the NetWare Multiprotocol Router. See "Options When Loading the IPX Gateway," later in this file, for additional functions you can perform when loading the IPX gateway software. BINDING THE IPX GATEWAY TO THE IPX NETWORK After loading the gateway, you should bind the IPX gateway to the IPX network, using this command: BIND IPX TO MACIPXGW NET= The in this command must be a unique network number; think of this as the "MacIPX network number." This command effectively binds IPX to the gateway itself. The command can be executed at the server or router prompt or can be included in the server's or router's AUTOEXEC.NCF file, after the LOAD MACIPXGW command. To disconnect the IPX gateway from the IPX network, you can issue this command: UNBIND IPX FROM MACIPXGW If the IPX gateway is not connected to the IPX network with a bind command as described above, the IPX gateway will not appear in the IPX Gateway list in the MacIPX Control Panel, and Macintosh users will not be able to select it as part of configuring MacIPX at their workstations. General information about the BIND and UNBIND commands can be found in the NetWare operating system "Utilities Reference" manual. -- Options When Loading the IPX Gateway -- The LOAD MACIPXGW command has three optional parameters, specified in this syntax diagram: LOAD MACIPX [GATEWAY_NAME=""] [SHOW=yes] [UNICAST_THRESHOLD=] Use any of these optional parameters -- none is required, nor does any one require another -- to achieve the effects described below. The GATEWAY_NAME parameter specifies the name for the IPX gateway, as illustrated above. You may choose any name you like; choose a name that users will recognize easily, and don't forget to enclose the in double quotation marks. This is the NBP (Name Binding Protocol) object name used for advertising the IPX gateway's name on the AppleTalk network. This name appears in the dialog in which the Macintosh user selects an IPX gateway. If the LOAD MACIPXGW command lacks this parameter, the gateway name is set by default to the name of the server or router where the gateway is installed. The SHOW parameter displays information about the configuration and operation of the IPX gateway *after* MACIPXGW.LAN is already loaded, not *while* it is being loaded. See "Viewing Information about the IPX Gateway," further below in this file, for more information about this parameter. For example, to view information about an IPX gateway already loaded at the server or router, you can issue this command at the NetWare prompt: LOAD MACIPXGW SHOW=YES This command does not attempt to reload the IPX gateway but instead displays information about the IPX gateway and the AppleTalk networks that it serves, as in this example: MACIPXGW: Unicast threshold set at 1. AppleTalk nets this gateway is configured to serve: 10-10 100 1500-1502 2001-2005 AppleTalk nodes registered for IPX broadcasts: IPX node: 0xffffffffffff Socket: 0x452 10.128 1501.138 1502.168 Socket: 0x453 10.128 This information includes these items: * The value for the unicast threshold, described in the next section * The network numbers of all AppleTalk networks served by this gateway * All AppleTalk nodes (network.node) currently registered with the IPX gateway for broadcasts, identified by IPX socket The UNICAST_THRESHOLD parameter determines how to deliver IPX broadcast messages to MacIPX clients that use the IPX gateway. Depending on the argument, the IPX gateway delivers packets to MacIPX clients either by sending broadcasts to the AppleTalk networks to which the clients are connected or by sending directed packets to the MacIPX clients themselves. How you configure the IPX gateway determines how IPX broadcast messages are delivered to MacIPX clients that use the IPX gateway. IPX broadcast messages can be delivered either as single broadcasts on the AppleTalk networks or as individual packets directed to explicitly registered MacIPX clients. As mentioned in the previous section, the UNICAST_THRESHOLD parameter takes a numeric argument. This number, specified with the LOAD MACIPXGW command, represents a maximum number of MacIPX clients registered on an AppleTalk network at an IPX socket to which directed packets should be delivered. If an AppleTalk network includes more MacIPX clients than the number given with the UNICAST_THRESHOLD parameter, then the IPX gateway delivers an IPX broadcast encapsulated within an AppleTalk broadcast packet to all the AppleTalk networks that constitute the IPX network. Thus the packet is received by all Macintosh systems on those AppleTalk networks, including those running MacIPX. Macintosh systems not running MacIPX will not understand those broadcast packets and should drop them. This parameter is designed to control broadcast network traffic. For more information, see "Tips about Performance and Network Traffic," further below in this file. The default value for the UNICAST_THRESHOLD parameter is 1. You can specify from 1 to 4294967295 (unsigned four-byte integer) as the value for this parameter. -- Configuring the IPX Gateway to Serve Specific AppleTalk Networks -- You can configure the IPX gateway to serve a selection of available AppleTalk networks or all AppleTalk networks. By default, all AppleTalk networks are served, and you need not take any special action. To restrict the IPX gateway's service to specific AppleTalk networks, you must create a configuration file called MACIPXGW.DAT in the SYS:SYSTEM directory on the server or router. This file contains lines using this syntax: [EXCLUDE|INCLUDE] [-] {[-]} The first line can provide an optional keyword that specifies the mode of inclusion; EXCLUDE directs the gateway to serve *all* AppleTalk networks *except* for those specific networks whose numbers are listed below, and INCLUDE instructs the gateway to serve *only* those specific network numbers listed below. If no keyword appears, INCLUDE is the default mode. The file *must* include one network number or range and, as indicated by the curly braces in the syntax example, may optionally include more network numbers or ranges, with each network specified on its own line. For example, consider a MACIPXGW.DAT file containing this command: EXCLUDE 10-10 100 This instructs the gateway to serve *all* AppleTalk networks *except for* 10- 10 and 100. Alternatively, consider this MACIPXGW.DAT file: INCLUDE 10-10 100 This instructs the gateway to serve *only* AppleTalk networks 10-10 and 100, excluding all others. If no MACIPXGW.DAT file is found in SYS:SYSTEM, then the IPX gateway serves all AppleTalk networks. NOTE: The network numbers in these examples are AppleTalk network numbers, not IPX network numbers. This reflects the situation, referred to above, in which the APPLETLK.NLM software has already been installed and configured and already serves an AppleTalk-only segment of the network. -- Advertising the IPX Gateway Service on the Network -- After it is loaded, the IPX gateway advertises itself on the AppleTalk network by registering with AppleTalk's Name Binding Protocol (NBP). Following this registration with NBP, the IPX gateway displays a notice like this one at the server or router console, including the NBP name and AppleTalk address of the advertised service: MACIPXGW: Gateway registered with NBP as TITAN:IPX Gateway@TwilightZone at address 1428.28.28 If you unload MACIPXGW.LAN, the IPX gateway ceases to advertise itself because it is no longer registered with NBP, and after this occurs, the gateway displays a message like this one: MACIPXGW: Gateway TITAN:IPX Gateway@TwilightZone de-registered from NBP. IPX GATEWAY STATISTICS You can use the MONITOR NLM to review certain statistics about the IPX gateway. Here is a typical procedure: 1) Start the MONITOR NLM at the server or router: LOAD MONITOR 2) From the main menu, select the LAN Information option, and then the MACIPXGW option. The resulting display includes a General Statistics section that enumerates IPX packets that the IPX protocol stack has sent to and received from the IPX gateway. 3) Scroll down to see the Custom Statistics section to see information on gateway operation, which includes these categories: 1. Received Tickle Packets 2. IPX Broadcast Requests From IPX Stack 3. DDP Packets Broadcasted For IPX Broadcasts 4. DDP Packets Unicasted For IPX Broadcasts 5. IPX Broadcast Requests From MacIPX Clients 6. Received DDP Packets With Unknown Options 7. Received DDP Packets With Wrong Type 8. Received Service Requests 9. Transmitted Service Grants 10. Transmitted Service Refusals 11. Memory Allocation Failure Items 6 and 7 are of particular interest to the IPX gateway. Item 6 enumerates packets received from the AppleTalk network that are addressed to the encapsulation socket and include unrecognized de-multiplexing options. Item 7 enumerates packets received from the AppleTalk network that are addressed to the encapsulation socket for which the packet type was not the encapsulation type. IPX GATEWAY MESSAGES The IPX gateway generates these messages at the server or router console in the course of its operations: 1. MACIPXGW: Gateway registered with NBP as NBP entity at address ... This message appears when the gateway has successfully registered with NBP. 2. MACIPXGW: Gateway de-registered from NBP. This message appears when the gateway has successfully de-registered itself from NBP; this occurs after you unload the gateway. 3. MACIPXGW: Unloading MACIPXGW.LAN because of initialization failure. Check to see whether the resource utilization of the server or router is at reasonable level. Check if APPLETLK.NLM already loaded, and then try reloading again. 4. MACIPXGW: Unknown option in received encapsulated packet. The gateway received an AppleTalk packet addressed to the encapsulation socket, but an unknown option was found in the packet. This is probably caused by a misbehaving client. Take a packet trace and try to locate the packet originator. 5. MACIPXGW: Failed to open socket. Failed to open a DDP socket. Check for AppleTalk socket availability. 6. MACIPXGW: Failed to find zone for gateway. The gateway is unable to find the AppleTalk zone in which the IPX gateway should be registered. Determine whether APPLETLK.NLM was loaded successfully. Make sure that the zone lists for AppleTalk's interfaces were initialized successfully. 7. MACIPXGW: Bad NBP entity. A bad NBP entity was formed for the IPX gateway when it tried to register with NBP. Determine whether the zone list for AppleTalk's interfaces were initialized successfully. Also, determine whether the SYS volume is mounted because the IPX gateway can fail to get the local server or router name required to build its NBP name if the SYS volume is not mounted. 8. MACIPXGW: NBP registration failed. The gateway failed to register with NBP as :IPX_Gateway@. Determine whether a duplicate entity already exists on the network. 9. MACIPXGW: Unable to open . The configuration file MACIPXGW.DAT exists in the SYS:SYSTEM directory, but the IPX gateway is unable to open the file. Determine whether the SYS volume is mounted. Check file access. 10. MACIPXGW: Insufficient memory to read . There is not enough memory to read the MACIPXGW.DAT configuration file. Unload unnecessary modules to free up memory and try reloading again. 11. MACIPXGW: Unable to allocate ECB. This condition usually develops because some module is tying up system resources. Check for such modules using the MONITOR module. If such a condition prevails, unload unnecessary system modules to free up resources. 12. MACIPXGW: Failed to send AppleTalk packet, error []. The gateway may have lost its connection with AppleTalk. If the problem persists, unload the gateway and, if necessary, APPLETLK.NLM, and reload them again. 13. MACIPXGW: Error [] starting timer. There is not enough memory to start the timer. Unload the gateway, try to free up more memory by unloading unnecessary NLMs, and reload the gateway again. 14. MACIPXGW: Failed to register gateway with NBP. There may already be another NVE (network-visible entity) with the same name on the network, or the gateway may have lost its connection to AppleTalk. Check for a duplicate NVE on the network, and if there is a duplicated name, change the gateway name by using the NAME parameter on the LOAD line. Then reload. If there is no duplicated name, try unloading the gateway and, if necessary, APPLETLK.NLM, and then reload again. 15. MACIPXGW: Bad entry in . A bad entry is found in the configuration file MACIPXGW.DAT. Validate the file's contents. 16. MACIPXGW: Failed to receive AppleTalk packet, error []. The gateway is unable to get AppleTalk packets from the AppleTalk stack because either the gateway has lost its connection to AppleTalk or there are not enough system resources available. If the problem persists, unload the gateway and, if necessary, APPLETLK.NLM, and reload again. 17. MACIPXGW: IPX packet too big. IPX packet size exceeds maximum specified in the protocol for encapsulating IPX in AppleTalk. 18. MACIPXGW: Failed to get AppleTalk information. Determine whether APPLETLK.NLM is loaded successfully and whether its interfaces are initialized successfully. 19. Fatal Error: Could not allocate a memory resource tag. There are not enough system resources. Unload unnecessary NLMs and reload the gateway again. 20. Fatal Error: Could not allocate an ECB resource tag. See message number 11, further above. 21. Failed to initialize CLIB. There are not enough system resources. Unload unnecessary NLMs and reload the gateway again. 22. MACIPXGW: Gateway name truncated to 32 characters. The gateway name that was specified with the GATEWAY_NAME parameter on the LOAD MACIPXGW command line exceeded the 32-character limit. 23. MACIPXGW: Gateway name must be delimited by double quotes. The name for the gateway, specified with the GATEWAY_NAME parameter on the LOAD MACIPXGW command line, lacks the necessary double quotes. Either reissue a corrected command, or modify the AUTOEXEC.NCF file, or both. 24. MACIPXGW: Incomplete command line parameter. The LOAD MACIPXGW command contains an complete parameter. Either reissue a corrected command, or modify the AUTOEXEC.NCF file, or both. 25. MACIPXGW: Bad command line parameter. The LOAD MACIPXGW command contains an invalid parameter. Either reissue a corrected command, or modify the AUTOEXEC.NCF file, or both. 26. MACIPXGW: Fatal error []! MACIPXGW.LAN is no longer functional. Please unload the module. The gateway has encountered a problem from which it cannot recover. It has automatically unbound itself from the IPX network and closed the DDP socket it was using, so that it will no longer process any incoming or outgoing packets. Unload the gateway and reload it to use it again. TIPS ON ADMINISTERING AN IPX GATEWAY All IPX gateways, including those produced by Novell and those produced by other vendors, must conform to some administrative guidelines. Here are some tips and general information to make the job easier. -- Tips about Routing -- Keep these points in mind with regard to administering the routing of packets with an IPX gateway: * Each IPX gateway is also an IPX router and must be administered in the same way as any other IPX router. * Each IPX gateway always advertises itself via AppleTalk NBP, regardless of whether it can actually process IPX packets. This allows the IPX gateway to be located with AppleTalk network management tools. The IPX gateway is registered with an NBP Type of "IPX Gateway." NOTE: MacIPX clients will only find those gateways which *can* process IPX packets. This discovery is performed using a combination of AppleTalk DDP and NBP to produce a list of gateways that can service the MacIPX application. * You *cannot* use MacIPX for the purpose of bridging IPX networks across an AppleTalk internetwork. This means that you cannot use IPX gateways and their encapsulation capabilities to connect two or more IPX networks across an AppleTalk cloud. This is because MacIPX, its drivers, and associated utilities are not designed as extensions to AppleTalk networking. MacIPX is designed to enable Macintosh workstations to participate directly in IPX networks and to encourage multi-platform peer-to-peer connectivity. -- Tips about Addressing -- Keep these points in mind with regard to network numbers and addresses for nodes and clients: * Each IPX gateway must have a unique IPX network number in the same way that all other network interfaces in the server must have a unique network number. Any MacIPX clients using the gateway will be on that new IPX network. Some gateway implementations, including the IPX gateway provided with MacIPX from Novell, may enable you to restrict the set of AppleTalk networks that the IPX gateway can serve. (Refer to "Configuring the IPX Gateway to Serve Specific AppleTalk Networks," earlier in this file.) Thus, the IPX network that a MacIPX client is on will change when that client changes IPX gateways. * Here is how the IPX address of a MacIPX client using an IPX gateway is determined: -- The network number is the one that has been assigned to the gateway itself through the BIND command, and -- The node ID consists of three bytes of leading zeros followed by the client's two-byte AppleTalk network number (that is, the AppleTalk network that the client is on) and the client's one-byte AppleTalk node ID. For example, if the MacIPX client on AppleTalk network 0x1234 with node ID 0xAA is using a gateway whose IPX network is 0xFEEDFACE, then the IPX address of the client (hex) is FEEDFACE:0000001234AA. * The DDP socket 0x4E is used on the MacIPX client to communicate with the IPX gateway. -- Tips about Performance and Network Traffic -- Keep this point in mind with regard to broadcast data packets and network traffic: * A "broadcast" IPX packet may be forwarded as a *broadcast* data link packet onto all the AppleTalk networks that an IPX gateway serves. In this case, all nodes on an AppleTalk network that has at least one MacIPX client on it will receive the IPX packet. Alternatively, the "broadcast" IPX packet may be forwarded as a *unicast* data link packet to each MacIPX client using the IPX gateway. This feature enables you to decide whether some clients may receive "unnecessary" packets (that is, "broadcast" IPX packets may be sent to AppleTalk end nodes that are not MacIPX clients) or whether network traffic may be increased because of the greater number of packets being sent. This is because a single "broadcast" IPX packet could become a large number of unicast packets, thereby increasing the network load. We do not currently recommend one strategy over the other, but we do recommend that you refer to "Delivering IPX Broadcast Messages on AppleTalk Networks," further above in this file, for operational details on how to implement the preferred strategy. NOTE: Some gateway implementations may provide this feature; that is, the gateway may always send broadcast packets or it may always send unicast packets, or some combination thereof. KNOWN ANOMALIES IN THE IPX GATEWAY (VERSION 1.01) PROBLEM: The IPX gateway (MACIPXGW.LAN) may fail to load on a NetWare 4.0 server whose APPLETLK.NLM is configured in the following manner: Routing is enabled, the internal net is removed, and seed net and zone information are derived from the network. SOLUTION: You can work around this problem by changing the configuration of the APPLETLK.NLM (for example, you could explicitly specify the net and zone information for the interface that the AppleTalk stack is homed on). For more information about APPLETLK.NLM configuration, please refer to the NetWare for Macintosh Installation and Maintenance manual for NetWare for Macintosh 4.0 (Novell Part # 100-001795-001). TRADEMARKS Novell and NetWare are registered trademarks, NetWire is a service mark, and MacIPX, IPX, and NetWare Multiprotocol Router are trademarks, of Novell, Inc. Macintosh and AppleTalk are registered trademarks of Apple Computer, Inc. CompuServe is a registered trademark of CompuServe Incorporated.