Maintaining Knowledge of Database Server Machines

Maintaining Knowledge of Database Server Machines
	Chapter 10. Administering Client Machines and the Cache Manager

For the users of an AFS client machine to access a cell's AFS filespace and other services, the Cache Manager and other client-side agents must have an accurate list of the cell's database server machines. The affected functions include the following:

Accessing files. The Cache Manager contacts the Volume Location (VL) Server to learn which file server machine houses the volume containing a requested file or directory. If the Cache Manager cannot contact a cell's VL Servers, it cannot fetch files.
Authenticating. The klog program and AFS-modified login utilities contact the Authentication Server to obtain tokens, which the AFS server processes accept as proof that the user is authenticated.
Creating protection groups. The pts command interpreter contacts the Protection Server when users create protection groups or request information from the Protection Database.
Editing access control lists (ACLs). The fs command interpreter contacts the File Server that maintains the read/write volume containing a file or directory; the location information comes from the VL Server.

To enable a machine's users to access a cell, you must list the names and IP addresses of its database server machines in the /usr/vice/etc/CellServDB file on the machine's local disk. In addition to the machine's home cell, you can list any foreign cells that you want to enable users to access. (To enable access to a cell's filespace, you must also mount its root.cell volume in the local AFS filespace; the conventional location is just under the AFS root directory, /afs. For instructions, see the OpenAFS Quick Beginnings.)

How Clients Use the List of Database Server Machines

As the afsd program runs and initializes the Cache Manager, it reads the contents of the CellServDB file into kernel memory. The Cache Manager does not consult the file again until the machine next reboots. In contrast, the command interpreters for the AFS command suites (such as fs and pts) read the CellServDB file each time they need to contact a database server process.

When a cell's list of database server machines changes, you must change both the CellServDB file and the list in kernel memory to preserve consistent client performance; some commands probably fail if the two lists of machines disagree. One possible method for updating both the CellServDB file and kernel memory is to edit the file and reboot the machine. To avoid needing to reboot, you can instead perform both of the following steps:

Issue the fs newcell command to alter the list in kernel memory directly, making the changes available to the Cache Manager.
Edit the CellServDB file to make the changes available to command interpreters. For a description of the file's format, see The Format of the CellServDB file.

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

If there is no entry for a cell, the machine's users cannot access the cell.
If a cell's entry does not include a database server machine, then the Cache Manager and command interpreters never attempt to contact the machine. The omission does not prevent access to the cell--as long as the information about the other database server machines is correct and the server processes, machines, and network are functioning correctly--but it can put an undue burden on the machines that are listed. If all of the listed machines become inaccessible to clients, then the cell becomes inaccessible even if the omitted database server machine is functioning correctly.
If a machine's name or address is incorrect, or the machine is not actually running the database server processes, then requests from clients time out. Users can experience lengthy delays because they have to wait the full timeout period before the Cache Manager or command interpreter contacts another database server machine.

The Format of the CellServDB file

When editing the /usr/vice/etc/CellServDB file, you must use the correct format for cell and machine entries. Each cell has a separate entry. The first line has the following format:

   >cell_name      #organization

where cell_name is the cell's complete Internet domain name (for example, example.com) and organization is an optional field that follows any number of spaces and the number sign (#) and can name the organization to which the cell corresponds (for example, the Example Corporation). After the first line comes a separate line for each database server machine. Each line has the following format:

   IP_address   #machine_name

where IP_address is the machine's IP address in dotted decimal format (for example, 192.12.105.3). Following any number of spaces and the number sign (#) is machine_name, the machine's fully-qualified hostname (for example, db1.example.com). In this case, the number sign does not indicate a comment: machine_name is a required field.

The order in which the cells appear is not important, but it is convenient to put the client machine's home cell first. Do not include any blank lines in the file, not even after the last entry.

The following example shows entries for two cells, each of which has three database server machines:

   >example.com   #Example Corporation (home cell)
   192.12.105.3      #db1.example.com
   192.12.105.4      #db2.example.com
   192.12.105.55     #db3.example.com
   >example.org    #Example Organization cell
   138.255.68.93     #serverA.example.org
   138.255.68.72     #serverB.example.org
   138.255.33.154    #serverC.example.org

Maintaining the Client CellServDB File

Because a correct entry in the CellServDB file is vital for consistent client performance, you must also update the file on each client machine whenever a cell's list of database server machines changes (for instance, when you follow the instructions in the OpenAFS Quick Beginnings to add or remove a database server machine).

Creating a symbolic or hard link from /usr/vice/etc/CellServDB to a central source file in AFS is not a viable option. The afsd program reads the file into kernel memory before the Cache Manager is completely initialized and able to access AFS.

