WebDNS Users' Guide

WebDNS (CSAIL Login required) is a system developed at CSAIL to allow Lab members to manage entries in the Lab’s Domain Name System namespaces. Currently, WebDNS serves the ai.mit.edu, csail.mit.edu, and lcs.mit.edu domains, as well as a decreasing number of guest domains. Any authorized user may make changes to any of these domains.

Understanding Domain Names

(It’s OK to skip most of this section, but do pay attention to the parts in boldface.)

A Domain Name consists of a sequence of words, called “labels”, separated by dots ("."). The labels identify branches on a tree, with the root of the tree at right when the name is written out. (The label of the root is the empty string. Normally, the root and dot separating it from the first label below are represented implicitly, like the leading one bit in a floating-point number. In some contexts, however, a Domain Name must have an explicit root label.)

Theoretically, a label may contain any characters other than “.". However, there are practical limitations arising from the requirements of the applications which use domain names. For example, spaces are not allowed in domain names, because the standard written format for DNS records uses whitespace to separate fields. For domain names which are used as host names – the only kind we’ll be discussing from here on out, the requirements are much stricter.

A host name may contain only the following characters: the Roman letters “A” through Z”, digits “0” through “9”, the hyphen “-", and the period (dot, full stop) “.". Neither dot nor hyphen may be the first character of a host name. Case is not significant, but custom in CSAIL is to use lower case. .

(There is now a standardized mechanism to support “internationalized domain names”, whereby Unicode labels can be transformed into a plain-text representation that fits the requirements for a host name. CSAIL does not support this.)

A Fully-Qualified Domain Name is a Domain Name which includes a complete sequence of names all the way to the top level. For example, the FQDN of the WebDNS server itself is webdns.csail.mit.edu. All of the places where WebDNS wants a host name must be Fully-Qualified Domain Names. (As mentioned above, domain names may represent the root either explicitly, as a trailing ("."), or implicitly. When using the “Edit Raw Records” function, the root must always be explicit; in the main interface, WebDNS will handle this for you as needed. This document will not describe the “Edit Raw Records” interface.)

Choosing a Host Name

WebDNS enforces no restrictions on the host names that you use, beyond ensuring that the syntax is valid. You may choose any name you want, provided that it consists only of letters, numbers, dots, and hyphens. However, we offer the following guidelines to aid your choice:

• Do check your group for a standard naming scheme. If most of the other machines in your group are named after French Impressionists, then you should probably do likewise.
• Do give similar names to machines which are part of a natural grouping such as a cluster.
• Don’t use names which would be considered offensive.
• Don’t use names which would cause undue confusion; if there’s already a machine called “tobasco”, you probably shouldn’t call your machine “tabasco”.
• Don’t give workstations names which represent their current user or location. People move, and so do machines; the next user will thank you for your courtesy in naming.

Registering Your Host

Once you’ve selected a host name, you can create a DNS entry for your machine. This will give you a static IP address for the computer. We recommend that all machines belonging to CSAIL have a static IP address registered on a network which is appropriate for the use to which they are put; if you use our standard Linux or Windows configurations, you will be required to do so. If your system has a wired Ethernet network interface, then it should have an address on the network which is used in your work space. If you have more than one network interface (e.g., both wired and wireless), you will still be able to use both, but you may only have a static assignment on one network.

Proceed to WebDNS (CSAIL Login required). We recommend that you access WebDNS from a machine on the network your new machine will be using—if the new system is already up and running, it will make things easier if you run use a browser on that machine. (This will allow WebDNS to automatically figure out which network you are on.) If you have authenticated, you should see a screen that looks like the following:

Enter the new host name you selected in the input box (I’ve used example.csail.mit.edu here) and select Add. If your name is already taken, you’ll get an error message along with a listing of the records associated with that name. Otherwise, you’ll need to choose a network on the next screen, which looks like this:

The pull-down menu includes a list of all the networks WebDNS knows about. It’s important to set this correctly; if you are running WebDNS from the same network as the new machine will be on, it should be correct by default. Otherwise, you’ll have to figure out which network you need from the menu. If you’re having trouble, ask help@csail for assistance. Ignore the field that says Or enter a netblock in CIDR notation. When you click the Submit button, WebDNS will search the network you selected for an available IP address and tentatively offer it to you. The next screen is used both when adding a new host and also when editing an existing entry:

