This manual attempts to "tell you everything you need to know" in order to run a PupGateway and an internet. Corrections, additions, comments, etc. are encouraged and should be sent to the current maintainer (see the front page).

This documentation is [Indigo]<PupGateway>Doc>PupGatewayManual.*, where * is a number of different extensions depending on what format you want the document in.

[Indigo]<PupGateway> holds all of the code and related files specific to PupGateway.

[Indigo]<Dicentra>Doc>DicentraManual.* is the Dicenta documentation.

[Indigo]<Dicentra> holds all of the code and related files specific to the Dicentra.

[Indigo]<Portola> holds Pup-Network.txt and all (some) of the parameter files from gateways around the internet.

[Dexter] is the "root" boot server at PARC and holds most if not all of the current boot files for everything from Altos to XDE.

No longer supported and STRONGLY discouraged.

DO NOT USE DayBreaks as PupGateways. Among other things both the Ethernet and phoneline interfaces are junk. The Ethernet interface can go totally dead for periods of time (seconds/minutes) and the phoneline simply can't handle anthing faster than 9.6 Kbps (and even that is tricky to get right).

DLions only have the hardware to connect to a single Ethernet and therefore can't be used to (directly) connect two or more Ethernets together. DLions do have a single RS-232 port that can be used to connect to a phone line of a speed up to 56KB (really only ~50KB). DLions also have disks and therefore make good bootservers and nameservers.

Dicentras don't have disks (or displays for that matter) and therefore need a boot server to get going. They also can't (directly) provide bootservice. The big advantage of Dicentras are that they can drive a number of interface boards: multiple Ethernets (both 3Mb and 10Mb), T1 lines, and phone lines (a standard Dicentra has 8 phone line ports).

Pup-Network.txt is at the heart of the PUP Name Lookup Service (NLS). Any machines on the internet that communicate using PUP protocols should be registered in Pup-Network.txt. See the Pup-Network.txt section in this document for more information.

DLion PupGateways keep a log of events as the gateway runs. The size and layout of this file is described in the FTP Server chapter. The important thing to mention here is that the Dicentra does not keep a log file per se, remember, it doesn't have a disk. But, the Dicentra does "log" to the Chat connection, if one is open. This information is the same as what would go into the log file, if it had one.

The section of this manual on the FTP server mentions a number of interesting files that live on a DLion PupGateway. It also explains a GV group that is used to control FTP access.

If you are running a Dicentra PupGateway then you should also read the Dicentra Manual. This manual has a lot of information particular to the Dicentra. You can get a copy from [Indigo]<Dicentra>Doc>DicentraManual.*, where * represents a number of different formats such as interpress, press, or tioga.

The machine should be configured with at least these three volumes: Othello, Copilot, and Tajo.

As mentioned earlier, Dicentras Don't have disks and depend on a boot server to get started. The Germ (which is in PROM) loads the desired program over then net. The boot file number and which device to boot from can be stored in the EEPROM. The default is to boot NS boot file number 25200002000 from the first 10MB ethernet board. By convention this is OscarDicentra, the gateway program. You can also use the Alt-Boot button to manually select an alternative boot file or device.

MP codes in the 92x range will be shown while booting. If you make it to 990 then you have successfully loaded the boot file.

The Dicentra also needs an NS time server to get started. You'll get an MP of 1937 if it can't find one.

Dicentras can be booted with a blank parameter file. Once booted, you can use (Pup) Chat to load a new or modified parameter file. A Dicentra booted with a blank parameter file will know of any phonelines connected. NB: If the existing parameter file stored in the Dicentra has some sort of bug in it it will send you to 915 every time.

The way to deal with a bad parameter file is to boot BootMeAgainDicentra (Alt-boot 241, read the section on Alt-booting). BootMeAgainDicentra will smash (wiped clean) the "broken" parameter file. Let BootMeAgainDicentra run a while, it takes about 15 minutes. Once the file is smashed boot OscarDicentra again and start over by fetching a working version of the parameter file.

