TIPS FOR TCP/IP =============== by Robert Brewer and Rory Murtagh The 3-Script(TM) File Format ============================ Mathematica is a registered trademark, and 3-Script is a trademark of Wolfram Research, Inc. Mathematica is not associated with Mathematica, Inc., Mathematica Policy Research, Inc., or MathTech, Inc. Copyright 1988-1991 by Wolfram Research, Inc. All rights reserved. No part of this document may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording or otherwise, without the prior written permission of the copyright holder. Wolfram Research is the holder of the copyright to the Mathematica software system described in this document, including without limitation such aspects of the system as its code, structure, sequence, organization, ``look and feel'', programming language and compilation of command names. Use of the system unless pursuant to the terms of a license granted by Wolfram Research or as otherwise authorized by law is an infringement of the copyright. Wolfram Research Inc., makes no representations, express or implied, with respect to this documentation or the software it describes, including without limitations, any implied warranties of merchantability or fitness for a particular purpose, all of which are expressly disclaimed. Users should be aware that included in the terms and conditions under which Wolfram Research is willing to license Mathematica is a provision that Wolfram Research and its distribution licensees, distributors and dealers shall in no event be liable for any indirect, incidental or consequential damages, and that liability for direct damages shall be limited to the amount of the purchase price paid for Mathematica. In addition to the foregoing, users should recognize that all complex software systems and their documentation contain errors and omissions. Wolfram Research shall not be responsible under any circumstances for providing information on or corrections to errors and omissions discovered at any time in this document or the software it describes, whether or not they are aware of the errors or omissions. Wolfram Research does not recommend the use of the software described in this document for applications in which errors or omissions could threaten life, injury or significant loss. Introduction ============ Mathematica uses the MacTCP driver to allow you to connect to remote kernels. Since this feature allows you to configure your connection in a variety of ways, you may encounter some problems when trying to get Mathematica to work across your network for the first time. This document tries to make this process as easy as possible for you. It will assist you in setting up MacTCP on a Macintosh equipped with an Ethernet device or a Macintosh connected via LocalTalk to a DDP/IP gateway (such as a Shiva FastPath or Cayman GatorBox). It is assumed that you have some familiarity with networks and network protocols. If you are not familiar with networks in general, try reading the MacTCP Administrator's Guide. If your Macintosh is connected to multiple Unix networks, routers, or subnets, you'll probably need to study the Administrator's Guide in detail. If you are not the person primarily responsible for maintaining the network you want to connect to, be sure to talk to that person before installing MacTCP. Note: This document assumes that you are using MacTCP 1.1, which is currently distributed with Mathematica. If you cannot use this version, and are using an older version (1.0.x), then portions of this document do not apply to you. We strongly recommend you use MacTCP 1.1 if at all possible. If you are using a later version of MacTCP, then this document will probably apply, but you are basically on your own. Materials ========= To run a remote kernel, you will need to have a copy of Mathematica Version 1.2 or later running on a computer somewhere on your network. The front end talks to the remote kernel via a Telnet session, so the remote host must also provide that service (all Unix hosts will). Note that it is currently not possible for a Macintosh front end to connect to a remote kernel on another Macintosh. For the purposes of this document, it is assumed that you have Mathematica Version 1.2.1 or later properly installed on that remote computer. You will also need a way to connect your Macintosh to the network. There are two ways to connect your Macintosh--- via LocalTalk or by direct connection to the Ethernet. If you connect via LocalTalk, your Macintosh must be connected to a LocalTalk network that has a DDP/IP gateway to the network to which your remote host is connected. Alternatively, if you connect directly to the Ethernet, you will need a Macintosh with an Ethernet device connected directly (or via an Ethernet gateway) to the network on which your remote host is located. In addition, you will need a copy of the Macintosh front end version 2.0 or later, and MacTCP software. You can install MacTCP software from the Utilities disk that came with your copy of the front end (see the ``Installation'' section of your Mathematica User's Guide). Installation ============ If you are using an Ethernet device, first make sure that it is properly installed with the driver software that came with it. Its accompanying documentation will help you complete and check this installation. Once installed, select the Control Panel desk accessory from the Apple menu (if you are using System 6.0.7) or select the Control Panels folder from the Apple menu (if you are using System 7 or later). Find the Network control panel device, and make sure that the EtherTalk icon is selected. For both Ethernet and LocalTalk connections, it would be a good idea to make certain that the physical connection is working at this stage. By opening the Chooser from the Apple menu, you should be able to see your LocalTalk zone names. There should be a list titled ``AppleTalk Zones'' in the lower-left corner of the window. If there is no list of AppleTalk zones, there is most likely a problem with your wiring or gateway. Before proceeding, you must copy the file labeled ``MacTCP'' into the System Folder on your boot disk. (The file ``MacTCP'' is in the ``Networking Drivers.sit'' archive on the Utilities disk that came with your copy of the Mathematica front end.) To make sure that MacTCP goes in the right place, drag the MacTCP icon onto your System Folder. If you are using System 7, then you should see a dialog box telling you that the Finder will put the Control Panel in the Control Panels folder. If you are using System 6.0.7, then you will not see such a message. Now reboot your Macintosh. Configuration ============= A. Link Level (refer to chapter 6 of the MacTCP Administrator's Guide for more information) If you are using System 6.0.7, open the Control Panel desk accessory by selecting it from the Apple menu. If you are using System 7 or later, select the Control Panels folder from the Apple menu. Select or double-click the MacTCP icon. You can now see controls for the link-level configuration. Clicking the More button displays the Administrator dialog box for IP address and name server selection. If you have trouble changing things in the Administrator dialog box, your copy of MacTCP may be locked. There is a separate Control Panel device, called AdminTCP, which allows a network administrator to lock certain parts of MacTCP. If your copy of MacTCP is locked, you should consult your network administrator. If you wish to preconfigure MacTCP for other people in your company with AdminTCP, refer to chapter 6 of the MacTCP Administrator's Guide, ``Protecting the Configuration''. If you are using LocalTalk to connect to the remote host, select the LocalTalk icon, and select the zone where your DDP/IP gateway resides (if you don't know which zone this is, talk to your network administrator, or select the zone your Macintosh is in as a first guess) from the pop-up menu below the LocalTalk icon. If you are using an Ethernet device, make sure that the Ethernet icon is selected. (In most cases you would not want to select the EtherTalk icon.) IP Addresses ============ As detailed in the MacTCP Administrator's Guide, there are three methods of IP address assignment: static, server, and dynamic. Either the user sets the address manually, a server machine ( e.g., the Shiva FastPath) sets the address, or the user's Macintosh finds an address, respectively. 1. IP Addresses Assigned Manually (Static) ========================================== If you have a small network or are not using a gateway or process that acts as an IP address server, manually selected (or static) IP addresses may be the easiest or only choice. First you'll need to know what class of IP addressing you are using on your network. For more information on IP address classes, refer to chapter 3 of the MacTCP Administrator's Guide. If the remote host runs Unix, you might be able to find the IP address class by typing netstat -i on the console. This will show you the name of the device the Unix machine uses to communicate on the Ethernet. Second you'll want to see how that device is configured. On Unix, use ifconfig ie0 (where ie0 is the device name shown by netstat -i). This should say something like 128.1.10.1 netmask 255.255.0.0 flags=6.... Your Macintosh should be assigned an address of a similar form ( e.g., 128.1.10.100) and if the netmask was set, you should set it also on the Macintosh side. The IP address must be unique within your network. On a Unix network, typically on the Yellow Pages server, there is a file called /etc/hosts, where these IP addresses are assigned and saved. A conflicting (duplicate) address will cause the Unix user to get error messages flashing by on the screen. Type your IP address into the IP Address box at the bottom of the MacTCP control panel window. If you are using subnetting on your network, you need to click the More button and change the subnet configuration. Now quit MacTCP and reboot for the changes to take effect. 2. IP Addresses Assigned by Server ================================== For large networks, giving each Macintosh its own IP address can be an administrator's nightmare. In this situation, you will probably want to use server-assigned IP addressing. Note: An IP address server is not the same as a Name Server; the bottom right quarter of the second MacTCP dialog box (Name Server section) is decoupled from the rest. An IP address server associates an IP address ( e.g., 140.177.10.12) with an Ethernet address ( 8:0:89:a0:96:12), whereas a (Domain) Name Server associates a machine name ( e.g., dragonfly.wri.com) with an IP address ( e.g., 140.177.10.12). The name dragonfly.wri.com is just an alias for the address 140.177.10.12 and is useful but not necessary. The server-based addressing works quite differently depending on whether you are connecting via LocalTalk or Ethernet. If you are connecting by LocalTalk, the server is your DDP/IP gateway. These gateways are set up to respond to requests on the AppleTalk (DDP) side of the network. Your Macintosh will request an IP address, and the gateway will determine if any are available and then give your Macintosh an IP address. The network administrator will have to configure the DDP/IP gateway so that it knows what range of IP addresses to dole out to the Macintoshes. To do this, they will have to refer to the gateway's documentation. If you are connecting by Ethernet, the process is a little more difficult. You will need to have a Unix guru set up a process on a Unix computer that will act as an IP address server. Such a server may already be set up if a number of Unix machines are being used. In this configuration, your Macintosh will broadcast a RARP (Reverse Address Resolution Protocol) request, which contains your Macintosh's physical Ethernet address. The RARP server will respond to the request by checking its database and assigning you an IP address. In this fashion, the list of all the IP addresses can be maintained on one machine (albeit a Unix machine). As an end user, simply click the More button in the MacTCP control panel and select the Server radio button at the upper left of the dialog box. No other configuration is necessary. Now you must close the MacTCP dialog box and reboot the machine so the changes you made to MacTCP will take effect. 3. IP Addresses Assigned Dynamically ==================================== It is recommended to avoid dynamic IP addressing, especially through DDP/IP gateways. Apple officially recommends that dynamic IP addressing not be attempted through a DDP/IP gateway. In almost every case, server addressing should be used instead of dynamic addressing. Stay away from dynamic IP addressing. If you understand and are capable of making it work reliably, then you understand far more about TCP/IP networking and MacTCP than this simple document can convey. Note: A possible source of confusion is that some manuals, ( e.g., those from Cayman and Shiva), use the word "dynamic" when actually referring to server-based addressing. If It Still Doesn't Work ======================== There are many different levels on which the remote kernel connection process can fail. The physical network or the associated gateways could be broken or not functioning. MacTCP could be installed or configured incorrectly on your Macintosh. The Communications Toolbox (not discussed in this document, but necessary for remote kernel connections) could be installed incorrectly. See the ``Installation'' section of your Mathematica User's Guide. Mathematica could be installed incorrectly on either your local Macintosh or the remote host. Or, even more unlikely, there could be a bug in Mathematica . If you are unable even to connect to a remote host, the range of possible culprits can be narrowed down. Confirm that your network is working by looking for AppleTalk zones in the Chooser. If you cannot see any zones, then your network is probably not working. Try using NCSA Telnet to connect to the remote host by using its IP address (NCSA Telnet uses MacTCP, but not the Communications Toolbox). If NCSA Telnet cannot connect to the remote host then either the host is down or, more likely, MacTCP is not configured correctly. Try using the ``Sample App'' application, which uses MacTCP and the Communications Toolbox. If you cannot connect to the remote host, something is wrong with the Communications Toolbox or your VersaTerm Telnet Tool. If all of the above steps succeed but you are unable to connect to a remote kernel, there is an insidious problem. One thing you can try is creating a trivial network consisting of your Macintosh and the remote host. Or you can call Wolfram Research technical support. If you are able to bring up a terminal window from within Mathematica but are unable to start a remote kernel, then the problem almost certainly lies in the installation of Mathematica on the remote host. Ask the system administrator of that computer to confirm that Mathematica is installed correctly, and that the mathremote command is executable by you. Name Calling ============ Finally: names. =============== As mentioned previously, a name, such as dragonfly.wri.com, or a remote machine name, such as fred, are human aliases for the machine's IP address. To get connected initially, it is best to isolate yourself from translation problems and stick to the IP address. Later you may want to use the friendlier name. MacTCP tries to translate this name first by reference to the ``Hosts'' file in your System Folder, if present. To make it work, follow the examples in the ``hosts'' file and then try appending a dot (.) to the ``Edit Connections'' name. You can further centralize the administration of the name table by setting up a name server on a remote host and referring MacTCP to that name server. This process is quite involved, and it is recommended that you refer to the MacTCP Administrator's Guide and the remote host's documentation to help you set this up. When you have things going on one Macintosh, you can use the AdminTCP utility to configure and lock a distribution configuration.