Use this image map or the text links at the bottom of this page for navigation.

Domain Registration

This document is for system administrators of sites subscribing to ClariNet only. If you are a user and you have found that ClariNet's web servers do not recognize you as a subscriber even though you believe your site has a subscription that includes you, contact your own local systems administrators or technical support and point them to this web page.

When users whose site subscribes to a ClariNet service visit our web servers, the servers decode the user's address to figure out if the user is a subscriber, and what editions or products that user subscribes to.

However, in order for your users to be identified as subscribers to Clarinet, we must obtain for you in advance the addresses of users covered by your site licence.

There are several reasons to do this. The simplest is promotion of your own site. When your users visit our web page, it identifies them as a subscriber from your site, and is able to remind them that you are providing them with a subscription. The page can even offer graphics from your site to show your logo on our web page. The user will be able to proceed directly to the right documentation and menus as well.

Coming soon, users will be able to access certain types of subscriber-only data and services from our web site. Planned are the results of full text searches and stock quotes. You'll want to make sure your users get access to this so you will want to look into the procedure below.

There are two different methods that can be used to identify an incoming user making a request at a web site. The first is the host name, as returned from an "inverse domain name lookup" from the IP address. The second is for you to make available to us a table of the IP address ranges of your users. It is possible, and even encouraged, to do both.

Summary of Your Tasks and Options

You must provide us with the master domain names(s) for your site. At a minimum this is a path to special DNS entries you can create to further define who is at your site.
If your master domain name identifies all your licenced ClariNet users and doesn't identify any non-licenced users, you can make one DNS entry that says that and you're done.
If you don't have reverse domain name lookup for users or you have a complex set of internal domains, you can define IP address ranges instead of or in addition to your master domain names. You do that with a special DNS entry as defined below.

Master Domain Name

Summary: We need your top-level, master domain name(s) reported to us.

In order to make any of this work, we must have from you your "master domain name" or names. This is the highest level domain at your site, the name which forms the end of all your local and user domain names. It is the domain name you registered with the Internic or other authority.

For example, ours is "clarinet.com" though we also use "clari.net" interchangably.

You can have more than one (and not just ones that act identically like the ones above) as well.

Please make sure we have your master domain name(s). Send E-mail to support@clari.net to submit this information. You may already have provided it on your application form if you are a recent customer. Otherwise, we may have put in a guess (sometimes it's obvious from all your email addresses and server names) in our records. Visit our Customer customized page to check if we have your records, and if we have them as more than a guess. (If we just have a guess, the page may identify you but will say your records are incomplete.)

If you have more than one master domain name, we can record that. However, if you have two that are identical in function, we only need the one that is most official and which comes back as the result of reverse name lookups on your IP addresses. If one domain is a subdomain of another, we need only the higher level domain.

If you follow our procedures below you will be creating some special records in this master domain, so you need access to the DNS records for it.

Subdomains

If your ClariNet licence does not cover your entire site, but does cover a subdomain, this subdomain should be given as your master domain name. If your subdomains and licence can't be made to match in any meaningful way, contact us to work on the problem.

Host Name Lookup

Summary: Do all your systems have a reverse-lookup, "in-addr.arpa" PTR record inside your master domains? If so, let us know with a special entry and you are all set, otherwise, see below.

Every real machine on the internet has an IP address, though some machines with switched (dial-up) connections get a temporary address that is re-used by other switched machines. Domain names, like soprano.clari.net are commonly used to avoid the need for numbers. A domain name can map to an IP address in the internet's "domain name service" (DNS). More than one name can map to the same IP address as well. Often several famous net names refer to the same machine. (It's less known that one name can map to several addresses.)

Since incoming connections are identified only by IP address, a parallel DNS feature, called the "pointer" record, can be used to map numbers back to names. However, each number can map to only one domain name, even though many domain names might point to the number. This mapping is called an "in-addr.arpa" mapping, "reverse domain name lookup" or PTR record and is returned in programs by a function called gethostbyaddr.

We feel IP address ranges are the most reliable way to specify what users are covered by your licence, but sometimes they can be inconvenient.

You must make sure that all systems and IP addresses at your site have an valid reverse lookup or PTR entry. About 80% of systems do, because many FTP servers and web sites insist on knowing who is calling. Some sites have only partial mappings, because they haven't added new systems or don't create names for systems that get a dynamic IP address.

If you have such reverse lookups set up, just make sure they end in your master domain name, and be sure to add one for every new IP address you use. Explaining how to set up in-addr.arpa from scratch is beyond the scope of this document, but you can find web pages and books on the subject, such as this NIC FAQ.

