Installing Database Server Functionality

Installing Database Server Functionality
	Chapter 3. Installing Additional Server Machines

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.

In the conventional configuration, database server machines also serve as file server machines (run the File Server, Volume Server and Salvager processes). If you choose not to run file server functionality on a database server machine, then the kernel does not have to incorporate AFS modifications, but the local /usr/afs directory must house most of the standard files and subdirectories. In particular, the /usr/afs/etc/KeyFile file must contain the same keys as all other server machines in the cell. If you run a system control machine, run the upclientetc process on every database server machine other than the system control machine; if you do not run a system control machine, use the bos addkey command as instructed in the chapter in the OpenAFS Administration Guide about maintaining server encryption keys.
The instructions in this section assume that the machine on which you are installing database server functionality is already a file server machine. Contact the OpenAFS mailing list to learn how to install database server functionality on a non-file server machine.
During the installation of database server functionality, you must restart all of the database server machines to force the election of a new Ubik coordinator (synchronization site) for each database server process. This can cause a system outage, which usually lasts less than 5 minutes.
Updating the kernel memory list of database server machines on each client machine is generally the most time-consuming part of installing a new database server machine. It is, however, crucial for correct functioning in your cell. Incorrect knowledge of your cell's database server machines can prevent your users from authenticating, accessing files, and issuing AFS commands.
You update a client's kernel memory list by changing the /usr/vice/etc/CellServDB file and then either rebooting or issuing the fs newcell command. For instructions, see the chapter in the OpenAFS Administration Guide about administering client machines.
The point at which you update your clients' knowledge of database server machines depends on which of the database server machines has the lowest IP address. The following instructions indicate the appropriate place to update your client machines in either case.
- If the new database server machine has a lower IP address than any existing database server machine, update the CellServDB file on every client machine before restarting the database server processes. If you do not, users can become unable to update (write to) any of the AFS databases. This is because the machine with the lowest IP address is usually elected as the Ubik coordinator, and only the Coordinator accepts database writes. On client machines that do not have the new list of database server machines, the Cache Manager cannot locate the new coordinator. (Be aware that if clients contact the new coordinator before it is actually in service, they experience a timeout before contacting another database server machine. This is a minor, and temporary, problem compared to being unable to write to the database.)
- If the new database server machine does not have the lowest IP address of any database server machine, then it is better to update clients after restarting the database server processes. Client machines do not start using the new database server machine until you update their kernel memory list, but that does not usually cause timeouts or update problems (because the new machine is not likely to become the coordinator).

Summary of Procedures

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

Install the bos suite of commands locally, as a precaution
Add the new machine to the /usr/afs/etc/CellServDB file on existing file server machines
Update your cell's central CellServDB source file and the file you make available to foreign cells
Update every client machine's /usr/vice/etc/CellServDB file and kernel memory list of database server machines
Start the database server processes (Backup Server, Protection Server, and Volume Location Server)
Restart the database server processes on every database server machine
If required, request that grand.central.org add details of your new database server machine to the global CellServDB
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.

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
```
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
```
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.
(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>
```
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.
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.
If you are running a cell which still relies upon kaserver see Starting the Authentication Service for an additional installation step.
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
```

Start the Protection Server (the ptserver process).

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

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

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

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
If you did not update the CellServDB file on client machines in Step 6, do so now.
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


Chapter 3. Installing Additional Server Machines		Removing Database Server Functionality