Local Disk Files on a Server Machine

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.

Binaries in the /usr/afs/bin Directory

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.

backup

The command suite for the AFS Backup System (the binary for the Backup Server is buserver).

bos

The command suite for communicating with the Basic OverSeer (BOS) Server (the binary for the BOS Server is bosserver).

bosserver

The binary for the Basic OverSeer (BOS) Server process.

buserver

The binary for the Backup Server process.

fileserver

The binary for the File Server component of the fs process.

kas

The command suite for communicating with the Authentication Server (the binary for the Authentication Server is kaserver).

kaserver

The binary for the Authentication Server process.

ntpd

The binary for the Network Time Protocol Daemon (NTPD). AFS redistributes this binary and uses the runntp program to configure and initialize the NTPD process.

ntpdc

A debugging utility furnished with the ntpd program.

pts

The command suite for communicating with the Protection Server process (the binary for the Protection Server is ptserver).

ptserver

The binary for the Protection Server process.

runntp

The binary for the program used to configure NTPD most appropriately for use with AFS.

salvager

The binary for the Salvager component of the fs process.

udebug

The binary for a program that reports the status of AFS's distributed database technology, Ubik.

upclient

The binary for the client portion of the Update Server process.

upserver

The binary for the server portion of the Update Server process.

vlserver

The binary for the Volume Location (VL) Server process.

volserver

The binary for the Volume Server component of the fs process.

vos

The command suite for communicating with the Volume and VL Server processes (the binaries for the servers are volserver and vlserver, respectively).

Common Configuration Files in the /usr/afs/etc Directory

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 that run the United States edition of AFS 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.

  • Cells that run the international edition of AFS must not use the Update Server to distribute the contents of the /usr/afs/etc directory. Due to United States government regulations, the data encryption routines that AFS uses to protect the files in this directory as they cross the network are not available to the Update Server in the international edition of AFS. You must instead update the files on each server machine individually, taking extra care to issue exactly the same bos command for each machine. The necessary data encryption routines are available to the bos commands, so information is safe as it crosses the network from the machine where the bos command is issued to the server machines.

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:

CellServDB

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.

KeyFile

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.

ThisCell

An ASCII file that consists of a single line defining the complete Internet domain-style name of the cell (such as abc.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.

UserList

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.

Local Configuration Files in the /usr/afs/local Directory

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:

BosConfig

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.

NetInfo

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.

NetRestrict

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.

NoAuth

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.

SALVAGE.fs

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.

salvage.lock

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.

sysid

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.

Replicated Database Files in the /usr/afs/db Directory

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.

bdb.DB0

The Backup Database file.

bdb.DBSYS1

The Backup Database log file.

kaserver.DB0

The Authentication Database file.

kaserver.DBSYS1

The Authentication Database log file.

prdb.DB0

The Protection Database file.

prdb.DBSYS1

The Protection Database log file.

vldb.DB0

The Volume Location Database file.

vldb.DBSYS1

The Volume Location Database log file.

Log Files in the /usr/afs/logs Directory

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:

AuthLog

The Authentication Server's log file.

BackupLog

The Backup Server's log file.

BosLog

The BOS Server's log file.

FileLog

The File Server's log file.

SalvageLog

The Salvager's log file.

VLLog

The Volume Location (VL) Server's log file.

VolserLog

The Volume Server's log file.

core.process

If present, a core image file produced as an AFS server process on the machine crashed (probably the process named by process).

Note

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.

Volume Headers on Server Partitions

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:

Vvol_ID.vol

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.

FORCESALVAGE

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.

Note

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.