The problem with this system is that some users, even though they have an address from you, want to have their own name show up when a reverse name lookup is done. You can solve this problem with the address range system below.

Enabling Access Control with pointer records.

In addition, reverse name lookups have security problems and sometimes refer to too wide a network compared to customer site licences. As such, by default we only use them to identify users for promotional purposes, and not for access control -- unless you explicitly authorize us to do the latter.

To do that, create a special domain "A" record inside your master domain called clari-range.your-master-domain. Define this domain to be the IP address 127.0.0.1. We'll look up this name on your name server from time to time, and while this record is there, we'll know you want us to enable access to all users whose reverse name lookup ends in your master domain. (Our web server, like most, re-looks up the name after it gets it back from a reverse lookup, to assure people aren't cheating.)

Defining IP Address Ranges

Summary: You can define special domains with magic entries that tell us the IP address ranges of your licenced users.

The other way to let us know what IP addresses your users have is to define IP address ranges for us. You can do that by defining a special magic domain name with multiple IP addresses. Every day or so, our system will read the addresses in this magic domain and record them so our web server can take an IP address from your system, and know it is from your system. This will work even if the IP address has another reverse name lookup.

To do this you define the magic domain clari-range.your-master-domain. For example, clari-range.clarinet.com is the domain we would define if we were our own customer!

You will define an internet address or "A" record for this domain. You may not know it, but domains can have mutliple resource records associated with them, and in this case we will use multiple A records, in pairs, to specify ranges of addresses.

Note the ranges of IP addresses that are yours and used by customers included in your site licence. Define the starting and ending point for each range of addresses. Most sites have a contiguous set of addresses and thus just need one start and end, but some sites may have various discontiguous blocks, and so will need to specify several sets. For example, for a typical class C network like ours:

clari-range	IN	A	192.54.253.0 
		IN	A	192.54.253.255

This definition enables all addresses between these two numbers to get access to the information you have purchased for them. You can define several ranges. While the limit on the number of addresess in a domain is not specified, we recommend you limit yourself to 8 pairs per domain. If you need more pairs, you can define domains clari-range1, clari-range2 and so on. Note that the system will not look for such extension domains unless the one it just read had at least 14 or more entries in it. So if you define clari-range with 12 entries we will not look for clari-range1.

Take care in defining the ranges. We'll sort the values so you don't have to worry about them getting out of order, but if by accident you define too large a range (for example the whole internet!) we will discard such results and you may disable access for your users that way. Let us know if you need to define a range with many more addresses than there are users in your licenced user count.

In addition, generally you should not define a range for more than one master domain. (If you have two master domains that have identical domain servers, you must not tell us both of them.) If you do define more than one range in more than one master domain, be sure they don't overlap as our software will consider that an error -- each IP address must map to only one customer.

With this method you can freely add new systems in the range and they'll get access if they don't have a reverse lookup name in your domain or if they don't have a reverse lookup name at all.

Allowing both

If you want us to grant access both by reverse name lookup, if present, and by an IP address range, you can add the fake address

		IN	A	127.0.0.1

To your list of addresses. This will give you an odd number of addresses, but we'll treat this one as a flag to indicate you want to enable access to information based on the domain name as well as the IP address. If you do this, you can have access for most users by domain name, but do a few exceptions by IP address, or vice versa.

Web Server Documents

We also encourage sites to make available to us graphics and information from your own local web servers that we can include in our pages. Future plans for this vary, but our first goal is to be able to have you define a URL for your own logo or other suitable graphic that we can insert in a page.

To do this, first tell us where a web server is that can be used to serve up such graphics. You can do that with a DNS "CNAME" record, mapping the special name "clari-www" to the name of a real web server you have.

clari-www	IN	CNAME	www

The above record creates a new name in your master domain that points to your web server, if it's called "www" in your domain.

Please note that to be efficient we do not check for clari-www if clari-range does not exist. If you want to define clari-www but don't want to use a clari-range domain, you can define a clari-range with just the address 127.0.0.2 in it. (All 127.0.0.* addresses are treated specially by the program and are not valid IP addresses anyway.)

Our systems will, every few days, check to see if the name clari-www.your-master-domain exists. If it does, it will try to test for the existence of certain URLs on that web server. In particular http://clari-www.your-domain/clarifiles/loclogo.jpg or http://clari-www.your-master-domain/clarifiles/loclogo.gif. One of these files (whichever is found first) will be expected to contain a small version of your logo, no larger than 150 pixels wide and 100 pixels high, suitable for display on any colour background. (Note that these files must be present on your web server so that a HEAD request returns a 200 series response or response 302 (found), and not a relocation or error response.) The response on the JPEG must be 404 (not found) before it tries to look for the GIF. We don't wish to make multiple attempts on a server that is failing to respond for other reasons.

Note that while we may fetch the image to test its size, generally the system will simply note its existence. Then in web pages here we may insert an inlining reference to the URL on your web server, though with the name clari-www.your-master-domain. That means the graphic will be fetched locally, not from our server, which is faster for the user and doesn't use any of your own internet bandwidth. Our test is just there to make sure the image is there for inclusion.

Later we may expand this and allow you to store text and other information on web pages for our use in customizing things for your users -- while allowing you to retain control of, and in fact serve up, the data in question.

Of course, you don't have to create a new web server to do this. You just create a clarifiles directory on your own main web server and put a logo file in it -- or even link to an existing logo file you already use on your web pages. The CNAME record simply tells us in a standard way where your web server is. It also means you can change the name of that web server without having to tell us.

Local ClariNet Reading Page

If you have created a web page for your local users to use as an anchor for reading the news, be it our newstrees or your own guide, then we can direct users to it. We will check the URL http://clari-www.your-domain/clarifiles/read.html and if we get any non-error, we will direct users to this page. However, note that since they will be reading it via this URL, any references on the page will be relative to the clari-www machine and the clarifiles directory. One way around that is to have your web server do a "redirect" from the /clarifiles/read.html URL to the real news home page on your system.

Summary

Make sure you have told us about your master domain, or domains, and we have that recorded in your files.
Make sure IP addresses of your users have a reverse name lookup (DNS Pointer or in-addr.arpa records).
Define a clari-range.yourdomain with pairs of A records to show the stand and end of all your licenced IP address ranges
Define a special A record inside the clari-range entry of 127.0.0.1 to indicate that your reverse lookups are "authoritative."
Create a CNAME record to point the name clari-www to a web server inside your site. Create a directory clarifiles on that web server and store your logo there in the file loclogo.jpg or loclogo.gif
Put comments in the DNS files to indicate the purposes of these records for people who may have to handle your duties when you aren't there. Remind yourself to update these records and images as needed.

Notes

The system we use does not pound on your DNS server. Rather we look up the addresses as needed, and remember them for a day, or until told to reload them. This is actually more efficient than reverse DNS lookup. Even if your DNS server is down at the time a user comes in we can still give them access this way.

Keeping graphics on your own web server puts a slight extra load on your own web server but it cuts down on internet traffic and gives your users faster response.

If you have dial-up users who have their own IP addresses outside your ranges and who have domain names outside your domains, this must present a routing nightmare. It's stronly discouraged these days but if you only have just a few of these perhaps there is some other solution.

FAQs

Q: Do I have to list every domain used by users at our site?

A: Not usually. At least one master domain should be defined, so that you can define clari-range inside it. You can use clari-range to list IP address ranges rather than domains. In general, since your news server serves up ClariNet news to users, you must have enabled it to provide access only to customers and bar access to users not licenced for ClariNet. The same method you used there, be it a few domains or an IP address range, will work for us. If you've really put 1000 domains into your news server, we may need to work out a way to reliably export your list of internal domains. Contact us.

Q: How often will you fetch the data?

A: Usually once a day. We don't, unfortunately, pay attention to the time-to-live (TTL) fields on the records, though we might in future. We preserve data if your site is unreachable, however, so in effect it never expires until updated or you are removed from our customer records :-(. If a fetch failes, we'll try to refetch after an hour. You can ask us to manually reload your data.

Q: Is it legal to use DNS for this?

A: Sure. If anybody tries to use one of these made-up domains they will get back a strange answer but there is no reason for any other program to try to fetch such a domain. DNS provides a nice way for you to store data on your system about you that we can fetch reliably, which always works through firewalls etc. Plus since you usually update your DNS entries when adding more IP addresses, it puts all this info in one place.

Q: What if my info gets out of date?

A: We hope you'll put in comments to remind people who take over any of your duties how to keep the data up to date. However, if it does get inaccurate, the users whose domains or IP addresses you have not registered will get access denied messages when they try to fetch things from our systems. They'll then send a note to you to update the records, after which they won't get access denied, so it should be self regulating.

Summary of what your status might be

For most sites we already have a master domain, either guessed from information provided by you, known by us or provided explicitly by your site.
If your master domain is only guessed, and the guess is wrong, your users won't get recognized by our web site.
If your domain name is only guessed, but is right, your users will get recognized by our web site but not get access to restricted data and services on our web site. Be sure to confirm your domain name with us.
If your domain name is authenticated by you, either by telling us or through a DNS entry, your users will get recongized by our site and be granted access to any customer-only data offered to them. There is no such data up as yet but it is planned.