jimzah/openafs
1
0
Fork 0
mirror of https://git.openafs.org/openafs.git synced 2025-01-20 07:51:00 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
81e1d54034
openafs/doc/xml/AdminGuide/c3025.html
Chas Williams 52557c982e xml-docbook-documentation-first-pass-20060915 
needs more massaging to make it fit the tree, but, get it here first
2006-09-16 01:13:22 +00:00

9263 lines
190 KiB
HTML
Raw Blame History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Administering Server Machines</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
TITLE="AFS Administration Guide"
HREF="book1.html"><LINK
REL="UP"
TITLE="Managing File Server Machines"
HREF="p3023.html"><LINK
REL="PREVIOUS"
TITLE="Managing File Server Machines"
HREF="p3023.html"><LINK
REL="NEXT"
TITLE="Monitoring and Controlling Server Processes"
HREF="c6449.html"></HEAD
><BODY
CLASS="chapter"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>AFS Administration Guide: Version 3.6</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="p3023.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="c6449.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="chapter"
><H1
><A
NAME="HDRWQ80"
></A
>Chapter 3. Administering Server Machines</H1
><P
>This chapter describes how to administer an AFS server machine. It describes the following configuration information and
administrative tasks: <UL
><LI
><P
>The binary and configuration files that must reside in the subdirectories of the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs</B
></SPAN
> directory on every server machine's local disk; see <A
HREF="c3025.html#HDRWQ83"
>Local Disk Files
on a Server Machine</A
>.</P
></LI
><LI
><P
>The various <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>roles</I
></SPAN
> or functions that an AFS server machine can perform, and how to determine which
machines are taking a role; see <A
HREF="c3025.html#HDRWQ90"
>The Four Roles for File Server Machines</A
>.</P
></LI
><LI
><P
>How to maintain database server machines; see <A
HREF="c3025.html#HDRWQ101"
>Administering Database Server
Machines</A
>.</P
></LI
><LI
><P
>How to maintain the list of database server machines in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/CellServDB</B
></SPAN
>
file; see <A
HREF="c3025.html#HDRWQ118"
>Maintaining the Server CellServDB File</A
>.</P
></LI
><LI
><P
>How to control authorization checking on a server machine; see <A
HREF="c3025.html#HDRWQ123"
>Managing Authentication and
Authorization Requirements</A
>.</P
></LI
><LI
><P
>How to install new disks or partitions on a file server machine; see <A
HREF="c3025.html#HDRWQ130"
>Adding or Removing Disks
and Partitions</A
>.</P
></LI
><LI
><P
>How to change a server machine's IP addresses and manager VLDB server entries; see <A
HREF="c3025.html#HDRWQ138"
>Managing
Server IP Addresses and VLDB Server Entries</A
>.</P
></LI
><LI
><P
>How to reboot a file server machine; see <A
HREF="c3025.html#HDRWQ139"
>Rebooting a Server Machine</A
>.</P
></LI
></UL
></P
><P
>To learn how to install and configure a new server machine, see the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS Quick Beginnings</I
></SPAN
>.</P
><P
>To learn how to administer the server processes themselves, see <A
HREF="c6449.html"
>Monitoring and Controlling Server
Processes</A
>.</P
><P
>To learn how to administer volumes, see <A
HREF="c8420.html"
>Managing Volumes</A
>.</P
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="HDRWQ81"
>Summary of Instructions</A
></H1
><P
>This chapter explains how to perform the following tasks by using the indicated commands:</P
><DIV
CLASS="informaltable"
><A
NAME="AEN3071"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL
WIDTH="70*"><COL
WIDTH="30*"><TBODY
><TR
><TD
>Install new binaries</TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos install</B
></SPAN
></TD
></TR
><TR
><TD
>Examine binary check-and-restart time</TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos getrestart</B
></SPAN
></TD
></TR
><TR
><TD
>Set binary check-and-restart time</TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos setrestart</B
></SPAN
></TD
></TR
><TR
><TD
>Examine compilation dates on binary files</TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos getdate</B
></SPAN
></TD
></TR
><TR
><TD
>Restart a process to use new binaries</TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
></TD
></TR
><TR
><TD
>Revert to old version of binaries</TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos uninstall</B
></SPAN
></TD
></TR
><TR
><TD
>Remove obsolete <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.BAK</B
></SPAN
> and <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.OLD</B
></SPAN
> versions</TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos prune</B
></SPAN
></TD
></TR
><TR
><TD
>List partitions on a file server machine</TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos listpart</B
></SPAN
></TD
></TR
><TR
><TD
>Shutdown AFS server processes</TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos shutdown</B
></SPAN
></TD
></TR
><TR
><TD
>List volumes on a partition</TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos listvldb</B
></SPAN
></TD
></TR
><TR
><TD
>Move read/write volumes</TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos move</B
></SPAN
></TD
></TR
><TR
><TD
>List a cell's database server machines</TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listhosts</B
></SPAN
></TD
></TR
><TR
><TD
>Add a database server machine to server <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file</TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos addhost</B
></SPAN
></TD
></TR
><TR
><TD
>Remove a database server machine from server <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file</TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos removehost</B
></SPAN
></TD
></TR
><TR
><TD
>Set authorization checking requirements</TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos setauth</B
></SPAN
></TD
></TR
><TR
><TD
>Prevent authentication for <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
>, <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>pts</B
></SPAN
>, and
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos</B
></SPAN
> commands</TD
><TD
>Include <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-noauth</B
></SPAN
> flag</TD
></TR
><TR
><TD
>Prevent authentication for kas commands</TD
><TD
>Include <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-noauth</B
></SPAN
> flag on some commands or issue <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>noauthentication</B
></SPAN
> while in interactive mode</TD
></TR
><TR
><TD
>Display all VLDB server entries</TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos listaddrs</B
></SPAN
></TD
></TR
><TR
><TD
>Remove a VLDB server entry</TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos changeaddr</B
></SPAN
></TD
></TR
><TR
><TD
>Reboot a server machine remotely</TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos exec</B
></SPAN
> <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>reboot_command</I
></SPAN
></TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="HDRWQ83"
>Local Disk Files on a Server Machine</A
></H1
><P
>Several types of files must reside in the subdirectories of the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs</B
></SPAN
> 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.</P
><P
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>Note for Windows users:</B
></SPAN
> Some files described in this document possibly do not exist on
machines that run a Windows operating system. Also, Windows uses a backslash (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>\</B
></SPAN
>) rather than a
forward slash (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/</B
></SPAN
>) to separate the elements in a pathname.</P
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ84"
>Binaries in the /usr/afs/bin Directory</A
></H2
><P
>The <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/bin</B
></SPAN
> 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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs</B
></SPAN
>
process), each component resides in a separate file.</P
><P
>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 <A
HREF="c3025.html#HDRWQ93"
>Binary Distribution Machines</A
>.</P
><P
>It is best to keep the binaries for all processes in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/bin</B
></SPAN
> 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.</P
><P
>The following lists the binary files in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/bin</B
></SPAN
> directory that are directly
related to the AFS server processes or command suites. Other binaries (for example, for the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>klog</B
></SPAN
> command) sometimes appear in this directory on a particular file server machine's disk or in an
AFS distribution. <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>backup</B
></SPAN
></DT
><DD
><P
>The command suite for the AFS Backup System (the binary for the Backup Server is <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>buserver</B
></SPAN
>).</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
></DT
><DD
><P
>The command suite for communicating with the Basic OverSeer (BOS) Server (the binary for the BOS Server is
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bosserver</B
></SPAN
>).</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bosserver</B
></SPAN
></DT
><DD
><P
>The binary for the Basic OverSeer (BOS) Server process.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>buserver</B
></SPAN
></DT
><DD
><P
>The binary for the Backup Server process.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fileserver</B
></SPAN
></DT
><DD
><P
>The binary for the File Server component of the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs</B
></SPAN
> process.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas</B
></SPAN
></DT
><DD
><P
>The command suite for communicating with the Authentication Server (the binary for the Authentication Server is
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kaserver</B
></SPAN
>).</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kaserver</B
></SPAN
></DT
><DD
><P
>The binary for the Authentication Server process.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>ntpd</B
></SPAN
></DT
><DD
><P
>The binary for the Network Time Protocol Daemon (NTPD). AFS redistributes this binary and uses the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>runntp</B
></SPAN
> program to configure and initialize the NTPD process.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>ntpdc</B
></SPAN
></DT
><DD
><P
>A debugging utility furnished with the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>ntpd</B
></SPAN
> program.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>pts</B
></SPAN
></DT
><DD
><P
>The command suite for communicating with the Protection Server process (the binary for the Protection Server is
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>ptserver</B
></SPAN
>).</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>ptserver</B
></SPAN
></DT
><DD
><P
>The binary for the Protection Server process.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>runntp</B
></SPAN
></DT
><DD
><P
>The binary for the program used to configure NTPD most appropriately for use with AFS.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>salvager</B
></SPAN
></DT
><DD
><P
>The binary for the Salvager component of the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs</B
></SPAN
> process.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>udebug</B
></SPAN
></DT
><DD
><P
>The binary for a program that reports the status of AFS's distributed database technology, Ubik.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upclient</B
></SPAN
></DT
><DD
><P
>The binary for the client portion of the Update Server process.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upserver</B
></SPAN
></DT
><DD
><P
>The binary for the server portion of the Update Server process.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vlserver</B
></SPAN
></DT
><DD
><P
>The binary for the Volume Location (VL) Server process.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>volserver</B
></SPAN
></DT
><DD
><P
>The binary for the Volume Server component of the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs</B
></SPAN
> process.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos</B
></SPAN
></DT
><DD
><P
>The command suite for communicating with the Volume and VL Server processes (the binaries for the servers are
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>volserver</B
></SPAN
> and <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vlserver</B
></SPAN
>, respectively).</P
></DD
></DL
></DIV
></P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ85"
>Common Configuration Files in the /usr/afs/etc Directory</A
></H2
><P
>The directory <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc</B
></SPAN
> 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: <UL
><LI
><P
>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 <A
HREF="c3025.html#HDRWQ94"
>The System Control Machine</A
>). 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.</P
></LI
><LI
><P
>Cells that run the international edition of AFS must not use the Update Server to distribute the contents of the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc</B
></SPAN
> 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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> command for each machine.
The necessary data encryption routines are available to the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> commands, so
information is safe as it crosses the network from the machine where the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> command is
issued to the server machines.</P
></LI
></UL
></P
><P
>Never directly edit any of the files in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc</B
></SPAN
> directory, except as directed
by instructions for dealing with emergencies. In normal circumstances, use the appropriate <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> commands to change the files. The following list includes pointers to instructions.</P
><P
>The files in this directory include: <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
></DT
><DD
><P
>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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos
setcellname</B
></SPAN
> 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.</P
><P
>The server <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file is not the same as the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file stored in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/vice/etc</B
></SPAN
> 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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file lists only the local
cell's database server machines, because server processes never contact processes in other cells.</P
><P
>For instructions on maintaining this file, see <A
HREF="c3025.html#HDRWQ118"
>Maintaining the Server CellServDB
File</A
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
></DT
><DD
><P
>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.</P
><P
>For instructions on maintaining this file, see <A
HREF="c20494.html"
>Managing Server Encryption
Keys</A
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>ThisCell</B
></SPAN
></DT
><DD
><P
>An ASCII file that consists of a single line defining the complete Internet domain-style name of the cell (such
as <SAMP
CLASS="computeroutput"
>abc.com</SAMP
>). You create this file with the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos
setcellname</B
></SPAN
> command during the installation of your cell's first file server machine, as instructed in the
<SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS Quick Beginnings</I
></SPAN
>.</P
><P
>Note that changing this file is only one step in changing your cell's name. For discussion, see <A
HREF="c667.html#HDRWQ34"
>Choosing a Cell Name</A
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>UserList</B
></SPAN
></DT
><DD
><P
>An ASCII file that lists the usernames of the system administrators authorized to issue privileged <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
>, <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos</B
></SPAN
>, and <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>backup</B
></SPAN
>
commands. For instructions on maintaining the file, see <A
HREF="c32432.html#HDRWQ592"
>Administering the UserList
File</A
>.</P
></DD
></DL
></DIV
></P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ86"
>Local Configuration Files in the /usr/afs/local Directory</A
></H2
><P
>The directory <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/local</B
></SPAN
> 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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/bin</B
></SPAN
> and <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc</B
></SPAN
> directories. The most important file is
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>BosConfig</B
></SPAN
> file; it defines which server processes are to run on that machine.</P
><P
>As with the common configuration files in <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc</B
></SPAN
>, you must not edit these files
directly. Use commands from the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> command suite where appropriate; some files never need to
be altered.</P
><P
>The files in this directory include the following: <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>BosConfig</B
></SPAN
></DT
><DD
><P
>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.</P
><P
>As you create server processes during a file server machine's installation, their entries are defined in this
file automatically. The <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS Quick Beginnings</I
></SPAN
> outlines the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> 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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> suite, see
<A
HREF="c6449.html"
>Monitoring and Controlling Server Processes</A
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>NetInfo</B
></SPAN
></DT
><DD
><P
>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 <A
HREF="c3025.html#HDRWQ138"
>Managing Server IP
Addresses and VLDB Server Entries</A
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>NetRestrict</B
></SPAN
></DT
><DD
><P
>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 <A
HREF="c3025.html#HDRWQ138"
>Managing Server IP Addresses and VLDB Server Entries</A
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>NoAuth</B
></SPAN
></DT
><DD
><P
>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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>anonymous</B
></SPAN
>. This very
insecure state is useful only in rare instances, mainly during the installation of the machine.</P
><P
>The file is created automatically when you start the initial <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bosserver</B
></SPAN
> process
with the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-noauth</B
></SPAN
> flag, or issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos setauth</B
></SPAN
>
command to turn off authentication requirements. When you use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos setauth</B
></SPAN
> command
to turn on authentication, the BOS Server removes this file. For more information, see <A
HREF="c3025.html#HDRWQ123"
>Managing Authentication and Authorization Requirements</A
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>SALVAGE.fs</B
></SPAN
></DT
><DD
><P
>This zero-length file controls how the BOS Server handles a crash of the File Server component of the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs</B
></SPAN
> process. The BOS Server creates this file each time it starts or restarts the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs</B
></SPAN
> 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.</P
><P
>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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos salvage</B
></SPAN
> command; see <A
HREF="c8420.html#HDRWQ232"
>Salvaging Volumes</A
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>salvage.lock</B
></SPAN
></DT
><DD
><P
>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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos salvage</B
></SPAN
> command), it creates this zero-length
file and issues the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>flock</B
></SPAN
> 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.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>sysid</B
></SPAN
></DT
><DD
><P
>This file records the network interface addresses that the File Server (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fileserver</B
></SPAN
> 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 <A
HREF="c3025.html#HDRWQ138"
>Managing Server
IP Addresses and VLDB Server Entries</A
>.</P
></DD
></DL
></DIV
></P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ87"
>Replicated Database Files in the /usr/afs/db Directory</A
></H2
><P
>The directory <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/db</B
></SPAN
> 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):
<UL
><LI
><P
>A file that contains each database, with a <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.DB0</B
></SPAN
> extension.</P
></LI
><LI
><P
>A log file for each database, with a <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.DBSYS1</B
></SPAN
> 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.</P
></LI
></UL
></P
><P
>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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas</B
></SPAN
> suite (for the Authentication Database), <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>backup</B
></SPAN
> suite (for the
Backup Database), <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>pts</B
></SPAN
> suite (for the Protection Database), or <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos</B
></SPAN
> suite (for the VLDB).</P
><P
>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 <A
HREF="c3025.html#HDRWQ102"
>Replicating the AFS Administrative Databases</A
>.</P
><P
>The files listed here appear in this directory only on database server machines. On non-database server machines, this
directory is empty. <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bdb.DB0</B
></SPAN
></DT
><DD
><P
>The Backup Database file.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bdb.DBSYS1</B
></SPAN
></DT
><DD
><P
>The Backup Database log file.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kaserver.DB0</B
></SPAN
></DT
><DD
><P
>The Authentication Database file.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kaserver.DBSYS1</B
></SPAN
></DT
><DD
><P
>The Authentication Database log file.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>prdb.DB0</B
></SPAN
></DT
><DD
><P
>The Protection Database file.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>prdb.DBSYS1</B
></SPAN
></DT
><DD
><P
>The Protection Database log file.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vldb.DB0</B
></SPAN
></DT
><DD
><P
>The Volume Location Database file.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vldb.DBSYS1</B
></SPAN
></DT
><DD
><P
>The Volume Location Database log file.</P
></DD
></DL
></DIV
></P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ88"
>Log Files in the /usr/afs/logs Directory</A
></H2
><P
>The <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/logs</B
></SPAN
> 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
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>VolserLog</B
></SPAN
> file. Events are recorded at completion, so the server processes do not use these
files to reconstruct failed operations unlike the ones in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/db</B
></SPAN
> directory.</P
><P
>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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>FileLog</B
></SPAN
> file
possibly provides an explanation, showing that the File Server was unable to attach the volume. To examine a log file
remotely, use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos getlog</B
></SPAN
> command as described in <A
HREF="c6449.html#HDRWQ173"
>Displaying
Server Process Log Files</A
>.</P
><P
>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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>core</B
></SPAN
> name to indicate which process
generated the core file (for example, naming a core file generated by the Protection Server <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>core.ptserver</B
></SPAN
>). 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.</P
><P
>The directory contains the following files: <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>AuthLog</B
></SPAN
></DT
><DD
><P
>The Authentication Server's log file.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>BackupLog</B
></SPAN
></DT
><DD
><P
>The Backup Server's log file.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>BosLog</B
></SPAN
></DT
><DD
><P
>The BOS Server's log file.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>FileLog</B
></SPAN
></DT
><DD
><P
>The File Server's log file.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>SalvageLog</B
></SPAN
></DT
><DD
><P
>The Salvager's log file.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>VLLog</B
></SPAN
></DT
><DD
><P
>The Volume Location (VL) Server's log file.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>VolserLog</B
></SPAN
></DT
><DD
><P
>The Volume Server's log file.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>core.process</B
></SPAN
></DT
><DD
><P
>If present, a core image file produced as an AFS server process on the machine crashed (probably the process
named by process).</P
></DD
></DL
></DIV
></P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>rm</B
></SPAN
> command to
remove the file as the process runs; it re-creates it automatically.</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ89"
>Volume Headers on Server Partitions</A
></H2
><P
>A partition that houses AFS volumes must be mounted at a subdirectory of the machine's root ( / ) directory (not, for
instance under the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr</B
></SPAN
> directory). The file server machine's file system registry file
(<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/etc/fstab</B
></SPAN
> or equivalent) must correctly map the directory name and the partition's device
name. The directory name is of the form <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/vicep</B
></SPAN
>index, where each index is one or two lowercase
letters. By convention, the first AFS partition on a machine is mounted at <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/vicepa</B
></SPAN
>, the
second at <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/vicepb</B
></SPAN
>, and so on. If there are more than 26 partitions, continue with <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/vicepaa</B
></SPAN
>, <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/vicepab</B
></SPAN
> and so on. The <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS Release
Notes</I
></SPAN
> specifies the number of supported partitions per server machine.</P
><P
>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.</P
><P
>The <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/vicep</B
></SPAN
> directories contain two types of files: <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>Vvol_ID.vol</B
></SPAN
></DT
><DD
><P
>Each such file is a volume header. The vol_ID corresponds to the volume ID number displayed in the output from
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos examine</B
></SPAN
>, <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos listvldb</B
></SPAN
>, and <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos listvol</B
></SPAN
> commands.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>FORCESALVAGE</B
></SPAN
></DT
><DD
><P
>This zero-length file triggers the Salvager to salvage the entire partition. The AFS-modified version of the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fsck</B
></SPAN
> program creates this file if it discovers corruption.</P
></DD
></DL
></DIV
></P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>For most system types, it is important never to run the standard <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fsck</B
></SPAN
> 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.</P
></BLOCKQUOTE
></DIV
></DIV
></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="HDRWQ90"
>The Four Roles for File Server Machines</A
></H1
><P
>In cells that have more than one server machine, not all server machines have to perform exactly the same functions. The
are four possible <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>roles</I
></SPAN
> a machine can assume, determined by which server processes it is running. A machine
can assume more than one role by running all of the relevant processes. The following list summarizes the four roles, which are
described more completely in subsequent sections. <UL
><LI
><P
>A <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>simple file server</I
></SPAN
> machine runs only the processes that store and deliver AFS files to client
machines. You can run as many simple file server machines as you need to satisfy your cell's performance and disk space
requirements.</P
></LI
><LI
><P
>A <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>database server machine</I
></SPAN
> runs the four database server processes that maintain AFS's
replicated administrative databases: the Authentication, Backup, Protection, and Volume Location (VL) Server
processes.</P
></LI
><LI
><P
>A <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>binary distribution machine</I
></SPAN
> distributes the AFS server binaries for its system type to all
other server machines of that system type.</P
></LI
><LI
><P
>The single <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>system control machine</I
></SPAN
> distributes common server configuration files to all other
server machines in the cell, in a cell that runs the United States edition of AFS (cells that use the international
edition of AFS must not use the system control machine for this purpose). The machine conventionally also serves as the
time synchronization source for the cell, adjusting its clock according to a time source outside the cell.</P
></LI
></UL
></P
><P
>If a cell has a single server machine, it assumes the simple file server and database server roles. The instructions in
the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS Quick Beginnings</I
></SPAN
> also have you configure it as the system control machine and binary
distribution machine for its system type, but it does not actually perform those functions until you install another server
machine.</P
><P
>It is best to keep the binaries for all of the AFS server processes in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/bin</B
></SPAN
>
directory, even if not all processes are running. You can then change which roles a machine assumes simply by starting or
stopping the processes that define the role.</P
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ91"
>Simple File Server Machines</A
></H2
><P
>A <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>simple file server machine</I
></SPAN
> runs only the server processes that store and deliver AFS files to
client machines, monitor process status, and pick up binaries and configuration files from the cell's binary distribution and
system control machines.</P
><P
>In general, only cells with more than three server machines need to run simple file server machines. In cells with three
or fewer machines, all of them are usually database server machines (to benefit from replicating the administrative
databases); see <A
HREF="c3025.html#HDRWQ92"
>Database Server Machines</A
>.</P
><P
>The following processes run on a simple file server machine: <UL
><LI
><P
>The BOS Server (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bosserver</B
></SPAN
> process)</P
></LI
><LI
><P
>The <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs</B
></SPAN
> process, which combines the File Server, Volume Server, and Salvager
processes so that they can coordinate their operations on the data in volumes and avoid the inconsistencies that can
result from multiple simultaneous operations on the same data</P
></LI
><LI
><P
>The NTP coordinator (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>runntp</B
></SPAN
> process), which helps keep the machine's clock
synchronized with the clocks on the other server machines in the cell</P
></LI
><LI
><P
>A client portion of the Update Server that picks up binary files from the binary distribution machine of its AFS
system type (the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upclientbin</B
></SPAN
> process)</P
></LI
><LI
><P
>A client portion of the Update Server that picks up common configuration files from the system control machine, in
cells running the United States edition of AFS (the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upclientetc</B
></SPAN
> process)</P
></LI
></UL
></P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ92"
>Database Server Machines</A
></H2
><P
>A <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>database server machine</I
></SPAN
> runs the four processes that maintain the AFS replicated administrative
databases: the Authentication Server, Backup Server, Protection Server, and Volume Location (VL) Server, which maintain the
Authentication Database, Backup Database, Protection Database, and Volume Location Database (VLDB), respectively. To review
the functions of these server processes and their databases, see <A
HREF="c130.html#HDRWQ17"
>AFS Server Processes and the Cache
Manager</A
>.</P
><P
>If a cell has more than one server machine, it is best to run more than one database server machine, but more than three
are rarely necessary. Replicating the databases in this way yields the same benefits as replicating volumes: increased
availability and reliability of information. If one database server machine or process goes down, the information in the
database is still available from others. The load of requests for database information is spread across multiple machines,
preventing any one from becoming overloaded.</P
><P
>Unlike replicated volumes, however, replicated databases do change frequently. Consistent system performance demands
that all copies of the database always be identical, so it is not possible to record changes in only some of them. To
synchronize the copies of a database, the database server processes use AFS's distributed database technology, Ubik. See <A
HREF="c3025.html#HDRWQ102"
>Replicating the AFS Administrative Databases</A
>.</P
><P
>It is critical that the AFS server processes on every server machine in a cell know which machines are the database
server machines. The database server processes in particular must maintain constant contact with their peers in order to
coordinate the copies of the database. The other server processes often need information from the databases. Every file server
machine keeps a list of its cell's database server machines in its local <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/CellServDB</B
></SPAN
> file. Cells that use the States edition of AFS can use the system control
machine to distribute this file (see <A
HREF="c3025.html#HDRWQ94"
>The System Control Machine</A
>).</P
><P
>The following processes define a database server machine: <UL
><LI
><P
>The Authentication Server (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kaserver</B
></SPAN
> process)</P
></LI
><LI
><P
>The Backup Server (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>buserver</B
></SPAN
> process)</P
></LI
><LI
><P
>The Protection Server (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>ptserver</B
></SPAN
> process)</P
></LI
><LI
><P
>The VL Server (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vlserver</B
></SPAN
> process)</P
></LI
></UL
></P
><P
>Database server machines can also run the processes that define a simple file server machine, as listed in <A
HREF="c3025.html#HDRWQ91"
>Simple File Server Machines</A
>. One database server machine can act as the cell's system control
machine, and any database server machine can serve as the binary distribution machine for its system type; see <A
HREF="c3025.html#HDRWQ94"
>The System Control Machine</A
> and <A
HREF="c3025.html#HDRWQ93"
>Binary Distribution Machines</A
>.</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ93"
>Binary Distribution Machines</A
></H2
><P
>A <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>binary distribution machine</I
></SPAN
> stores and distributes the binary files for the AFS processes and
command suites to all other server machines of its system type. Each file server machine keeps its own copy of AFS server
process binaries on its local disk, by convention in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/bin</B
></SPAN
> directory. For
consistent system performance, however, all server machines must run the same version (build level) of a process. For
instructions for checking a binary's build level, see <A
HREF="c3025.html#HDRWQ117"
>Displaying A Binary File's Build Level</A
>.
The easiest way to keep the binaries consistent is to have a binary distribution machine of each system type distribute them
to its system-type peers.</P
><P
>The process that defines a binary distribution machine is the server portion of the Update Server (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upserver</B
></SPAN
> process). The client portion of the Update Server (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upclientbin</B
></SPAN
> process) runs on the other server machines of that system type and references the binary
distribution machine.</P
><P
>Binary distribution machines usually also run the processes that define a simple file server machine, as listed in <A
HREF="c3025.html#HDRWQ91"
>Simple File Server Machines</A
>. One binary distribution machine can act as the cell's system control
machine, and any binary distribution machine can serve as a database server machine; see <A
HREF="c3025.html#HDRWQ94"
>The System
Control Machine</A
> and <A
HREF="c3025.html#HDRWQ92"
>Database Server Machines</A
>.</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ94"
>The System Control Machine</A
></H2
><P
>In cells that run the United States edition of AFS, the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>system control machine</I
></SPAN
> stores and
distributes system configuration files shared by all of the server machines in the cell. Each file server machine keeps its
own copy of the configuration files on its local disk, by convention in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc</B
></SPAN
>
directory. For consistent system performance, however, all server machines must use the same files. The easiest way to keep
the files consistent is to have the system control machine distribute them. You make changes only to the copy stored on the
system control machine, as directed by the instructions in this document. The United States edition of AFS is available to
cells in the United States and Canada and to selected institutions in other countries, as determined by United States
government regulations.</P
><P
>Cells that run the international version of AFS do not use the system control machine to distribute system configuration
files. Some of the files contain information that is too sensitive to cross the network unencrypted, and United States
government regulations forbid the export of the necessary encryption routines in the form that the Update Server uses. You
must instead update the configuration files on each file server machine individually. The <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
>
commands that you use to update the files encrypt the information using an exportable form of the encryption routines.</P
><P
>For a list of the configuration files stored in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc</B
></SPAN
> directory, see <A
HREF="c3025.html#HDRWQ85"
>Common Configuration Files in the /usr/afs/etc Directory</A
>.</P
><P
>The <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS Quick Beginnings</I
></SPAN
> configures a cell's first server machine as the system control
machine. If you wish, you can reassign the role to a different machine that you install later, but you must then change the
client portion of the Update Server (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upclientetc</B
></SPAN
>) process running on all other server
machines to refer to the new system control machine.</P
><P
>The following processes define the system control machine: <UL
><LI
><P
>The server portion of the Update Server (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upserver</B
></SPAN
>) process, in cells using the
United States edition of AFS. The client portion of the Update Server (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upclientetc</B
></SPAN
>
process) runs on the other server machines and references the system control machine.</P
></LI
><LI
><P
>The NTP coordinator (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>runntp</B
></SPAN
> process) which points to a time source outside the
cell, if the cell uses NTPD to synchronize its clocks. The <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>runntp</B
></SPAN
> process on other
machines reference the system control machine as their main time source.</P
></LI
></UL
></P
><P
>The system control machine can also run the processes that define a simple file server machine, as listed in <A
HREF="c3025.html#HDRWQ91"
>Simple File Server Machines</A
>. It can also server as a database server machine, and by convention acts
as the binary distribution machine for its system type. A single <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upserver</B
></SPAN
> process can
distribute both configuration files and binaries. See <A
HREF="c3025.html#HDRWQ92"
>Database Server Machines</A
> and <A
HREF="c3025.html#HDRWQ93"
>Binary Distribution Machines</A
>.</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ95"
>To locate database server machines</A
></H2
><OL
TYPE="1"
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listhosts</B
></SPAN
> command. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listhosts</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62;
</PRE
></P
><P
>The machines listed in the output are the cell's database server machines. For complete instructions and example
output, see <A
HREF="c3025.html#HDRWQ120"
>To display a cell's database server machines</A
>.</P
></LI
><LI
><P
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>(Optional)</B
></SPAN
> Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos status</B
></SPAN
> command to verify
that a machine listed in the output of the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listhosts</B
></SPAN
> command is actually running the
processes that define it as a database server machine. For complete instructions, see <A
HREF="c6449.html#HDRWQ158"
>Displaying
Process Status and Information from the BosConfig File</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos status</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>buserver kaserver ptserver vlserver</B
></SPAN
>
</PRE
></P
><P
>If the specified machine is a database server machine, the output from the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos
status</B
></SPAN
> command includes the following lines:</P
><PRE
CLASS="programlisting"
>&#13; Instance buserver, currently running normally.
Instance kaserver, currently running normally.
Instance ptserver, currently running normally.
Instance vlserver, currently running normally.
</PRE
></LI
></OL
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ96"
>To locate the system control machine</A
></H2
><OL
TYPE="1"
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos status</B
></SPAN
> command for any server machine. Complete instructions appear
in <A
HREF="c6449.html#HDRWQ158"
>Displaying Process Status and Information from the BosConfig File</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos status</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upserver upclientbin upclientetc</B
></SPAN
> <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-long</B
></SPAN
>
</PRE
></P
><P
>The output you see depends on the machine you have contacted: a simple file server machine, the system control
machine, or a binary distribution machine. See <A
HREF="c3025.html#HDRWQ98"
>Interpreting the Output from the bos status
Command</A
>.</P
></LI
></OL
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ97"
>To locate the binary distribution machine for a system type</A
></H2
><OL
TYPE="1"
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos status</B
></SPAN
> command for a file server machine of the system type you are
checking (to determine a machine's system type, issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs sysname</B
></SPAN
> or <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>sys</B
></SPAN
> command as described in <A
HREF="c21473.html#HDRWQ417"
>Displaying and Setting the System Type
Name</A
>. Complete instructions for the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos status</B
></SPAN
> command appear in <A
HREF="c6449.html#HDRWQ158"
>Displaying Process Status and Information from the BosConfig File</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos status</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upserver upclientbin upclientetc -long</B
></SPAN
>
</PRE
></P
><P
>The output you see depends on the machine you have contacted: a simple file server machine, the system control
machine, or a binary distribution machine. See <A
HREF="c3025.html#HDRWQ98"
>Interpreting the Output from the bos status
Command</A
>.</P
></LI
></OL
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ98"
>Interpreting the Output from the bos status Command</A
></H2
><P
>Interpreting the output of the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos status</B
></SPAN
> command is most straightforward for a simple
file server machine. There is no <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upserver</B
></SPAN
> process, so the output includes the following
message:</P
><PRE
CLASS="programlisting"
>&#13; bos: failed to get instance info for 'upserver' (no such entity)
</PRE
><P
>A simple file server machine runs the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upclientbin</B
></SPAN
> process, so the output includes a
message like the following. It indicates that <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs7.abc.com</B
></SPAN
> is the binary distribution machine
for this system type.</P
><PRE
CLASS="programlisting"
>&#13; Instance upclientbin, (type is simple) currently running normally.
Process last started at Wed Mar 10 23:37:09 1999 (1 proc start)
Command 1 is '/usr/afs/bin/upclient fs7.abc.com -t 60 /usr/afs/bin'
</PRE
><P
>If you run the United States edition of AFS, a simple file server machine also runs the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upclientetc</B
></SPAN
> process, so the output includes a message like the following. It indicates that <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs1.abc.com</B
></SPAN
> is the system control machine.</P
><PRE
CLASS="programlisting"
>&#13; Instance upclientetc, (type is simple) currently running normally.
Process last started at Mon Mar 22 05:23:49 1999 (1 proc start)
Command 1 is '/usr/afs/bin/upclient fs1.abc.com -t 60 /usr/afs/etc'
</PRE
><DIV
CLASS="sect3"
><H3
CLASS="sect3"
><A
NAME="HDRWQ99"
>The Output on the System Control Machine</A
></H3
><P
>If you run the United States edition of AFS and have issued the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos status</B
></SPAN
> command
for the system control machine, the output includes an entry for the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upserver</B
></SPAN
> process
similar to the following:</P
><PRE
CLASS="programlisting"
>&#13; Instance upserver, (type is simple) currently running normally.
Process last started at Mon Mar 22 05:23:54 1999 (1 proc start)
Command 1 is '/usr/afs/bin/upserver'
</PRE
><P
>If you are using the default configuration recommended in the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS Quick Beginnings</I
></SPAN
>, the
system control machine is also the binary distribution machine for its system type, and a single <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upserver</B
></SPAN
> process distributes both kinds of updates. In that case, the output includes the following
messages:</P
><PRE
CLASS="programlisting"
>&#13; bos: failed to get instance info for 'upclientbin' (no such entity)
bos: failed to get instance info for 'upclientetc' (no such entity)
</PRE
><P
>If the system control machine is not a binary distribution machine, the output includes an error message for the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upclientetc</B
></SPAN
> process, but a complete a listing for the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upclientbin</B
></SPAN
> process (in this case it refers to the machine <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs5.abc.com</B
></SPAN
> as the binary distribution machine):</P
><PRE
CLASS="programlisting"
>&#13; Instance upclientbin, (type is simple) currently running normally.
Process last started at Mon Mar 22 05:23:49 1999 (1 proc start)
Command 1 is '/usr/afs/bin/upclient fs5.abc.com -t 60 /usr/afs/bin'
bos: failed to get instance info for 'upclientetc' (no such entity)
</PRE
></DIV
><DIV
CLASS="sect3"
><H3
CLASS="sect3"
><A
NAME="HDRWQ100"
>The Output on a Binary Distribution Machine</A
></H3
><P
>If you have issued the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos status</B
></SPAN
> command for a binary distribution machine, the
output includes an entry for the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upserver</B
></SPAN
> process similar to the following and error
message for the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upclientbin</B
></SPAN
> process:</P
><PRE
CLASS="programlisting"
>&#13; Instance upserver, (type is simple) currently running normally.
Process last started at Mon Apr 5 05:23:54 1999 (1 proc start)
Command 1 is '/usr/afs/bin/upserver'
bos: failed to get instance info for 'upclientbin' (no such entity)
</PRE
><P
>Unless this machine also happens to be the system control machine, a message like the following references the system
control machine (in this case, <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs3.abc.com</B
></SPAN
>):</P
><PRE
CLASS="programlisting"
>&#13; Instance upclientetc, (type is simple) currently running normally.
Process last started at Mon Apr 5 05:23:49 1999 (1 proc start)
Command 1 is '/usr/afs/bin/upclient fs3.abc.com -t 60 /usr/afs/etc'
</PRE
></DIV
></DIV
></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="HDRWQ101"
>Administering Database Server Machines</A
></H1
><P
>This section explains how to administer database server machines. For installation instructions, see the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS
Quick Beginnings</I
></SPAN
>.</P
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ102"
>Replicating the AFS Administrative Databases</A
></H2
><P
>There are several benefits to replicating the AFS administrative databases (the Authentication, Backup, Protection, and
Volume Location Databases), as discussed in <A
HREF="c667.html#HDRWQ52"
>Replicating the AFS Administrative Databases</A
>. For
correct cell functioning, the copies of each database must be identical at all times. To keep the databases synchronized, AFS
uses library of utilities called <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>Ubik</I
></SPAN
>. Each database server process runs an associated lightweight Ubik
process, and client-side programs call Ubik's client-side subroutines when they submit requests to read and change the
databases.</P
><P
>Ubik is designed to work with minimal administrator intervention, but there are several configuration requirements, as
detailed in <A
HREF="c3025.html#HDRWQ103"
>Configuring the Cell for Proper Ubik Operation</A
>. The following brief overview of
Ubik's operation is helpful for understanding the requirements. For more details, see <A
HREF="c3025.html#HDRWQ104"
>How Ubik
Operates Automatically</A
>.</P
><P
>Ubik is designed to distribute changes made in an AFS administrative database to all copies as quickly as possible. Only
one copy of the database, the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>synchronization site</I
></SPAN
>, accepts change requests from clients; the lightweight
Ubik process running there is the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>Ubik coordinator</I
></SPAN
>. To maintain maximum availability, there is a separate
Ubik coordinator for each database, and the synchronization site for each of the four databases can be on a different machine.
The synchronization site for a database can also move from machine to machine in response to process, machine, or network
outages.</P
><P
>The other copies of a database, and the Ubik processes that maintain them, are termed <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>secondary</I
></SPAN
>.
The secondary sites do not accept database changes directly from client-side programs, but only from the synchronization
site.</P
><P
>After the Ubik coordinator records a change in its copy of a database, it immediately sends the change to the secondary
sites. During the brief distribution period, clients cannot access any of the copies of the database, even for reading. If the
coordinator cannot reach a majority of the secondary sites, it halts the distribution and informs the client that the
attempted change failed.</P
><P
>To avoid distribution failures, the Ubik processes maintain constant contact by exchanging time-stamped messages. As
long as a majority of the secondary sites respond to the coordinator's messages, there is a <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>quorum</I
></SPAN
> of
sites that are synchronized with the coordinator. If a process, machine, or network outage breaks the quorum, the Ubik
processes attempt to elect a new coordinator in order to establish a new quorum among the highest possible number of sites.
See <A
HREF="c3025.html#HDRWQ106"
>A Flexible Coordinator Boosts Availability</A
>.</P
><DIV
CLASS="sect3"
><H3
CLASS="sect3"
><A
NAME="HDRWQ103"
>Configuring the Cell for Proper Ubik Operation</A
></H3
><P
>This section describes how to configure your cell to maintain proper Ubik operation. <UL
><LI
><P
>Run all four database server processes--Authentication Server, Backup Server, Protection Server, and VL
Server--on all database server machines.</P
><P
>Both the client and server portions of Ubik expect that all the database server machines listed in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file are running all of the database server processes. There is no mechanism for
indicating that only some database server processes are running on a machine.</P
></LI
><LI
><P
>Maintain correct information in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/CellServDB</B
></SPAN
> file at all
times.</P
><P
>Ubik consults the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/CellServDB</B
></SPAN
> file to determine the sites with
which to establish and maintain a quorum. Incorrect information can result in unsynchronized databases or election of
a coordinator in each of several subgroups of machines, because the Ubik processes on various machines do not agree on
which machines need to participate in the quorum.</P
><P
>If you run the United States version of AFS and use the Update Server, it is simplest to maintain the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/CellServDB</B
></SPAN
> file on the system control machine, which distributes its copy to all
other server machines. The <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS Quick Beginnings</I
></SPAN
> explains how to configure the Update Server.
If you run the international version of AFS, you must update the file on each machine individually.</P
><P
>The only reason to alter the file is when configuring or decommissioning a database server machine. Use the
appropriate <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> commands rather than editing the file by hand. For instructions, see
<A
HREF="c3025.html#HDRWQ118"
>Maintaining the Server CellServDB File</A
>. The instructions in <A
HREF="c6449.html"
>Monitoring and Controlling Server Processes</A
> for stopping and starting processes remind you
to alter the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file when appropriate, as do the instructions in the
<SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS Quick Beginnings</I
></SPAN
> for installing or decommissioning a database server machine.</P
><P
>(Client processes and the server processes that do not maintain databases also rely on correct information in
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file for proper operation, but their use of the information does not
affect Ubik's operation. See <A
HREF="c3025.html#HDRWQ118"
>Maintaining the Server CellServDB File</A
> and <A
HREF="c21473.html#HDRWQ406"
>Maintaining Knowledge of Database Server Machines</A
>.)</P
></LI
><LI
><P
>Keep the clocks synchronized on all machines in the cell, especially the database server machines.</P
><P
>In the conventional configuration specified in the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS Quick Beginnings</I
></SPAN
>, you run the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>runntp</B
></SPAN
> process to supervise the local Network Time Protocol Daemon (NTPD) on every
AFS server machine. The NTPD on the system control machine synchronizes its clock with a reliable source outside the
cell and broadcasts the time to the NTPDs on the other server machines. You can choose to run a different time
synchronization protocol if you wish.</P
><P
>Keeping clocks synchronized is important because the Ubik processes at a database's sites timestamp the messages
which they exchange to maintain constant contact. Timestamping the messages is necessary because in a networked
environment it is not safe to assume that a message reaches its destination instantly. Ubik compares the timestamp on
an incoming message with the current time. If the difference is too great, it is possible that an outage is preventing
reliable communication between the Ubik sites, which can possibly result in unsynchronized databases. Ubik considers
the message invalid, which can prompt it to attempt election of a different coordinator.</P
><P
>Electing a new coordinator is appropriate if a timestamped message is expired due to actual interruption of
communication, but not if a message appears expired only because the sender and recipient do not share the same time.
For detailed examples of how unsynchronized clocks can destabilize Ubik operation, see <A
HREF="c3025.html#HDRWQ105"
>How
Ubik Uses Timestamped Messages</A
>.</P
></LI
></UL
></P
></DIV
><DIV
CLASS="sect3"
><H3
CLASS="sect3"
><A
NAME="HDRWQ104"
>How Ubik Operates Automatically</A
></H3
><P
>The following Ubik features help keep its maintenance requirements to a minimum: <UL
><LI
><P
>Ubik's server and client portions operate automatically.</P
><P
>Each database server process runs a lightweight process to call on the server portion of the Ubik library. It is
common to refer to this lightweight process itself as Ubik. Because it is lightweight, the Ubik process does not
appear in process listings such as those generated by the UNIX <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>ps</B
></SPAN
> command.
Client-side programs that need to read and change the databases directly call the subroutines in the Ubik library's
client portion, rather than running a separate lightweight process. Examples of such programs are the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>klog</B
></SPAN
> command and the commands in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>pts</B
></SPAN
> suite.</P
></LI
><LI
><P
>Ubik tracks database version numbers.</P
><P
>As the coordinator records a change to a database, it increments the database's version number. The version
number makes it easy for the coordinator to determine if a site has the most recent version or not. The version number
speeds the return to normal functioning after election of a new coordinator or when communication is restored after an
outage, because it makes it easy to determine which site has the most current database and which need to be
updated.</P
></LI
><LI
><P
>Ubik's use of timestamped messages guarantees that database copies are always synchronized during normal
operation.</P
><P
>Replicating a database to increase data availability is pointless if all copies of the database are not the
same. Inconsistent performance can result if clients receive different information depending on which copy of the
database they access. As previously noted, Ubik sites constantly track the status of their peers by exchanging
timestamped messages. For a detailed description, see <A
HREF="c3025.html#HDRWQ105"
>How Ubik Uses Timestamped
Messages</A
>.</P
></LI
><LI
><P
>The ability to move the coordinator maximizes database availability.</P
><P
>Suppose, for example, that in a cell with three database server machines a network partition separates the two
secondary sites from the coordinator. The coordinator retires because it is no longer in contact with a majority of
the sites listed in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file. The two sites on the other side of the
partition can elect a new coordinator among themselves, and it can then accept database changes from clients. If the
coordinator cannot move in this way, the database has to be read-only until the network partition is repaired. For a
detailed description of Ubik's election procedure, see <A
HREF="c3025.html#HDRWQ106"
>A Flexible Coordinator Boosts
Availability</A
>.</P
></LI
></UL
></P
><DIV
CLASS="sect4"
><H4
CLASS="sect4"
><A
NAME="HDRWQ105"
>How Ubik Uses Timestamped Messages</A
></H4
><P
>Ubik synchronizes the copies of a database by maintaining constant contact between the synchronization site and the
secondary sites. The Ubik coordinator frequently sends a time-stamped <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>guarantee</I
></SPAN
> message to each of
the secondary sites. When the secondary site receives the message, it concludes that it is in contact with the
coordinator. It considers its copy of the database to be valid until time <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>T</I
></SPAN
>, which is usually 60
seconds from the time the coordinator sent the message. In response, the secondary site returns a
<SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>vote</I
></SPAN
> message that acknowledges the coordinator as valid until a certain time X, which is usually 120
seconds in the future.</P
><P
>The coordinator sends guarantee messages more frequently than every <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>T</I
></SPAN
> seconds, so that the
expiration periods overlap. There is no danger of expiration unless a network partition or other outage actually
interrupts communication. If the guarantee expires, the secondary site's copy of the database it not necessarily current.
Nonetheless, the database server continues to service client requests. It is considered better for overall cell
functioning that a secondary site remains accessible even if the information it is distributing is possibly out of date.
Most of the AFS administrative databases do not change that frequently, in any case, and making a database inaccessible
causes a timeout for clients that happen to access that copy.</P
><P
>As previously mentioned, Ubik's use of timestamped messages makes it vital to synchronize the clocks on database
server machines. There are two ways that skewed clocks can interrupt normal Ubik functioning, depending on which clock is
ahead of the others.</P
><P
>Suppose, for example, that the Ubik coordinator's clock is ahead of the secondary sites: the coordinator's clock
says 9:35:30, but the secondary clocks say 9:31:30. The secondary sites send votes messages that acknowledge the
coordinator as valid until 9:33:30. This is two minutes in the future according to the secondary clocks, but is already in
the past from the coordinator's perspective. The coordinator concludes that it no longer has enough support to remain
coordinator and forces election of a new coordinator. Election takes about three minutes, during which time no copy of the
database accepts changes.</P
><P
>The opposite possibility is that a secondary site's clock (14:50:00) is ahead of the coordinator's (14:46:30). When
the coordinator sends a guarantee message good until 14:47:30), it has already expired according to the secondary clock.
Believing that it is out of contact with the coordinator, the secondary site stops sending votes for the coordinator and
tries get itself elected as coordinator. This is appropriate if the coordinator has actually failed, but is inappropriate
when there is no actual outage.</P
><P
>The attempt of a single secondary site to get elected as the new coordinator usually does not affect the performance
of the other sites. As long as their clocks agree with the coordinator's, they ignore the other secondary site's request
for votes and continue voting for the current coordinator. However, if enough of the secondary sites's clocks get ahead of
the coordinator's, they can force election of a new coordinator even though the current one is actually working
fine.</P
></DIV
><DIV
CLASS="sect4"
><H4
CLASS="sect4"
><A
NAME="HDRWQ106"
>A Flexible Coordinator Boosts Availability</A
></H4
><P
>Ubik uses timestamped messages to determine when coordinator election is necessary, just as it does to keep the
database copies synchronized. As long as the coordinator receives vote messages from a majority of the sites (it
implicitly votes for itself), it is appropriate for it to continue as coordinator because it is successfully distributing
database changes. A majority is defined as more than 50% of all database sites when there are an odd number of sites; with
an even number of sites, the site with the lowest Internet address has an extra vote for breaking ties as necessary.If the
coordinator is not receiving sufficient votes, it retires and the Ubik sites elect a new coordinator. This does not happen
spontaneously, but only when the coordinator really fails or stops receiving a majority of the votes. The secondary sites
have a built-in bias to continue voting for an existing coordinator, which prevents undue elections.</P
><P
>The election of the new coordinator is by majority vote. The Ubik subprocesses have a bias to vote for the site with
the lowest Internet address, which helps it gather the necessary majority quicker than if all the sites were competing to
receive votes themselves. During the election (which normally lasts less than three minutes), clients can read information
from the database, but cannot make any changes.</P
><P
>Ubik's election procedure makes it possible for each database server process's coordinator to be on a different
machine. For example, if the Ubik coordinators for all four processes start out on machine A and the Protection Server on
machine A fails for some reason, then a different site (say machine B) must be elected as the new Protection Database Ubik
coordinator. Machine B remains the coordinator for the Protection Database even after the Protection Server on machine A
is working again. The failure of the Protection Server has no effect on the Authentication, Backup, or VL Servers, so
their coordinators remain on machine A.</P
></DIV
></DIV
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ107"
>Backing Up and Restoring the Administrative Databases</A
></H2
><P
>The AFS administrative databases store information that is critical for AFS operation in your cell. If a database
becomes corrupted due to a hardware failure or other problem on a database server machine, it likely to be difficult and
time-consuming to recreate all of the information from scratch. To protect yourself against loss of data, back up the
administrative databases to a permanent media, such as tape, on a regular basis. The recommended method is to use a standard
local disk backup utility such as the UNIX <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>tar</B
></SPAN
> command.</P
><P
>When deciding how often to back up a database, consider the amount of data that you are willing to recreate by hand if
it becomes necessary to restore the database from a backup copy. In most cells, the databases differ quite a bit in how often
and how much they change. Changes to the Authentication Database are probably the least frequent, and consist mostly of
changed user passwords. Protection Database and VLDB changes are probably more frequent, as users add or delete groups and
change group memberships, and as you and other administrators create or move volumes. The number and frequency of changes is
probably greatest in the Backup Database, particularly if you perform backups every day.</P
><P
>The ease with which you can recapture lost changes also differs for the different databases: <UL
><LI
><P
>If regular users make a large proportion of the changes to the Authentication Database and Protection Database in
your cell, then recovering them possibly requires a large amount of detective work and interviewing of users, assuming
that they can even remember what changes they made at what time.</P
></LI
><LI
><P
>Recovering lost changes to the VLDB is more straightforward, because you can use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos
syncserv</B
></SPAN
> and <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos syncvldb</B
></SPAN
> commands to correct any discrepancies between the
VLDB and the actual state of volumes on server machines. Running these commands can be time-consuming, however.</P
></LI
><LI
><P
>The configuration information in the Backup Database (Tape Coordinator port offsets, volume sets and entries, the
dump hierarchy, and so on) probably does not change that often, in which case it is not that hard to recover a few
recent changes. In contrast, there are likely to be a large number of new dump records resulting from dump operations.
You can recover these records by using the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-dbadd</B
></SPAN
> argument to the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>backup scantape</B
></SPAN
> command, reading in information from the backup tapes themselves. This can take a
long time and require numerous tape changes, however, depending on how much data you back up in your cell and how you
append dumps. Furthermore, the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>backup scantape</B
></SPAN
> command is subject to several
restrictions. The most basic is that it halts if it finds that an existing dump record in the database has the same dump
ID number as a dump on the tape it is scanning. If you want to continue with the scanning operation, you must locate and
remove the existing record from the database. For further discussion, see the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>backup
scantape</B
></SPAN
> command's reference page in the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS Administration Reference</I
></SPAN
>.</P
></LI
></UL
></P
><P
>These differences between the databases possibly suggest backing up the database at different frequencies, ranging from
every few days or weekly for the Backup Database to every few weeks for the Authentication Database. On the other hand, it is
probably simpler from a logistical standpoint to back them all up at the same time (and frequently), particularly if tape
consumption is not a major concern. Also, it is not generally necessary to keep backup copies of the databases for a long
time, so you can recycle the tapes fairly frequently.</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ108"
>To back up the administrative databases</A
></H2
><OL
TYPE="1"
><LI
><P
>Log in as the local superuser <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>root</B
></SPAN
> on a database server machine that is not the
synchronization site. The machine with the highest IP address is normally the best choice, since it is least likely to
become the synchronization site in an election.</P
></LI
><LI
><P
><A
NAME="LIDBBK_SHUTDOWN"
></A
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos shutdown</B
></SPAN
> command to shut down the
relevant server process on the local machine. For a complete description of the command, see <A
HREF="c6449.html#HDRWQ168"
>To
stop processes temporarily</A
>.</P
><P
>For the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-instance</B
></SPAN
> argument, specify one or more database server process names
(<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>buserver</B
></SPAN
> for the Backup Server, <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kaserver</B
></SPAN
> for the
Authentication Server, <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>ptserver</B
></SPAN
> for the Protection Server, or <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vlserver</B
></SPAN
> for the Volume Location Server. Include the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-localauth</B
></SPAN
>
flag because you are logged in as the local superuser <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>root</B
></SPAN
> but do not necessarily have
administrative tokens.</P
><PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos shutdown</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-instance</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>instances</VAR
>&#62;+ <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-localauth</B
></SPAN
> [<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-wait</B
></SPAN
>]
</PRE
></LI
><LI
><P
>Use a local disk backup utility, such as the UNIX <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>tar</B
></SPAN
> command, to transfer one or
more database files to tape. If the local database server machine does not have a tape device attached, use a remote copy
command to transfer the file to a machine with a tape device, then use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>tar</B
></SPAN
> command
there.</P
><P
>The following command sequence backs up the complete contents of the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/db</B
></SPAN
>
directory</P
><PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>cd /usr/afs/db</B
></SPAN
>
# <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>tar cvf</B
></SPAN
> tape_device <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.</B
></SPAN
>
</PRE
><P
>To back up individual database files, substitute their names for the period in the preceding <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>tar</B
></SPAN
> command: <UL
><LI
><P
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bdb.DB0</B
></SPAN
> for the Backup Database</P
></LI
><LI
><P
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kaserver.DB0</B
></SPAN
> for the Authentication Database</P
></LI
><LI
><P
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>prdb.DB0</B
></SPAN
> for the Protection Database</P
></LI
><LI
><P
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vldb.DB0</B
></SPAN
> for the VLDB</P
></LI
></UL
></P
></LI
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos start</B
></SPAN
> command to restart the server processes on the local machine.
For a complete description of the command, see <A
HREF="c6449.html#HDRWQ166"
>To start processes by changing their status flags
to Run</A
>. Provide the same values for the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-instance</B
></SPAN
> argument as in Step <A
HREF="c3025.html#LIDBBK_SHUTDOWN"
>2</A
>, and the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-localauth</B
></SPAN
> flag for the same reason.
<PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos start</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-instance</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>server process name</VAR
>&#62;+ <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-localauth</B
></SPAN
>
</PRE
></P
></LI
></OL
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ109"
>To restore an administrative database</A
></H2
><OL
TYPE="1"
><LI
><P
>Log in as the local superuser <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>root</B
></SPAN
> on each database server machine in the
cell.</P
></LI
><LI
><P
><A
NAME="LIDBREST_SHUTDOWN"
></A
>Working on one of the machines, issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos
shutdown</B
></SPAN
> command once for each database server machine, to shut down the relevant server process on all of
them. For a complete description of the command, see <A
HREF="c6449.html#HDRWQ168"
>To stop processes temporarily</A
>.</P
><P
>For the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-instance</B
></SPAN
> argument, specify one or more database server process names
(<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>buserver</B
></SPAN
> for the Backup Server, <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kaserver</B
></SPAN
> for the
Authentication Server, <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>ptserver</B
></SPAN
> for the Protection Server, or <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vlserver</B
></SPAN
> for the Volume Location Server. Include the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-localauth</B
></SPAN
>
flag because you are logged in as the local superuser <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>root</B
></SPAN
> but do not necessarily have
administrative tokens.</P
><PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos shutdown</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-instance</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>instances</VAR
>&#62;+ <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-localauth</B
></SPAN
> [<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-wait</B
></SPAN
>]
</PRE
></LI
><LI
><P
>Remove the database from each database server machine, by issuing the following commands on each one.
<PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>cd /usr/afs/db</B
></SPAN
>
</PRE
></P
><P
>For the Backup Database:</P
><PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>rm bdb.DB0</B
></SPAN
>
# <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>rm bdb.DBSYS1</B
></SPAN
>
</PRE
><P
>For the Authentication Database:</P
><PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>rm kaserver.DB0</B
></SPAN
>
# <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>rm kaserver.DBSYS1</B
></SPAN
>
</PRE
><P
>For the Protection Database:</P
><PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>rm prdb.DB0</B
></SPAN
>
# <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>rm prdb.DBSYS1</B
></SPAN
>
</PRE
><P
>For the VLDB:</P
><PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>rm vldb.DB0</B
></SPAN
>
# <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>rm vldb.DBSYS1</B
></SPAN
>
</PRE
></LI
><LI
><P
>Using the local disk backup utility that you used to back up the database, copy the most recently backed-up version
of it to the appropriate file on the database server machine with the lowest IP address. The following is an appropriate
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>tar</B
></SPAN
> command if the synchronization site has a tape device attached: <PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>cd /usr/afs/db</B
></SPAN
>
# <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>tar xvf</B
></SPAN
> tape_device database_file
</PRE
></P
><P
>where <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>database_file</I
></SPAN
> is one of the following: <UL
><LI
><P
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bdb.DB0</B
></SPAN
> for the Backup Database</P
></LI
><LI
><P
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kaserver.DB0</B
></SPAN
> for the Authentication Database</P
></LI
><LI
><P
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>prdb.DB0</B
></SPAN
> for the Protection Database</P
></LI
><LI
><P
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vldb.DB0</B
></SPAN
> for the VLDB</P
></LI
></UL
></P
></LI
><LI
><P
>Working on one of the machines, issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos start</B
></SPAN
> command to restart the server
process on each of the database server machines in turn. Start with the machine with the lowest IP address, which becomes
the synchronization site for the Backup Database. Wait for it to establish itself as the synchronization site before
repeating the command to restart the process on the other database server machines. For a complete description of the
command, see <A
HREF="c6449.html#HDRWQ166"
>To start processes by changing their status flags to Run</A
>. Provide the same
values for the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-instance</B
></SPAN
> argument as in Step <A
HREF="c3025.html#LIDBREST_SHUTDOWN"
>2</A
>,
and the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-localauth</B
></SPAN
> flag for the same reason. <PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos start</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-instance</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>server process name</VAR
>&#62;+ <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-localauth</B
></SPAN
>
</PRE
></P
></LI
><LI
><P
>If the database has changed since you last backed it up, issue the appropriate commands from the instructions in the
indicated sections to recreate the information in the restored database. If issuing <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>pts</B
></SPAN
>
commands, you must first obtain administrative tokens. The <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>backup</B
></SPAN
> and <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos</B
></SPAN
> commands accept the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-localauth</B
></SPAN
> flag if you are logged in as
the local superuser <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>root</B
></SPAN
>, so you do not need administrative tokens. The Authentication
Server always performs a separate authentication anyway, so you only need to include the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-admin</B
></SPAN
> argument if issuing <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas</B
></SPAN
> commands. <UL
><LI
><P
>To define or remove volume sets and volume entries in the Backup Database, see <A
HREF="c12776.html#HDRWQ265"
>Defining and Displaying Volume Sets and Volume Entries</A
>.</P
></LI
><LI
><P
>To edit the dump hierarchy in the Backup Database, see <A
HREF="c12776.html#HDRWQ267"
>Defining and Displaying the
Dump Hierarchy</A
>.</P
></LI
><LI
><P
>To define or remove Tape Coordinator port offset entries in the Backup Database, see <A
HREF="c12776.html#HDRWQ261"
>Configuring Tape Coordinator Machines and Tape Devices</A
>.</P
></LI
><LI
><P
>To restore dump records in the Backup Database, see <A
HREF="c15383.html#HDRWQ305"
>To scan the contents of a
tape</A
>.</P
></LI
><LI
><P
>To recreate Authentication Database entries or password changes for users, see the appropriate section of
<A
HREF="c27596.html"
>Administering User Accounts</A
>.</P
></LI
><LI
><P
>To recreate Protection Database entries or group membership information, see the appropriate section of <A
HREF="c29323.html"
>Administering the Protection Database</A
>.</P
></LI
><LI
><P
>To synchronize the VLDB with volume headers, see <A
HREF="c8420.html#HDRWQ227"
>Synchronizing the VLDB and Volume
Headers</A
>.</P
></LI
></UL
></P
></LI
></OL
></DIV
></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="HDRWQ110"
>Installing Server Process Software</A
></H1
><P
>This section explains how to install new server process binaries on file server machines, how to revert to a previous
version if the current version is not working properly, and how to install new disks to house AFS volumes on a file server
machine.</P
><P
>The most frequent reason to replace a server process's binaries is to upgrade AFS to a new version. In general,
installation instructions accompany the updated software, but this chapter provides an additional reference.</P
><P
>Each AFS server machine must store the server process binaries in a local disk directory, called <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/bin</B
></SPAN
> by convention. For predictable system performance, it is best that all server machines run
the same build level, or at least the same version, of the server software. For instructions on checking AFS build level, see
<A
HREF="c3025.html#HDRWQ117"
>Displaying A Binary File's Build Level</A
>.</P
><P
>The Update Server makes it easy to distribute a consistent version of software to all server machines. You designate one
server machine of each system type as the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>binary distribution machine</I
></SPAN
> by running the server portion of the
Update Server (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upserver</B
></SPAN
> process) on it. All other server machines of that system type run the
client portion of the Update Server (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upclientbin</B
></SPAN
> process) to retrieve updated software from the
binary distribution machine. The <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS Quick Beginnings</I
></SPAN
> explains how to install the appropriate
processes. For more on binary distribution machines, see <A
HREF="c3025.html#HDRWQ93"
>Binary Distribution Machines</A
>.</P
><P
>When you use the Update Server, you install new binaries on binary distribution machines only. If you install binaries
directly on a machine that is running the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upclientbin</B
></SPAN
> process, they are overwritten the next
time the process compares the contents of the local <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/bin</B
></SPAN
> directory to the contents on
the system control machine, by default within five minutes.</P
><P
>The following instructions explain how to use the appropriate commands from the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> suite
to install and uninstall server binaries.</P
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ111"
>Installing New Binaries</A
></H2
><P
>An AFS server process does not automatically switch to a new process binary file as soon as it is installed in the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/bin</B
></SPAN
> directory. The process continues to use the previous version of the binary file
until it (the process) next restarts. By default, the BOS Server restarts processes for which there are new binary files every
day at 5:00 a.m., as specified in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/local/BosConfig</B
></SPAN
> file. To display or change
this <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>binary restart time</I
></SPAN
>, use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos getrestart</B
></SPAN
> and <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos setrestart</B
></SPAN
> commands, as described in <A
HREF="c6449.html#HDRWQ171"
>Setting the BOS Server's Restart
Times</A
>.</P
><P
>You can force the server machine to start using new server process binaries immediately by issuing the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> command as described in the following instructions.</P
><P
>You do not need to restart processes when you install new command suite binaries. The new binary is invoked
automatically the next time a command from the suite is issued.</P
><P
>When you use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos install</B
></SPAN
> command, the BOS Server automatically saves the current
version of a binary file by adding a <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.BAK</B
></SPAN
> extension to its name. It renames the current
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.BAK</B
></SPAN
> version, if any, to the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.OLD</B
></SPAN
> version, if there is no
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.OLD</B
></SPAN
> version already. If there is a current <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.OLD</B
></SPAN
> version,
the current <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.BAK</B
></SPAN
> version must be at least seven days old to replace it.</P
><P
>It is best to store AFS binaries in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/bin</B
></SPAN
> directory, because that is the
only directory the BOS Server automatically checks for new binaries. You can, however, use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos
install</B
></SPAN
> command's <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-dir</B
></SPAN
> argument to install non-AFS binaries into other directories
on a server machine's local disk. See the command's reference page in the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS Administration
Reference</I
></SPAN
> for further information.</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="Header_130"
>To install new server binaries</A
></H2
><OL
TYPE="1"
><LI
><P
>Verify that you are listed in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/UserList</B
></SPAN
> file. If necessary, issue
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> command, which is fully described in <A
HREF="c32432.html#HDRWQ593"
>To
display the users in the UserList file</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62;
</PRE
></P
></LI
><LI
><P
>Verify that the binaries are available in the source directory from which you are installing them. If the machine is
also an AFS client, you can retrieve the binaries from a central directory in AFS. Otherwise, you can obtain them directly
from the AFS distribution media, from a local disk directory where you previously installed them, or from a remote machine
using a transfer utility such as the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>ftp</B
></SPAN
> command.</P
></LI
><LI
><P
><A
NAME="LIWQ112"
></A
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos install</B
></SPAN
> command for the binary distribution
machine. (If you have forgotten which machine is performing that role, see <A
HREF="c3025.html#HDRWQ97"
>To locate the binary
distribution machine for a system type</A
>.) <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos install</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; &#60;<VAR
CLASS="replaceable"
>files to install</VAR
>&#62;+
</PRE
></P
><P
>where <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>i</B
></SPAN
></DT
><DD
><P
>Is the shortest acceptable abbreviation of <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>install</B
></SPAN
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>machine name</B
></SPAN
></DT
><DD
><P
>Names the binary distribution machine.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>files to install</B
></SPAN
></DT
><DD
><P
>Names each binary file to install into the local <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/bin</B
></SPAN
> directory.
Partial pathnames are interpreted relative to the current working directory. The last element in each pathname
(the filename itself) matches the name of the file it is replacing, such as <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bosserver</B
></SPAN
> or <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>volserver</B
></SPAN
> for server processes, <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> or <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos</B
></SPAN
> for commands.</P
><P
>Each AFS server process other than the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs</B
></SPAN
> process uses a single binary
file. The <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs</B
></SPAN
> process uses three binary files: <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fileserver</B
></SPAN
>, <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>volserver</B
></SPAN
>, and <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>salvager</B
></SPAN
>. Installing a new version of one component does not necessarily mean that you need
to replace all three.</P
></DD
></DL
></DIV
></P
></LI
><LI
><P
>Repeat Step <A
HREF="c3025.html#LIWQ112"
>3</A
> for each binary distribution machine.</P
></LI
><LI
><P
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>(Optional)</B
></SPAN
> If you want to restart processes to use the new binaries immediately,
wait until the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upclientbin</B
></SPAN
> process retrieves them from the binary distribution machine.
You can verify the timestamps on binary files by using the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos getdate</B
></SPAN
> command as
described in <A
HREF="c3025.html#HDRWQ115"
>Displaying Binary Version Dates</A
>. When the binary files are available on each
server machine, issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> command, for which complete instructions appear in
<A
HREF="c6449.html#HDRWQ170"
>Stopping and Immediately Restarting Processes</A
>.</P
><P
>If you are working on an AFS client machine, it is a wise precaution to have a copy of the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> command suite binaries on the local disk before restarting server processes. In the
conventional configuration, the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afsws/bin</B
></SPAN
> directory that houses the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> command binary on client machines is a symbolic link into AFS, which conserves local disk
space. However, restarting certain processes (particularly the database server processes) can make the AFS filespace
inaccessible, particularly if a problem arises during the restart. Having a local copy of the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> binary enables you to uninstall or reinstall process binaries or restart processes even in this
case. Use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>cp</B
></SPAN
> command to copy the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> command binary
from the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afsws/bin</B
></SPAN
> directory to a local directory such as <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/tmp</B
></SPAN
>.</P
><P
>Restarting a process causes a service outage. It is best to perform the restart at times of low system usage if
possible.</P
><PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; &#60;<VAR
CLASS="replaceable"
>instances</VAR
>&#62;+
</PRE
></LI
></OL
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ113"
>Reverting to the Previous Version of Binaries</A
></H2
><P
>In rare cases, installing a new binary can cause problems serious enough to require reverting to the previous version.
Just as with installing binaries, consistent system performance requires reverting every server machine back to the same
version. Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos uninstall</B
></SPAN
> command described here on each binary distribution
machine.</P
><P
>When you use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos uninstall</B
></SPAN
> command, the BOS Server discards the current version of
a binary file and promotes the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.BAK</B
></SPAN
> version of the file by removing the extension. It renames
the current <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.OLD</B
></SPAN
> version, if any, to <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.BAK</B
></SPAN
>.</P
><P
>If there is no current <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.BAK</B
></SPAN
> version, the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos uninstall</B
></SPAN
>
command operation fails and generates an error message. If a <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.OLD</B
></SPAN
> version still exists, issue
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>mv</B
></SPAN
> command to rename it to <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.BAK</B
></SPAN
> before reissuing the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos uninstall</B
></SPAN
> command.</P
><P
>Just as when you install new binaries, the server processes do not start using a reverted version immediately.
Presumably you are reverting because the current binaries do not work, so the following instructions have you restart the
relevant processes.</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="Header_132"
>To revert to the previous version of binaries</A
></H2
><OL
TYPE="1"
><LI
><P
>Verify that you are listed in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/UserList</B
></SPAN
> file. If necessary, issue
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> command, which is fully described in <A
HREF="c32432.html#HDRWQ593"
>To
display the users in the UserList file</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62;
</PRE
></P
></LI
><LI
><P
>Verify that the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.BAK</B
></SPAN
> version of each relevant binary is available in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/bin</B
></SPAN
> directory on each binary distribution machine. If necessary, you can use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos getdate</B
></SPAN
> command as described in <A
HREF="c3025.html#HDRWQ115"
>Displaying Binary Version
Dates</A
>. If necessary, rename the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.OLD</B
></SPAN
> version to <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.BAK</B
></SPAN
></P
></LI
><LI
><P
><A
NAME="LIWQ114"
></A
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos uninstall</B
></SPAN
> command for a binary distribution
machine. (If you have forgotten which machine is performing that role, see <A
HREF="c3025.html#HDRWQ97"
>To locate the binary
distribution machine for a system type</A
>.) <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos uninstall</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; &#60;<VAR
CLASS="replaceable"
>files to uninstall</VAR
>&#62;+
</PRE
></P
><P
>where <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>u</B
></SPAN
></DT
><DD
><P
>Is the shortest acceptable abbreviation of <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>uninstall</B
></SPAN
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>machine name</B
></SPAN
></DT
><DD
><P
>Names the binary distribution machine.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>files to uninstall</B
></SPAN
></DT
><DD
><P
>Names each binary file in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/bin</B
></SPAN
> directory to replace with its
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.BAK</B
></SPAN
> version. The file name alone is sufficient, because the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/bin</B
></SPAN
> directory is assumed.</P
></DD
></DL
></DIV
></P
></LI
><LI
><P
>Repeat Step <A
HREF="c3025.html#LIWQ114"
>3</A
> for each binary distribution machine.</P
></LI
><LI
><P
>Wait until the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upclientbin</B
></SPAN
> process on each server machine retrieves the reverted
from the binary distribution machine. You can verify the timestamps on binary files by using the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos
getdate</B
></SPAN
> command as described in <A
HREF="c3025.html#HDRWQ115"
>Displaying Binary Version Dates</A
>. When the
binary files are available on each server machine, issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> command, for
which complete instructions appear in <A
HREF="c6449.html#HDRWQ170"
>Stopping and Immediately Restarting
Processes</A
>.</P
><P
>If you are working on an AFS client machine, it is a wise precaution to have a copy of the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> command suite binaries on the local disk before restarting server processes. In the
conventional configuration, the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afsws/bin</B
></SPAN
> directory that houses the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> command binary on client machines is a symbolic link into AFS, which conserves local disk
space. However, restarting certain processes (particularly the database server processes) can make the AFS filespace
inaccessible, particularly if a problem arises during the restart. Having a local copy of the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> binary enables you to uninstall or reinstall process binaries or restart processes even in this
case. Use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>cp</B
></SPAN
> command to copy the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> command binary
from the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afsws/bin</B
></SPAN
> directory to a local directory such as <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/tmp</B
></SPAN
>.</P
><PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; &#60;<VAR
CLASS="replaceable"
>instances</VAR
>&#62;+
</PRE
></LI
></OL
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ115"
>Displaying Binary Version Dates</A
></H2
><P
>You can check the compilation dates for all three versions of a binary file in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/bin</B
></SPAN
> directory--the current, <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.BAK</B
></SPAN
> and .<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>OLD</B
></SPAN
> versions. This is useful for verifying that new binaries have been copied to a file server machine
from its binary distribution machine before restarting a server process to use the new binaries.</P
><P
>To check dates on binaries in a directory other than <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/bin</B
></SPAN
>, add the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-dir</B
></SPAN
> argument. See the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS Administration Reference</I
></SPAN
>.</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="Header_134"
>To display binary version dates</A
></H2
><OL
TYPE="1"
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos getdate</B
></SPAN
> command. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos getdate</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; &#60;<VAR
CLASS="replaceable"
>files to check</VAR
>&#62;+
</PRE
></P
><P
>where <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>getd</B
></SPAN
></DT
><DD
><P
>Is the shortest acceptable abbreviation of <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>getdate</B
></SPAN
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>machine name</B
></SPAN
></DT
><DD
><P
>Name the file server machine for which to display binary dates.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>files to check</B
></SPAN
></DT
><DD
><P
>Names each binary file to display.</P
></DD
></DL
></DIV
></P
></LI
></OL
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ116"
>Removing Obsolete Binary Files</A
></H2
><P
>When processes with new binaries have been running without problems for a number of days, it is generally safe to remove
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.BAK</B
></SPAN
> and <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.OLD</B
></SPAN
> versions from the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/bin</B
></SPAN
> directory, both to reduce clutter and to free space on the file server machine's local
disk.</P
><P
>You can use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos prune</B
></SPAN
> command's flags to remove the following types of files:
<UL
><LI
><P
>To remove files in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/bin</B
></SPAN
> directory with a <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.BAK</B
></SPAN
> extension, use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-bak</B
></SPAN
> flag.</P
></LI
><LI
><P
>To remove files in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/bin</B
></SPAN
> directory with a <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.OLD</B
></SPAN
> extension, use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-old</B
></SPAN
> flag.</P
></LI
><LI
><P
>To remove files in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/logs</B
></SPAN
> directory called <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>core</B
></SPAN
>, with any extension, use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-core</B
></SPAN
> flag.</P
></LI
><LI
><P
>To remove all three types of files, use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-all</B
></SPAN
> flag.</P
></LI
></UL
></P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="Header_136"
>To remove obsolete binaries</A
></H2
><OL
TYPE="1"
><LI
><P
>Verify that you are listed in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/UserList</B
></SPAN
> file. If necessary, issue
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> command, which is fully described in <A
HREF="c32432.html#HDRWQ593"
>To
display the users in the UserList file</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62;
</PRE
></P
></LI
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos prune</B
></SPAN
> command with one or more of its flags. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos prune</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; [<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-bak</B
></SPAN
>] [<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-old</B
></SPAN
>] [<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-core</B
></SPAN
>] [<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-all</B
></SPAN
>]
</PRE
></P
><P
>where <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>p</B
></SPAN
></DT
><DD
><P
>Is the shortest acceptable abbreviation of <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>prune</B
></SPAN
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>machine name</B
></SPAN
></DT
><DD
><P
>Names the file server machine on which to remove obsolete files.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-bak</B
></SPAN
></DT
><DD
><P
>Removes all the files with a <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>.BAK</B
></SPAN
> extension from the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/bin</B
></SPAN
> directory. Do not combine this flag with the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-all</B
></SPAN
> flag.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-old</B
></SPAN
></DT
><DD
><P
>Removes all the files a .<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>OLD</B
></SPAN
> extension from the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/bin</B
></SPAN
> directory. Do not combine this flag with the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-all</B
></SPAN
> flag.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-core</B
></SPAN
></DT
><DD
><P
>Removes all core files from the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/logs</B
></SPAN
> directory. Do not combine
this flag with the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-all</B
></SPAN
> flag</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-all</B
></SPAN
></DT
><DD
><P
>Combines the effect of the other three flags. Do not combine it with the other three flags.</P
></DD
></DL
></DIV
></P
></LI
></OL
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ117"
>Displaying A Binary File's Build Level</A
></H2
><P
>For the most consistent performance on a server machine, and cell-wide, it is best for all server processes to come from
the same AFS distribution. Every AFS binary includes an ASCII string that specifies its version, or <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>build
level</I
></SPAN
>. To display it, use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>strings</B
></SPAN
> and <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>grep</B
></SPAN
>
commands, which are included in most UNIX distributions.</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="Header_138"
>To display an AFS binary's build level</A
></H2
><OL
TYPE="1"
><LI
><P
>Change to the directory that houses the binary file . If you are not sure where the binary resides, issue the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>which</B
></SPAN
> command. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>which</B
></SPAN
> binary_file
/bin_dir_path/binary_file
% <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>cd</B
></SPAN
> bin_dir_path
</PRE
></P
></LI
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>strings</B
></SPAN
> command to extract all ASCII strings from the binary file. Pipe
the output to the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>grep</B
></SPAN
> command to locate the relevant line. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>strings ./</B
></SPAN
>binary_file <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>| grep Base</B
></SPAN
>
</PRE
></P
><P
>The output reports the AFS build level in a format like the following:</P
><PRE
CLASS="programlisting"
>&#13; @(#)Base configuration afsversion build_level
</PRE
><P
>For example, the following string indicates the binary is from AFS 3.6 build 3.0:</P
><PRE
CLASS="programlisting"
>&#13; @(#)Base configuration afs3.6 3.0
</PRE
></LI
></OL
></DIV
></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="HDRWQ118"
>Maintaining the Server CellServDB File</A
></H1
><P
>Every file server machine maintains a list of its home cell's database server machines in the local disk file <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/CellServDB</B
></SPAN
> on its local disk. Both database server processes and non-database server
processes consult the file: <UL
><LI
><P
>The database server processes (the Authentication, Backup, Protection, and Volume Location Servers) maintain
constant contact with their peers in order to keep their copies of the replicated administrative databases
synchronized.</P
><P
>As detailed in <A
HREF="c3025.html#HDRWQ102"
>Replicating the AFS Administrative Databases</A
>, the database server
processes use the Ubik utility to synchronize the information in the databases they maintain. The Ubik coordinator at the
synchronization site for each database maintains the single read/write copy of the database and distributes changes to the
secondary sites as necessary. It must maintain contact with a majority of the secondary sites to remain the coordinator,
and consults the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file to learn how many peers it has and on which machines
they are running.</P
><P
>If the coordinator loses contact with the majority of its peers, they all cooperate to elect a new coordinator by
majority vote. During the election, all of the Ubik processes consult the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file
to learn where to send their votes, and what number constitutes a majority.</P
></LI
><LI
><P
>The non-database server processes must know which machines are running the database server processes in order to
retrieve information from the databases. For example, the first time that a user accesses an AFS file, the File Server
that houses it contacts the Protection Server to obtain a list of the user's group memberships (the list is called a
current protection subgroup, or CPS). The File Server uses the CPS as it determines if the access control list (ACL)
protecting the file grants the required permissions to the user (for more details, see <A
HREF="c29323.html#HDRWQ534"
>About the
Protection Database</A
>).</P
></LI
></UL
></P
><P
>The consequences of missing or incorrect information in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file are as
follows: <UL
><LI
><P
>If the file does not list a machine, then it is effectively not a database server machine even if the database
server processes are running. The Ubik coordinator does not send it database updates or include it in the count that
establishes a majority. It does not participate in Ubik elections, and so refuses to distribute database information to
any client machines that happen to contact it (which they can do if their <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/vice/etc/CellServDB</B
></SPAN
> file lists it). Users of the client machine must wait for a timeout before
they can contact a correctly functioning database server machine.</P
></LI
><LI
><P
>If the file lists a machine that is not running the database server processes, the consequences can be serious. The
Ubik coordinator cannot send it database updates, but includes it in the count that establishes a majority. If valid
secondary sites go down and stop sending their votes to the coordinator, it can wrongly appear that the coordinator no
longer has the majority it needs. The resulting election of a new coordinator causes a service outage during which
information from the database becomes unavailable. Furthermore, the lack of a vote from the incorrectly listed site can
disturb the election, if it makes the other sites believe that a majority of sites are not voting for the new
coordinator.</P
><P
>A more minor consequence is that non-database server processes attempt to contact the database server processes on
the machine. They experience a timeout delay because the processes are not running.</P
></LI
></UL
></P
><P
>Note that the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/CellServDB</B
></SPAN
> file on a server machine is not the same as the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/vice/etc/CellServDB</B
></SPAN
> file on client machine. The client version includes entries for
foreign cells as well as the local cell. However, it is important to update both versions of the file whenever you change your
cell's database server machines. A server machine that is also a client needs to have both files, and you need to update them
both. For more information on maintaining the client version of the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file, see <A
HREF="c21473.html#HDRWQ406"
>Maintaining Knowledge of Database Server Machines</A
>.</P
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ119"
>Distributing the Server CellServDB File</A
></H2
><P
>To avoid the negative consequences of incorrect information in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/CellServDB</B
></SPAN
> file, you must update it on all of your cell's server machines every time you
add or remove a database server machine. The <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS Quick Beginnings</I
></SPAN
> provides complete instructions for
installing or removing a database server machine and for updating the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file in that
context. This section explains how to distribute the file to your server machines and how to make other cells aware of the
changes if you participate in the AFS global name space.</P
><P
>If you use the United States edition of AFS, use the Update Server to distribute the central copy of the server
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file stored on the cell's system control machine. If you use the international
edition of AFS, instead change the file on each server machine individually. For further discussion of the system control
machine and why international cells must not use it for files in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc</B
></SPAN
> directory,
see <A
HREF="c3025.html#HDRWQ94"
>The System Control Machine</A
>. For instructions on configuring the Update Server when using
the United States version of AFS, see the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS Quick Beginnings</I
></SPAN
>.</P
><P
>To avoid formatting errors that can cause errors, always use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos addhost</B
></SPAN
> and
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos removehost</B
></SPAN
> commands, rather than editing the file directly. You must also restart the
database server processes running on the machine, to initiate a coordinator election among the new set of database server
machines. This step is included in the instructions that appear in <A
HREF="c3025.html#HDRWQ121"
>To add a database server machine
to the CellServDB file</A
> and <A
HREF="c3025.html#HDRWQ122"
>To remove a database server machine from the CellServDB
file</A
>. For instructions on displaying the contents of the file, see <A
HREF="c3025.html#HDRWQ120"
>To display a cell's
database server machines</A
>.</P
><P
>If you make your cell accessible to foreign users as part of the AFS global name space, you also need to inform other
cells when you change your cell's database server machines. The AFS Support group maintains a <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file that lists all cells that participate in the AFS global name space, and can change your
cell's entry at your request. For further details, see <A
HREF="c667.html#HDRWQ38"
>Making Your Cell Visible to
Others</A
>.</P
><P
>Another way to advertise your cell's database server machines is to maintain a copy of the file at the conventional
location in your AFS filespace, <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/afs/</B
></SPAN
><SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>cellname</I
></SPAN
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/service/etc/CellServDB.local</B
></SPAN
>. For further discussion, see <A
HREF="c667.html#HDRWQ43"
>The Third
Level</A
>.</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ120"
>To display a cell's database server machines</A
></H2
><OL
TYPE="1"
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listhosts</B
></SPAN
> command. If you have maintained the file properly, the
output is the same on every server machine, but the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>machine name</I
></SPAN
> argument enables you to check
various machines if you wish. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listhosts</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; [&#60;<VAR
CLASS="replaceable"
>cell name</VAR
>&#62;]
</PRE
></P
><P
>where <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>listh</B
></SPAN
></DT
><DD
><P
>Is the shortest acceptable abbreviation of <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>listhosts</B
></SPAN
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>machine name</B
></SPAN
></DT
><DD
><P
>Specifies the server machine from which to display the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/CellServDB</B
></SPAN
> file.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>cell name</B
></SPAN
></DT
><DD
><P
>Specifies the complete Internet domain name of a foreign cell. You must already know the name of at least
one server machine in the cell, to provide as the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>machine name</B
></SPAN
> argument.</P
></DD
></DL
></DIV
></P
></LI
></OL
><P
>The output lists the machines in the order they appear in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file on the
specified server machine. It assigns each one a <SAMP
CLASS="computeroutput"
>Host</SAMP
> index number, as in the following
example. There is no implied relationship between the index and a machine's IP address, name, or role as Ubik coordinator or
secondary site.</P
><PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listhosts fs1.abc.com</B
></SPAN
>
Cell name is abc.com
Host 1 is fs1.abc.com
Host 2 is fs7.abc.com
Host 3 is fs4.abc.com
</PRE
><P
>The output lists machines by name rather than IP address as long as the naming service (such as the Domain Name Service
or local host table) is functioning properly. To display IP addresses, login to a server machine as the local superuser
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>root</B
></SPAN
> and use a text editor or display command, such as the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>cat</B
></SPAN
> command, to view the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/CellServDB</B
></SPAN
> file.</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ121"
>To add a database server machine to the CellServDB file</A
></H2
><OL
TYPE="1"
><LI
><P
>Verify that you are listed in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/UserList</B
></SPAN
> file. If necessary, issue
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> command, which is fully described in <A
HREF="c32432.html#HDRWQ593"
>To
display the users in the UserList file</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62;
</PRE
></P
></LI
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos addhost</B
></SPAN
> command to add each new database server machine to the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file. If you use the United States edition of AFS, specify the system control
machine as <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>machine name</I
></SPAN
>. (If you have forgotten which machine is the system control machine, see
<A
HREF="c3025.html#HDRWQ99"
>The Output on the System Control Machine</A
>.) If you use the international edition of AFS,
repeat the command on each or your cell's server machines in turn by substituting its name for <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>machine
name</I
></SPAN
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos addhost</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; &#60;<VAR
CLASS="replaceable"
>host name</VAR
>&#62;+
</PRE
></P
><P
>where <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>addh</B
></SPAN
></DT
><DD
><P
>Is the shortest acceptable abbreviation of <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>addhost</B
></SPAN
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>machine name</B
></SPAN
></DT
><DD
><P
>Names the system control machine, if you are using the United States edition of AFS. If you are using the
international edition of AFS, it names each of your server machines in turn.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>host name</B
></SPAN
></DT
><DD
><P
>Specifies the fully qualified hostname of each database server machine to add to the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file (for example: <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs4.abc.com</B
></SPAN
>). The BOS Server
uses the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>gethostbyname()</B
></SPAN
> routine to obtain each machine's IP address and records
both the name and address automatically.</P
></DD
></DL
></DIV
></P
></LI
><LI
><P
>Restart the Authentication Server, Backup Server, Protection Server, and VL Server on every database server machine,
so that the new set of machines participate in the election of a new Ubik coordinator. The instruction uses the
conventional names for the processes; make the appropriate substitution if you use different process names. For complete
syntax, see <A
HREF="c6449.html#HDRWQ170"
>Stopping and Immediately Restarting Processes</A
>.</P
><P
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>Important:</B
></SPAN
> Repeat the following command in quick succession on all of the database
server machines.</P
><PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>buserver kaserver ptserver vlserver</B
></SPAN
>
</PRE
></LI
><LI
><P
>Edit the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/vice/etc/CellServDB</B
></SPAN
> file on each of your cell's client machines. For
instructions, see <A
HREF="c21473.html#HDRWQ406"
>Maintaining Knowledge of Database Server Machines</A
>.</P
></LI
><LI
><P
>If you participate in the AFS global name space, please have one of your cell's designated site contacts register
the changes you have made with the AFS Product Support group.</P
><P
>If you maintain a central copy of your cell's server <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file in the
conventional location (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/afs/</B
></SPAN
><SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>cellname</I
></SPAN
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/service/etc/CellServDB.local</B
></SPAN
>), edit the file to reflect the change.</P
></LI
></OL
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ122"
>To remove a database server machine from the CellServDB file</A
></H2
><OL
TYPE="1"
><LI
><P
>Verify that you are listed in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/UserList</B
></SPAN
> file. If necessary, issue
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> command, which is fully described in <A
HREF="c32432.html#HDRWQ593"
>To
display the users in the UserList file</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62;
</PRE
></P
></LI
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos removehost</B
></SPAN
> command to remove each database server machine from the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file. If you use the United States edition of AFS, specify the system control
machine as <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>machine name</I
></SPAN
>. (If you have forgotten which machine is the system control machine, see
<A
HREF="c3025.html#HDRWQ99"
>The Output on the System Control Machine</A
>.) If you use the international edition of AFS,
repeat the command on each or your cell's server machines in turn by substituting its name for <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>machine
name</I
></SPAN
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos removehost</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; &#60;<VAR
CLASS="replaceable"
>host name</VAR
>&#62;+
</PRE
></P
><P
>where <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>removeh</B
></SPAN
></DT
><DD
><P
>Is the shortest acceptable abbreviation of <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>removehost</B
></SPAN
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>machine name</B
></SPAN
></DT
><DD
><P
>Names the system control machine, if you are using the United States edition of AFS. If you are using the
international edition of AFS, it names each of your server machines in turn.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>host name</B
></SPAN
></DT
><DD
><P
>Specifies the fully qualified hostname of each database server machine to remove from the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file (for example: <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs4.abc.com</B
></SPAN
>).</P
></DD
></DL
></DIV
></P
></LI
><LI
><P
>Restart the Authentication Server, Backup Server, Protection Server, and VL Server on every database server machine,
so that the new set of machines participate in the election of a new Ubik coordinator. The instruction uses the
conventional names for the processes; make the appropriate substitution if you use different process names. For complete
syntax, see <A
HREF="c6449.html#HDRWQ170"
>Stopping and Immediately Restarting Processes</A
>.</P
><P
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>Important:</B
></SPAN
> Repeat the following command in quick succession on all of the database
server machines.</P
><PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>buserver kaserver ptserver vlserver</B
></SPAN
>
</PRE
></LI
><LI
><P
>Edit the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/vice/etc/CellServDB</B
></SPAN
> file on each of your cell's client machines. For
instructions, see <A
HREF="c21473.html#HDRWQ406"
>Maintaining Knowledge of Database Server Machines</A
>.</P
></LI
><LI
><P
>If you participate in the AFS global name space, please have one of your cell's designated site contacts register
the changes you have made with the AFS Product Support group.</P
><P
>If you maintain a central copy of your cell's server <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>CellServDB</B
></SPAN
> file in the
conventional location (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/afs/</B
></SPAN
><SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>cellname</I
></SPAN
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/service/etc/CellServDB.local</B
></SPAN
>), edit the file to reflect the change.</P
></LI
></OL
></DIV
></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="HDRWQ123"
>Managing Authentication and Authorization Requirements</A
></H1
><P
>This section describes how the AFS server processes guarantee that only properly authorized users perform privileged
commands, by checking authorization checking and mutually authenticating with their clients. It explains how you can control
authorization checking requirements on a per-machine or per-cell basis, and how to bypass mutual authentication when issuing
commands.</P
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ124"
>Authentication versus Authorization</A
></H2
><P
>Many AFS commands are <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>privileged</I
></SPAN
> in that the AFS server process invoked by the command performs it
only for a properly authorized user. The server process performs the following two tests to determine if someone is properly
authorized: <UL
><LI
><P
>In the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>authentication</I
></SPAN
> test, the server process mutually authenticates with the command
interpreter, Cache Manager, or other client process that is acting on behalf of a user or application. The goal of this
test is to determine who is issuing the command. The server process verifies that the issuer really is who he or she
claims to be, by examining the server ticket and other components of the issuer's token. (Secondarily, it allows the
client process to verify that the server process is genuine.) If the issuer has no token or otherwise fails the test,
the server process assigns him or her the identity <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>anonymous</B
></SPAN
>, a completely unprivileged
user. For a more complete description of mutual authentication, see <A
HREF="c667.html#HDRWQ75"
>A More Detailed Look at
Mutual Authentication</A
>.</P
><P
>Many individual commands enable you to bypass the authentication test by assuming the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>anonymous</B
></SPAN
> identity without even attempting to mutually authenticate. Note, however, that this is
futile if the command is privileged and the server process is still performing the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>authorization</I
></SPAN
>
test, because in that case the process refuses to execute privileged commands for the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>anonymous</B
></SPAN
> user.</P
></LI
><LI
><P
>In the authorization test, the server process determines if the issuer is authorized to use the command by
consulting a list of privileged users. The goal of this test is to determine what the issuer is allowed to do. Different
server processes consult different lists of users, as described in <A
HREF="c32432.html"
>Managing Administrative
Privilege</A
>. The server process refuses to execute any privileged command for an unauthorized issuer. If a command
has no privilege requirements, the server process skips this step and executes and immediately.</P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>Never place the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>anonymous</B
></SPAN
> user or the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>system:anyuser</B
></SPAN
> group on a privilege list; it makes authorization checking meaningless.</P
><P
>You can use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos setauth</B
></SPAN
> command to control whether the server processes on
a server machine check for authorization. Other server machines are not affected. Keep in mind that turning off
authorization checking is a grave security risk, because the server processes on that machine perform any action for
any user.</P
></BLOCKQUOTE
></DIV
></LI
></UL
></P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ125"
>Controlling Authorization Checking on a Server Machine</A
></H2
><P
>Disabling authorization checking is a serious breach of security because it means that the AFS server processes on a
file server machine performs any action for any user, even the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>anonymous</B
></SPAN
> user.</P
><P
>The only time it is common to disable authorization checking is when installing a new file server machine (see the IBM
AFS Quick Beginnings). It is necessary then because it is not possible to configure all of the necessary security mechanisms
before performing other actions that normally make use of them. For greatest security, work at the console of the machine you
are installing and enable authorization checking as soon as possible.</P
><P
>During normal operation, the only reason to disable authorization checking is if an error occurs with the server
encryption keys, leaving the servers unable to authenticate users properly. For instructions on handling key-related
emergencies, see <A
HREF="c20494.html#HDRWQ370"
>Handling Server Encryption Key Emergencies</A
>.</P
><P
>You control authorization checking on each file server machine separately; turning it on or off on one machine does not
affect the others. Because client machines generally choose a server process at random, it is hard to predict what
authorization checking conditions prevail for a given command unless you make the requirement the same on all machines. To
turn authorization checking on or off for the entire cell, you must repeat the appropriate command on every file server
machine.</P
><P
>The server processes constantly monitor the directory <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/local</B
></SPAN
> on their local
disks to determine if they need to check for authorization. If the file called <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>NoAuth</B
></SPAN
> appears
in that directory, then the servers do not check for authorization. When it is not present (the usual case), they perform
authorization checking.</P
><P
>Control the presence of the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>NoAuth</B
></SPAN
> file through the BOS Server. When you disable
authorization checking with the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos setauth</B
></SPAN
> command (or, during installation, by putting the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-noauth</B
></SPAN
> flag on the command that starts up the BOS Server), the BOS Server creates the
zero-length <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>NoAuth</B
></SPAN
> file. When you reenable authorization checking, the BOS Server removes the
file.</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ126"
>To disable authorization checking on a server machine</A
></H2
><OL
TYPE="1"
><LI
><P
>Verify that you are listed in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/UserList</B
></SPAN
> file. If necessary, issue
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> command, which is fully described in <A
HREF="c32432.html#HDRWQ593"
>To
display the users in the UserList file</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62;
</PRE
></P
></LI
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos setauth</B
></SPAN
> command to disable authorization checking. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos setauth</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>off</B
></SPAN
>
</PRE
></P
><P
>where <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>seta</B
></SPAN
></DT
><DD
><P
>Is the shortest acceptable abbreviation of <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>setauth</B
></SPAN
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>machine name</B
></SPAN
></DT
><DD
><P
>Specifies the file server machine on which server processes do not check for authorization.</P
></DD
></DL
></DIV
></P
></LI
></OL
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ127"
>To enable authorization checking on a server machine</A
></H2
><OL
TYPE="1"
><LI
><P
>Reenable authorization checking. (No privilege is required because the machine is not currently checking for
authorization.) For detailed syntax information, see the preceding section. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos setauth</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>on</B
></SPAN
>
</PRE
></P
></LI
></OL
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ128"
>Bypassing Mutual Authentication for an Individual Command</A
></H2
><P
>Several of the server processes allow any user (not just system administrators) to disable mutual authentication when
issuing a command. The server process treats the issuer as the unauthenticated user <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>anonymous</B
></SPAN
>.</P
><P
>The facilities for preventing mutual authentication are provided for use in emergencies (such as the key emergency
discussed in <A
HREF="c20494.html#HDRWQ370"
>Handling Server Encryption Key Emergencies</A
>). During normal circumstances,
authorization checking is turned on, making it useless to prevent authentication: the server processes refuse to perform
privileged commands for the user <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>anonymous</B
></SPAN
>.</P
><P
>It can be useful to prevent authentication when authorization checking is turned off. The very act of trying to
authenticate can cause problems if the server cannot understand a particular encryption key, as is likely to happen in a key
emergency.</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ129"
>To bypass mutual authentication for bos, kas, pts, and vos commands</A
></H2
><P
>Provide the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-noauth</B
></SPAN
> flag which is available on many of the commands in the suites. To
verify that a command accepts the flag, issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>help</B
></SPAN
> command in its suite, or consult the
command's reference page in the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS Administration Reference</I
></SPAN
> (the reference page also specifies the
shortest acceptable abbreviation for the flag on each command). The suites' <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>apropos</B
></SPAN
> and
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>help</B
></SPAN
> commands do not themselves accept the flag.</P
><P
>You can bypass mutual authentication for all <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas</B
></SPAN
> commands issued during an interactive
session by including the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-noauth</B
></SPAN
> flag on the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas interactive</B
></SPAN
>
command. If you have already entered interactive mode with an authenticated identity, issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>(kas)
noauthentication</B
></SPAN
> command to assume the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>anonymous</B
></SPAN
> identity.</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="Header_151"
>To bypass mutual authentication for fs commands</A
></H2
><P
>This is not possible, except by issuing the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>unlog</B
></SPAN
> command to discard your tokens before
issuing the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs</B
></SPAN
> command.</P
></DIV
></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="HDRWQ130"
>Adding or Removing Disks and Partitions</A
></H1
><P
>AFS makes it very easy to add storage space to your cell, just by adding disks to existing file server machines. This
section explains how to install or remove a disk used to store AFS volumes. (Another way to add storage space is to install
additional server machines, as instructed in the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS Quick Beginnings</I
></SPAN
>.)</P
><P
>Both adding and removing a disk cause at least a brief file system outage, because you must restart the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs</B
></SPAN
> process to have it recognize the new set of server partitions. Some operating systems require that you
shut the machine off before adding or removing a disk, in which case you must shut down all of the AFS server processes first.
Otherwise, the AFS-related aspects of adding or removing a disk are not complicated, so the duration of the outage depends
mostly on how long it takes to install or remove the disk itself.</P
><P
>The following instructions for installing a new disk completely prepare it to house AFS volumes. You can then use the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos create</B
></SPAN
> command to create new volumes, or the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos move</B
></SPAN
>
command to move existing ones from other partitions. For instructions, see <A
HREF="c8420.html#HDRWQ185"
>Creating Read/write
Volumes</A
> and <A
HREF="c8420.html#HDRWQ226"
>Moving Volumes</A
>. The instructions for removing a disk are basically the
reverse of the installation instructions, but include extra steps that protect against data loss.</P
><P
>A server machines can house 256 AFS server partitions, each one mounted at a directory with a name of the form <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/vicep</B
></SPAN
><SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>index</I
></SPAN
>, where <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>index</I
></SPAN
> is one or two lowercase letters. By
convention, the first partition on a machine is mounted at <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/vicepa</B
></SPAN
>, the second at <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/vicepb</B
></SPAN
>, and so on to the twenty-sixth at <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/vicepz</B
></SPAN
>. Additional partitions
are mounted at <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/vicepaa</B
></SPAN
> through <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/vicepaz</B
></SPAN
> and so on up to
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/vicepiv</B
></SPAN
>. Using the letters consecutively is not required, but is simpler.</P
><P
>Mount each <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/vicep</B
></SPAN
> directory directly under the local file system's root directory (
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/</B
></SPAN
> ), not as a subdirectory of any other directory; for example, <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/vicepa</B
></SPAN
> is not an acceptable location. You must also map the directory to the partition's device name
in the file server machine's file systems registry file (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/etc/fstab</B
></SPAN
> or equivalent).</P
><P
>These instructions assume that the machine's AFS initialization file includes the following command to restart the BOS
Server after each reboot. The BOS Server starts the other AFS server processes listed in the local <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/local/BosConfig</B
></SPAN
> file. For information on the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bosserver</B
></SPAN
>
command's optional arguments, see its reference page in the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS Administration Reference</I
></SPAN
>.</P
><PRE
CLASS="programlisting"
>&#13; /usr/afs/bin/bosserver &#38;
</PRE
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ131"
>To add and mount a new disk to house AFS volumes</A
></H2
><OL
TYPE="1"
><LI
><P
>Become the local superuser <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>root</B
></SPAN
> on the machine, if you are not already, by issuing
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>su</B
></SPAN
> command. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>su root</B
></SPAN
>
Password: <VAR
CLASS="replaceable"
>root_password</VAR
>
</PRE
></P
></LI
><LI
><P
>Decide how many AFS partitions to divide the new disk into and the names of the directories at which to mount them
(the introduction to this section describes the naming conventions). To display the names of the existing server
partitions on the machine, issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos listpart</B
></SPAN
> command. Include the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-localauth</B
></SPAN
> flag because you are logged in as the local superuser <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>root</B
></SPAN
> but do not necessarily have administrative tokens. <PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos listpart</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-localauth</B
></SPAN
>
</PRE
></P
><P
>where <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>listp</B
></SPAN
></DT
><DD
><P
>Is the shortest acceptable abbreviation of <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>listpart</B
></SPAN
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>machine name</B
></SPAN
></DT
><DD
><P
>Names the local file server machine.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-localauth</B
></SPAN
></DT
><DD
><P
>Constructs a server ticket using a key from the local <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/KeyFile</B
></SPAN
>
file. The <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> command interpreter presents it to the BOS Server during mutual
authentication.</P
></DD
></DL
></DIV
></P
></LI
><LI
><P
>Create each directory at which to mount a partition. <PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>mkdir /vicep</B
></SPAN
><VAR
CLASS="replaceable"
>x</VAR
>[<VAR
CLASS="replaceable"
>x</VAR
>]
</PRE
></P
></LI
><LI
><P
><A
NAME="LIWQ132"
></A
>Using a text editor, create an entry in the machine's file systems registry file (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/etc/fstab</B
></SPAN
> or equivalent) for each new disk partition, mapping its device name to the directory you
created in the previous step. Refer to existing entries in the file to learn the proper format, which varies for different
operating systems.</P
></LI
><LI
><P
><A
NAME="LIWQ133"
></A
>If the operating system requires that you shut off the machine to install a new disk, issue
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos shutdown</B
></SPAN
> command to shut down all AFS server processes other than the BOS Server
(it terminates safely when you shut off the machine). Include the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-localauth</B
></SPAN
> flag because
you are logged in as the local superuser <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>root</B
></SPAN
> but do not necessarily have administrative
tokens. For a complete description of the command, see <A
HREF="c6449.html#HDRWQ168"
>To stop processes temporarily</A
>.
<PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos shutdown</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-localauth</B
></SPAN
> [<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-wait</B
></SPAN
>]
</PRE
></P
></LI
><LI
><P
><A
NAME="LIWQ134"
></A
>If necessary, shut off the machine. Install and format the new disk according to the
instructions provided by the disk and operating system vendors. If necessary, edit the disk's partition table to reflect
the changes you made to the files system registry file in step <A
HREF="c3025.html#LIWQ132"
>4</A
>; consult the operating
system documentation for instructions.</P
></LI
><LI
><P
>If you shut off the machine down in step <A
HREF="c3025.html#LIWQ134"
>6</A
>, turn it on. Otherwise, issue the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> command to restart the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs</B
></SPAN
> process, forcing
it to recognize the new set of server partitions. Include the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-localauth</B
></SPAN
> flag because you
are logged in as the local superuser <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>root</B
></SPAN
> but do not necessarily have administrative
tokens. For complete instructions for the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> command, see <A
HREF="c6449.html#HDRWQ170"
>Stopping and Immediately Restarting Processes</A
>. <PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs -localauth</B
></SPAN
>
</PRE
></P
></LI
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos status</B
></SPAN
> command to verify that all server processes are running
correctly. For more detailed instructions, see <A
HREF="c6449.html#HDRWQ158"
>Displaying Process Status and Information from the
BosConfig File</A
>. <PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos status</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62;
</PRE
></P
></LI
></OL
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ135"
>To unmount and remove a disk housing AFS volumes</A
></H2
><OL
TYPE="1"
><LI
><P
>Verify that you are listed in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/UserList</B
></SPAN
> file. If necessary, issue
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> command, which is fully described in <A
HREF="c32432.html#HDRWQ593"
>To
display the users in the UserList file</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62;
</PRE
></P
></LI
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos listvol</B
></SPAN
> command to list the volumes housed on each partition of each
disk you are about to remove, in preparation for removing them or moving them to other partitions. For detailed
instructions, see <A
HREF="c8420.html#HDRWQ219"
>Displaying Volume Headers</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos listvol</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; [&#60;<VAR
CLASS="replaceable"
>partition name</VAR
>&#62;]
</PRE
></P
></LI
><LI
><P
>Move any volume you wish to retain in the file system to another partition. You can move only read/write volumes.
For more detailed instructions, and for instructions on moving read-only and backup volumes, see <A
HREF="c8420.html#HDRWQ226"
>Moving Volumes</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos move</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>volume name or ID</VAR
>&#62; \
&#60;<VAR
CLASS="replaceable"
>machine name on source</VAR
>&#62; &#60;<VAR
CLASS="replaceable"
>partition name on source</VAR
>&#62; \
&#60;<VAR
CLASS="replaceable"
>machine name on destination</VAR
>&#62; &#60;<VAR
CLASS="replaceable"
>partition name on destination</VAR
>&#62;
</PRE
></P
></LI
><LI
><P
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>(Optional)</B
></SPAN
> If there are any volumes you do not wish to retain, back them up using
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos dump</B
></SPAN
> command or the AFS Backup System. See <A
HREF="c8420.html#HDRWQ240"
>Dumping and
Restoring Volumes</A
> or <A
HREF="c15383.html#HDRWQ296"
>Backing Up Data</A
>, respectively.</P
></LI
><LI
><P
>Become the local superuser <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>root</B
></SPAN
> on the machine, if you are not already, by issuing
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>su</B
></SPAN
> command. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>su root</B
></SPAN
>
Password: <VAR
CLASS="replaceable"
>root_password</VAR
>
</PRE
></P
></LI
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>umount</B
></SPAN
> command, repeating it for each partition on the disk to be
removed. <PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>cd /</B
></SPAN
>
# <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>umount /dev/</B
></SPAN
>&#60;<VAR
CLASS="replaceable"
>partition_block_device_name</VAR
>&#62;
</PRE
></P
></LI
><LI
><P
><A
NAME="LIWQ136"
></A
>Using a text editor, remove or comment out each partition's entry from the machine's file
systems registry file (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/etc/fstab</B
></SPAN
> or equivalent).</P
></LI
><LI
><P
>Remove the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/vicep</B
></SPAN
> directory associated with each partition. <PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>rmdir /vicep</B
></SPAN
>xx
</PRE
></P
></LI
><LI
><P
>If the operating system requires that you shut off the machine to remove a disk, issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos
shutdown</B
></SPAN
> command to shut down all AFS server processes other than the BOS Server (it terminates safely when you
shut off the machine). Include the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-localauth</B
></SPAN
> flag because you are logged in as the local
superuser <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>root</B
></SPAN
> but do not necessarily have administrative tokens. For a complete
description of the command, see <A
HREF="c6449.html#HDRWQ168"
>To stop processes temporarily</A
>. <PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos shutdown</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-localauth</B
></SPAN
> [<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-wait</B
></SPAN
>]
</PRE
></P
></LI
><LI
><P
><A
NAME="LIWQ137"
></A
>If necessary, shut off the machine. Remove the disk according to the instructions provided by
the disk and operating system vendors. If necessary, edit the disk's partition table to reflect the changes you made to
the files system registry file in step <A
HREF="c3025.html#LIWQ136"
>7</A
>; consult the operating system documentation for
instructions.</P
></LI
><LI
><P
>If you shut off the machine down in step <A
HREF="c3025.html#LIWQ137"
>10</A
>, turn it on. Otherwise, issue the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> command to restart the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs</B
></SPAN
> process, forcing
it to recognize the new set of server partitions. Include the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-localauth</B
></SPAN
> flag because you
are logged in as the local superuser <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>root</B
></SPAN
> but do not necessarily have administrative
tokens. For complete instructions for the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> command, see <A
HREF="c6449.html#HDRWQ170"
>Stopping and Immediately Restarting Processes</A
>. <PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs -localauth</B
></SPAN
>
</PRE
></P
></LI
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos status</B
></SPAN
> command to verify that all server processes are running
correctly. For more detailed instructions, see <A
HREF="c6449.html#HDRWQ158"
>Displaying Process Status and Information from the
BosConfig File</A
>. <PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos status</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62;
</PRE
></P
></LI
></OL
></DIV
></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="HDRWQ138"
>Managing Server IP Addresses and VLDB Server Entries</A
></H1
><P
>The AFS support for multihomed file server machines is largely automatic. The File Server process records the IP addresses
of its file server machine's network interfaces in the local <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/local/sysid</B
></SPAN
> file and also
registers them in a <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>server entry</I
></SPAN
> in the Volume Location Database (VLDB). The <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>sysid</B
></SPAN
> file and server entry are identified by the same unique number, which creates an association
between them.</P
><P
>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.</P
><P
>If you wish, you can control which interfaces the File Server registers in its VLDB server entry by creating two files in
the local <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/local</B
></SPAN
> directory: <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>NetInfo</B
></SPAN
> and <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>NetRestrict</B
></SPAN
>. Each time the File Server restarts, it builds a list of the local machine's interfaces by
reading the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>NetInfo</B
></SPAN
> file, if it exists. If you do not create the file, the File Server uses the
list of network interfaces configured with the operating system. It then removes from the list any addresses that appear in the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>NetRestrict</B
></SPAN
> file, if it exists. The File Server records the resulting list in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>sysid</B
></SPAN
> file and registers the interfaces in the VLDB server entry that has the same unique
identifier.</P
><P
>On database server machines, the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>NetInfo</B
></SPAN
> and <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>NetRestrict</B
></SPAN
>
files also determine which interfaces the Ubik database synchronization library uses when communicating with the database server
processes running on other database server machines.</P
><P
>There is a maximum number of IP addresses in each server entry, as documented in the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS Release
Notes</I
></SPAN
>. If a multihomed file server machine has more interfaces than the maximum, AFS simply ignores the excess ones.
It is probably appropriate for such machines to use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>NetInfo</B
></SPAN
> and <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>NetRestrict</B
></SPAN
> files to control which interfaces are registered.</P
><P
>If for some reason the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>sysid</B
></SPAN
> file no longer exists, the File Server creates a new one
with a new unique identifier. When the File Server registers the contents of the new file, the Volume Location (VL) Server
normally recognizes automatically that the new file corresponds to an existing server entry, and overwrites the existing server
entry with the new file contents and identifier. However, it is best not to remove the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>sysid</B
></SPAN
>
file if that can be avoided.</P
><P
>Similarly, it is important not to copy the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>sysid</B
></SPAN
> file from one file server machine to
another. If you commonly copy the contents of the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs</B
></SPAN
> directory from an existing machine
as part of installing a new file server machine, be sure to remove the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>sysid</B
></SPAN
> file from the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/local</B
></SPAN
> directory on the new machine before starting the File Server.</P
><P
>There are certain cases where the VL Server cannot determine whether it is appropriate to overwrite an existing server
entry with a new <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>sysid</B
></SPAN
> file's contents and identifier. It then refuses to allow the File Server
to register the interfaces, which prevents the File Server from starting. This can happen if, for example, a new <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>sysid</B
></SPAN
> file includes two interfaces that currently are registered by themselves in separate server
entries. In such cases, error messages in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/log/VLLog</B
></SPAN
> file on the VL Server machine
and in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/log/FileLog</B
></SPAN
> file on the file server machine indicate that you need to use
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos changeaddr</B
></SPAN
> command to resolve the problem. Contact the AFS Product Support group for
instructions and assistance.</P
><P
>Except in this type of rare error case, the only appropriate use of the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos changeaddr</B
></SPAN
>
command is to remove a VLDB server entry completely when you remove a file server machine from service. The VLDB can accommodate
a maximum number of server entries, as specified in the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>IBM AFS Release Notes</I
></SPAN
>. Removing obsolete entries
makes it possible to allocate server entries for new file server machines as required. See the instructions that follow.</P
><P
>Do not use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos changeaddr</B
></SPAN
> command to change the list of interfaces registered in a
VLDB server entry. To change a file server machine's IP addresses and server entry, see the instructions that follow.</P
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="Header_156"
>To create or edit the server NetInfo file</A
></H2
><OL
TYPE="1"
><LI
><P
>Become the local superuser <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>root</B
></SPAN
> on the machine, if you are not already, by issuing
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>su</B
></SPAN
> command. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>su root</B
></SPAN
>
Password: <VAR
CLASS="replaceable"
>root_password</VAR
>
</PRE
></P
></LI
><LI
><P
>Using a text editor, open the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/local/NetInfo</B
></SPAN
> file. Place one IP address in
dotted decimal format (for example, <SAMP
CLASS="computeroutput"
>192.12.107.33</SAMP
>) on each line. The order of entries is
not significant.</P
></LI
><LI
><P
>If you want the File Server to start using the revised list immediately, use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos
restart</B
></SPAN
> command to restart the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs</B
></SPAN
> process. For instructions, see <A
HREF="c6449.html#HDRWQ170"
>Stopping and Immediately Restarting Processes</A
>.</P
></LI
></OL
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="Header_157"
>To create or edit the server NetRestrict file</A
></H2
><OL
TYPE="1"
><LI
><P
>Become the local superuser <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>root</B
></SPAN
> on the machine, if you are not already, by issuing
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>su</B
></SPAN
> command. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>su root</B
></SPAN
>
Password: <VAR
CLASS="replaceable"
>root_password</VAR
>
</PRE
></P
></LI
><LI
><P
>Using a text editor, open the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/local/NetRestrict</B
></SPAN
> file. Place one IP address
in dotted decimal format on each line. The order of the addresses is not significant. Use the value <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>255</B
></SPAN
> as a wildcard that represents all possible addresses in that field. For example, the entry
<SAMP
CLASS="computeroutput"
>192.12.105.255</SAMP
> indicates that the Cache Manager does not register any of the addresses in
the 192.12.105 subnet.</P
></LI
><LI
><P
>If you want the File Server to start using the revised list immediately, use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos
restart</B
></SPAN
> command to restart the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs</B
></SPAN
> process. For instructions, see <A
HREF="c6449.html#HDRWQ170"
>Stopping and Immediately Restarting Processes</A
>.</P
></LI
></OL
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="Header_158"
>To display all server entries from the VLDB</A
></H2
><OL
TYPE="1"
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos listaddrs</B
></SPAN
> command to display all server entries from the VLDB.
<PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos listaddrs</B
></SPAN
>
</PRE
></P
><P
>where <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>lista</B
></SPAN
> is the shortest acceptable abbreviation of <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>listaddrs</B
></SPAN
>.</P
><P
>The output displays all server entries from the VLDB, each on its own line. If a file server machine is multihomed,
all of its registered addresses appear on the line. The first one is the one reported as a volume's site in the output
from the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos examine</B
></SPAN
> and <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos listvldb</B
></SPAN
> commands.</P
><P
>VLDB server entries record IP addresses, and the command interpreter has the local name service (either a process
like the Domain Name Service or a local host table) translate them to hostnames before displaying them. If an IP address
appears in the output, it is not possible to translate it.</P
><P
>The existence of an entry does not necessarily indicate that the machine that is still an active file server
machine. To remove obsolete server entries, see the following instructions.</P
></LI
></OL
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="Header_159"
>To remove obsolete server entries from the VLDB</A
></H2
><OL
TYPE="1"
><LI
><P
>Verify that you are listed in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/UserList</B
></SPAN
> file. If necessary, issue
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> command, which is fully described in <A
HREF="c32432.html#HDRWQ593"
>To
display the users in the UserList file</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62;
</PRE
></P
></LI
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos changeaddr</B
></SPAN
> command to remove a server entry from the VLDB.
<PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vos changeaddr</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>original IP address</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-remove</B
></SPAN
>
</PRE
></P
><P
>where <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>ch</B
></SPAN
></DT
><DD
><P
>Is the shortest acceptable abbreviation of <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>changeaddr</B
></SPAN
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>original IP address</B
></SPAN
></DT
><DD
><P
>Specifies one of the IP addresses currently registered for the file server machine in the VLDB. Any of a
multihomed file server machine's addresses are acceptable to identify it.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-remove</B
></SPAN
></DT
><DD
><P
>Removes the server entry.</P
></DD
></DL
></DIV
></P
></LI
></OL
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="Header_160"
>To change a server machine's IP addresses</A
></H2
><OL
TYPE="1"
><LI
><P
>Verify that you are listed in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/UserList</B
></SPAN
> file. If necessary, issue
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> command, which is fully described in <A
HREF="c32432.html#HDRWQ593"
>To
display the users in the UserList file</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62;
</PRE
></P
></LI
><LI
><P
>If the machine is the system control machine or a binary distribution machine, and you are also changing its
hostname, redefine all relevant <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upclient</B
></SPAN
> processes on other server machines to refer to
the new hostname. Use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos delete</B
></SPAN
> and <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos create</B
></SPAN
>
commands as instructed in <A
HREF="c6449.html#HDRWQ161"
>Creating and Removing Processes</A
>.</P
></LI
><LI
><P
>If the machine is a database server machine, edit its entry in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/CellServDB</B
></SPAN
> file on every server machine in the cell to list one of the new IP
addresses. If you use the United States edition of AFS, you can edit the file on the system control machine and wait the
required time (by default, five minutes) for the Update Server to distribute the changed file to all server
machines.</P
></LI
><LI
><P
>If the machine is a database server machine, issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos shutdown</B
></SPAN
> command to stop
all server processes. If the machine is also a file server, the volumes on it are inaccessible during this time. For a
complete description of the command, see <A
HREF="c6449.html#HDRWQ168"
>To stop processes temporarily</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos shutdown</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62;
</PRE
></P
></LI
><LI
><P
>Use the utilities provided with the operating system to change one or more of the machine's IP addresses.</P
></LI
><LI
><P
>If appropriate, edit the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/local/NetInfo</B
></SPAN
> file, the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/local/NetRestrict</B
></SPAN
> file, or both, to reflect the changed addresses. Instructions appear
earlier in this section.</P
></LI
><LI
><P
>If the machine is a database server machine, issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> command to
restart all server processes on the machine. For complete instructions for the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos
restart</B
></SPAN
> command, see <A
HREF="c6449.html#HDRWQ170"
>Stopping and Immediately Restarting Processes</A
>.
<PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-all</B
></SPAN
>
</PRE
></P
><P
>At the same time, issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> command on all other database server
machines in the cell to restart the database server processes only (the Authentication, Backup, Protection, and Volume
Location Servers). Issue the commands in quick succession so that all of the database server processes vote in the quorum
election.</P
><PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kaserver buserver ptserver vlserver</B
></SPAN
>
</PRE
><P
>If you are changing IP addresses on every database server machine in the cell, you must also issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> command on every file server machine in the cell to restart the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs</B
></SPAN
> process.</P
></LI
><LI
><P
>If the machine is not a database server machine, issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> command to
restart the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs</B
></SPAN
> process (if the machine is a database server, you already restarted the
process in the previous step). The File Server automatically compiles a new list of interfaces, records them in the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/local/sysid</B
></SPAN
> file, and registers them in its VLDB server entry. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>fs</B
></SPAN
>
</PRE
></P
></LI
><LI
><P
>If the machine is a database server machine, edit its entry in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/vice/etc/CellServDB</B
></SPAN
> file on every client machine in the cell to list one of the new IP
addresses. Instructions appear in <A
HREF="c21473.html#HDRWQ406"
>Maintaining Knowledge of Database Server
Machines</A
>.</P
></LI
><LI
><P
>If there are machine entries in the Protection Database for the machine's previous IP addresses, use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>pts rename</B
></SPAN
> command to change them to the new addresses. For instructions, see <A
HREF="c29323.html#HDRWQ556"
>Changing a Protection Database Entry's Name</A
>.</P
></LI
></OL
></DIV
></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="HDRWQ139"
>Rebooting a Server Machine</A
></H1
><P
>You can reboot a server machine either by typing the appropriate commands at its console or by issuing the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos exec</B
></SPAN
> command on a remote machine. Remote rebooting can be more convenient, because you do not need to
leave your present location, but you cannot track the progress of the reboot as you can at the console. Remote rebooting is
possible because the server machine's operating system recognizes the BOS Server, which executes the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos
exec</B
></SPAN
> command, as the local superuser <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>root</B
></SPAN
>.</P
><P
>Rebooting server machines is part of routine maintenance in some cells, and some instructions in the AFS documentation
include it as a step. It is certainly not intended to be the standard method for recovering from AFS-related problems, however,
but only a last resort when the machine is unresponsive and you have tried all other reasonable options.</P
><P
>Rebooting causes a service outage. If the machine stores volumes, they are all inaccessible until the reboot completes and
the File Server reattaches them. If the machine is a database server machine, information from the databases can become
unavailable during the reelection of the synchronization site for each database server process; the VL Server outage generally
has the greatest impact, because the Cache Manager must be able to access the VLDB to fetch AFS data.</P
><P
>By convention, a server machine's AFS initialization file includes the following command to restart the BOS Server after
each reboot. It starts the other AFS server processes listed in the local <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/local/BosConfig</B
></SPAN
> file. These instructions assume that the initialization file includes the
command.</P
><PRE
CLASS="programlisting"
>&#13; /usr/afs/bin/bosserver &#38;
</PRE
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ140"
>To reboot a file server machine from its console</A
></H2
><OL
TYPE="1"
><LI
><P
>Become the local superuser <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>root</B
></SPAN
> on the machine, if you are not already, by issuing
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>su</B
></SPAN
> command. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>su root</B
></SPAN
>
Password: <VAR
CLASS="replaceable"
>root_password</VAR
>
</PRE
></P
></LI
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos shutdown</B
></SPAN
> command to shut down all AFS server processes other than the
BOS Server, which terminates safely when you reboot the machine. Include the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-localauth</B
></SPAN
>
flag because you are logged in as the local superuser <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>root</B
></SPAN
> but do not necessarily have
administrative tokens. For a complete description of the command, see <A
HREF="c6449.html#HDRWQ168"
>To stop processes
temporarily</A
>. <PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos shutdown</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-localauth</B
></SPAN
> [<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-wait</B
></SPAN
>]
</PRE
></P
></LI
><LI
><P
>Reboot the machine. On many system types, the appropriate command is <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>shutdown</B
></SPAN
>, but
the appropriate options vary; consult your UNIX administrator's guide. <PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>shutdown</B
></SPAN
>
</PRE
></P
></LI
></OL
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ141"
>To reboot a file server machine remotely</A
></H2
><OL
TYPE="1"
><LI
><P
>Verify that you are listed in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/UserList</B
></SPAN
> file on the machine you are
rebooting. If necessary, issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> command, which is fully described in
<A
HREF="c32432.html#HDRWQ593"
>To display the users in the UserList file</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62;
</PRE
></P
></LI
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos shutdown</B
></SPAN
> to halt AFS server processes other than the BOS Server,
which terminates safely when you turn off the machine. For a complete description of the command, see <A
HREF="c6449.html#HDRWQ168"
>To stop processes temporarily</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos shutdown</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; [<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-wait</B
></SPAN
>]
</PRE
></P
></LI
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos exec</B
></SPAN
> command to reboot the machine remotely. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos exec</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; reboot_command
</PRE
></P
><P
>where <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>machine name</B
></SPAN
></DT
><DD
><P
>Names the file server machine to reboot.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>reboot_command</B
></SPAN
></DT
><DD
><P
>Is the rebooting command for the machine's operating system. The <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>shutdown</B
></SPAN
>
command is appropriate on many system types, but consult your operating system documentation.</P
></DD
></DL
></DIV
></P
></LI
></OL
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="p3023.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="book1.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="c6449.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Managing File Server Machines</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="p3023.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Monitoring and Controlling Server Processes</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
Reference in New Issue View Git Blame Copy Permalink