STABLE14-man-page-cellservdb-extras-20090605

LICENSE IPL10

Document linked cells and non-voting replicas in the CellServDB man page
and note the need for better linked cell documentation.

(cherry picked from commit 6d973e499acd598bbc3a4e131d14f9801b94fe71)

diff --git a/doc/man-pages/README b/doc/man-pages/README
index c537a491e571c468793d5a9b211a4b4729c8e437..11682eea657d82c3ee5797e7934fd8195edd3130 100644 (file)
--- a/doc/man-pages/README
+++ b/doc/man-pages/README
@@ -271,6 +271,10 @@ Known Problems
      kaserver (and possibly without fakeka), and deprecation warnings
      on the .krb varient commands.
 
+   * Linked cells are currently documented in fs newcell as being only
+     for DCE, which is not correct.  That documentation, aklog, and the
+     CellServDB documentation needs to be updated.
+
    * We need a way to add links to other man pages (kinit most notably)
      without creating dangling links in the HTML output.  This probably
      means that the HTML conversion script needs to generate at startup

diff --git a/doc/man-pages/pod5/CellServDB.pod b/doc/man-pages/pod5/CellServDB.pod
index da4c6648af410bd8ee8253a308cf4d6094e391a6..3fa9ecf76f4a1dd0be06ac6f1794282d6d38e7c6 100644 (file)
--- a/doc/man-pages/pod5/CellServDB.pod
+++ b/doc/man-pages/pod5/CellServDB.pod
@@ -8,7 +8,8 @@ There are two versions of the F<CellServDB> file, both of which have the
 same format.  One version is used by an AFS client and lists all of the
 database server machines in the local cell and any foreign cell that is to
 be accessible from the local client machine.  The other version is used on
-servers and lists only the database servers in the local cell.
+servers and need list only the database servers in the local cell; in some
+configurations it can be a link to the same file the client uses.
 
 =head2 Client CellServDB
 
@@ -94,7 +95,11 @@ setcellname> command during the installation of the cell's server machine,
 which is automatically recorded as the cell's first database server
 machine. When adding or removing database server machines, be sure to
 update this file appropriately. It must reside in the F</usr/afs/etc>
-directory on each AFS server machine.
+directory on each AFS server machine. The database server processes,
+in addition to the usual configuration allowing each to be elected
+synchronization site and coordinate updates, can be set up as readonly
+database clone servers. Such servers can never be elected as the
+synchronization site.
 
 The database server processes consult the F<CellServDB> file to learn
 about their peers, with which they must maintain constant connections in
@@ -129,7 +134,9 @@ F</usr/afs/etc> directory, it is customary to edit only the copy of the
 file stored on the system control machine. Otherwise, edit the file on
 each server machine individually. For instructions on adding and removing
 database server machine, see the I<OpenAFS Quick Start> chapter on
-installing additional server machines.
+installing additional server machines. Updates to the server F<CellServDB>
+will trigger reloading the cell server configurations automatically in the
+AFS server processes.
 
 =head2 CellServDB Format
 
@@ -141,9 +148,11 @@ Both F<CellServDB> files have the same format:
 
 The first line begins at the left margin with the greater-than character
 (C<< > >>), followed immediately by the cell's name without an intervening
-space. Optionally, a comment can follow any number of spaces and a number
-sign (C<#>), perhaps to identify the organization associated with the
-cell.
+space. Optionally, a comment can follow any number of spaces and a octothorpe
+(C<#>), perhaps to identify the organization associated with the
+cell. A variant of this allows the defintion of a linked cell: after the 
+leading (C<< > >>) and cell name, a space and a second cell name may be
+listed before the optional spaces, octothorpe and comment.
 
 =item *
 
@@ -154,7 +163,8 @@ server machines, with the indicated information in order:
 
 =item *
 
-The database server machine's IP address in dotted-decimal format.
+The database server machine's IP address in dotted-decimal format, optionally
+enclosed in square braces (C<< [ >>)(C<< ] >>) to define a non-voting clone.
 
 =item *
 
@@ -162,7 +172,7 @@ One or more spaces.
 
 =item *
 
-A number sign (#), followed by the machine's fully qualified hostname
+An octothorpe (#), followed by the machine's fully qualified hostname
 without an intervening space. This number sign does not indicate that the
 hostname is a comment. It is a required field.
 
@@ -190,8 +200,8 @@ F<CellServDB> file and illustrates the required format.
    >abc.com        # ABC Corporation
    192.12.105.2                #db1.abc.com
    192.12.105.3                #db2.abc.com
-   192.12.107.3                #db3.abc.com
-   >test.abc.com   # ABC Corporation Test Cell
+   [192.12.107.3]       #db3.abc.com
+   >test.abc.com abc.com   # ABC Corporation Test Cell
    192.12.108.57        #testdb1.abc.com
    192.12.108.55        #testdb2.abc.com