Current versions of both OscarDicentra.boot and BootMeAgainDicentra.boot can be gotten from [Dexter].

Pup-Network.txt is the text file that is at the heart of the Pup Name database. Pup-Network.txt lives on [Indigo]<Portola> and is readable by virtually anyone. This text file provides the mapping between PUP names and addresses. There is an XDE tool called NetDirBuilder that is used to convert this text file into the two "machine format" files: Pup-Network.directory and Pup-Network.big. These two "machine format" files are the files that are actually passed around between the Pup Name servers.

NetDirBuilder is a tool that comes with the XDE (DLion) version of PupGateway that is used to generate new versions of the Pup name database based on Pup-Network.txt. It provides a means of coordinating updates to the Pup-Network database by using the Librarian (Marion, presently located in Sunnyvale) to limit edits of Pup-Network.txt to one person at a time. NetDirBuilder also parses the new file for validity, creates the new versions of Pup-Network.directory and Pup-Network.big, and then becomes a Pup Directory server in order to start propagating the new version of Pup-Network throughout the network.

Pup-Network.txt has a syntax definition and some general guidelines spelled out in the begining of the file. In addition to all of things mentioned there be aware that you should not use 0# or 377# for any network or host number. These are special values and will result in chaos if used for a particular net or machine.

To be able to run NetDirBuilder you must be a member of Updaters^.internet. Being a member of Updaters^.internet is what is referred to as "being an Updater".

Being an Updater is not something to be taken lightly. Pup-Network.txt is the "heart" of the PUP world (and to some degree other worlds such as NS and TCP too) and mistakes can cause disasters if not just confusion and a lot of hassles. Updaters are held responsible for any and all changes that they make. Also, Updaters must follow "NetDirBuilder Etiquette". Failure to act responsibly or to follow NetDirBuilder Etiquette will result in lose of privilege -- and the wrath of GatewaySupport^.pa.

When two machines are connected via a phone line, you can really think of them being connected via two separate paths, one from machine A to machine B, and the other machine B to machine A. Usually, when something affects one path it affects the other at the same time. Examples of this might be the RS232 plug not being plugged into a machine or modem, or a phone company cable being severed by a work crew somewhere. The result is that machine A and machine B can either communicate with each other when everything is fine, or they can't if something is "broken".

Occasionally one path will be affected independently of the other. If machine A can hear machine B but machine B can't hear machine A, we have what we call the "Half-up" problem. Half-up can be caused by bad circuits in one side of a modem, bad connections in an otherwise good cable, etc. Since machine A can hear machine B it will think that it can send packets to any networks that machine B has in its routing tables, and it will include routes to these nets in its own routing table. However, every time A actually sends a packet to B, B never hears it because that path is down. The bottom line is that routing tables (in this case the tables in A) can be deceiving in the Half-up situation. You should try and echo packets off of the gateway on the far end. If you don't get any response then this might be the cause of the problem.

If you forget the "password" value and/or incorrectly use the values "NIL" or "DLion" in the "SDLC" entry in a Dicentra parameter the phoneline may exhibit a behavior very similar to "Half-up". Check the information for the proper use of the "SDLC" entry in the [Gateway] section of this manual (chapter 8).

