Omni DNS Helper
app version 1.0 beta 3
document version 1.0 beta 3

Contents

	·	Contact Info and Disclaimer
	·	General Overview - an overview of this app's purpose
	·	Application Requirements
	·	Application Usage
	·	A Brief Technical Overview
	·	The Data - an explanation of the data manipulated by this app
	·	What if this app doesn't work for me?
	·	Notes on setting up Rhapsody and OPENSTEP/Mach networking in a non-NetInfo environment
	· Release Notes

Contact Info and Disclaimer

Send bug reports, feature requests, questions, etc. to omnidnshelper@omnigroup.com. For the latest version of this application, as well as release notes etc., see http://www.omnigroup.com/Software/OmniDNSHelper/.

We think this works fine - we've used it here some and we've let some other people test it. But we could be wrong, and we're not going to promise that it's perfect or even safe. If it doesn't work, if it wipes out all data on your network, if it sneaks around after dark and steals everything from your fridge, whatever it does, we're not responsible. See the release notes below for any caveats.

General Overview - an overview of this app's purpose

Omni DNS Helper is intended to fill in a couple of holes in the networking configuration applications for OPENSTEP/Mach and the Rhapsody Developer Release. Specifically, the currently provided configuration apps provide no nice way to maintain your domain name and DNS server entries. Rhapsody and OPENSTEP/Mach use a network management system called NetInfo, which allows this information (and much other information) to be stored on servers, so the individual client machines need never worry about these issues, assuming that you are using NetInfo.

However, for people who have standalone Rhapsody or OPENSTEP/Mach systems connected to the Internet via PPP or some similar means, or for people connecting Rhapsody or OPENSTEP/Mach systems to an existing non-NetInfo office (or wherever) network, they usually need to be able to configure these parameters, and there isn't currently a user-friendly way of doing this via the standard tools.

I wrote this app in order to bridge this gap for people who otherwise don't know how to deal with this, or wish for a more palatable solution than the existing ones. Be a bit careful with it - if you enter invalid data, much of your networking capabilities will be compromised until you correct the data.

Below is more information on the data maintained by this application, as well as some other notes about setting up networking on a Rhapsody or OPENSTEP/Mach system in a non-NetInfo environment.

Application Requirements

This application requires OPENSTEP/Mach 4.2 or the Rhapsody Developer Release.

If your system isn't supported by this application (old versions of NeXTstep, for instance), see the What if this app doesn't work for me? section below for an alternative approach.

Full source code is available for this app from the URL given in the Contact Info and Disclaimer section above, so you can examine what it's doing. At runtime, this application, depending on situation, may ask for an authentication password before you can save changes. Usually, you will want to use the root password. This is a security issue - this app could easily take this password, and other information about your system, and email it to me, or could delete your files, or pretty much anything. It doesn't do anything like that, but if for any reason you don't trust me, you should examine the code to see just what it does, then compile that code, rather than using the provided executable. An executable version is supplied as well, for those who don't have access to the developer tools and therefore cannot build the app from the source themselves - you'll just have to trust me. The OPENSTEP executable is provided as a fat (multi-architecture) binary and should run without problems on NeXT, Intel, and SPARC hardware running OPENSTEP/Mach 4.2. The Rhapsody executable, which runs on the Rhapsody Developer Release, is provided as a fat binary for PowerPC and Intel. (Note that it hasn't been tested on the Intel version of Rhapsody, but no problems are anticipated.)

Application Usage

Launch the app. You will be presented with a panel with several options on configuring your resolver data, as well as information explaining each option. Choose whichever option fits your situation. Enter/modify domain and nameserver values as appropriate. (See below for more information on domain and nameserver entries.) Save. (You may be prompted to enter authorization information - usually this will be the root password.)