*Do not change the IP address assigned to you by WebDNS* unless a staff member explicitly directs you to do so. If you are currently using a dynamic address, you may not reserve that particular address as a static IP; it belongs to the DHCP server. The address that WebDNS gives you is guaranteed to be available for static assignment.

You may add as many aliases (Nicknames or “CNAME records”) as you need. Aliases are considered host names, just like the official name, and must conform to the same rules. If you need more fields for aliases, you’ll be able to add additional ones later. You should not enter Mail Exchangers. When you select Commit Changes, if all goes well, you’ll see a display similar to the following:

The “change log” information is also mailed to system administrators. If you do something that seems like a mistake, a sysadmin may contact you to make sure that was what you really intended.

Propagation Time

All WebDNS updates should be reflected in the DNS servers within a quarter hour. That is to say, if you make a change at 11:25, the servers will see the new information at 11:30. However, DNS data in the CSAIL domains may be cached up to an hour (depending on lots of factors) at servers around the Internet. So, to use the same example, if your update still hasn’t shown up everywhere after 12:30, you should ask for help.

Editing an Existing Registration

Editing data in WebDNS uses the same display as adding a new host. There will always be three more entry fields in each section of the display than are currently needed; this allows you to add as many aliases and mail exchangers as you need, incrementally.

Renaming a Host

Renaming a host in WebDNS is nearly trivial. However, your machine has its own idea of what its name is, and this needs to be updated at the same time as you rename it. Contact help@csail for assistance in renaming Windows or CSAIL Ubuntu machines.

You need to decide whether the old name should be kept around as an alias. If there are likely to be people depending on the old name, then you should keep it. If, on the other hand, the system is going to be completely repurposed, then there’s no point in keeping the old name around; it will probably just confuse people.

The rename screen looks like this:

When you select Confirm, if the new name you have requested is available, you’ll get a confirmation message like this:

Otherwise, you’ll need to find another name.

Deleting a Registration

When a host is no longer being used, it should be deleted from the DNS to allow someone else to use that name and IP address. You should look over the DNS information shown in the confirmation screen:

If this looks like what you meant to delete, then select Confirm and your host name registration is history.

History and Credits

When the Domain Name System was first implemented at LCS/AI in the 1980s, the authoritative namespace data store was the Lisp Machine namespace system. A nightly job on one of the LispMs would store a flat-file export of the namespace on a TOPS-20 server, MIT-XX. Rob Austein developed a program on XX to parse the flat file into standard-format zone files, which were then transferred to the name servers. When XX was shut down, Austein and Mike Patton developed two schemes to convert the LispM dumps to zone files on a Unix machine; Austein’s (written in Emacs Lisp) was completed first, so Patton’s more general solution was never deployed.

By 1991, Austein’s Emacs Lisp hack was taking several hours to run, and users were grumbling that their changes were not taking effect in a timely manner (defined as “before I get in the next day”). Chris Lindblad wrote code to generate the zone files directly on a LispM, which was significantly more efficient; from the LispM server, Zermatt, they could be FTP’ed to a Unix server and installed in the name servers.

LCS finally gave up on maintaining Lisp Machines around 1995. The namespace system (with its accompanying DNS hack) running on Zermatt was one of the last essential services which needed to be migrated off the LispMs before they could be shut down for good (reclaiming much valuable space in NE43’s third-floor machine room). In what he described as a “dissertation-avoidance exercise”, Chris Lindblad again came to the rescue, developing the first implementation of WebDNS. As originally implemented, WebDNS was a monolithic Perl 4 CGI script, which stored its back-end database as DBM files on the main LCS server, mintaka, a Sun SPARCstation IPX. It was not very efficient, but it was more accessible to the Lab’s users than the old LispM namespace was, and it got Zermatt out of the way.

By 1999, the problems with the new implementation were clear. It was difficult to maintain, did a lot more work than it needed to accomplish its function, and made it too easy for Lab members to unintentionally break services for the whole Lab. I (Garrett Wollman) began designing a new relational-database back end (implemented using PostgreSQL) but never built the user interface.

The “new” system, and the machine it ran on, lasted until 2003. That year, Noah Meyerhans took my code and built the missing pieces for a Web front end. The result is the current implementation of WebDNS.

(History cobbled together by Garrett Wollman and Mike Patton.)