UPGRADING FROM PREVIOUS (1.0) VERSIONS OF RWHOISD

In version 1.5.0(Bx) of the RWhois server (rwhoisd), no attempt at
complete backwards compatibility with previous versions was attempted.
This document is an attempt to outline and explain the issues involved
with upgrading the server installation from one of those previous
installations to this version.  This document does not intend to
address the differences in the RWhois protocol between Version 1.5 and
1.0.  In general, it is assumed that the previous version is 1.0B9,
although the same arguments apply for earlier versions.

A. Summary of Upgrade Procedure

   1. Start with provided (1.5) main configuration files (rwhois.*)
      and edit them to suit.
   2. Create appropriate authority area directories by copying the
      sample data authority areas and editing the data files to suit.
   3. Take old data, split into separate authority areas, if
      necessary, and rewrite into new format.

B. The Main Configuration Files

   The main configuration files look similar to those in previous
   releases, however there are some fundamental differences.  It is
   probably easier to start fresh, using the supplied sample data as a
   starting point rather than editing the old configuration files.

   1. rwhois.conf (the main config file)
      a. 'default-dir' is now called 'root-dir'.
      b. 'object-file' or 'schema-file' (they referred to the same
         thing) are now gone.  The equivalent file is stored as part of
         the authority area (see the next section).
      c. 'display-file' is gone.
      e. 'directive-file' refers to a different file.  This is now
         called 'x-directive-file'.  The 'directive-file' is a file
         indicating which of the built-in directives are enabled or
         disabled.
      f. 'update-prog' and 'index-prog' are now gone.  This
         functionality is included in the server itself.
      g. 'verbosity' is renumbered and probably more useful.  It
         ranges from 0 (no logging) to 8 (log everything).  The numbers
         correspond to the eight syslog log levels.
      h. 'root-file' has been renamed to 'punt-file'.  It refers to the
         same thing: a referral to the next level up (which is called a
         "punt").
      i. 'auth-area-file'.  This file controls the authority areas
         for which the server is responsible.  It fulfills roughly the 
         same role as BIND's "named.boot" file.  See the operations guide
         for more details.
      j. 'pid-file' and 'server-contact' were added.
      k. A number of other, optional parameters were added; see the
         operations guide for further information.

   2. rwhois.allow/rwhois.deny. These have not changed.

   3. rwhois.directive. This file has changed altogether.  See the
      operations guide for details.

   4. rwhois.x.dir. This is mostly the same as the old
      'rwhois.directive' file.

   5. rwhois.objects. This data as been moved into the authority area
      data.

   6. rwhois.help. No longer needed.

   7. rwhois.define. No longer used.

   8. rwhois.display. No longer used.

   9. rwhois.root. The reference for this in the main config file has
      changed, and the format of the data itself has changed.  See the
      operations guide for details.

C. Authority Areas

   The fundamental difference between the older versions of the server
   and this one is the concept of authority areas.  In the old server,
   the authority area concept was only partially implemented and never
   enforced.  In this server, authority areas have a much stonger
   implementation.

   1. Authority areas contain database schemas.

      Each authority area (which currently can be a domain name or IP
      network) has its own, separate database schema.  This is
      primarily to facilitate using one server for many different
      tasks, each needing its own schema.  It is also to facilitate
      the creation of secondary servers.

      To this end, the following information is now local to an
      authority area.

      a. the database schema.  The old servers 'rwhois.objects' file
         has been moved into the authority area as the 'schema-file'
         tag in the 'rwhois.auth_area' file.  The schema file, in turn,
         points to a series of attribute templates, which are very
         similar to the old attribute templates, which the deletion and
         addition of a few tags (see the operations guide).

      b. The SOA data.  This resides in its own file.

      c. The data that logically belongs in a particular authority area.

   2. Authority areas are a namespace.

      Each authority area defines a namespace for query routing purposes.
      These authority areas typically correspond to DNS zones.  For
      instance, if you are responsible for the DNS zone
      "provider.net", you would probably have an authority area named
      "provider.net".  Also, if you were responsible for the
      10.1.1.0/18 network, then you would probably have an authority
      area named "10.1.1.0/18".

D. The Data Files

   Both the data file format, the data requirements, and the data file
   placement changed for this release.

   The data file format has change from a
   <object-type>:<attribute-name>:<value> triplet to a simpler
   <attribute-name>:<value> format.

   The RWhois 1.5 protocol also imposes a few new data requirements in
   that now all objects must contain certain attributes: the RWhois
   'base class'.

   1. The 'Object-Type' attribute is now 'Class-Name'

   2. All objects require an 'ID' attribute, which is an authority-area-
      unique local part suffixed with a period and the authority area
      name.  The local part cannot contain a period.  At the root, the
      local part consists of the NIC handle but can be anything, as
      long as it is unique.

   3. All objects require an Auth-Area attribute.

   4. Objects that reference other rwhois object have attributes that
      are of type 'ID' and should just contain the ID of the referred-to
      object as the value.

   5. See-Also type attributes should have Uniform Resouce Locators (URLs)
      as values.

   The RWhois data also needs to be split into the different authority
   areas.  Data needs to be in the right authority area so query
   routing works correctly.  In general, data is split by examining
   any attribute that has a heirarchical value and finding the
   appropriate authority area.

   For example, if you are running a server with two domain authority
   areas 'a.com' and 'b.com', you would split classes like this:
	
   For contact objects, examine the email address:

   email:joe@a.com -> a.com
   email:bill@b.com -> b.com
   email:bob@ffo.a.com -> a.com
   email:jill@roto.bbr.b.com -> b.com

   For domain objects, examine the domain name:

   domain: ffo.a.com -> a.com
   domain: bbr.b.com -> b.com

   For host objects, use the host name:

   host-name: ns.a.com -> a.com
   host-name: ns.b.com -> b.com