If name lookups don't work after saving your configuration, you may need to reboot (or restart the appropriate services without rebooting if you are savvy enough) but usually this shouldn't be required. (If you performed failed name lookups shortly before using this application, those failures may be cached - try looking up different names.

A name lookup is performed when you try to connect to a web site, ping a host, etc., and you use a machine's name rather than it's IP address.

A Brief Technical Overview

This app manages configuration of the data that is often put in the file /etc/resolv.conf - the domain name and the DNS server entries. It does this via NetInfo - not by resolv.conf (and the existance of a resolv.conf may cause this configuration to be ignored - I haven't tested that). It manages the /locations/resolver directory in a NetInfo Domain, creating it if necessary. It creates, updates, and deletes the domain and nameserver entries in that directory. If the user saves a configuration with no domain name and no DNS entries and there are no other entries in the resolver directory (except of course for the name entry which defines the name of the directory), then this app removes the resolver directory from the NetInfo domain as an empty resolver directory will interfere with normal resolver operations. (It is very unlikely for the vast majority of people that there will be any other entries in this directory, but if there are, this app obviously will not know why the extra entries exist and therefore cannot safely delete them; this can cause undesired resolver behavior.)

The Data - an explanation of the data manipulated by this app

Domain

Basically, a domain is a network's name. For example, Omni Development's domain is omnigroup.com. We have a machine called www which is our web server, but if you tried to browse our web site by simply typing "www" into your web browser, you wouldn't succeed because that's not enough information for your machine to find ours. You have to provide the fully-qualified name: "www.omnigroup.com".

If you are connected to the Internet, then you also have a domain name - it may be the domain name of your employer if you're connected to your employer's network, it may be the domain name of your Internet service provider if you have one, or it may be some other name that you registered just for yourself.

If you are not connected to the Internet, then you may not have a domain name, in which case you should leave this field empty.

DNS servers (domain name servers)

In order to connect from your machine to another machine (in order to browse a web site, ftp, etc.), your machine needs the IP address of that remote machine, such as 198.151.161.40. Obviously, these numbers are difficult to remember, so we give machines names and use those names instead - the name for the IP address above is "www.omnigroup.com". (A machine can be given multiple names - the additional names are called aliases.) Your machine needs a way to convert those names back to the corresponding IP addresses and vice versa.

DNS servers (often simply called nameservers) take machine names, like www.omnigroup.com, and translate them to IP addresses, like 198.151.161.40. They can also take IP addresses and find the matching machine name. If you are connected to the Internet via an Internet service provider, they should provide at least one DNS server for you (they usually also provide a backup DNS server, which provides the conversion service in the instance that the primary DNS server is unavailable for some reason). If you are connected to your employer's network, they will likely provide DNS servers as well.

There are other ways to provide this service; if you do not have access to any DNS servers, then this application is probably not useful to you.

What if this app doesn't work for me? - an alternative solution

If for some reason this application doesn't work for you, you can take the brute force approach. Create a file called "resolv.conf" in the "/etc" directory. (Make sure that this is a plain ASCII file - not RTF or any other rich text format.) Put your domain and nameserver entries in that file. See The Data section above for details on these entries. The end result should look something like:

domain omnigroup.com
nameserver 198.151.161.40
nameserver 198.151.161.1

Alternatively, have a look at the Brief Technical Overview section above, which should give enough information to allow you to manually manage this data in the NetInfo database yourself if you are comfortable working directly with NetInfo databases.

You may need to reboot (or manually restart the appropriate processes if you know how to do that) before changes will go info effect, though usually this is not needed.

Notes on setting up Rhapsody and OPENSTEP networking in a non-NetInfo environment

These instructions are assuming a typical configuration with a non-NetInfo network: most usually, a single machine hooked up to the Internet via a dial-up link (normally PPP) or a single machine hooked up to an existing network that doesn't know anything about Rhapsody or OPENSTEP. If you have any reason to believe that you have a different situation, be wary of these notes.

Most networking configuration will probably be done via HostManager. In the Local Configuration panel, you probably want the following settings:

NetInfo Binding: Use local domain only. Also, turn on "Readable only by local net."

Hostname: whatever name you wish to call your machine. Do not include the domain, just the machine name.

NIS Domain Name: None. If you enter a name here, then Rhapsody and OPENSTEP will try to start up NIS networking services (called Yellow Pages in a previous incarnation), which for most people will cause bad things to happen. This is for compatibility with Sun networks, and you don't want to use it unless you really know what you're doing. More details on this are beyond the scope of this document.

Internet Address: Set this to whatever IP address you have been assigned (or which you can assign yourself, assuming you're in such a position to do so). If you're connected to your employer's network, then you will definitely need an IP address which 1) fits into your employer's subnet, as appropriate, and 2) does not clash with any other machines on the network. If you're connected to the Internet via an Internet service provider, then they either assigned you an IP address (or a group of addresses, from which you can choose as long as it doesn't clash with any other machines you have set up), or you don't have a dedicated IP address; the latter is actually the norm.

If you don't have a dedicated address (IE, you have a dynamic address), use the default IP address (not the Autoconfigure, but click on the other radio button and keep the number that is filled in automatically). Also, if you have a dial-up connection to the Internet you will almost always also use the default address, as the dial-up connection will use a separate address (which is often configured automatically, or is otherwise configured as part of the PPP configuration).

Specifically, this field should not be 127.0.0.1 - that is a special address (called the loopback address).

Broadcast Address: In the standard case, this address is based on your Internet (IP) address and can be determined automatically by the system. However, this is not always the case. If you're connected to the Internet via an Internet service provider, they should have provided you with a broadcast address - enter that IP address here. If you are connected to your employer's network, you should be able to get the broadcast address from your network administrator.

Time Standard: Ignore Network Time. There are ways of keeping your machine's clock in sync with the network, but they are out of the scope of this application and this document. Normally, this means using ntp - aggressive users may explore this option (there is a unix man page for ntp). PPP users may wish to have ntp run when a PPP connection is made (with the included PPP for OPENSTEP, this is done via the ip-up file - see the PPP documentation for details). If you take this route, you may wish to tell ntp to connect to the machine timehost (or something along those lines) and create a corresponding host entry with HostManager.

Netmask: In the standard case, this value is based on your Internet (IP) address and can be determined automatically by the system. However, this is not always the case. If you're connected to the Internet via an Internet service provider, they should have provided you with a netmask - enter that value here. If you are connected to your employer's network, you should be able to get the netmask from your network administrator.

Router: This is often referred to as your gateway. Some routers advertise themselves, in which case you can use Dynamic, and the system will look to see who is advertising as a router. If you know a router/gateway address, enter it here. If you know that you do not have a router/gateway, select None here.

When you are done and satisfied with your choices, click on the Set button. You will be prompted to let the system reboot. If you choose to not reboot at this time, then your changes will not take effect until you do reboot (or until you restart the appropriate services manually, should you happen to know how to do this).

You should also use HostManager to create a host entry for your machine: give it the Internet (IP) address that you entered in the Local Configuration panel and the name that you entered in the Hostname field. The reason for this is that your machine won't recognize itself under all circumstances unless there is a local host entry. You should probably not bother with the other attributes unless you know what you are doing (System Owner and System Type are just comments, and it's safe to put whatever you wish there - by convention, the System Owner is set to be whoever normally uses that machine). Do not simply add your hostname as an alias to localhost or broadcasthost, and do not add them as aliases to your new host entry - those are special names with special addresses, and things will likely go haywire if you alias them together.

