| Local Disk Files on a Server Machine | ||
|---|---|---|
 | Chapter 3. Administering Server Machines |  |
| Local Disk Files on a Server Machine | ||
|---|---|---|
| | Chapter 3. Administering Server Machines | |
Several types of files must reside in the subdirectories of the /usr/afs directory on an AFS server machine's local disk. They include binaries, configuration files, the administrative database files (on database server machines), log files, and volume header files.
Note for Windows users: Some files described in this document possibly do not exist on machines that run a Windows operating system. Also, Windows uses a backslash (\) rather than a forward slash (/) to separate the elements in a pathname.
The /usr/afs/bin directory stores the AFS server process and command suite binaries appropriate for the machine's system (CPU and operating system) type. If a process has both a server portion and a client portion (as with the Update Server) or if it has separate components (as with the fs process), each component resides in a separate file.
To ensure predictable system performance, all file server machines must run the same AFS build version of a given process. To maintain consistency easily, use the Update Server process to distribute binaries from a binary distribution machine of each system type, as described further in Binary Distribution Machines.
It is best to keep the binaries for all processes in the /usr/afs/bin directory, even if you do not run the process actively on the machine. It simplifies the process of reconfiguring machines (for example, adding database server functionality to an existing file server machine). Similarly, it is best to keep the command suite binaries in the directory, even if you do not often issue commands while working on the server machine. It enables you to issue commands during recovery from server and machine outages.
The following lists the binary files in the /usr/afs/bin directory that are directly related to the AFS server processes or command suites. Other binaries (for example, for the klog command) sometimes appear in this directory on a particular file server machine's disk or in an AFS distribution.
The command suite for the AFS Backup System (the binary for the Backup Server is buserver).
The command suite for communicating with the Basic OverSeer (BOS) Server (the binary for the BOS Server is bosserver).
The binary for the Basic OverSeer (BOS) Server process.
The binary for the Backup Server process.
The binary for the File Server component of the fs process.
The command suite for communicating with the Authentication Server (the binary for the Authentication Server is kaserver).
The binary for the Authentication Server process.
The command suite for communicating with the Protection Server process (the binary for the Protection Server is ptserver).
The binary for the Protection Server process.
The binary for the Salvager component of the fs process.
The binary for a program that reports the status of AFS's distributed database technology, Ubik.
The binary for the client portion of the Update Server process.
The binary for the server portion of the Update Server process.
The binary for the Volume Location (VL) Server process.
The binary for the Volume Server component of the fs process.
The command suite for communicating with the Volume and VL Server processes (the binaries for the servers are volserver and vlserver, respectively).
The directory /usr/afs/etc on every file server machine's local disk contains configuration files in ASCII and machine-independent binary format. For predictable AFS performance throughout a cell, all server machines must have the same version of each configuration file:
Cells conventionally use the Update Server to distribute a common version of each file from the cell's system control machine to other server machines (for more on the system control machine, see The System Control Machine). Run the Update Server's server portion on the system control machine, and the client portion on all other server machines. Update the files on the system control machine only, except as directed by instructions for dealing with emergencies.
Never directly edit any of the files in the /usr/afs/etc directory, except as directed by instructions for dealing with emergencies. In normal circumstances, use the appropriate bos commands to change the files. The following list includes pointers to instructions.
The files in this directory include:
An ASCII file that names the cell's database server machines, which run the Authentication, Backup, Protection, and VL Server processes. You create the initial version of this file by issuing the bos setcellname command while installing your cell's first server machine. It is very important to update this file when you change the identity of your cell's database server machines.
The server CellServDB file is not the same as the CellServDB file stored in the /usr/vice/etc directory on client machines. The client version lists the database server machines for every AFS cell that you choose to make accessible from the client machine. The server CellServDB file lists only the local cell's database server machines, because server processes never contact processes in other cells.
For instructions on maintaining this file, see Maintaining the Server CellServDB File.
A machine-independent, binary-format file that lists the server encryption keys the AFS server processes use to encrypt and decrypt tickets. The information in this file is the basis for secure communication in the cell, and so is extremely sensitive. The file is specially protected so that only privileged users can read or change it.
For instructions on maintaining this file, see Managing Server Encryption Keys.
An ASCII file that consists of a single line defining the complete Internet domain-style name of the cell (such
as example.com). You create this file with the bos
setcellname command during the installation of your cell's first file server machine, as instructed in the
OpenAFS Quick Beginnings.
Note that changing this file is only one step in changing your cell's name. For discussion, see Choosing a Cell Name.
An ASCII file that lists the usernames of the system administrators authorized to issue privileged bos, vos, and backup commands. For instructions on maintaining the file, see Administering the UserList File.
The directory /usr/afs/local contains configuration files that are different for each file server machine in a cell. Thus, they are not updated automatically from a central source like the files in /usr/afs/bin and /usr/afs/etc directories. The most important file is the BosConfig file; it defines which server processes are to run on that machine.
As with the common configuration files in /usr/afs/etc, you must not edit these files directly. Use commands from the bos command suite where appropriate; some files never need to be altered.
The files in this directory include the following:
This file lists the server processes to run on the server machine, by defining which processes the BOS Server monitors and what it does if the process fails. It also defines the times at which the BOS Server automatically restarts processes for maintenance purposes.
As you create server processes during a file server machine's installation, their entries are defined in this file automatically. The OpenAFS Quick Beginnings outlines the bos commands to use. For a more complete description of the file, and instructions for controlling process status by editing the file with commands from the bos suite, see Monitoring and Controlling Server Processes.
This optional ASCII file lists one or more of the network interface addresses on the server machine. If it exists when the File Server initializes, the File Server uses it as the basis for the list of interfaces that it registers in its Volume Location Database (VLDB) server entry. See Managing Server IP Addresses and VLDB Server Entries.
This optional ASCII file lists one or more network interface addresses. If it exists when the File Server initializes, the File Server removes the specified addresses from the list of interfaces that it registers in its VLDB server entry. See Managing Server IP Addresses and VLDB Server Entries.
This zero-length file instructs all AFS server processes running on the machine not to perform authorization checking. Thus, they perform any action for any user, even anonymous. This very insecure state is useful only in rare instances, mainly during the installation of the machine.
The file is created automatically when you start the initial bosserver process with the -noauth flag, or issue the bos setauth command to turn off authentication requirements. When you use the bos setauth command to turn on authentication, the BOS Server removes this file. For more information, see Managing Authentication and Authorization Requirements.
This zero-length file controls how the BOS Server handles a crash of the File Server component of the fs process. The BOS Server creates this file each time it starts or restarts the fs process. If the file is present when the File Server crashes, then the BOS Server runs the Salvager before restarting the File Server and Volume Server again. When the File Server exits normally, the BOS Server removes the file so that the Salvager does not run.
Do not create or remove this file yourself; the BOS Server does so automatically. If necessary, you can salvage a volume or partition by using the bos salvage command; see Salvaging Volumes.
This file guarantees that only one Salvager process runs on a file server machine at a time (the single process can fork multiple subprocesses to salvage multiple partitions in parallel). As the Salvager initiates (when invoked by the BOS Server or by issue of the bos salvage command), it creates this zero-length file and issues the flock system call on it. It removes the file when it completes the salvage operation. Because the Salvager must lock the file in order to run, only one Salvager can run at a time.
This file records the network interface addresses that the File Server (fileserver process) registers in its VLDB server entry. When the Cache Manager requests volume location information, the Volume Location (VL) Server provides all of the interfaces registered for each server machine that houses the volume. This enables the Cache Manager to make use of multiple addresses when accessing AFS data stored on a multihomed file server machine. For further information, see Managing Server IP Addresses and VLDB Server Entries.
The directory /usr/afs/db contains two types of files pertaining to the four replicated databases in the cell--the Authentication Database, Backup Database, Protection Database, and Volume Location Database (VLDB):
A file that contains each database, with a .DB0 extension.
A log file for each database, with a .DBSYS1 extension. The database server process logs each database operation in this file before performing it. If the operation is interrupted, the process consults this file to learn how to finish it.
Each database server process (Authentication, Backup, Protection, or VL Server) maintains its own database and log files. The database files are in binary format, so you must always access or alter them using commands from the kas suite (for the Authentication Database), backup suite (for the Backup Database), pts suite (for the Protection Database), or vos suite (for the VLDB).
If a cell runs more than one database server machine, each database server process keeps its own copy of its database on its machine's hard disk. However, it is important that all the copies of a given database are the same. To synchronize them, the database server processes call on AFS's distributed database technology, Ubik, as described in Replicating the OpenAFS Administrative Databases.
The files listed here appear in this directory only on database server machines. On non-database server machines, this directory is empty.
The Backup Database file.
The Backup Database log file.
The Authentication Database file.
The Authentication Database log file.
The Protection Database file.
The Protection Database log file.
The Volume Location Database file.
The Volume Location Database log file.
The /usr/afs/logs directory contains log files from various server processes. The files detail interesting events that occur during normal operations. For instance, the Volume Server can record volume moves in the VolserLog file. Events are recorded at completion, so the server processes do not use these files to reconstruct failed operations unlike the ones in the /usr/afs/db directory.
The information in log files can be very useful as you evaluate process failures and other problems. For instance, if you receive a timeout message when you try to access a volume, checking the FileLog file possibly provides an explanation, showing that the File Server was unable to attach the volume. To examine a log file remotely, use the bos getlog command as described in Displaying Server Process Log Files.
This directory also contains the core image files generated if a process being monitored by the BOS Server crashes. The BOS Server attempts to add an extension to the standard core name to indicate which process generated the core file (for example, naming a core file generated by the Protection Server core.ptserver). The BOS Server cannot always assign the correct extension if two processes fail at about the same time, so it is not guaranteed to be correct.
The directory contains the following files:
The Authentication Server's log file.
The Backup Server's log file.
The BOS Server's log file.
The File Server's log file.
The Salvager's log file.
The Volume Location (VL) Server's log file.
The Volume Server's log file.
If present, a core image file produced as an AFS server process on the machine crashed (probably the process named by process).
To prevent log files from growing unmanageably large, restart the server processes periodically, particularly the database server processes. To avoid restarting the processes, use the UNIX rm command to remove the file as the process runs; it re-creates it automatically.
A partition that houses AFS volumes must be mounted at a subdirectory of the machine's root ( / ) directory (not, for instance under the /usr directory). The file server machine's file system registry file (/etc/fstab or equivalent) must correctly map the directory name and the partition's device name. The directory name is of the form /vicepindex, where each index is one or two lowercase letters. By convention, the first AFS partition on a machine is mounted at /vicepa, the second at /vicepb, and so on. If there are more than 26 partitions, continue with /vicepaa, /vicepab and so on. The OpenAFS Release Notes specifies the number of supported partitions per server machine.
Do not store non-AFS files on AFS partitions. The File Server and Volume Server expect to have available all of the space on the partition.
The /vicep directories contain two types of files:
Each such file is a volume header. The vol_ID corresponds to the volume ID number displayed in the output from the vos examine, vos listvldb, and vos listvol commands.
This zero-length file triggers the Salvager to salvage the entire partition. The AFS-modified version of the fsck program creates this file if it discovers corruption.
For most system types, it is important never to run the standard fsck program provided with the operating system on an AFS file server machine. It removes all AFS volume data from server partitions because it does not recognize their format.
| |  | |
| Chapter 3. Administering Server Machines |  | The Four Roles for File Server Machines |