Virtually all Xerox equipment (DLions, Dicentras, the Multi-port board for the DLion, Daybreaks, etc.) has the same design flaw (some call it a feature) in the RS-232 circuit. The line receivers are biased to shift the 1/0 threshold to something unreasonable (-4 volts?, I don't remember off hand). What this means is that some modems don't work and/or work poorly with our equipment. Fortunately, the solution is very simple. Simply remove the DIP/SIP resistor pack(s) that bias the line receivers. With the bias resistors gone the chips now operate with their threshold at roughly 0 volts, exactly what you want!

If you echo from a PupGateway to another machine, be it PupGateway or not, sometimes the echo will appear to "break" after a number of echos have succeeded. The problem has to do with bigbuffers vs non-bigbuffers. The source of the echo cycles through its concept of min to max size packets and then back again, in a continuous loop. If the sender is a bigbuffer machine and the receiver is a non-bigbuffer machine then the echo will appear to break after ~530 packets. If you let it run long enough it would actually start working again when the sender wraps around to min size packets again. If the sender is a non-bigbuffer machine and/or the receiver is a bigbuffer machine then everything will work fine over the full range of sender packet sizes.

Every gateway will always advertise, via routing tables, that it can reach the networks that it is directly connected to. Problems arise when some, but not all, of the interfaces are not actually connected. It doesn't matter if the reason is failed hardware or simply an unplugged cable. When this happens, the gateway will continue to broadcast what amounts to bogus routes to the unconnected networks on all of the connected networks. This is because the gateway has no way of knowing that it is no longer connect to the networks in question.

This isn't much of a problem with phone lines, because the phoneline itself isn't very interesting to machines other than the gateways. By interesting we mean that there are no end hosts connected to that particular network that any other end host on the internet would want to communicate with. Routing table traffic (or lack thereof) will maintain good routes to the interesting nets. Ethernets, on the other hand, are interesting to machines other than just the gateways and therefore are subject to this type of failure.

Every once in a while an Ethernet stops working and affects (virtually) every machine connected to it (or at least to a given segment if repeaters are used). How do you deal with this type of problem?..

First of all you, should read and understand "The Blue Book" (the actual title is "The Ethernet, A Local Area Network"). This is the definitive standard for the physical and data link layers of the 10Mb Ethernet. All Ethernet terms (such as Section, Segment, Repeater, ...) are explained; limits are defined (such as cable lengths, repeater configurations, ...); timings are explained and tallied; pinouts are given; waveforms are shown; etc. If you are going to work on Ethernet problems you will need to understand this document.

Remember, "The Blue Book" and the discussion that follows below all pertains to 10Mb Ethernets. 3Mb Ethernets are similar but differ by more than just speed. 10Mb nets terminate in 50 ohms; 3Mb nets terminate in 75 ohms. 10Mb nets vary between 0 and -2.05 volts; 3Mb nets vary between 0 and +3 volts. 10Mb nets have "The Blue Book"; 3Mb nets have "The Ethernet Local Network: Three Reports" (Blue+White CSL-80-2).

Page 73 of The Blue Book shows what the waveform on a healthy cable should look like. When there are no packets on the cable there should be no signal on the cable (no AC and no DC). A good packet drives the cable between 0 and -2.05 volts (let's call it -2 volts for simplicity). The further you are from the source of the packet the lower it will read, but the general idea is that it is bounded by 0 on the plus side and -2 on the minus side.

To look at the signal with a scope you need to gain access to the center conductor of the coax without otherwise disturbing the cable. There are at least two ways to do this. If you are at a place in the cable where there are coax connectors, either at one of the ends or a section break, you can use a coaxial T connector to gain access. If you aren't at such a location or if you don't have the T connector, then you can tap in at a "tap, remove an existing transceiver is necessary. Don't forget to ground the scope probe to the shield of the cable and to use DC coupling. Also, make sure that the probe is set to high impedance.

Packets should be distinct bursts on the cable. Be careful, if you set the scope to too fast of a sweep time a single packet will be wider than the scope's screen and you can get easily fooled; too slow and you'll just see what look like spikes. A setting somewhere around 100uSec per division should be good. Also, don't forget that the amplitude of a signal will decrease with distance from the source of that signal. Therefore, even on a healthy cable, you will see packets with different amplitudes (but at least some should be near 2V P-P).

If you see a continuous signal on the cable then you probably have a bad transceiver or a sick machine "singing" on the net.

If you see distinct bursts but their amplitude is very small (no signals greater than 1 volt Peak-to-Peak), or if the bursts look as if they are going positive, then you probably have a short or open on your cable somewhere.

If you don't see anything on the cable then you probably have your scope set wrong or are right at the location of a short.

Check for missing terminators, open sections, shorted taps, etc. A tiny wire from the shield of the cable shorting to the center pin of a transceiver is not an uncommon problem. If you've installed or moved any taps recently this is a good place to check first. If you still haven't found the problem, then the best way to locate a problem like this is to break your cable at sections. Simply undo the barrel connector and to put a terminator on each piece. Now check each piece with the scope and see which is ok and which is still bad. Depending on how your cable is sectioned this can help narrow things down considerably.

In certain cases you can also use a TDR (Time Domain Reflectomometer) to help locate the problem. I won't go in to details here on how to use the TDR since few sites have them and even fewer have people who know how to use them correctly.

When a machine on a 10Mb net, such as a DLion, comes up (after power-on and/or being booted) all that it knows from its hardware is its 48 bit id. At this point, if it intends to speak PUPs, it uses an NS packet, and hence its 48 bit id, to request that someone tell it its 8 bit PUP host number. Servers that understand this protocol, PupGateways in particular, reply using information that they have from Pup-Network.txt. If the requesting machine doesn't get an answer after some number of retries, it dies with an MPC of 981 indicating that it can't figure out its PUP host number.

Problems arise when the machine is registered, but on the wrong net! Most systems (XDE, LISP, ...) simply ignore the returned network number and overwrite it with the number of the network that they are currently connected to, only using the returned host number. This is the problem that can lead to two registered machines conflicting on the same net; they each have the same host number but on different nets, but they ignore the net and clash! When two machines try to use the same PUP id they can get very confused.

Gateways keep a cache of 8<->48 translations to use when routing packets. Translations are needed for sending packets over networks where the physical and logical addresses differ. For example, if a gateway gets a packet destined for PUP host #45# on a 10 Mb network, it needs to know what 48bit physical id to put on the wire for the logical PUP host #45#. (The same thing is true for NS packets on 3 Mb nets.) On PupGateways these cached entries are updated/flushed every 3 minutes. This is why looking at a gateway's translation table is only useful if checked right away.

If you have a machine that occasionally (or not so occasionally) has problems when trying to use PUP protocols but is fine when using NS protocols then you might want to check this angle out. The next time the problem is actively happening, you need to check the translation cache of some gateway that the troubled machine is trying to use. Use PupChat to talk to a Dicentra PupGateway (from a working PUP machine) or select the proper menu item on a DLion PupGateway and "print translation Cache(s)". This will enumerate its current 8<->48 bit translation cache, by net.

Under the proper net, look for the host number of the PUP machine that isn't working (it's just a plain octal number without any # signs on the left hand side of each entry) and then look at the current Translation value (on the right hand side) -- this is its 48 bit address on the 10Mb net. Normally, this should be the id of the intended machine but in this case it will probably be the id of some other machine; this is the culprit machine's id!

Now, using NameLookupTool (or NameAndAddressTool) and/or a current copy of Pup-Network.txt, lookup the 48 bit address. If you find it then this will usually lead you to the offending machine somehow (via an owner comment or something),. Odds are that it is registered on some other net but with the same Pup host number as the machine that is having problems.

It may not be quite that easy...

Some systems (LISP in particular) have a "backdoor" where the user can specify the host id for that machine even though it's not registered in Pup-Network.txt at all. This is a definite NO-NO but some people do it anyway from time to time. (They usually just don't know any better.) In this case there may be no record in Pup-Network.txt at all for that particular 48 bit id. At that point you have to carry the 48 bit id around with you and start checking the id of every machine on the net, usually in areas that you don't know very well first. Look for LISP users first; they are often the worst offenders because LISP makes it so easy to plow ahead.

If the troubled machine is definitely using the gateway that you just checked (don't forget about the 3 minute timeout) but you can't find its PUP number or its 48 bit id, then it isn't using the 48 bit id that you think it is. In this case a good place to start would be to use Othello (or OthelloTool in XDE) and verify the machines host number (48 bit id). Odds are that somehow its host id PROM got changed or fell out (I've heard of it happening) and that it is no longer what you thought. Assuming that this is the problem then once you find out the correct number all you have to do is to properly re-register it and then you should be home free.

In the PupGateway world the terms Gateway and Router are interchangeable; they both refer to something that passes internet level packets between two or more networks or systems. Be warned, in the product world they "redefined" Gateway to mean a Mail Gateway. A Mail Gateway is something that connects two or more networks or systems together in such a way that only electronic mail is allowed to pass. In the PupGateway world if we ever mean a Mail Gateway then we say Mail Gateway.

"Internet Transport Protocols" (Xerox Systems Integration Standard publication XSIS-028112) covers NS routing in addition to a number of other interesting low-level NS protocols. This is recommended reading for anyone working with gateways. The Chapter on routing (Chapter 4; "Level two: Routing information protocol") does a pretty good job of explaining routing and routing table maintenance. Read this chapter for the full details.

Pup routing and routing table maintenance is very similar (although not identical) to that described for NS.

Every machine on the internet maintains a routing table. This table is consulted every time a machine sends a packet to a destination machine with which it can not communicate directly. This consultation is necessary because it must send the packet to an intermediate host who is closer to the destination machine than itself. This intermediate host is called a gateway or router. If the router can not communicate directly with the destination machine then it too follows the exact same procedure as the previous machine. In this manner the packet travels from the source to the destination through as many routers as needed via the "best" path at every step along the way.

The routing table consists of a number of entries, one for each network in the internet. (NB: Some workstations don't maintain full routing tables all the time. The reasons are explained in the gray book. Consider this, for the most part, an implementation detail.) Each entry contains: the number for the network that it represents, the intermediate host that should be used to reach that network, the current "distance" to that network in "hops", and the "age" of the entry.

All gateways gratuitously broadcast their complete routing tables periodically (about once every 30 seconds). It is this gratuitous broadcasting (and the willingness to forward other machines packets) that makes a gateway a gateway. All machines, gateways and workstations alike, maintain their own routing tables by using this gratuitously broadcasted routing information to update the individual entries in their table.

Age and hop count are the keys to maintaining a routing table. When entries are first created or updated their age is set to zero. Entries are deemed "suspect" if their age is 90 seconds or greater. Entries are "discarded" when their age hits 180 seconds or greater. (Discarded may actually mean discarded or it may simply mean having their hop count set to logical infinity.)

Whenever you receive incoming routing information you update every entry in your table that is mentioned in the incoming information.

The current permissible range of hop counts is from 0 to 15. Any hop count of 16 or greater is considered to be infinity. This limits the "diameter" of our internet to 16 hops (0..15).

Every packet that is transmitted has a counter which is initially set to zero. Every time the packet passes through a gateway the gateway adds +1 to the counter. If this counter ever reaches 16 or greater then the gateway deletes the packet. This is to prevent packets from traveling around the internet for long periods of time due to topology transitions or routing bugs. This also limits the "diameter" of our internet to 16 hops.

There is actually a +1 that is done whenever you "Replace the hop count" as described in the To "update" an entry algorithm. This is what makes the distance to a network grow as you get further away. The NS and PUP protocols do the addition at slightly different places. In the NS world you add the +1 to each entry just before you transmit it. In the PUP world you add the +1 to each entry when you receive it.

PupGateways have a hack that allows them to add more than just +1 to each entry. This is called "Extra Hops". Extra Hops can be used to make certain routes less desirable than they would otherwise look. This can be very useful because the normal "hops" metric doesn't reflect the speeds of different routes such as a 9.6Kb path vs a 56Kb path. NB: Do not use "Extra Hops" on a gateway without first getting an explicit OK from a wizard. "Extra Hops" have to be carefully tweaked in order to be a help rather than a hindrance.

As mentioned above, the ultimate source of the TRUE time is PopCorn. PopCorn is a "magic" box that sits in the Clover printer room (2106) at PARC. It's a satellite receiver that listens to a time satellite(s) and also connects to the Ethernet via an RS232 line and the DLS. PopCorn has a very accurate internal clock. It also understands things like the speed of light, clock drift, transmission delays and rates, etc. The end result is that you can ask PopCorn the time over the network and you get back a very accurate answer, including error bounds.

This is exactly what some PupGateways do. Every so often a few hand-chosen PupGateways ask PopCorn the time. If PopCorn's answer is more accurate (read the code for the fine print) than their own concept of the current time (modulo some delta) then they adopt PopCorn's answer as their new concept of the current time and give it a new version number.

Independent of what is going on with PopCorn all NS time servers periodically (on the order of 15 minutes to an hour) compare their time to that of the other, usually nearby, time servers. They update their concept of the time from someone else if and only if the other machine has a newer version (this is how PopCorn becomes the ultimate authority) or if the other machine has a better concept of the current time (modulo some delta) when error bounds are taken into account. Again, read the code for the real fine print.

IFSs set their clock via the net when they boot but after that they don't track the other timeservers. This is why you should disable the time service on your IFS. The PupGateway will supply a more accurate time. If you have an IFS that deviates from the correct time to can help things by adjusting the "Clock correction" parameter on the IFS.

Here's a bit of folklore for you. From PARC the local telephone number to call for the current time is 767-2676, which can be dialed by spelling POPCORN on the telephone!

This year (1987) the U.S. changed the official start day for Daylight Savings Time. Since we may someday need to do something similar again (and because it has some other interesting information in it too) the information on how to do the conversion is reproduced below:

TimeServer and TimeChecker both operate the same on the DLion and the Dicentra.

Sends a RAW BreathOfLife Packet (it's not a PUP, it's not an XNS, it's a BreathOfLife) every 5 seconds or so on all directly connected 3Mb Ethernets. BreathOfLife packets are needed by Altos when booting from the net.

For testing and debugging purposes there is a BSPSink server in PupGateway. It accepts BSP connections and obediently dumps everything on the floor. This can be used for protocol and throughput testing.

There is no parameter section associated with the BSPSink server.

GateControl is a Pup protocol for getting a "view" of a gateway in real-time. It also allows you to halt and restart a gateway remotely. As far as I know this protocol is totally undocumented, except by the code that implements it. Both DLion and Dicentra versions of PupGateway support this protocol.

There is a tool, GateWatcherTool, that comes with the DLion version of PupGateway that allows you to monitor and control a remote gateway via this protocol.

There is no parameter file for this server.

For testing and debugging purposes there is a PupEchoServer in PupGateway. Various statistic printouts include echo server information.

There is no parameter section associated with the Pup echo server.

A number of Pup servers actually use the same well know socket (WKS), the Miscellaneous services socket. The PupMiscServer is really just an umbrella server that dispatches to a particular server as a function of the Pup Type field. The servers that use the Misc socket are: boot, directory, name and time. The Misc server also supports the echo protocol (this is in addition to the echo server on the echo socket) and the whereIsUser/userIs protocol.

There is no parameter section associated with the Misc server.

If a PupGateway has a [TrapBadPups] section then it will detect and report, via GV mail, any Pup packets that it receives with good encapsulation but a bad internal packet. This usually points to sick software or a sick machine. These messages can be decoded to indicate the machine that was the source of the bad packet.

Net Watcher is not a server. It is a process on a PupGateway that watches the local machine's routing tables and prints a line to the log whenever it notices a change in the routing table. Since this is a separate process, and a very polite one at that (it does yields all over the place), it does not guarantee to log ALL changes of the routing table, but it does give a feel for the stability of the routing table.

There are two net watchers, one for PUP nets and one for NS nets.

Gateways keep a cache of 8<->48 translations to use when routing packets. Translations are needed for sending packets over networks where the physical and logical addresses differ. For example, if a gateway gets a packet destined for PUP host #45# on a 10 Mb network, it needs to know what 48bit physical id to put on the wire for the logical PUP host #45#. The same thing is true for NS packets on 3 Mb nets. On PupGateways these cached entries are updated/flushed every 3 minutes.

See "MP 981 and Pup Registration Problems" under the "Common Problems and Fixes" section for more information on the Translation Cache.