Rhapsody and OPENSTEP include online documentation on system administration. Many people will not need or want to delve into this documentation, but some will. The documentation is located at /NextLibrary/Documentation/NextAdmin/SysAdminManual. (The documenation in the Rhapsody developer release has not yet been updated from the OPENSTEP/Mach version; a README file attempts to cover some of the differences.) Release notes are located close by, and can be very informative and helpful, especially in reference to bugs.

Sendmail configuration is an issue which is out of the scope of this document and application (sendmail documentation is available in the online SysAdminManual). However, as a note to those confronting this issue: you may wish to define a host entry for your mailhost machine (or mail-relay machine, depending on which sendmail configuration file you are using and assuming that it's one of the standard ones supplied with OPENSTEP) instead of manually placing the appropriate hostname in your sendmail configuration file. (It does however require that you know the IP address of your mailhost.)

Release Notes

1997-10-29, version 1.0 beta 3 
·	Added support for the Intel version of the Rhapsody Developer Release. (untested)
·	Modified to tiptoe around an authentication bug in NetInfo which was causing a crash in previous versions. It turns out that if you have a flat netinfo hierarchy (local netinfo domain == root netinfo domain), once you hit the Authenticate button on the authentication panel, the app crashes (strcpy with a null parameter). It works fine if your netinfo domain isn't flat. Fortunately, if you are root and you are editing a local domain then authentication is automatic, so I bypassed the authentication panel if you are in this situation. If you aren't root and you have a flat netinfo hierarchy, I simply stick up an error panel informing you that you can't save changes. The upshot? You're best off just going ahead and running this app as root. (Warning: don't make this app setuid root as then anyone can make modifications at will.)
·	Added some exception handling.
·	Corrected some of the Rhapsody UI.

1997-10-17, version 1.0 beta 2 (slipstreamed as beta 1)
·	Added support for the Rhapsody Developer Release.

1997-07-07, version 1.0 beta 1
·	The first public beta, developed on and for OPENSTEP/Mach 4.2.