Because every client machine has its own copy of the CellServDB file, you can in theory make the set of accessible cells differ on various machines. In most cases, however, it is best to maintain consistency between the files on all client machines in the cell: differences between machines are particularly confusing if users commonly use a variety of machines rather than just one.

The AFS Product Support group maintains a central CellServDB file that includes all cells that have agreed to make their database server machines access to other AFS cells. It is advisable to check this file periodically for updated information. See Making Your Cell Visible to Others.

An entry in the local CellServDB is one of the two requirements for accessing a cell. The other is that the cell's root.cell volume is mounted in the local filespace, by convention as a subdirectory of the /afs directory. For instructions, see To create a cellular mount point.

Note

The /usr/vice/etc/CellServDB file on a client machine is not the same as the /usr/afs/etc/CellServDB file on the local disk of a file server machine. The server version lists only the database server machines in the server machine's home cell, because server processes never need to contact foreign cells. It is important to update both types of CellServDB file on all machines in the cell whenever there is a change to your cell's database server machines. For more information about maintaining the server version of the CellServDB file, see Maintaining the Server CellServDB File.

To display the /usr/vice/etc/CellServDB file

Use a text editor or the cat command to display the contents of the /usr/vice/etc/CellServDB file. By default, the mode bits on the file permit anyone to read it.
```
   % cat /usr/vice/etc/CellServDB
```

To display the list of database server machines in kernel memory

Issue the fs listcells command.
```
   % fs listcells [&] 
```
where listc is the shortest acceptable abbreviation of listcells.
To have your shell prompt return immediately, include the ampersand (&), which makes the command run in the background. It can take a while to generate the complete output because the kernel stores database server machines' IP addresses only, and the fs command interpreter has the cell's name resolution service (such as the Domain Name Service or a local host table) translate them into hostnames. You can halt the command at any time by issuing an interrupt signal such as Ctrl-c.
The output includes a single line for each cell, in the following format:
```
   Cell cell_name on hosts list_of_hostnames.
```
The name service sometimes returns hostnames in uppercase letters, and if it cannot resolve a name at all, it returns its IP address. The following example illustrates all three possibilities:
```
   % fs listcells
      .
      .
   Cell example.com on hosts db1.example.com db2.example.com db3.example.com
   Cell example.org on hosts SERVERA.EXAMPLE.ORG SERVERB.EXAMPLE.ORG 
                            SERVERC.EXAMPLE.ORG
   Cell example.net on hosts 191.255.64.111 191.255.64.112
      .
      .
```

To change the list of a cell's database server machines in kernel memory

Become the local superuser root on the machine, if you are not already, by issuing the su command.
```
   % su root
   Password: <root_password>
```
If you a use a central copy of the CellServDB file as a source for client machines, verify that its directory's ACL grants you the l (lookup), r (read), and w (write) permissions. The conventional directory is /afs/cell_name/common/etc. If necessary, issue the fs listacl command, which is fully described in Displaying ACLs.
```
   # fs listacl [<dir/file path>]
```
Issue the fs newcell command to add or change a cell's entry in kernel memory. Repeat the command for each cell.
Note
You cannot use this command to remove a cell's entry completely from kernel memory. In the rare cases when you urgently need to prevent access to a specific cell, you must edit the CellServDB file and reboot the machine.
```
   # fs newcell <cell name> <primary servers>+ \
                [-linkedcell <linked cell name>]
```
where
n
Is the shortest acceptable abbreviation of newcell.
cell name
Specifies the complete Internet domain name of the cell for which to record a new list of database server machines.
primary servers
Specifies the fully-qualified hostname or IP address in dotted-decimal format for each database server machine in the cell. The list you provide completely replaces the existing list.
-linkedcell
Specifies the complete Internet domain name of the AFS cell to link to a DCE cell for the purposes of DFS fileset location. You can use this argument if the machine's AFS users access DFS via the AFS/DFS Migration Toolkit Protocol Translator. For instructions, see the OpenAFS/DFS Migration Toolkit Administration Guide and Reference.
Add or edit the cell's entry in the local /usr/vice/etc/CellServDB file, using one of the following three methods. In each case, be sure to obey the formatting requirements described in The Format of the CellServDB file.
- If you maintain a central source CellServDB file, first use a text editor to alter the central copy of the file. Then use a copying command such as the cp command to copy it to the local /usr/vice/etc/CellServDB file.
- If you do not use a central source CellServDB file, edit the local machine's /usr/vice/etc/CellServDB file directly.


Setting Other Cache Parameters with the afsd program		Determining if a Client Can Run Setuid Programs