Installing Database Server Functionality

This section explains how to install database server functionality. Database server machines have two defining characteristics. First, they run the Protection Server, and Volume Location (VL) Server processes. They also run the Backup Server if the cell uses the AFS Backup System, as is assumed in these instructions. Second, they appear in the CellServDB file of every machine in the cell (and of client machines in foreign cells, if they are to access files in this cell).

Note the following requirements for database server machines.

Summary of Procedures

To install a database server machine, perform the following procedures.

  1. Install the bos suite of commands locally, as a precaution

  2. Add the new machine to the /usr/afs/etc/CellServDB file on existing file server machines

  3. Update your cell's central CellServDB source file and the file you make available to foreign cells

  4. Update every client machine's /usr/vice/etc/CellServDB file and kernel memory list of database server machines

  5. Start the database server processes (Backup Server, Protection Server, and Volume Location Server)

  6. Restart the database server processes on every database server machine

  7. If required, request that grand.central.org add details of your new database server machine to the global CellServDB

  8. If required, add details of your new database server to the AFS database location records in your site's DNS

Instructions

Note

It is assumed that your PATH environment variable includes the directory that houses the AFS command binaries. If not, you possibly need to precede the command names with the appropriate pathname.

  1. You can perform the following instructions on either a server or client machine. Login as an AFS administrator who is listed in the /usr/afs/etc/UserList file on all server machines.

     
       % kinit admin_user
       Password: admin_password
       % aklog
    

  2. If you are working on a client machine configured in the conventional manner, the bos command suite resides in the /usr/afsws/bin directory, a symbolic link to an AFS directory. An error during installation can potentially block access to AFS, in which case it is helpful to have a copy of the bos binary on the local disk. This step is not necessary if you are working on a server machine, where the binary resides in the local /usr/afs/bin directory.

       % cp  /usr/afsws/bin/bos   /tmp
    

  3. Issue the bos addhost command to add the new database server machine to the /usr/afs/etc/CellServDB file on existing server machines (as well as the new database server machine itself).

    Substitute the new database server machine's fully-qualified hostname for the host name argument. If you run a system control machine, substitute its fully-qualified hostname for the machine name argument. If you do not run a system control machine, repeat the bos addhost command once for each server machine in your cell (including the new database server machine itself), by substituting each one's fully-qualified hostname for the machine name argument in turn.

       % bos addhost <machine name>  <host name>   
    

    If you run a system control machine, wait for the Update Server to distribute the new CellServDB file, which takes up to five minutes by default. If you are issuing individual bos addhost commands, attempt to issue all of them within five minutes.

    Note

    It is best to maintain a one-to-one mapping between hostnames and IP addresses on a multihomed database server machine (the conventional configuration for any AFS machine). The BOS Server uses the gethostbyname( ) routine to obtain the IP address associated with the host name argument. If there is more than one address, the BOS Server records in the CellServDB entry the one that appears first in the list of addresses returned by the routine. The routine possibly returns addresses in a different order on different machines, which can create inconsistency.

  4. (Optional) Issue the bos listhosts command on each server machine to verify that the new database server machine appears in its CellServDB file.

       % bos listhosts <machine name>
    
  5. Add the new database server machine to your cell's central CellServDB source file, if you use one. The standard location is /afs/cellname/common/etc/CellServDB.

    If you are willing to make your cell accessible to users in foreign cells, add the new database server machine to the file that lists your cell's database server machines. The conventional location is /afs/cellname/service/etc/CellServDB.local.

  6. If this machine's IP address is lower than any existing database server machine's, update every client machine's /usr/vice/etc/CellServDB file and kernel memory list to include this machine. (If this machine's IP address is not the lowest, it is acceptable to wait until Step 12.)

    There are several ways to update the CellServDB file on client machines, as detailed in the chapter of the OpenAFS Administration Guide about administering client machines. One option is to copy over the central update source (which you updated in Step 5). To update the machine's kernel memory list, you can either reboot after changing the CellServDB file or issue the fs newcell command.

  7. If you are running a cell which still relies upon kaserver see Starting the Authentication Service for an additional installation step.

  8. Start the Backup Server (the buserver process). You must perform other configuration procedures before actually using the AFS Backup System, as detailed in the OpenAFS Administration Guide.

       % bos create <machine name> buserver simple /usr/afs/bin/buserver
    

  9. Start the Protection Server (the ptserver process).

       % bos create <machine name> ptserver simple /usr/afs/bin/ptserver
    

  10. Start the Volume Location (VL) Server (the vlserver process).

       % bos create <machine name> vlserver simple /usr/afs/bin/vlserver
    

  11. Issue the bos restart command on every database server machine in the cell, including the new machine. The command restarts the Authentication, Backup, Protection, and VL Servers, which forces an election of a new Ubik coordinator for each process. The new machine votes in the election and is considered as a potential new coordinator.

    A cell-wide service outage is possible during the election of a new coordinator for the VL Server, but it normally lasts less than five minutes. Such an outage is particularly likely if you are installing your cell's second database server machine. Messages tracing the progress of the election appear on the console.

    Repeat this command on each of your cell's database server machines in quick succession. Begin with the machine with the lowest IP address.

       %  bos restart <machine name> kaserver buserver ptserver vlserver    
    

    If an error occurs, restart all server processes on the database server machines again by using one of the following methods:

    • Issue the bos restart command with the -bosserver flag for each database server machine

    • Reboot each database server machine, either using the bos exec command or at its console

  12. If you did not update the CellServDB file on client machines in Step 6, do so now.

  13. If you wish to participate in the AFS global name space, send the new database server machine's name and IP address to grand.central.org. Do so, by emailing an updated CellServDB fragment for your cell to cellservdb@grand.central.org

    More details on the registration procedures for the CellServDB maintained by grand.central.org are available from http://grand.central.org/csdb.html