Maintaining the Server CellServDB File

Every file server machine maintains a list of its home cell's database server machines in the local disk file /usr/afs/etc/CellServDB on its local disk. Both database server processes and non-database server processes consult the file:

The consequences of missing or incorrect information in the CellServDB file are as follows:

Note that the /usr/afs/etc/CellServDB file on a server machine is not the same as the /usr/vice/etc/CellServDB file on client machine. The client version includes entries for foreign cells as well as the local cell. However, it is important to update both versions of the file whenever you change your cell's database server machines. A server machine that is also a client needs to have both files, and you need to update them both. For more information on maintaining the client version of the CellServDB file, see Maintaining Knowledge of Database Server Machines.

Distributing the Server CellServDB File

To avoid the negative consequences of incorrect information in the /usr/afs/etc/CellServDB file, you must update it on all of your cell's server machines every time you add or remove a database server machine. The OpenAFS Quick Beginnings provides complete instructions for installing or removing a database server machine and for updating the CellServDB file in that context. This section explains how to distribute the file to your server machines and how to make other cells aware of the changes if you participate in the AFS global name space.

If you use the Update Server to distribute the central copy of the server CellServDB file stored on the cell's system control machine. For instructions on configuring the Update Server, see the OpenAFS Quick Beginnings.

To avoid formatting errors that can cause errors, always use the bos addhost and bos removehost commands, rather than editing the file directly. You must also restart the database server processes running on the machine, to initiate a coordinator election among the new set of database server machines. This step is included in the instructions that appear in To add a database server machine to the CellServDB file and To remove a database server machine from the CellServDB file. For instructions on displaying the contents of the file, see To display a cell's database server machines.

If you make your cell accessible to foreign users as part of the AFS global name space, you also need to inform other cells when you change your cell's database server machines. The AFS Support group maintains a CellServDB file that lists all cells that participate in the AFS global name space, and can change your cell's entry at your request. For further details, see Making Your Cell Visible to Others.

Another way to advertise your cell's database server machines is to maintain a copy of the file at the conventional location in your AFS filespace, /afs/cellname/service/etc/CellServDB.local. For further discussion, see The Third Level.

To display a cell's database server machines

  1. Issue the bos listhosts command. If you have maintained the file properly, the output is the same on every server machine, but the machine name argument enables you to check various machines if you wish.

       % bos listhosts <machine name> [<cell name>]
    

    where

    listh

    Is the shortest acceptable abbreviation of listhosts.

    machine name

    Specifies the server machine from which to display the /usr/afs/etc/CellServDB file.

    cell name

    Specifies the complete Internet domain name of a foreign cell. You must already know the name of at least one server machine in the cell, to provide as the machine name argument.

The output lists the machines in the order they appear in the CellServDB file on the specified server machine. It assigns each one a Host index number, as in the following example. There is no implied relationship between the index and a machine's IP address, name, or role as Ubik coordinator or secondary site.

   % bos listhosts fs1.example.com
   Cell name is example.com
       Host 1 is fs1.example.com
       Host 2 is fs7.example.com
       Host 3 is fs4.example.com

The output lists machines by name rather than IP address as long as the naming service (such as the Domain Name Service or local host table) is functioning properly. To display IP addresses, login to a server machine as the local superuser root and use a text editor or display command, such as the cat command, to view the /usr/afs/etc/CellServDB file.

To add a database server machine to the CellServDB file

  1. Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

       % bos listusers <machine name>
    
  2. Issue the bos addhost command to add each new database server machine to the CellServDB file. Specify the system control machine as machine name. (If you have forgotten which machine is the system control machine, see The Output on the System Control Machine.)

       % bos addhost  <machine name>  <host name>+
    

    where

    addh

    Is the shortest acceptable abbreviation of addhost.

    machine name

    Names the system control machine

    host name

    Specifies the fully qualified hostname of each database server machine to add to the CellServDB file (for example: fs4.example.com). The BOS Server uses the gethostbyname() routine to obtain each machine's IP address and records both the name and address automatically.

  3. Restart the Authentication Server, Backup Server, Protection Server, and VL Server on every database server machine, so that the new set of machines participate in the election of a new Ubik coordinator. The instruction uses the conventional names for the processes; make the appropriate substitution if you use different process names. For complete syntax, see Stopping and Immediately Restarting Processes.

    Important: Repeat the following command in quick succession on all of the database server machines.

       % bos restart <machine name> buserver kaserver ptserver vlserver
    
  4. Edit the /usr/vice/etc/CellServDB file on each of your cell's client machines. For instructions, see Maintaining Knowledge of Database Server Machines.

  5. If you participate in the AFS global name space, please have one of your cell's designated site contacts register the changes you have made with the AFS Product Support group.

    If you maintain a central copy of your cell's server CellServDB file in the conventional location (/afs/cellname/service/etc/CellServDB.local), edit the file to reflect the change.

To remove a database server machine from the CellServDB file

  1. Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

       % bos listusers <machine name>
    
  2. Issue the bos removehost command to remove each database server machine from the CellServDB file. Specify the system control machine as machine name. (If you have forgotten which machine is the system control machine, see The Output on the System Control Machine.)

       % bos removehost <machine name>  <host name>+
    

    where

    removeh

    Is the shortest acceptable abbreviation of removehost.

    machine name

    Names the system control machine.

    host name

    Specifies the fully qualified hostname of each database server machine to remove from the CellServDB file (for example: fs4.example.com).

  3. Restart the Authentication Server, Backup Server, Protection Server, and VL Server on every database server machine, so that the new set of machines participate in the election of a new Ubik coordinator. The instruction uses the conventional names for the processes; make the appropriate substitution if you use different process names. For complete syntax, see Stopping and Immediately Restarting Processes.

    Important: Repeat the following command in quick succession on all of the database server machines.

       % bos restart <machine name> buserver kaserver ptserver vlserver
    
  4. Edit the /usr/vice/etc/CellServDB file on each of your cell's client machines. For instructions, see Maintaining Knowledge of Database Server Machines.

  5. If you participate in the AFS global name space, please have one of your cell's designated site contacts register the changes you have made with the AFS Product Support group.

    If you maintain a central copy of your cell's server CellServDB file in the conventional location (/afs/cellname/service/etc/CellServDB.local), edit the file to reflect the change.