doc/html/AdminGuide/auagd008.htm

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
   2 <HTML><HEAD>
   3 <TITLE>Administration Guide</TITLE>
   4 <!-- Begin Header Records  ========================================== -->
   5 <!-- /tmp/idwt3570/auagd000.scr converted by idb2h R4.2 (359) ID      -->
   6 <!-- Workbench Version (AIX) on 2 Oct 2000 at 11:42:14                -->
   7 <META HTTP-EQUIV="updated" CONTENT="Mon, 02 Oct 2000 11:42:13">
   8 <META HTTP-EQUIV="review" CONTENT="Tue, 02 Oct 2001 11:42:13">
   9 <META HTTP-EQUIV="expires" CONTENT="Wed, 02 Oct 2002 11:42:13">
  10 </HEAD><BODY>
  11 <!-- (C) IBM Corporation 2000. All Rights Reserved    -->
  12 <BODY bgcolor="ffffff">
  13 <!-- End Header Records  ============================================ -->
  14 <A NAME="Top_Of_Page"></A>
  15 <H1>Administration Guide</H1>
  16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auagd002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auagd007.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auagd009.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auagd026.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
  17 <P>
  18 <A NAME="IDX5840"></A>
  19 <A NAME="IDX5841"></A>
  20 <HR><H1><A NAME="HDRWQ80" HREF="auagd002.htm#ToC_99">Administering Server Machines</A></H1>
  21 <P>This chapter describes how to administer an AFS server
  22 machine. It describes the following configuration information and
  23 administrative tasks:
  24 <UL>
  25 <P><LI>The binary and configuration files that must reside in the subdirectories
  26 of the <B>/usr/afs</B> directory on every server machine's local
  27 disk; see <A HREF="#HDRWQ83">Local Disk Files on a Server Machine</A>.
  28 <P><LI>The various <I>roles</I> or functions that an AFS server machine can
  29 perform, and how to determine which machines are taking a role; see <A HREF="#HDRWQ90">The Four Roles for File Server Machines</A>.
  30 <P><LI>How to maintain database server machines; see <A HREF="#HDRWQ101">Administering Database Server Machines</A>.
  31 <P><LI>How to maintain the list of database server machines in the
  32 <B>/usr/afs/etc/CellServDB</B> file; see <A HREF="#HDRWQ118">Maintaining the Server CellServDB File</A>.
  33 <P><LI>How to control authorization checking on a server machine; see <A HREF="#HDRWQ123">Managing Authentication and Authorization Requirements</A>.
  34 <P><LI>How to install new disks or partitions on a file server machine; see <A HREF="#HDRWQ130">Adding or Removing Disks and Partitions</A>.
  35 <P><LI>How to change a server machine's IP addresses and manager VLDB server
  36 entries; see <A HREF="#HDRWQ138">Managing Server IP Addresses and VLDB Server Entries</A>.
  37 <P><LI>How to reboot a file server machine; see <A HREF="#HDRWQ139">Rebooting a Server Machine</A>.
  38 </UL>
  39 <P>To learn how to install and configure a new server machine, see the
  40 <I>IBM AFS Quick Beginnings</I>.
  41 <P>To learn how to administer the server processes themselves, see <A HREF="auagd009.htm#HDRWQ142">Monitoring and Controlling Server Processes</A>.
  42 <P>To learn how to administer volumes, see <A HREF="auagd010.htm#HDRWQ174">Managing Volumes</A>.
  43 <HR><H2><A NAME="HDRWQ81" HREF="auagd002.htm#ToC_100">Summary of Instructions</A></H2>
  44 <P>This chapter explains how to perform the following tasks by
  45 using the indicated commands:
  46 <BR>
  47 <TABLE WIDTH="100%">
  48 <TR>
  49 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Install new binaries
  50 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>bos install</B>
  51 </TD></TR><TR>
  52 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Examine binary check-and-restart time
  53 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>bos getrestart</B>
  54 </TD></TR><TR>
  55 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Set binary check-and-restart time
  56 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>bos setrestart</B>
  57 </TD></TR><TR>
  58 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Examine compilation dates on binary files
  59 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>bos getdate</B>
  60 </TD></TR><TR>
  61 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Restart a process to use new binaries
  62 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>bos restart</B>
  63 </TD></TR><TR>
  64 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Revert to old version of binaries
  65 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>bos uninstall</B>
  66 </TD></TR><TR>
  67 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Remove obsolete <B>.BAK</B> and <B>.OLD</B>
  68 versions
  69 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>bos prune</B>
  70 </TD></TR><TR>
  71 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">List partitions on a file server machine
  72 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>vos listpart</B>
  73 </TD></TR><TR>
  74 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Shutdown AFS server processes
  75 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>bos shutdown</B>
  76 </TD></TR><TR>
  77 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">List volumes on a partition
  78 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>vos listvldb</B>
  79 </TD></TR><TR>
  80 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Move read/write volumes
  81 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>vos move</B>
  82 </TD></TR><TR>
  83 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">List a cell's database server machines
  84 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>bos listhosts</B>
  85 </TD></TR><TR>
  86 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Add a database server machine to server <B>CellServDB</B> file
  87 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>bos addhost</B>
  88 </TD></TR><TR>
  89 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Remove a database server machine from server <B>CellServDB</B> file
  90 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>bos removehost</B>
  91 </TD></TR><TR>
  92 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Set authorization checking requirements
  93 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>bos setauth</B>
  94 </TD></TR><TR>
  95 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Prevent authentication for <B>bos</B>, <B>pts</B>, and
  96 <B>vos</B> commands
  97 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%">Include <B>-noauth</B> flag
  98 </TD></TR><TR>
  99 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Prevent authentication for kas commands
 100 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%">Include <B>-noauth</B> flag on some commands or issue
 101 <B>noauthentication</B> while in interactive mode
 102 </TD></TR><TR>
 103 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Display all VLDB server entries
 104 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>vos listaddrs</B>
 105 </TD></TR><TR>
 106 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Remove a VLDB server entry
 107 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>vos changeaddr</B>
 108 </TD></TR><TR>
 109 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Reboot a server machine remotely
 110 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>bos exec</B> <I>reboot_command</I>
 111 </TD></TR></TABLE>
 112 <HR><H2><A NAME="HDRWQ83" HREF="auagd002.htm#ToC_101">Local Disk Files on a Server Machine</A></H2>
 113 <P>Several types of files must reside in the subdirectories of
 114 the <B>/usr/afs</B> directory on an AFS server machine's local
 115 disk. They include binaries, configuration files, the administrative
 116 database files (on database server machines), log files, and volume header
 117 files.
 118 <P><B>Note for Windows users:</B> Some files described in this
 119 document possibly do not exist on machines that run a Windows operating
 120 system. Also, Windows uses a backslash
 121 (&nbsp;<B>\</B>&nbsp;) rather than a forward slash
 122 (&nbsp;<B>/</B>&nbsp;) to separate the elements in a
 123 pathname.
 124 <A NAME="IDX5842"></A>
 125 <A NAME="IDX5843"></A>
 126 <A NAME="IDX5844"></A>
 127 <P><H3><A NAME="HDRWQ84" HREF="auagd002.htm#ToC_102">Binaries in the /usr/afs/bin Directory</A></H3>
 128 <P>The <B>/usr/afs/bin</B> directory stores the AFS server
 129 process and command suite binaries appropriate for the machine's system
 130 (CPU and operating system) type. If a process has both a server portion
 131 and a client portion (as with the Update Server) or if it has separate
 132 components (as with the <B>fs</B> process), each component resides in a
 133 separate file.
 134 <P>To ensure predictable system performance, all file server machines must run
 135 the same AFS build version of a given process. To maintain consistency
 136 easily, use the Update Server process to distribute binaries from a
 137 <I>binary distribution machine</I> of each system type, as described
 138 further in <A HREF="#HDRWQ93">Binary Distribution Machines</A>.
 139 <P>It is best to keep the binaries for all processes in the
 140 <B>/usr/afs/bin</B> directory, even if you do not run the process actively
 141 on the machine. It simplifies the process of reconfiguring machines
 142 (for example, adding database server functionality to an existing file server
 143 machine). Similarly, it is best to keep the command suite binaries in
 144 the directory, even if you do not often issue commands while working on the
 145 server machine. It enables you to issue commands during recovery from
 146 server and machine outages.
 147 <P>The following lists the binary files in the <B>/usr/afs/bin</B>
 148 directory that are directly related to the AFS server processes or command
 149 suites. Other binaries (for example, for the <B>klog</B> command)
 150 sometimes appear in this directory on a particular file server machine's
 151 disk or in an AFS distribution.
 152 <DL>
 153 <A NAME="IDX5845"></A>
 154 <A NAME="IDX5846"></A>
 155 <P><DT><B>backup
 156 </B><DD>The command suite for the AFS Backup System (the binary for the Backup
 157 Server is <B>buserver</B>).
 158 <A NAME="IDX5847"></A>
 159 <A NAME="IDX5848"></A>
 160 <P><DT><B>bos
 161 </B><DD>The command suite for communicating with the Basic OverSeer (BOS) Server
 162 (the binary for the BOS Server is <B>bosserver</B>).
 163 <A NAME="IDX5849"></A>
 164 <A NAME="IDX5850"></A>
 165 <A NAME="IDX5851"></A>
 166 <A NAME="IDX5852"></A>
 167 <A NAME="IDX5853"></A>
 168 <A NAME="IDX5854"></A>
 169 <P><DT><B>bosserver
 170 </B><DD>The binary for the Basic OverSeer (BOS) Server process.
 171 <A NAME="IDX5855"></A>
 172 <A NAME="IDX5856"></A>
 173 <A NAME="IDX5857"></A>
 174 <A NAME="IDX5858"></A>
 175 <A NAME="IDX5859"></A>
 176 <A NAME="IDX5860"></A>
 177 <P><DT><B>buserver
 178 </B><DD>The binary for the Backup Server process.
 179 <A NAME="IDX5861"></A>
 180 <A NAME="IDX5862"></A>
 181 <A NAME="IDX5863"></A>
 182 <A NAME="IDX5864"></A>
 183 <A NAME="IDX5865"></A>
 184 <A NAME="IDX5866"></A>
 185 <P><DT><B>fileserver
 186 </B><DD>The binary for the File Server component of the <B>fs</B>
 187 process.
 188 <A NAME="IDX5867"></A>
 189 <A NAME="IDX5868"></A>
 190 <P><DT><B>kas
 191 </B><DD>The command suite for communicating with the Authentication Server (the
 192 binary for the Authentication Server is <B>kaserver</B>).
 193 <A NAME="IDX5869"></A>
 194 <A NAME="IDX5870"></A>
 195 <A NAME="IDX5871"></A>
 196 <A NAME="IDX5872"></A>
 197 <A NAME="IDX5873"></A>
 198 <A NAME="IDX5874"></A>
 199 <P><DT><B>kaserver
 200 </B><DD>The binary for the Authentication Server process.
 201 <A NAME="IDX5875"></A>
 202 <A NAME="IDX5876"></A>
 203 <A NAME="IDX5877"></A>
 204 <A NAME="IDX5878"></A>
 205 <A NAME="IDX5879"></A>
 206 <A NAME="IDX5880"></A>
 207 <P><DT><B>ntpd
 208 </B><DD>The binary for the Network Time Protocol Daemon (NTPD). AFS
 209 redistributes this binary and uses the <B>runntp</B> program to configure
 210 and initialize the NTPD process.
 211 <A NAME="IDX5881"></A>
 212 <A NAME="IDX5882"></A>
 213 <A NAME="IDX5883"></A>
 214 <P><DT><B>ntpdc
 215 </B><DD>A debugging utility furnished with the <B>ntpd</B> program.
 216 <A NAME="IDX5884"></A>
 217 <A NAME="IDX5885"></A>
 218 <P><DT><B>pts
 219 </B><DD>The command suite for communicating with the Protection Server process
 220 (the binary for the Protection Server is <B>ptserver</B>).
 221 <A NAME="IDX5886"></A>
 222 <A NAME="IDX5887"></A>
 223 <A NAME="IDX5888"></A>
 224 <A NAME="IDX5889"></A>
 225 <A NAME="IDX5890"></A>
 226 <A NAME="IDX5891"></A>
 227 <P><DT><B>ptserver
 228 </B><DD>The binary for the Protection Server process.
 229 <A NAME="IDX5892"></A>
 230 <A NAME="IDX5893"></A>
 231 <A NAME="IDX5894"></A>
 232 <A NAME="IDX5895"></A>
 233 <P><DT><B>runntp
 234 </B><DD>The binary for the program used to configure NTPD most appropriately for
 235 use with AFS.
 236 <A NAME="IDX5896"></A>
 237 <A NAME="IDX5897"></A>
 238 <A NAME="IDX5898"></A>
 239 <A NAME="IDX5899"></A>
 240 <A NAME="IDX5900"></A>
 241 <A NAME="IDX5901"></A>
 242 <P><DT><B>salvager
 243 </B><DD>The binary for the Salvager component of the <B>fs</B> process.
 244 <A NAME="IDX5902"></A>
 245 <A NAME="IDX5903"></A>
 246 <A NAME="IDX5904"></A>
 247 <A NAME="IDX5905"></A>
 248 <P><DT><B>udebug
 249 </B><DD>The binary for a program that reports the status of AFS's distributed
 250 database technology, Ubik.
 251 <A NAME="IDX5906"></A>
 252 <A NAME="IDX5907"></A>
 253 <A NAME="IDX5908"></A>
 254 <A NAME="IDX5909"></A>
 255 <A NAME="IDX5910"></A>
 256 <A NAME="IDX5911"></A>
 257 <P><DT><B>upclient
 258 </B><DD>The binary for the client portion of the Update Server process.
 259 <A NAME="IDX5912"></A>
 260 <A NAME="IDX5913"></A>
 261 <A NAME="IDX5914"></A>
 262 <A NAME="IDX5915"></A>
 263 <P><DT><B>upserver
 264 </B><DD>The binary for the server portion of the Update Server process.
 265 <A NAME="IDX5916"></A>
 266 <A NAME="IDX5917"></A>
 267 <A NAME="IDX5918"></A>
 268 <A NAME="IDX5919"></A>
 269 <A NAME="IDX5920"></A>
 270 <A NAME="IDX5921"></A>
 271 <A NAME="IDX5922"></A>
 272 <P><DT><B>vlserver
 273 </B><DD>The binary for the Volume Location (VL) Server process.
 274 <A NAME="IDX5923"></A>
 275 <A NAME="IDX5924"></A>
 276 <A NAME="IDX5925"></A>
 277 <A NAME="IDX5926"></A>
 278 <A NAME="IDX5927"></A>
 279 <A NAME="IDX5928"></A>
 280 <P><DT><B>volserver
 281 </B><DD>The binary for the Volume Server component of the <B>fs</B>
 282 process.
 283 <A NAME="IDX5929"></A>
 284 <A NAME="IDX5930"></A>
 285 <P><DT><B>vos
 286 </B><DD>The command suite for communicating with the Volume and VL Server
 287 processes (the binaries for the servers are <B>volserver</B> and
 288 <B>vlserver</B>, respectively).
 289 </DL>
 290 <A NAME="IDX5931"></A>
 291 <A NAME="IDX5932"></A>
 292 <A NAME="IDX5933"></A>
 293 <A NAME="IDX5934"></A>
 294 <A NAME="IDX5935"></A>
 295 <P><H3><A NAME="HDRWQ85" HREF="auagd002.htm#ToC_103">Common Configuration Files in the /usr/afs/etc Directory</A></H3>
 296 <P>The directory <B>/usr/afs/etc</B> on every file server
 297 machine's local disk contains configuration files in ASCII and
 298 machine-independent binary format. For predictable AFS performance
 299 throughout a cell, all server machines must have the same version of each
 300 configuration file:
 301 <UL>
 302 <A NAME="IDX5936"></A>
 303 <P><LI>Cells that run the United States edition of AFS conventionally use the
 304 Update Server to distribute a common version of each file from the cell's
 305 system control machine to other server machines (for more on the system
 306 control machine, see <A HREF="#HDRWQ94">The System Control Machine</A>). Run the Update Server's server portion on the
 307 system control machine, and the client portion on all other server
 308 machines. Update the files on the system control machine only, except
 309 as directed by instructions for dealing with emergencies.
 310 <P><LI>Cells that run the international edition of AFS must not use the Update
 311 Server to distribute the contents of the <B>/usr/afs/etc</B>
 312 directory. Due to United States government regulations, the data
 313 encryption routines that AFS uses to protect the files in this directory as
 314 they cross the network are not available to the Update Server in the
 315 international edition of AFS. You must instead update the files on each
 316 server machine individually, taking extra care to issue exactly the same
 317 <B>bos</B> command for each machine. The necessary data encryption
 318 routines are available to the <B>bos</B> commands, so information is safe
 319 as it crosses the network from the machine where the <B>bos</B> command is
 320 issued to the server machines.
 321 </UL>
 322 <P>Never directly edit any of the files in the <B>/usr/afs/etc</B>
 323 directory, except as directed by instructions for dealing with
 324 emergencies. In normal circumstances, use the appropriate
 325 <B>bos</B> commands to change the files. The following list
 326 includes pointers to instructions.
 327 <P>The files in this directory include:
 328 <DL>
 329 <A NAME="IDX5937"></A>
 330 <A NAME="IDX5938"></A>
 331 <P><DT><B>CellServDB
 332 </B><DD>An ASCII file that names the cell's database server machines, which
 333 run the Authentication, Backup, Protection, and VL Server processes.
 334 You create the initial version of this file by issuing the <B>bos
 335 setcellname</B> command while installing your cell's first server
 336 machine. It is very important to update this file when you change the
 337 identity of your cell's database server machines.
 338 <P>The server <B>CellServDB</B> file is not the same as the
 339 <B>CellServDB</B> file stored in the <B>/usr/vice/etc</B> directory on
 340 client machines. The client version lists the database server machines
 341 for every AFS cell that you choose to make accessible from the client
 342 machine. The server <B>CellServDB</B> file lists only the local
 343 cell's database server machines, because server processes never contact
 344 processes in other cells.
 345 <P>For instructions on maintaining this file, see <A HREF="#HDRWQ118">Maintaining the Server CellServDB File</A>.
 346 <A NAME="IDX5939"></A>
 347 <A NAME="IDX5940"></A>
 348 <A NAME="IDX5941"></A>
 349 <P><DT><B>KeyFile
 350 </B><DD>A machine-independent, binary-format file that lists the server encryption
 351 keys the AFS server processes use to encrypt and decrypt tickets. The
 352 information in this file is the basis for secure communication in the cell,
 353 and so is extremely sensitive. The file is specially protected so that
 354 only privileged users can read or change it.
 355 <P>For instructions on maintaining this file, see <A HREF="auagd014.htm#HDRWQ355">Managing Server Encryption Keys</A>.
 356 <A NAME="IDX5942"></A>
 357 <A NAME="IDX5943"></A>
 358 <P><DT><B>ThisCell
 359 </B><DD>An ASCII file that consists of a single line defining the complete
 360 Internet domain-style name of the cell (such as
 361 <TT>abc.com</TT>). You create this file with the <B>bos
 362 setcellname</B> command during the installation of your cell's first
 363 file server machine, as instructed in the <I>IBM AFS Quick
 364 Beginnings</I>.
 365 <P>Note that changing this file is only one step in changing your cell's
 366 name. For discussion, see <A HREF="auagd007.htm#HDRWQ34">Choosing a Cell Name</A>.
 367 <A NAME="IDX5944"></A>
 368 <A NAME="IDX5945"></A>
 369 <P><DT><B>UserList
 370 </B><DD>An ASCII file that lists the usernames of the system administrators
 371 authorized to issue privileged <B>bos</B>, <B>vos</B>, and
 372 <B>backup</B> commands. For instructions on maintaining the file,
 373 see <A HREF="auagd021.htm#HDRWQ592">Administering the UserList File</A>.
 374 </DL>
 375 <A NAME="IDX5946"></A>
 376 <A NAME="IDX5947"></A>
 377 <A NAME="IDX5948"></A>
 378 <A NAME="IDX5949"></A>
 379 <P><H3><A NAME="HDRWQ86" HREF="auagd002.htm#ToC_104">Local Configuration Files in the /usr/afs/local Directory</A></H3>
 380 <P>The directory <B>/usr/afs/local</B> contains
 381 configuration files that are different for each file server machine in a
 382 cell. Thus, they are not updated automatically from a central source
 383 like the files in <B>/usr/afs/bin</B> and <B>/usr/afs/etc</B>
 384 directories. The most important file is the <B>BosConfig</B>
 385 file; it defines which server processes are to run on that
 386 machine.
 387 <P>As with the common configuration files in <B>/usr/afs/etc</B>, you must
 388 not edit these files directly. Use commands from the <B>bos</B>
 389 command suite where appropriate; some files never need to be
 390 altered.
 391 <P>The files in this directory include the following:
 392 <DL>
 393 <A NAME="IDX5950"></A>
 394 <A NAME="IDX5951"></A>
 395 <P><DT><B>BosConfig
 396 </B><DD>This file lists the server processes to run on the server machine, by
 397 defining which processes the BOS Server monitors and what it does if the
 398 process fails. It also defines the times at which the BOS Server
 399 automatically restarts processes for maintenance purposes.
 400 <P>As you create server processes during a file server machine's
 401 installation, their entries are defined in this file automatically. The
 402 <I>IBM AFS Quick Beginnings</I> outlines the <B>bos</B> commands to
 403 use. For a more complete description of the file, and instructions for
 404 controlling process status by editing the file with commands from the
 405 <B>bos</B> suite, see <A HREF="auagd009.htm#HDRWQ142">Monitoring and Controlling Server Processes</A>.
 406 <A NAME="IDX5952"></A>
 407 <A NAME="IDX5953"></A>
 408 <P><DT><B>NetInfo
 409 </B><DD>This optional ASCII file lists one or more of the network interface
 410 addresses on the server machine. If it exists when the File Server
 411 initializes, the File Server uses it as the basis for the list of interfaces
 412 that it registers in its Volume Location Database (VLDB) server entry.
 413 See <A HREF="#HDRWQ138">Managing Server IP Addresses and VLDB Server Entries</A>.
 414 <A NAME="IDX5954"></A>
 415 <A NAME="IDX5955"></A>
 416 <P><DT><B>NetRestrict
 417 </B><DD>This optional ASCII file lists one or more network interface
 418 addresses. If it exists when the File Server initializes, the File
 419 Server removes the specified addresses from the list of interfaces that it
 420 registers in its VLDB server entry. See <A HREF="#HDRWQ138">Managing Server IP Addresses and VLDB Server Entries</A>.
 421 <A NAME="IDX5956"></A>
 422 <A NAME="IDX5957"></A>
 423 <P><DT><B>NoAuth
 424 </B><DD>This zero-length file instructs all AFS server processes running on the
 425 machine not to perform authorization checking. Thus, they perform any
 426 action for any user, even <B>anonymous</B>. This very insecure
 427 state is useful only in rare instances, mainly during the installation of the
 428 machine.
 429 <P>The file is created automatically when you start the initial
 430 <B>bosserver</B> process with the <B>-noauth</B> flag, or issue the
 431 <B>bos setauth</B> command to turn off authentication requirements.
 432 When you use the <B>bos setauth</B> command to turn on authentication, the
 433 BOS Server removes this file. For more information, see <A HREF="#HDRWQ123">Managing Authentication and Authorization Requirements</A>.
 434 <A NAME="IDX5958"></A>
 435 <A NAME="IDX5959"></A>
 436 <P><DT><B>SALVAGE.fs
 437 </B><DD>This zero-length file controls how the BOS Server handles a crash of the
 438 File Server component of the <B>fs</B> process. The BOS Server
 439 creates this file each time it starts or restarts the <B>fs</B>
 440 process. If the file is present when the File Server crashes, then the
 441 BOS Server runs the Salvager before restarting the File Server and Volume
 442 Server again. When the File Server exits normally, the BOS Server
 443 removes the file so that the Salvager does not run.
 444 <P>Do not create or remove this file yourself; the BOS Server does so
 445 automatically. If necessary, you can salvage a volume or partition by
 446 using the <B>bos salvage</B> command; see <A HREF="auagd010.htm#HDRWQ232">Salvaging Volumes</A>.
 447 <A NAME="IDX5960"></A>
 448 <A NAME="IDX5961"></A>
 449 <P><DT><B>salvage.lock
 450 </B><DD>This file guarantees that only one Salvager process runs on a file server
 451 machine at a time (the single process can fork multiple subprocesses to
 452 salvage multiple partitions in parallel). As the Salvager initiates
 453 (when invoked by the BOS Server or by issue of the <B>bos salvage</B>
 454 command), it creates this zero-length file and issues the <B>flock</B>
 455 system call on it. It removes the file when it completes the salvage
 456 operation. Because the Salvager must lock the file in order to run,
 457 only one Salvager can run at a time.
 458 <A NAME="IDX5962"></A>
 459 <A NAME="IDX5963"></A>
 460 <A NAME="IDX5964"></A>
 461 <A NAME="IDX5965"></A>
 462 <P><DT><B>sysid
 463 </B><DD>This file records the network interface addresses that the File Server
 464 (<B>fileserver</B> process) registers in its VLDB server entry.
 465 When the Cache Manager requests volume location information, the Volume
 466 Location (VL) Server provides all of the interfaces registered for each server
 467 machine that houses the volume. This enables the Cache Manager to make
 468 use of multiple addresses when accessing AFS data stored on a multihomed file
 469 server machine. For further information, see <A HREF="#HDRWQ138">Managing Server IP Addresses and VLDB Server Entries</A>.
 470 </DL>
 471 <A NAME="IDX5966"></A>
 472 <A NAME="IDX5967"></A>
 473 <A NAME="IDX5968"></A>
 474 <A NAME="IDX5969"></A>
 475 <A NAME="IDX5970"></A>
 476 <A NAME="IDX5971"></A>
 477 <P><H3><A NAME="HDRWQ87" HREF="auagd002.htm#ToC_105">Replicated Database Files in the /usr/afs/db Directory</A></H3>
 478 <P>The directory <B>/usr/afs/db</B> contains two types of
 479 files pertaining to the four replicated databases in the cell--the
 480 Authentication Database, Backup Database, Protection Database, and Volume
 481 Location Database (VLDB):
 482 <UL>
 483 <P><LI>A file that contains each database, with a <B>.DB0</B>
 484 extension.
 485 <P><LI>A log file for each database, with a <B>.DBSYS1</B>
 486 extension. The database server process logs each database operation in
 487 this file before performing it. If the operation is interrupted, the
 488 process consults this file to learn how to finish it.
 489 </UL>
 490 <P>Each database server process (Authentication, Backup, Protection, or VL
 491 Server) maintains its own database and log files. The database files
 492 are in binary format, so you must always access or alter them using commands
 493 from the <B>kas</B> suite (for the Authentication Database),
 494 <B>backup</B> suite (for the Backup Database), <B>pts</B> suite (for
 495 the Protection Database), or <B>vos</B> suite (for the VLDB).
 496 <P>If a cell runs more than one database server machine, each database server
 497 process keeps its own copy of its database on its machine's hard
 498 disk. However, it is important that all the copies of a given database
 499 are the same. To synchronize them, the database server processes call
 500 on AFS's distributed database technology, Ubik, as described in <A HREF="#HDRWQ102">Replicating the AFS Administrative Databases</A>.
 501 <P>The files listed here appear in this directory only on database server
 502 machines. On non-database server machines, this directory is
 503 empty.
 504 <DL>
 505 <A NAME="IDX5972"></A>
 506 <A NAME="IDX5973"></A>
 507 <P><DT><B>bdb.DB0
 508 </B><DD>The Backup Database file.
 509 <A NAME="IDX5974"></A>
 510 <A NAME="IDX5975"></A>
 511 <P><DT><B>bdb.DBSYS1
 512 </B><DD>The Backup Database log file.
 513 <A NAME="IDX5976"></A>
 514 <A NAME="IDX5977"></A>
 515 <P><DT><B>kaserver.DB0
 516 </B><DD>The Authentication Database file.
 517 <A NAME="IDX5978"></A>
 518 <A NAME="IDX5979"></A>
 519 <P><DT><B>kaserver.DBSYS1
 520 </B><DD>The Authentication Database log file.
 521 <A NAME="IDX5980"></A>
 522 <A NAME="IDX5981"></A>
 523 <P><DT><B>prdb.DB0
 524 </B><DD>The Protection Database file.
 525 <A NAME="IDX5982"></A>
 526 <A NAME="IDX5983"></A>
 527 <P><DT><B>prdb.DBSYS1
 528 </B><DD>The Protection Database log file.
 529 <A NAME="IDX5984"></A>
 530 <A NAME="IDX5985"></A>
 531 <P><DT><B>vldb.DB0
 532 </B><DD>The Volume Location Database file.
 533 <A NAME="IDX5986"></A>
 534 <A NAME="IDX5987"></A>
 535 <P><DT><B>vldb.DBSYS1
 536 </B><DD>The Volume Location Database log file.
 537 </DL>
 538 <A NAME="IDX5988"></A>
 539 <A NAME="IDX5989"></A>
 540 <A NAME="IDX5990"></A>
 541 <A NAME="IDX5991"></A>
 542 <A NAME="IDX5992"></A>
 543 <A NAME="IDX5993"></A>
 544 <P><H3><A NAME="HDRWQ88" HREF="auagd002.htm#ToC_106">Log Files in the /usr/afs/logs Directory</A></H3>
 545 <P>The <B>/usr/afs/logs</B> directory contains log files
 546 from various server processes. The files detail interesting events that
 547 occur during normal operations. For instance, the Volume Server can
 548 record volume moves in the <B>VolserLog</B> file. Events are
 549 recorded at completion, so the server processes do not use these files to
 550 reconstruct failed operations unlike the ones in the <B>/usr/afs/db</B>
 551 directory.
 552 <P>The information in log files can be very useful as you evaluate process
 553 failures and other problems. For instance, if you receive a timeout
 554 message when you try to access a volume, checking the <B>FileLog</B> file
 555 possibly provides an explanation, showing that the File Server was unable to
 556 attach the volume. To examine a log file remotely, use the <B>bos
 557 getlog</B> command as described in <A HREF="auagd009.htm#HDRWQ173">Displaying Server Process Log Files</A>.
 558 <P>This directory also contains the core image files generated if a process
 559 being monitored by the BOS Server crashes. The BOS Server attempts to
 560 add an extension to the standard <B>core</B> name to indicate which
 561 process generated the core file (for example, naming a core file generated by
 562 the Protection Server <B>core.ptserver</B>). The BOS Server
 563 cannot always assign the correct extension if two processes fail at about the
 564 same time, so it is not guaranteed to be correct.
 565 <P>The directory contains the following files:
 566 <DL>
 567 <A NAME="IDX5994"></A>
 568 <A NAME="IDX5995"></A>
 569 <P><DT><B>AuthLog
 570 </B><DD>The Authentication Server's log file.
 571 <A NAME="IDX5996"></A>
 572 <A NAME="IDX5997"></A>
 573 <P><DT><B><B>BackupLog</B>
 574 </B><DD>The Backup Server's log file.
 575 <A NAME="IDX5998"></A>
 576 <A NAME="IDX5999"></A>
 577 <P><DT><B><B>BosLog</B>
 578 </B><DD>The BOS Server's log file.
 579 <A NAME="IDX6000"></A>
 580 <A NAME="IDX6001"></A>
 581 <P><DT><B><B>FileLog</B>
 582 </B><DD>The File Server's log file.
 583 <A NAME="IDX6002"></A>
 584 <A NAME="IDX6003"></A>
 585 <P><DT><B><B>SalvageLog</B>
 586 </B><DD>The Salvager's log file.
 587 <A NAME="IDX6004"></A>
 588 <A NAME="IDX6005"></A>
 589 <P><DT><B><B>VLLog</B>
 590 </B><DD>The Volume Location (VL) Server's log file.
 591 <A NAME="IDX6006"></A>
 592 <A NAME="IDX6007"></A>
 593 <P><DT><B><B>VolserLog</B>
 594 </B><DD>The Volume Server's log file.
 595 <P><DT><B><B>core</B>.<VAR>process</VAR>
 596 </B><DD>If present, a core image file produced as an AFS server process on the
 597 machine crashed (probably the process named by <VAR>process</VAR>).
 598 </DL>
 599 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">To prevent log files from growing unmanageably large, restart the server
 600 processes periodically, particularly the database server processes. To
 601 avoid restarting the processes, use the UNIX <B>rm</B> command to remove
 602 the file as the process runs; it re-creates it automatically.
 603 </TD></TR></TABLE>
 604 <A NAME="IDX6008"></A>
 605 <A NAME="IDX6009"></A>
 606 <A NAME="IDX6010"></A>
 607 <A NAME="IDX6011"></A>
 608 <A NAME="IDX6012"></A>
 609 <P><H3><A NAME="HDRWQ89" HREF="auagd002.htm#ToC_107">Volume Headers on Server Partitions</A></H3>
 610 <P>A partition that houses AFS volumes must be mounted at a
 611 subdirectory of the machine's root ( / ) directory (not, for instance
 612 under the <B>/usr</B> directory). The file server machine's
 613 file system registry file (<B>/etc/fstab</B> or equivalent) must correctly
 614 map the directory name and the partition's device name. The
 615 directory name is of the form <B>/vicep</B><VAR>index</VAR>, where each
 616 <VAR>index</VAR> is one or two lowercase letters. By convention, the
 617 first AFS partition on a machine is mounted at <B>/vicepa</B>, the second
 618 at <B>/vicepb</B>, and so on. If there are more than 26 partitions,
 619 continue with <B>/vicepaa</B>, <B>/vicepab</B> and so on. The
 620 <I>IBM AFS Release Notes</I> specifies the number of supported partitions
 621 per server machine.
 622 <P>Do not store non-AFS files on AFS partitions. The File Server and
 623 Volume Server expect to have available all of the space on the
 624 partition.
 625 <P>The <B>/vicep</B> directories contain two types of files:
 626 <DL>
 627 <A NAME="IDX6013"></A>
 628 <A NAME="IDX6014"></A>
 629 <P><DT><B>V<VAR>vol_ID</VAR>.vol
 630 </B><DD>Each such file is a volume header. The <VAR>vol_ID</VAR> corresponds
 631 to the volume ID number displayed in the output from the <B>vos
 632 examine</B>, <B>vos listvldb</B>, and <B>vos listvol</B>
 633 commands.
 634 <A NAME="IDX6015"></A>
 635 <A NAME="IDX6016"></A>
 636 <P><DT><B>FORCESALVAGE
 637 </B><DD>This zero-length file triggers the Salvager to salvage the entire
 638 partition. The AFS-modified version of the <B>fsck</B> program
 639 creates this file if it discovers corruption.
 640 </DL>
 641 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">For most system types, it is important never to run the standard
 642 <B>fsck</B> program provided with the operating system on an AFS file
 643 server machine. It removes all AFS volume data from server partitions
 644 because it does not recognize their format.
 645 </TD></TR></TABLE>
 646 <A NAME="IDX6017"></A>
 647 <A NAME="IDX6018"></A>
 648 <HR><H2><A NAME="HDRWQ90" HREF="auagd002.htm#ToC_108">The Four Roles for File Server Machines</A></H2>
 649 <P>In cells that have more than one server machine, not all
 650 server machines have to perform exactly the same functions. The are
 651 four possible <I>roles</I> a machine can assume, determined by which
 652 server processes it is running. A machine can assume more than one role
 653 by running all of the relevant processes. The following list summarizes
 654 the four roles, which are described more completely in subsequent
 655 sections.
 656 <UL>
 657 <P><LI>A <I>simple file server machine</I> runs only the processes that store
 658 and deliver AFS files to client machines. You can run as many simple
 659 file server machines as you need to satisfy your cell's performance and
 660 disk space requirements.
 661 <P><LI>A <I>database server machine</I> runs the four database server
 662 processes that maintain AFS's replicated administrative databases:
 663 the Authentication, Backup, Protection, and Volume Location (VL) Server
 664 processes.
 665 <P><LI>A <I>binary distribution machine</I> distributes the AFS server
 666 binaries for its system type to all other server machines of that system
 667 type.
 668 <P><LI>The single <I>system control machine</I> distributes common server
 669 configuration files to all other server machines in the cell, in a cell that
 670 runs the United States edition of AFS (cells that use the international
 671 edition of AFS must not use the system control machine for this
 672 purpose). The machine conventionally also serves as the time
 673 synchronization source for the cell, adjusting its clock according to a time
 674 source outside the cell.
 675 </UL>
 676 <P>If a cell has a single server machine, it assumes the simple file server
 677 and database server roles. The instructions in the <I>IBM AFS Quick
 678 Beginnings</I> also have you configure it as the system control machine and
 679 binary distribution machine for its system type, but it does not actually
 680 perform those functions until you install another server machine.
 681 <P>It is best to keep the binaries for all of the AFS server processes in the
 682 <B>/usr/afs/bin</B> directory, even if not all processes are
 683 running. You can then change which roles a machine assumes simply by
 684 starting or stopping the processes that define the role.
 685 <A NAME="IDX6019"></A>
 686 <A NAME="IDX6020"></A>
 687 <P><H3><A NAME="HDRWQ91" HREF="auagd002.htm#ToC_109">Simple File Server Machines</A></H3>
 688 <P>A <I>simple file server machine</I> runs only the server
 689 processes that store and deliver AFS files to client machines, monitor process
 690 status, and pick up binaries and configuration files from the cell's
 691 binary distribution and system control machines.
 692 <P>In general, only cells with more than three server machines need to run
 693 simple file server machines. In cells with three or fewer machines, all
 694 of them are usually database server machines (to benefit from replicating the
 695 administrative databases); see <A HREF="#HDRWQ92">Database Server Machines</A>.
 696 <P>The following processes run on a simple file server machine:
 697 <UL>
 698 <P><LI>The BOS Server (<B>bosserver</B> process)
 699 <P><LI>The <B>fs</B> process, which combines the File Server, Volume Server,
 700 and Salvager processes so that they can coordinate their operations on the
 701 data in volumes and avoid the inconsistencies that can result from multiple
 702 simultaneous operations on the same data
 703 <P><LI>The NTP coordinator (<B>runntp</B> process), which helps keep the
 704 machine's clock synchronized with the clocks on the other server machines
 705 in the cell
 706 <P><LI>A client portion of the Update Server that picks up binary files from the
 707 binary distribution machine of its AFS system type (the <B>upclientbin</B>
 708 process)
 709 <P><LI>A client portion of the Update Server that picks up common configuration
 710 files from the system control machine, in cells running the United States
 711 edition of AFS (the <B>upclientetc</B> process)
 712 </UL>
 713 <A NAME="IDX6021"></A>
 714 <A NAME="IDX6022"></A>
 715 <A NAME="IDX6023"></A>
 716 <A NAME="IDX6024"></A>
 717 <A NAME="IDX6025"></A>
 718 <A NAME="IDX6026"></A>
 719 <P><H3><A NAME="HDRWQ92" HREF="auagd002.htm#ToC_110">Database Server Machines</A></H3>
 720 <P>A <I>database server machine</I> runs the four processes
 721 that maintain the AFS replicated administrative databases: the
 722 Authentication Server, Backup Server, Protection Server, and Volume Location
 723 (VL) Server, which maintain the Authentication Database, Backup Database,
 724 Protection Database, and Volume Location Database (VLDB), respectively.
 725 To review the functions of these server processes and their databases, see <A HREF="auagd006.htm#HDRWQ17">AFS Server Processes and the Cache Manager</A>.
 726 <P>If a cell has more than one server machine, it is best to run more than one
 727 database server machine, but more than three are rarely necessary.
 728 Replicating the databases in this way yields the same benefits as replicating
 729 volumes: increased availability and reliability of information.
 730 If one database server machine or process goes down, the information in the
 731 database is still available from others. The load of requests for
 732 database information is spread across multiple machines, preventing any one
 733 from becoming overloaded.
 734 <P>Unlike replicated volumes, however, replicated databases do change
 735 frequently. Consistent system performance demands that all copies of
 736 the database always be identical, so it is not possible to record changes in
 737 only some of them. To synchronize the copies of a database, the
 738 database server processes use AFS's distributed database technology,
 739 Ubik. See <A HREF="#HDRWQ102">Replicating the AFS Administrative Databases</A>.
 740 <P>It is critical that the AFS server processes on every server machine in a
 741 cell know which machines are the database server machines. The database
 742 server processes in particular must maintain constant contact with their peers
 743 in order to coordinate the copies of the database. The other server
 744 processes often need information from the databases. Every file server
 745 machine keeps a list of its cell's database server machines in its local
 746 <B>/usr/afs/etc/CellServDB</B> file. Cells that use the States
 747 edition of AFS can use the system control machine to distribute this file (see
 748 <A HREF="#HDRWQ94">The System Control Machine</A>).
 749 <P>The following processes define a database server machine:
 750 <UL>
 751 <P><LI>The Authentication Server (<B>kaserver</B> process)
 752 <P><LI>The Backup Server (<B>buserver</B> process)
 753 <P><LI>The Protection Server (<B>ptserver</B> process)
 754 <P><LI>The VL Server (<B>vlserver</B> process)
 755 </UL>
 756 <P>Database server machines can also run the processes that define a simple
 757 file server machine, as listed in <A HREF="#HDRWQ91">Simple File Server Machines</A>. One database server machine can act as the
 758 cell's system control machine, and any database server machine can serve
 759 as the binary distribution machine for its system type; see <A HREF="#HDRWQ94">The System Control Machine</A> and <A HREF="#HDRWQ93">Binary Distribution Machines</A>.
 760 <A NAME="IDX6027"></A>
 761 <A NAME="IDX6028"></A>
 762 <A NAME="IDX6029"></A>
 763 <A NAME="IDX6030"></A>
 764 <P><H3><A NAME="HDRWQ93" HREF="auagd002.htm#ToC_111">Binary Distribution Machines</A></H3>
 765 <P>A <I>binary distribution machine</I> stores and
 766 distributes the binary files for the AFS processes and command suites to all
 767 other server machines of its system type. Each file server machine
 768 keeps its own copy of AFS server process binaries on its local disk, by
 769 convention in the <B>/usr/afs/bin</B> directory. For consistent
 770 system performance, however, all server machines must run the same version
 771 (build level) of a process. For instructions for checking a
 772 binary's build level, see <A HREF="#HDRWQ117">Displaying A Binary File's Build Level</A>. The easiest way to keep the binaries
 773 consistent is to have a binary distribution machine of each system type
 774 distribute them to its system-type peers.
 775 <P>The process that defines a binary distribution machine is the server
 776 portion of the Update Server (<B>upserver</B> process). The client
 777 portion of the Update Server (<B>upclientbin</B> process) runs on the
 778 other server machines of that system type and references the binary
 779 distribution machine.
 780 <P>Binary distribution machines usually also run the processes that define a
 781 simple file server machine, as listed in <A HREF="#HDRWQ91">Simple File Server Machines</A>. One binary distribution machine can act as the
 782 cell's system control machine, and any binary distribution machine can
 783 serve as a database server machine; see <A HREF="#HDRWQ94">The System Control Machine</A> and <A HREF="#HDRWQ92">Database Server Machines</A>.
 784 <A NAME="IDX6031"></A>
 785 <A NAME="IDX6032"></A>
 786 <A NAME="IDX6033"></A>
 787 <P><H3><A NAME="HDRWQ94" HREF="auagd002.htm#ToC_112">The System Control Machine</A></H3>
 788 <P>In cells that run the United States edition of AFS, the
 789 <I>system control machine</I> stores and distributes system configuration
 790 files shared by all of the server machines in the cell. Each file
 791 server machine keeps its own copy of the configuration files on its local
 792 disk, by convention in the <B>/usr/afs/etc</B> directory. For
 793 consistent system performance, however, all server machines must use the same
 794 files. The easiest way to keep the files consistent is to have the
 795 system control machine distribute them. You make changes only to the
 796 copy stored on the system control machine, as directed by the instructions in
 797 this document. The United States edition of AFS is available to cells
 798 in the United States and Canada and to selected institutions in other
 799 countries, as determined by United States government regulations.
 800 <P>Cells that run the international version of AFS do not use the system
 801 control machine to distribute system configuration files. Some of the
 802 files contain information that is too sensitive to cross the network
 803 unencrypted, and United States government regulations forbid the export of the
 804 necessary encryption routines in the form that the Update Server uses.
 805 You must instead update the configuration files on each file server machine
 806 individually. The <B>bos</B> commands that you use to update the
 807 files encrypt the information using an exportable form of the encryption
 808 routines.
 809 <P>For a list of the configuration files stored in the <B>/usr/afs/etc</B>
 810 directory, see <A HREF="#HDRWQ85">Common Configuration Files in the /usr/afs/etc Directory</A>.
 811 <P>The <I>IBM AFS Quick Beginnings</I> configures a cell's first
 812 server machine as the system control machine. If you wish, you can
 813 reassign the role to a different machine that you install later, but you must
 814 then change the client portion of the Update Server (<B>upclientetc</B>)
 815 process running on all other server machines to refer to the new system
 816 control machine.
 817 <P>The following processes define the system control machine:
 818 <UL>
 819 <A NAME="IDX6034"></A>
 820 <A NAME="IDX6035"></A>
 821 <P><LI>The server portion of the Update Server (<B>upserver</B>) process, in
 822 cells using the United States edition of AFS. The client portion of the
 823 Update Server (<B>upclientetc</B> process) runs on the other server
 824 machines and references the system control machine.
 825 <P><LI>The NTP coordinator (<B>runntp</B> process) which points to a time
 826 source outside the cell, if the cell uses NTPD to synchronize its
 827 clocks. The <B>runntp</B> process on other machines reference the
 828 system control machine as their main time source.
 829 </UL>
 830 <P>The system control machine can also run the processes that define a simple
 831 file server machine, as listed in <A HREF="#HDRWQ91">Simple File Server Machines</A>. It can also server as a database server machine, and
 832 by convention acts as the binary distribution machine for its system
 833 type. A single <B>upserver</B> process can distribute both
 834 configuration files and binaries. See <A HREF="#HDRWQ92">Database Server Machines</A> and <A HREF="#HDRWQ93">Binary Distribution Machines</A>.
 835 <A NAME="IDX6036"></A>
 836 <A NAME="IDX6037"></A>
 837 <A NAME="IDX6038"></A>
 838 <A NAME="IDX6039"></A>
 839 <A NAME="IDX6040"></A>
 840 <A NAME="IDX6041"></A>
 841 <A NAME="IDX6042"></A>
 842 <P><H3><A NAME="HDRWQ95" HREF="auagd002.htm#ToC_113">To locate database server machines</A></H3>
 843 <OL TYPE=1>
 844 <P><LI>Issue the <B>bos listhosts</B> command.
 845 <PRE>   % <B>bos listhosts</B> &lt;<VAR>machine&nbsp;name</VAR>>
 846 </PRE>
 847 <P>The machines listed in the output are the cell's database server
 848 machines. For complete instructions and example output, see <A HREF="#HDRWQ120">To display a cell's database server machines</A>.
 849 <P><LI><B>(Optional)</B> Issue the <B>bos status</B> command to verify
 850 that a machine listed in the output of the <B>bos listhosts</B> command is
 851 actually running the processes that define it as a database server
 852 machine. For complete instructions, see <A HREF="auagd009.htm#HDRWQ158">Displaying Process Status and Information from the BosConfig File</A>.
 853 <PRE>   % <B>bos status</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>buserver kaserver ptserver vlserver</B>
 854 </PRE>
 855 <P>If the specified machine is a database server machine, the output from the
 856 <B> bos status</B> command includes the following lines:
 857 <PRE>   Instance buserver, currently running normally.
 858    Instance kaserver, currently running normally.
 859    Instance ptserver, currently running normally.
 860    Instance vlserver, currently running normally.
 861 </PRE>
 862 </OL>
 863 <A NAME="IDX6043"></A>
 864 <A NAME="IDX6044"></A>
 865 <A NAME="IDX6045"></A>
 866 <P><H3><A NAME="HDRWQ96" HREF="auagd002.htm#ToC_114">To locate the system control machine</A></H3>
 867 <OL TYPE=1>
 868 <P><LI>Issue the <B>bos status</B> command for any server machine.
 869 Complete instructions appear in <A HREF="auagd009.htm#HDRWQ158">Displaying Process Status and Information from the BosConfig File</A>.
 870 <PRE>   % <B>bos status</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>upserver upclientbin upclientetc</B> <B>-long</B>
 871 </PRE>
 872 <P>The output you see depends on the machine you have contacted: a
 873 simple file server machine, the system control machine, or a binary
 874 distribution machine. See <A HREF="#HDRWQ98">Interpreting the Output from the bos status Command</A>.
 875 </OL>
 876 <A NAME="IDX6046"></A>
 877 <A NAME="IDX6047"></A>
 878 <A NAME="IDX6048"></A>
 879 <P><H3><A NAME="HDRWQ97" HREF="auagd002.htm#ToC_115">To locate the binary distribution machine for a system type</A></H3>
 880 <OL TYPE=1>
 881 <P><LI>Issue the <B>bos status</B> command for a file server machine of the
 882 system type you are checking (to determine a machine's system type, issue
 883 the <B>fs sysname</B> or <B>sys</B> command as described in <A HREF="auagd015.htm#HDRWQ417">Displaying and Setting the System Type Name</A>. Complete instructions for the <B>bos status</B>
 884 command appear in <A HREF="auagd009.htm#HDRWQ158">Displaying Process Status and Information from the BosConfig File</A>.
 885 <PRE>   % <B>bos status</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>upserver upclientbin upclientetc -long</B>
 886 </PRE>
 887 <P>The output you see depends on the machine you have contacted: a
 888 simple file server machine, the system control machine, or a binary
 889 distribution machine. See <A HREF="#HDRWQ98">Interpreting the Output from the bos status Command</A>.
 890 </OL>
 891 <A NAME="IDX6049"></A>
 892 <A NAME="IDX6050"></A>
 893 <A NAME="IDX6051"></A>
 894 <P><H3><A NAME="HDRWQ98" HREF="auagd002.htm#ToC_116">Interpreting the Output from the bos status Command</A></H3>
 895 <P>Interpreting the output of the <B>bos status</B> command
 896 is most straightforward for a simple file server machine. There is no
 897 <B>upserver</B> process, so the output includes the following
 898 message:
 899 <PRE>   bos: failed to get instance info for 'upserver' (no such entity)
 900 </PRE>
 901 <P>A simple file server machine runs the <B>upclientbin</B> process, so
 902 the output includes a message like the following. It indicates that
 903 <B>fs7.abc.com</B> is the binary distribution machine for
 904 this system type.
 905 <PRE>   Instance upclientbin, (type is simple) currently running normally.
 906    Process last started at Wed Mar 10  23:37:09 1999 (1 proc start)
 907    Command 1 is '/usr/afs/bin/upclient fs7.abc.com -t 60 /usr/afs/bin'
 908 </PRE>
 909 <P>If you run the United States edition of AFS, a simple file server machine
 910 also runs the <B>upclientetc</B> process, so the output includes a message
 911 like the following. It indicates that
 912 <B>fs1.abc.com</B> is the system control machine.
 913 <PRE>   Instance upclientetc, (type is simple) currently running normally.
 914    Process last started at Mon Mar 22  05:23:49 1999 (1 proc start)
 915    Command 1 is '/usr/afs/bin/upclient fs1.abc.com -t 60 /usr/afs/etc'
 916 </PRE>
 917 <P><H4><A NAME="HDRWQ99">The Output on the System Control Machine</A></H4>
 918 <P>If you run the United States edition of AFS and have issued
 919 the <B>bos status</B> command for the system control machine, the output
 920 includes an entry for the <B>upserver</B> process similar to the
 921 following:
 922 <PRE>   Instance upserver, (type is simple) currently running normally.
 923    Process last started at Mon Mar 22 05:23:54 1999 (1 proc start)
 924    Command 1 is '/usr/afs/bin/upserver'
 925 </PRE>
 926 <P>If you are using the default configuration recommended in the <I>IBM AFS
 927 Quick Beginnings</I>, the system control machine is also the binary
 928 distribution machine for its system type, and a single <B>upserver</B>
 929 process distributes both kinds of updates. In that case, the output
 930 includes the following messages:
 931 <PRE>   bos: failed to get instance info for 'upclientbin' (no such entity)
 932    bos: failed to get instance info for 'upclientetc' (no such entity)
 933 </PRE>
 934 <P>If the system control machine is not a binary distribution machine, the
 935 output includes an error message for the <B>upclientetc</B> process, but a
 936 complete a listing for the <B>upclientbin</B> process (in this case it
 937 refers to the machine <B>fs5.abc.com</B> as the binary
 938 distribution machine):
 939 <PRE>   Instance upclientbin, (type is simple) currently running normally.
 940    Process last started at Mon Mar 22  05:23:49 1999 (1 proc start)
 941    Command 1 is '/usr/afs/bin/upclient fs5.abc.com -t 60 /usr/afs/bin'
 942    bos: failed to get instance info for 'upclientetc' (no such entity)
 943 </PRE>
 944 <P><H4><A NAME="HDRWQ100">The Output on a Binary Distribution Machine</A></H4>
 945 <P>If you have issued the <B>bos status</B> command for a
 946 binary distribution machine, the output includes an entry for the
 947 <B>upserver</B> process similar to the following and error message for the
 948 <B>upclientbin</B> process:
 949 <PRE>   Instance upserver, (type is simple) currently running normally.
 950    Process last started at Mon Apr 5 05:23:54 1999 (1 proc start)
 951    Command 1 is '/usr/afs/bin/upserver'
 952    bos: failed to get instance info for 'upclientbin' (no such entity)
 953 </PRE>
 954 <P>Unless this machine also happens to be the system control machine, a
 955 message like the following references the system control machine (in this
 956 case, <B>fs3.abc.com</B>):
 957 <PRE>   Instance upclientetc, (type is simple) currently running normally.
 958    Process last started at Mon Apr 5 05:23:49 1999 (1 proc start)
 959    Command 1 is '/usr/afs/bin/upclient fs3.abc.com -t 60 /usr/afs/etc'
 960 </PRE>
 961 <HR><H2><A NAME="HDRWQ101" HREF="auagd002.htm#ToC_119">Administering Database Server Machines</A></H2>
 962 <P>This section explains how to administer database server
 963 machines. For installation instructions, see the <I>IBM AFS Quick
 964 Beginnings</I>.
 965 <A NAME="IDX6052"></A>
 966 <A NAME="IDX6053"></A>
 967 <A NAME="IDX6054"></A>
 968 <A NAME="IDX6055"></A>
 969 <A NAME="IDX6056"></A>
 970 <A NAME="IDX6057"></A>
 971 <A NAME="IDX6058"></A>
 972 <A NAME="IDX6059"></A>
 973 <A NAME="IDX6060"></A>
 974 <A NAME="IDX6061"></A>
 975 <A NAME="IDX6062"></A>
 976 <P><H3><A NAME="HDRWQ102" HREF="auagd002.htm#ToC_120">Replicating the AFS Administrative Databases</A></H3>
 977 <P>There are several benefits to replicating the AFS
 978 administrative databases (the Authentication, Backup, Protection, and Volume
 979 Location Databases), as discussed in <A HREF="auagd007.htm#HDRWQ52">Replicating the AFS Administrative Databases</A>. For correct cell functioning, the copies of each
 980 database must be identical at all times. To keep the databases
 981 synchronized, AFS uses library of utilities called <I>Ubik</I>.
 982 Each database server process runs an associated lightweight Ubik process, and
 983 client-side programs call Ubik's client-side subroutines when they submit
 984 requests to read and change the databases.
 985 <P>Ubik is designed to work with minimal administrator intervention, but there
 986 are several configuration requirements, as detailed in <A HREF="#HDRWQ103">Configuring the Cell for Proper Ubik Operation</A>. The following brief overview of Ubik's
 987 operation is helpful for understanding the requirements. For more
 988 details, see <A HREF="#HDRWQ104">How Ubik Operates Automatically</A>.
 989 <P>Ubik is designed to distribute changes made in an AFS administrative
 990 database to all copies as quickly as possible. Only one copy of the
 991 database, the <I>synchronization site</I>, accepts change requests from
 992 clients; the lightweight Ubik process running there is the <I>Ubik
 993 coordinator</I>. To maintain maximum availability, there is a
 994 separate Ubik coordinator for each database, and the synchronization site for
 995 each of the four databases can be on a different machine. The
 996 synchronization site for a database can also move from machine to machine in
 997 response to process, machine, or network outages.
 998 <P>The other copies of a database, and the Ubik processes that maintain them,
 999 are termed <I>secondary</I>. The secondary sites do not accept
1000 database changes directly from client-side programs, but only from the
1001 synchronization site.
1002 <P>After the Ubik coordinator records a change in its copy of a database, it
1003 immediately sends the change to the secondary sites. During the brief
1004 distribution period, clients cannot access any of the copies of the database,
1005 even for reading. If the coordinator cannot reach a majority of the
1006 secondary sites, it halts the distribution and informs the client that the
1007 attempted change failed.
1008 <P>To avoid distribution failures, the Ubik processes maintain constant
1009 contact by exchanging time-stamped messages. As long as a majority of
1010 the secondary sites respond to the coordinator's messages, there is a
1011 <I>quorum</I> of sites that are synchronized with the coordinator.
1012 If a process, machine, or network outage breaks the quorum, the Ubik processes
1013 attempt to elect a new coordinator in order to establish a new quorum among
1014 the highest possible number of sites. See <A HREF="#HDRWQ106">A Flexible Coordinator Boosts Availability</A>.
1015 <A NAME="IDX6063"></A>
1016 <A NAME="IDX6064"></A>
1017 <A NAME="IDX6065"></A>
1018 <P><H4><A NAME="HDRWQ103">Configuring the Cell for Proper Ubik Operation</A></H4>
1019 <P>This section describes how to configure your cell to
1020 maintain proper Ubik operation.
1021 <UL>
1022 <P><LI>Run all four database server processes--Authentication Server, Backup
1023 Server, Protection Server, and VL Server--on all database server
1024 machines.
1025 <P>Both the client and server portions of Ubik expect that all the database
1026 server machines listed in the <B>CellServDB</B> file are running all of
1027 the database server processes. There is no mechanism for indicating
1028 that only some database server processes are running on a machine.
1029 <P><LI>Maintain correct information in the <B>/usr/afs/etc/CellServDB</B>
1030 file at all times.
1031 <P>Ubik consults the <B>/usr/afs/etc/CellServDB</B> file to determine the
1032 sites with which to establish and maintain a quorum. Incorrect
1033 information can result in unsynchronized databases or election of a
1034 coordinator in each of several subgroups of machines, because the Ubik
1035 processes on various machines do not agree on which machines need to
1036 participate in the quorum.
1037 <P>If you run the United States version of AFS and use the Update Server, it
1038 is simplest to maintain the <B>/usr/afs/etc/CellServDB</B> file on the
1039 system control machine, which distributes its copy to all other server
1040 machines. The <I>IBM AFS Quick Beginnings</I> explains how to
1041 configure the Update Server. If you run the international version of
1042 AFS, you must update the file on each machine individually.
1043 <P>The only reason to alter the file is when configuring or decommissioning a
1044 database server machine. Use the appropriate <B>bos</B> commands
1045 rather than editing the file by hand. For instructions, see <A HREF="#HDRWQ118">Maintaining the Server CellServDB File</A>. The instructions in <A HREF="auagd009.htm#HDRWQ142">Monitoring and Controlling Server Processes</A> for stopping and starting processes remind
1046 you to alter the <B>CellServDB</B> file when appropriate, as do the
1047 instructions in the <I>IBM AFS Quick Beginnings</I> for installing or
1048 decommissioning a database server machine.
1049 <P>(Client processes and the server processes that do not maintain databases
1050 also rely on correct information in the <B>CellServDB</B> file for proper
1051 operation, but their use of the information does not affect Ubik's
1052 operation. See <A HREF="#HDRWQ118">Maintaining the Server CellServDB File</A> and <A HREF="auagd015.htm#HDRWQ406">Maintaining Knowledge of Database Server Machines</A>.)
1053 <A NAME="IDX6066"></A>
1054 <P><LI>Keep the clocks synchronized on all machines in the cell, especially the
1055 database server machines.
1056 <P>In the conventional configuration specified in the <I>IBM AFS Quick
1057 Beginnings</I>, you run the <B>runntp</B> process to supervise the local
1058 Network Time Protocol Daemon (NTPD) on every AFS server machine. The
1059 NTPD on the system control machine synchronizes its clock with a reliable
1060 source outside the cell and broadcasts the time to the NTPDs on the other
1061 server machines. You can choose to run a different time synchronization
1062 protocol if you wish.
1063 <P>Keeping clocks synchronized is important because the Ubik processes at a
1064 database's sites timestamp the messages which they exchange to maintain
1065 constant contact. Timestamping the messages is necessary because in a
1066 networked environment it is not safe to assume that a message reaches its
1067 destination instantly. Ubik compares the timestamp on an incoming
1068 message with the current time. If the difference is too great, it is
1069 possible that an outage is preventing reliable communication between the Ubik
1070 sites, which can possibly result in unsynchronized databases. Ubik
1071 considers the message invalid, which can prompt it to attempt election of a
1072 different coordinator.
1073 <P>Electing a new coordinator is appropriate if a timestamped message is
1074 expired due to actual interruption of communication, but not if a message
1075 appears expired only because the sender and recipient do not share the same
1076 time. For detailed examples of how unsynchronized clocks can
1077 destabilize Ubik operation, see <A HREF="#HDRWQ105">How Ubik Uses Timestamped Messages</A>.
1078 </UL>
1079 <A NAME="IDX6067"></A>
1080 <A NAME="IDX6068"></A>
1081 <A NAME="IDX6069"></A>
1082 <P><H4><A NAME="HDRWQ104">How Ubik Operates Automatically</A></H4>
1083 <P>The following Ubik features help keep its maintenance
1084 requirements to a minimum:
1085 <UL>
1086 <P><LI>Ubik's server and client portions operate automatically.
1087 <P>Each database server process runs a lightweight process to call on the
1088 server portion of the Ubik library. It is common to refer to this
1089 lightweight process itself as Ubik. Because it is lightweight, the Ubik
1090 process does not appear in process listings such as those generated by the
1091 UNIX <B>ps</B> command. Client-side programs that need to read and
1092 change the databases directly call the subroutines in the Ubik library's
1093 client portion, rather than running a separate lightweight process.
1094 Examples of such programs are the <B>klog</B> command and the commands in
1095 the <B>pts</B> suite.
1096 <P><LI>Ubik tracks database version numbers.
1097 <P>As the coordinator records a change to a database, it increments the
1098 database's version number. The version number makes it easy for
1099 the coordinator to determine if a site has the most recent version or
1100 not. The version number speeds the return to normal functioning after
1101 election of a new coordinator or when communication is restored after an
1102 outage, because it makes it easy to determine which site has the most current
1103 database and which need to be updated.
1104 <P><LI>Ubik's use of timestamped messages guarantees that database copies
1105 are always synchronized during normal operation.
1106 <P>Replicating a database to increase data availability is pointless if all
1107 copies of the database are not the same. Inconsistent performance can
1108 result if clients receive different information depending on which copy of the
1109 database they access. As previously noted, Ubik sites constantly track
1110 the status of their peers by exchanging timestamped messages. For a
1111 detailed description, see <A HREF="#HDRWQ105">How Ubik Uses Timestamped Messages</A>.
1112 <P><LI>The ability to move the coordinator maximizes database
1113 availability.
1114 <P>Suppose, for example, that in a cell with three database server machines a
1115 network partition separates the two secondary sites from the
1116 coordinator. The coordinator retires because it is no longer in contact
1117 with a majority of the sites listed in the <B>CellServDB</B> file.
1118 The two sites on the other side of the partition can elect a new coordinator
1119 among themselves, and it can then accept database changes from clients.
1120 If the coordinator cannot move in this way, the database has to be read-only
1121 until the network partition is repaired. For a detailed description of
1122 Ubik's election procedure, see <A HREF="#HDRWQ106">A Flexible Coordinator Boosts Availability</A>.
1123 </UL>
1124 <A NAME="IDX6070"></A>
1125 <A NAME="IDX6071"></A>
1126 <P><H5><A NAME="HDRWQ105">How Ubik Uses Timestamped Messages</A></H5>
1127 <P>Ubik synchronizes the copies of a database by maintaining
1128 constant contact between the synchronization site and the secondary
1129 sites. The Ubik coordinator frequently sends a time-stamped
1130 <I>guarantee</I> message to each of the secondary sites. When the
1131 secondary site receives the message, it concludes that it is in contact with
1132 the coordinator. It considers its copy of the database to be valid
1133 until time <I>T</I>, which is usually 60 seconds from the time the
1134 coordinator sent the message. In response, the secondary site returns a
1135 <I>vote</I> message that acknowledges the coordinator as valid until a
1136 certain time X, which is usually 120 seconds in the future.
1137 <P>The coordinator sends guarantee messages more frequently than every
1138 <I>T</I> seconds, so that the expiration periods overlap. There is
1139 no danger of expiration unless a network partition or other outage actually
1140 interrupts communication. If the guarantee expires, the secondary
1141 site's copy of the database it not necessarily current.
1142 Nonetheless, the database server continues to service client requests.
1143 It is considered better for overall cell functioning that a secondary site
1144 remains accessible even if the information it is distributing is possibly out
1145 of date. Most of the AFS administrative databases do not change that
1146 frequently, in any case, and making a database inaccessible causes a timeout
1147 for clients that happen to access that copy.
1148 <P>As previously mentioned, Ubik's use of timestamped messages makes it
1149 vital to synchronize the clocks on database server machines. There are
1150 two ways that skewed clocks can interrupt normal Ubik functioning, depending
1151 on which clock is ahead of the others.
1152 <P>Suppose, for example, that the Ubik coordinator's clock is ahead of
1153 the secondary sites: the coordinator's clock says
1154 9:35:30, but the secondary clocks say 9:31:30.
1155 The secondary sites send votes messages that acknowledge the coordinator as
1156 valid until 9:33:30. This is two minutes in the future
1157 according to the secondary clocks, but is already in the past from the
1158 coordinator's perspective. The coordinator concludes that it no
1159 longer has enough support to remain coordinator and forces election of a new
1160 coordinator. Election takes about three minutes, during which time no
1161 copy of the database accepts changes.
1162 <P>The opposite possibility is that a secondary site's clock
1163 (14:50:00) is ahead of the coordinator's
1164 (14:46:30). When the coordinator sends a guarantee message
1165 good until 14:47:30), it has already expired according to the
1166 secondary clock. Believing that it is out of contact with the
1167 coordinator, the secondary site stops sending votes for the coordinator and
1168 tries get itself elected as coordinator. This is appropriate if the
1169 coordinator has actually failed, but is inappropriate when there is no actual
1170 outage.
1171 <P>The attempt of a single secondary site to get elected as the new
1172 coordinator usually does not affect the performance of the other sites.
1173 As long as their clocks agree with the coordinator's, they ignore the
1174 other secondary site's request for votes and continue voting for the
1175 current coordinator. However, if enough of the secondary sites's
1176 clocks get ahead of the coordinator's, they can force election of a new
1177 coordinator even though the current one is actually working fine.
1178 <A NAME="IDX6072"></A>
1179 <A NAME="IDX6073"></A>
1180 <A NAME="IDX6074"></A>
1181 <A NAME="IDX6075"></A>
1182 <A NAME="IDX6076"></A>
1183 <A NAME="IDX6077"></A>
1184 <A NAME="IDX6078"></A>
1185 <A NAME="IDX6079"></A>
1186 <A NAME="IDX6080"></A>
1187 <P><H5><A NAME="HDRWQ106">A Flexible Coordinator Boosts Availability</A></H5>
1188 <P>Ubik uses timestamped messages to determine when coordinator
1189 election is necessary, just as it does to keep the database copies
1190 synchronized. As long as the coordinator receives vote messages from a
1191 majority of the sites (it implicitly votes for itself), it is appropriate for
1192 it to continue as coordinator because it is successfully distributing database
1193 changes. A majority is defined as more than 50% of all database sites
1194 when there are an odd number of sites; with an even number of sites, the
1195 site with the lowest Internet address has an extra vote for breaking ties as
1196 necessary.If the coordinator is not receiving sufficient votes, it
1197 retires and the Ubik sites elect a new coordinator. This does not
1198 happen spontaneously, but only when the coordinator really fails or stops
1199 receiving a majority of the votes. The secondary sites have a built-in
1200 bias to continue voting for an existing coordinator, which prevents undue
1201 elections.
1202 <P>The election of the new coordinator is by majority vote. The Ubik
1203 subprocesses have a bias to vote for the site with the lowest Internet
1204 address, which helps it gather the necessary majority quicker than if all the
1205 sites were competing to receive votes themselves. During the election
1206 (which normally lasts less than three minutes), clients can read information
1207 from the database, but cannot make any changes.
1208 <P>Ubik's election procedure makes it possible for each database server
1209 process's coordinator to be on a different machine. For example,
1210 if the Ubik coordinators for all four processes start out on machine A and the
1211 Protection Server on machine A fails for some reason, then a different site
1212 (say machine B) must be elected as the new Protection Database Ubik
1213 coordinator. Machine B remains the coordinator for the Protection
1214 Database even after the Protection Server on machine A is working
1215 again. The failure of the Protection Server has no effect on the
1216 Authentication, Backup, or VL Servers, so their coordinators remain on machine
1217 A.
1218 <P><H3><A NAME="HDRWQ107" HREF="auagd002.htm#ToC_125">Backing Up and Restoring the Administrative Databases</A></H3>
1219 <P>The AFS administrative databases store information that is
1220 critical for AFS operation in your cell. If a database becomes
1221 corrupted due to a hardware failure or other problem on a database server
1222 machine, it likely to be difficult and time-consuming to recreate all of the
1223 information from scratch. To protect yourself against loss of data,
1224 back up the administrative databases to a permanent media, such as tape, on a
1225 regular basis. The recommended method is to use a standard local disk
1226 backup utility such as the UNIX <B>tar</B> command.
1227 <P>When deciding how often to back up a database, consider the amount of data
1228 that you are willing to recreate by hand if it becomes necessary to restore
1229 the database from a backup copy. In most cells, the databases differ
1230 quite a bit in how often and how much they change. Changes to the
1231 Authentication Database are probably the least frequent, and consist mostly of
1232 changed user passwords. Protection Database and VLDB changes are
1233 probably more frequent, as users add or delete groups and change group
1234 memberships, and as you and other administrators create or move
1235 volumes. The number and frequency of changes is probably greatest in
1236 the Backup Database, particularly if you perform backups every day.
1237 <P>The ease with which you can recapture lost changes also differs for the
1238 different databases:
1239 <UL>
1240 <P><LI>If regular users make a large proportion of the changes to the
1241 Authentication Database and Protection Database in your cell, then recovering
1242 them possibly requires a large amount of detective work and interviewing of
1243 users, assuming that they can even remember what changes they made at what
1244 time.
1245 <P><LI>Recovering lost changes to the VLDB is more straightforward, because you
1246 can use the <B>vos syncserv</B> and <B>vos syncvldb</B> commands to
1247 correct any discrepancies between the VLDB and the actual state of volumes on
1248 server machines. Running these commands can be time-consuming,
1249 however.
1250 <P><LI>The configuration information in the Backup Database (Tape Coordinator
1251 port offsets, volume sets and entries, the dump hierarchy, and so on) probably
1252 does not change that often, in which case it is not that hard to recover a few
1253 recent changes. In contrast, there are likely to be a large number of
1254 new dump records resulting from dump operations. You can recover these
1255 records by using the <B>-dbadd</B> argument to the <B>backup
1256 scantape</B> command, reading in information from the backup tapes
1257 themselves. This can take a long time and require numerous tape
1258 changes, however, depending on how much data you back up in your cell and how
1259 you append dumps. Furthermore, the <B>backup scantape</B> command
1260 is subject to several restrictions. The most basic is that it halts if
1261 it finds that an existing dump record in the database has the same dump ID
1262 number as a dump on the tape it is scanning. If you want to continue
1263 with the scanning operation, you must locate and remove the existing record
1264 from the database. For further discussion, see the <B>backup
1265 scantape</B> command's reference page in the <I>IBM AFS
1266 Administration Reference</I>.
1267 </UL>
1268 <P>These differences between the databases possibly suggest backing up the
1269 database at different frequencies, ranging from every few days or weekly for
1270 the Backup Database to every few weeks for the Authentication Database.
1271 On the other hand, it is probably simpler from a logistical standpoint to back
1272 them all up at the same time (and frequently), particularly if tape
1273 consumption is not a major concern. Also, it is not generally necessary
1274 to keep backup copies of the databases for a long time, so you can recycle the
1275 tapes fairly frequently.
1276 <A NAME="IDX6081"></A>
1277 <A NAME="IDX6082"></A>
1278 <P><H3><A NAME="HDRWQ108" HREF="auagd002.htm#ToC_126">To back up the administrative databases</A></H3>
1279 <OL TYPE=1>
1280 <P><LI>Log in as the local superuser <B>root</B> on a database server machine
1281 that is not the synchronization site. The machine with the highest IP
1282 address is normally the best choice, since it is least likely to become the
1283 synchronization site in an election.
1284 <P><LI><A NAME="LIDBBK_SHUTDOWN"></A>Issue the <B>bos shutdown</B> command to shut down
1285 the relevant server process on the local machine. For a complete
1286 description of the command, see <A HREF="auagd009.htm#HDRWQ168">To stop processes temporarily</A>.
1287 <P>For the <B>-instance</B> argument, specify one or more database server
1288 process names (<B>buserver</B> for the Backup Server, <B>kaserver</B>
1289 for the Authentication Server, <B>ptserver</B> for the Protection Server,
1290 or <B>vlserver</B> for the Volume Location Server. Include the
1291 <B>-localauth</B> flag because you are logged in as the local superuser
1292 <B>root</B> but do not necessarily have administrative tokens.
1293 <PRE>   # <B>bos shutdown</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>-instance</B> &lt;<VAR>instances</VAR>><SUP>+</SUP> <B>-localauth</B> [<B>-wait</B>]
1294 </PRE>
1295 <P><LI>Use a local disk backup utility, such as the UNIX <B>tar</B> command,
1296 to transfer one or more database files to tape. If the local database
1297 server machine does not have a tape device attached, use a remote copy command
1298 to transfer the file to a machine with a tape device, then use the
1299 <B>tar</B> command there.
1300 <P>The following command sequence backs up the complete contents of the
1301 <B>/usr/afs/db</B> directory
1302 <PRE>   # <B>cd /usr/afs/db</B>
1303    # <B>tar cvf</B>  <VAR>tape_device</VAR> <B> .</B>
1304 </PRE>
1305 <P>To back up individual database files, substitute their names for the period
1306 in the preceding <B>tar</B> command:
1307 <UL>
1308 <P><LI><B>bdb.DB0</B> for the Backup Database
1309 <P><LI><B>kaserver.DB0</B> for the Authentication Database
1310 <P><LI><B>prdb.DB0</B> for the Protection Database
1311 <P><LI><B>vldb.DB0</B> for the VLDB
1312 </UL>
1313 <P><LI>Issue the <B>bos start</B> command to restart the server processes on
1314 the local machine. For a complete description of the command, see <A HREF="auagd009.htm#HDRWQ166">To start processes by changing their status flags to Run</A>. Provide the same values for the <B>-instance</B>
1315 argument as in Step <A HREF="#LIDBBK_SHUTDOWN">2</A>, and the <B>-localauth</B> flag for the same
1316 reason.
1317 <PRE>   # <B>bos start</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>-instance</B> &lt;<VAR>server&nbsp;process&nbsp;name</VAR>><SUP>+</SUP> <B>-localauth</B>
1318 </PRE>
1319 </OL>
1320 <A NAME="IDX6083"></A>
1321 <A NAME="IDX6084"></A>
1322 <P><H3><A NAME="HDRWQ109" HREF="auagd002.htm#ToC_127">To restore an administrative database</A></H3>
1323 <OL TYPE=1>
1324 <P><LI>Log in as the local superuser <B>root</B> on each database server
1325 machine in the cell.
1326 <P><LI><A NAME="LIDBREST_SHUTDOWN"></A>Working on one of the machines, issue the <B>bos
1327 shutdown</B> command once for each database server machine, to shut down the
1328 relevant server process on all of them. For a complete description of
1329 the command, see <A HREF="auagd009.htm#HDRWQ168">To stop processes temporarily</A>.
1330 <P>For the <B>-instance</B> argument, specify one or more database server
1331 process names (<B>buserver</B> for the Backup Server, <B>kaserver</B>
1332 for the Authentication Server, <B>ptserver</B> for the Protection Server,
1333 or <B>vlserver</B> for the Volume Location Server. Include the
1334 <B>-localauth</B> flag because you are logged in as the local superuser
1335 <B>root</B> but do not necessarily have administrative tokens.
1336 <PRE>   # <B>bos shutdown</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>-instance</B> &lt;<VAR>instances</VAR>><SUP>+</SUP> <B>-localauth</B> [<B>-wait</B>]
1337 </PRE>
1338 <P><LI>Remove the database from each database server machine, by issuing the
1339 following commands on each one.
1340 <PRE>   # <B>cd /usr/afs/db</B>
1341 </PRE>
1342 <P>For the Backup Database:
1343 <PRE>   # <B>rm bdb.DB0</B>
1344    # <B>rm bdb.DBSYS1</B>
1345 </PRE>
1346 <P>For the Authentication Database:
1347 <PRE>   # <B>rm kaserver.DB0</B>
1348    # <B>rm kaserver.DBSYS1</B>
1349 </PRE>
1350 <P>For the Protection Database:
1351 <PRE>   # <B>rm prdb.DB0</B>
1352    # <B>rm prdb.DBSYS1</B>
1353 </PRE>
1354 <P>For the VLDB:
1355 <PRE>   # <B>rm vldb.DB0</B>
1356    # <B>rm vldb.DBSYS1</B>
1357 </PRE>
1358 <P><LI>Using the local disk backup utility that you used to back up the database,
1359 copy the most recently backed-up version of it to the appropriate file on the
1360 database server machine with the lowest IP address. The following is an
1361 appropriate <B>tar</B> command if the synchronization site has a tape
1362 device attached:
1363 <PRE>   # <B>cd /usr/afs/db</B>
1364    # <B>tar xvf</B> <VAR>tape_device  database_file</VAR>
1365 </PRE>
1366 <P>where <I>database_file</I> is one of the following:
1367 <UL>
1368 <P><LI><B>bdb.DB0</B> for the Backup Database
1369 <P><LI><B>kaserver.DB0</B> for the Authentication Database
1370 <P><LI><B>prdb.DB0</B> for the Protection Database
1371 <P><LI><B>vldb.DB0</B> for the VLDB
1372 </UL>
1373 <P><LI>Working on one of the machines, issue the <B>bos start</B> command to
1374 restart the server process on each of the database server machines in
1375 turn. Start with the machine with the lowest IP address, which becomes
1376 the synchronization site for the Backup Database. Wait for it to
1377 establish itself as the synchronization site before repeating the command to
1378 restart the process on the other database server machines. For a
1379 complete description of the command, see <A HREF="auagd009.htm#HDRWQ166">To start processes by changing their status flags to Run</A>. Provide the same values for the <B>-instance</B>
1380 argument as in Step <A HREF="#LIDBREST_SHUTDOWN">2</A>, and the <B>-localauth</B> flag for the same
1381 reason.
1382 <PRE>   # <B>bos start</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>-instance</B>  &lt;<VAR>server&nbsp;process&nbsp;name</VAR>><SUP>+</SUP>  <B>-localauth</B>
1383 </PRE>
1384 <P><LI>If the database has changed since you last backed it up, issue the
1385 appropriate commands from the instructions in the indicated sections to
1386 recreate the information in the restored database. If issuing
1387 <B>pts</B> commands, you must first obtain administrative tokens.
1388 The <B>backup</B> and <B>vos</B> commands accept the
1389 <B>-localauth</B> flag if you are logged in as the local superuser
1390 <B>root</B>, so you do not need administrative tokens. The
1391 Authentication Server always performs a separate authentication anyway, so you
1392 only need to include the <B>-admin</B> argument if issuing <B>kas</B>
1393 commands.
1394 <UL>
1395 <P><LI>To define or remove volume sets and volume entries in the Backup Database,
1396 see <A HREF="auagd011.htm#HDRWQ265">Defining and Displaying Volume Sets and Volume Entries</A>.
1397 <P><LI>To edit the dump hierarchy in the Backup Database, see <A HREF="auagd011.htm#HDRWQ267">Defining and Displaying the Dump Hierarchy</A>.
1398 <P><LI>To define or remove Tape Coordinator port offset entries in the Backup
1399 Database, see <A HREF="auagd011.htm#HDRWQ261">Configuring Tape Coordinator Machines and Tape Devices</A>.
1400 <P><LI>To restore dump records in the Backup Database, see <A HREF="auagd012.htm#HDRWQ305">To scan the contents of a tape</A>.
1401 <P><LI>To recreate Authentication Database entries or password changes for users,
1402 see the appropriate section of <A HREF="auagd018.htm#HDRWQ491">Administering User Accounts</A>.
1403 <P><LI>To recreate Protection Database entries or group membership information,
1404 see the appropriate section of <A HREF="auagd019.htm#HDRWQ531">Administering the Protection Database</A>.
1405 <P><LI>To synchronize the VLDB with volume headers, see <A HREF="auagd010.htm#HDRWQ227">Synchronizing the VLDB and Volume Headers</A>.
1406 </UL>
1407 </OL>
1408 <A NAME="IDX6085"></A>
1409 <A NAME="IDX6086"></A>
1410 <A NAME="IDX6087"></A>
1411 <A NAME="IDX6088"></A>
1412 <A NAME="IDX6089"></A>
1413 <A NAME="IDX6090"></A>
1414 <HR><H2><A NAME="HDRWQ110" HREF="auagd002.htm#ToC_128">Installing Server Process Software</A></H2>
1415 <P>This section explains how to install new server process
1416 binaries on file server machines, how to revert to a previous version if the
1417 current version is not working properly, and how to install new disks to house
1418 AFS volumes on a file server machine.
1419 <P>The most frequent reason to replace a server process's binaries is to
1420 upgrade AFS to a new version. In general, installation instructions
1421 accompany the updated software, but this chapter provides an additional
1422 reference.
1423 <P>Each AFS server machine must store the server process binaries in a local
1424 disk directory, called <B>/usr/afs/bin</B> by convention. For
1425 predictable system performance, it is best that all server machines run the
1426 same build level, or at least the same version, of the server software.
1427 For instructions on checking AFS build level, see <A HREF="#HDRWQ117">Displaying A Binary File's Build Level</A>.
1428 <P>The Update Server makes it easy to distribute a consistent version of
1429 software to all server machines. You designate one server machine of
1430 each system type as the <I>binary distribution machine</I> by running the
1431 server portion of the Update Server (<B>upserver</B> process) on
1432 it. All other server machines of that system type run the client
1433 portion of the Update Server (<B>upclientbin</B> process) to retrieve
1434 updated software from the binary distribution machine. The <I>IBM AFS
1435 Quick Beginnings</I> explains how to install the appropriate
1436 processes. For more on binary distribution machines, see <A HREF="#HDRWQ93">Binary Distribution Machines</A>.
1437 <P>When you use the Update Server, you install new binaries on binary
1438 distribution machines only. If you install binaries directly on a
1439 machine that is running the <B>upclientbin</B> process, they are
1440 overwritten the next time the process compares the contents of the local
1441 <B>/usr/afs/bin</B> directory to the contents on the system control
1442 machine, by default within five minutes.
1443 <P>The following instructions explain how to use the appropriate commands from
1444 the <B>bos</B> suite to install and uninstall server binaries.
1445 <A NAME="IDX6091"></A>
1446 <A NAME="IDX6092"></A>
1447 <A NAME="IDX6093"></A>
1448 <A NAME="IDX6094"></A>
1449 <A NAME="IDX6095"></A>
1450 <P><H3><A NAME="HDRWQ111" HREF="auagd002.htm#ToC_129">Installing New Binaries</A></H3>
1451 <P>An AFS server process does not automatically switch to a new
1452 process binary file as soon as it is installed in the <B>/usr/afs/bin</B>
1453 directory. The process continues to use the previous version of the
1454 binary file until it (the process) next restarts. By default, the BOS
1455 Server restarts processes for which there are new binary files every day at
1456 5:00 a.m., as specified in the
1457 <B>/usr/afs/local/BosConfig</B> file. To display or change this
1458 <I>binary restart time</I>, use the <B>bos getrestart</B> and <B>bos
1459 setrestart</B> commands, as described in <A HREF="auagd009.htm#HDRWQ171">Setting the BOS Server's Restart Times</A>.
1460 <P>You can force the server machine to start using new server process binaries
1461 immediately by issuing the <B>bos restart</B> command as described in the
1462 following instructions.
1463 <P>You do not need to restart processes when you install new command suite
1464 binaries. The new binary is invoked automatically the next time a
1465 command from the suite is issued.
1466 <A NAME="IDX6096"></A>
1467 <A NAME="IDX6097"></A>
1468 <A NAME="IDX6098"></A>
1469 <A NAME="IDX6099"></A>
1470 <A NAME="IDX6100"></A>
1471 <P>When you use the <B>bos install</B> command, the BOS Server
1472 automatically saves the current version of a binary file by adding a
1473 <B>.BAK</B> extension to its name. It renames the current
1474 <B>.BAK</B> version, if any, to the <B>.OLD</B> version,
1475 if there is no <B>.OLD</B> version already. If there is a
1476 current <B>.OLD</B> version, the current <B>.BAK</B>
1477 version must be at least seven days old to replace it.
1478 <P>It is best to store AFS binaries in the <B>/usr/afs/bin</B> directory,
1479 because that is the only directory the BOS Server automatically checks for new
1480 binaries. You can, however, use the <B>bos install</B>
1481 command's <B>-dir</B> argument to install non-AFS binaries into other
1482 directories on a server machine's local disk. See the
1483 command's reference page in the <I>IBM AFS Administration
1484 Reference</I> for further information.
1485 <A NAME="IDX6101"></A>
1486 <A NAME="IDX6102"></A>
1487 <P><H3><A NAME="Header_130" HREF="auagd002.htm#ToC_130">To install new server binaries</A></H3>
1488 <OL TYPE=1>
1489 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
1490 file. If necessary, issue the <B>bos listusers</B> command, which
1491 is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
1492 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1493 </PRE>
1494 <P><LI>Verify that the binaries are available in the source directory from which
1495 you are installing them. If the machine is also an AFS client, you can
1496 retrieve the binaries from a central directory in AFS. Otherwise, you
1497 can obtain them directly from the AFS distribution media, from a local disk
1498 directory where you previously installed them, or from a remote machine using
1499 a transfer utility such as the <B>ftp</B> command.
1500 <P><LI><A NAME="LIWQ112"></A>Issue the <B>bos install</B> command for the binary
1501 distribution machine. (If you have forgotten which machine is
1502 performing that role, see <A HREF="#HDRWQ97">To locate the binary distribution machine for a system type</A>.)
1503 <PRE>   % <B>bos install</B> &lt;<VAR>machine&nbsp;name</VAR>> &lt;<VAR>files&nbsp;to&nbsp;install</VAR>><SUP>+</SUP>
1504 </PRE>
1505 <P>where
1506 <DL>
1507 <P><DT><B>i
1508 </B><DD>Is the shortest acceptable abbreviation of <B>install</B>.
1509 <P><DT><B><VAR>machine name</VAR>
1510 </B><DD>Names the binary distribution machine.
1511 <P><DT><B><VAR>files to install</VAR>
1512 </B><DD>Names each binary file to install into the local <B>/usr/afs/bin</B>
1513 directory. Partial pathnames are interpreted relative to the current
1514 working directory. The last element in each pathname (the filename
1515 itself) matches the name of the file it is replacing, such as
1516 <B>bosserver</B> or <B>volserver</B> for server processes,
1517 <B>bos</B> or <B>vos</B> for commands.
1518 <P>Each AFS server process other than the <B>fs</B> process uses a single
1519 binary file. The <B>fs</B> process uses three binary files:
1520 <B>fileserver</B>, <B>volserver</B>, and <B>salvager</B>.
1521 Installing a new version of one component does not necessarily mean that you
1522 need to replace all three.
1523 </DL>
1524 <P><LI>Repeat Step <A HREF="#LIWQ112">3</A> for each binary distribution machine.
1525 <P><LI><B>(Optional)</B> If you want to restart processes to use the new
1526 binaries immediately, wait until the <B>upclientbin</B> process retrieves
1527 them from the binary distribution machine. You can verify the
1528 timestamps on binary files by using the <B>bos getdate</B> command as
1529 described in <A HREF="#HDRWQ115">Displaying Binary Version Dates</A>. When the binary files are available on each server
1530 machine, issue the <B>bos restart</B> command, for which complete
1531 instructions appear in <A HREF="auagd009.htm#HDRWQ170">Stopping and Immediately Restarting Processes</A>.
1532 <P>If you are working on an AFS client machine, it is a wise precaution to
1533 have a copy of the <B>bos</B> command suite binaries on the local disk
1534 before restarting server processes. In the conventional configuration,
1535 the <B>/usr/afsws/bin</B> directory that houses the <B>bos</B> command
1536 binary on client machines is a symbolic link into AFS, which conserves local
1537 disk space. However, restarting certain processes (particularly the
1538 database server processes) can make the AFS filespace inaccessible,
1539 particularly if a problem arises during the restart. Having a local
1540 copy of the <B>bos</B> binary enables you to uninstall or reinstall
1541 process binaries or restart processes even in this case. Use the
1542 <B>cp</B> command to copy the <B>bos</B> command binary from the
1543 <B>/usr/afsws/bin</B> directory to a local directory such as
1544 <B>/tmp</B>.
1545 <P>Restarting a process causes a service outage. It is best to perform
1546 the restart at times of low system usage if possible.
1547 <PRE>   % <B>bos restart</B> &lt;<VAR>machine&nbsp;name</VAR>> &lt;<VAR>instances</VAR>><SUP>+</SUP>
1548 </PRE>
1549 </OL>
1550 <A NAME="IDX6103"></A>
1551 <A NAME="IDX6104"></A>
1552 <A NAME="IDX6105"></A>
1553 <A NAME="IDX6106"></A>
1554 <A NAME="IDX6107"></A>
1555 <A NAME="IDX6108"></A>
1556 <A NAME="IDX6109"></A>
1557 <A NAME="IDX6110"></A>
1558 <P><H3><A NAME="HDRWQ113" HREF="auagd002.htm#ToC_131">Reverting to the Previous Version of Binaries</A></H3>
1559 <P>In rare cases, installing a new binary can cause problems
1560 serious enough to require reverting to the previous version. Just as
1561 with installing binaries, consistent system performance requires reverting
1562 every server machine back to the same version. Issue the <B>bos
1563 uninstall</B> command described here on each binary distribution
1564 machine.
1565 <P>When you use the <B>bos uninstall</B> command, the BOS Server discards
1566 the current version of a binary file and promotes the <B>.BAK</B>
1567 version of the file by removing the extension. It renames the current
1568 <B>.OLD</B> version, if any, to <B>.BAK</B>.
1569 <P>If there is no current <B>.BAK</B> version, the <B>bos
1570 uninstall</B> command operation fails and generates an error message.
1571 If a <B>.OLD</B> version still exists, issue the <B>mv</B>
1572 command to rename it to <B>.BAK</B> before reissuing the <B>bos
1573 uninstall</B> command.
1574 <P>Just as when you install new binaries, the server processes do not start
1575 using a reverted version immediately. Presumably you are reverting
1576 because the current binaries do not work, so the following instructions have
1577 you restart the relevant processes.
1578 <A NAME="IDX6111"></A>
1579 <A NAME="IDX6112"></A>
1580 <P><H3><A NAME="Header_132" HREF="auagd002.htm#ToC_132">To revert to the previous version of binaries</A></H3>
1581 <OL TYPE=1>
1582 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
1583 file. If necessary, issue the <B>bos listusers</B> command, which
1584 is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
1585 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1586 </PRE>
1587 <P><LI>Verify that the <B>.BAK</B> version of each relevant binary is
1588 available in the <B>/usr/afs/bin</B> directory on each binary distribution
1589 machine. If necessary, you can use the <B>bos getdate</B> command
1590 as described in <A HREF="#HDRWQ115">Displaying Binary Version Dates</A>. If necessary, rename the <B>.OLD</B>
1591 version to <B>.BAK</B>
1592 <P><LI><A NAME="LIWQ114"></A>Issue the <B>bos uninstall</B> command for a binary
1593 distribution machine. (If you have forgotten which machine is
1594 performing that role, see <A HREF="#HDRWQ97">To locate the binary distribution machine for a system type</A>.)
1595 <PRE>   % <B>bos uninstall</B> &lt;<VAR>machine&nbsp;name</VAR>> &lt;<VAR>files&nbsp;to&nbsp;uninstall</VAR>><SUP>+</SUP>
1596 </PRE>
1597 <P>where
1598 <DL>
1599 <P><DT><B>u
1600 </B><DD>Is the shortest acceptable abbreviation of <B>uninstall</B>.
1601 <P><DT><B><VAR>machine name</VAR>
1602 </B><DD>Names the binary distribution machine.
1603 <P><DT><B><VAR>files to uninstall</VAR>
1604 </B><DD>Names each binary file in the <B>/usr/afs/bin</B> directory to replace
1605 with its <B>.BAK</B> version. The file name alone is
1606 sufficient, because the <B>/usr/afs/bin</B> directory is assumed.
1607 </DL>
1608 <P><LI>Repeat Step <A HREF="#LIWQ114">3</A> for each binary distribution machine.
1609 <P><LI>Wait until the <B>upclientbin</B> process on each server machine
1610 retrieves the reverted from the binary distribution machine. You can
1611 verify the timestamps on binary files by using the <B>bos getdate</B>
1612 command as described in <A HREF="#HDRWQ115">Displaying Binary Version Dates</A>. When the binary files are available on each server
1613 machine, issue the <B>bos restart</B> command, for which complete
1614 instructions appear in <A HREF="auagd009.htm#HDRWQ170">Stopping and Immediately Restarting Processes</A>.
1615 <P>If you are working on an AFS client machine, it is a wise precaution to
1616 have a copy of the <B>bos</B> command suite binaries on the local disk
1617 before restarting server processes. In the conventional configuration,
1618 the <B>/usr/afsws/bin</B> directory that houses the <B>bos</B> command
1619 binary on client machines is a symbolic link into AFS, which conserves local
1620 disk space. However, restarting certain processes (particularly the
1621 database server processes) can make the AFS filespace inaccessible,
1622 particularly if a problem arises during the restart. Having a local
1623 copy of the <B>bos</B> binary enables you to uninstall or reinstall
1624 process binaries or restart processes even in this case. Use the
1625 <B>cp</B> command to copy the <B>bos</B> command binary from the
1626 <B>/usr/afsws/bin</B> directory to a local directory such as
1627 <B>/tmp</B>.
1628 <PRE>   % <B>bos restart</B> &lt;<VAR>machine&nbsp;name</VAR>> &lt;<VAR>instances</VAR>><SUP>+</SUP>
1629 </PRE>
1630 </OL>
1631 <A NAME="IDX6113"></A>
1632 <A NAME="IDX6114"></A>
1633 <A NAME="IDX6115"></A>
1634 <A NAME="IDX6116"></A>
1635 <A NAME="IDX6117"></A>
1636 <A NAME="IDX6118"></A>
1637 <P><H3><A NAME="HDRWQ115" HREF="auagd002.htm#ToC_133">Displaying Binary Version Dates</A></H3>
1638 <P>You can check the compilation dates for all three versions
1639 of a binary file in the <B>/usr/afs/bin</B> directory--the current,
1640 <B>.BAK</B> and .<B>OLD</B> versions. This is
1641 useful for verifying that new binaries have been copied to a file server
1642 machine from its binary distribution machine before restarting a server
1643 process to use the new binaries.
1644 <P>To check dates on binaries in a directory other than <B>
1645 /usr/afs/bin</B>, add the <B>-dir</B> argument. See the <I>IBM
1646 AFS Administration Reference</I>.
1647 <A NAME="IDX6119"></A>
1648 <A NAME="IDX6120"></A>
1649 <P><H3><A NAME="Header_134" HREF="auagd002.htm#ToC_134">To display binary version dates</A></H3>
1650 <OL TYPE=1>
1651 <P><LI>Issue the <B>bos getdate</B> command.
1652 <PRE>   % <B>bos getdate</B> &lt;<VAR>machine&nbsp;name</VAR>> &lt;<VAR>files&nbsp;to&nbsp;check</VAR>><SUP>+</SUP>
1653 </PRE>
1654 <P>where
1655 <DL>
1656 <P><DT><B>getd
1657 </B><DD>Is the shortest acceptable abbreviation of <B>getdate</B>.
1658 <P><DT><B><VAR>machine name</VAR>
1659 </B><DD>Name the file server machine for which to display binary dates.
1660 <P><DT><B><VAR>files to check</VAR>
1661 </B><DD>Names each binary file to display.
1662 </DL>
1663 </OL>
1664 <A NAME="IDX6121"></A>
1665 <A NAME="IDX6122"></A>
1666 <A NAME="IDX6123"></A>
1667 <A NAME="IDX6124"></A>
1668 <A NAME="IDX6125"></A>
1669 <A NAME="IDX6126"></A>
1670 <A NAME="IDX6127"></A>
1671 <A NAME="IDX6128"></A>
1672 <P><H3><A NAME="HDRWQ116" HREF="auagd002.htm#ToC_135">Removing Obsolete Binary Files</A></H3>
1673 <P>When processes with new binaries have been running without
1674 problems for a number of days, it is generally safe to remove the
1675 <B>.BAK</B> and <B>.OLD</B> versions from the
1676 <B>/usr/afs/bin</B> directory, both to reduce clutter and to free space on
1677 the file server machine's local disk.
1678 <P>You can use the <B>bos prune</B> command's flags to remove the
1679 following types of files:
1680 <UL>
1681 <P><LI>To remove files in the <B>/usr/afs/bin</B> directory with a
1682 <B>.BAK</B> extension, use the <B>-bak</B> flag.
1683 <P><LI>To remove files in the <B>/usr/afs/bin</B> directory with a
1684 <B>.OLD</B> extension, use the <B>-old</B> flag.
1685 <P><LI>To remove files in the <B>/usr/afs/logs</B> directory called
1686 <B>core</B>, with any extension, use the <B>-core</B> flag.
1687 <P><LI>To remove all three types of files, use the <B>-all</B> flag.
1688 </UL>
1689 <A NAME="IDX6129"></A>
1690 <A NAME="IDX6130"></A>
1691 <P><H3><A NAME="Header_136" HREF="auagd002.htm#ToC_136">To remove obsolete binaries</A></H3>
1692 <OL TYPE=1>
1693 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
1694 file. If necessary, issue the <B>bos listusers</B> command, which
1695 is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
1696 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1697 </PRE>
1698 <P><LI>Issue the <B>bos prune</B> command with one or more of its
1699 flags.
1700 <PRE>   % <B>bos prune</B> &lt;<VAR>machine&nbsp;name</VAR>> [<B>-bak</B>] [<B>-old</B>] [<B>-core</B>] [<B>-all</B>]
1701 </PRE>
1702 <P>where
1703 <DL>
1704 <P><DT><B>p
1705 </B><DD>Is the shortest acceptable abbreviation of <B>prune</B>.
1706 <P><DT><B><VAR>machine name</VAR>
1707 </B><DD>Names the file server machine on which to remove obsolete files.
1708 <P><DT><B>-bak
1709 </B><DD>Removes all the files with a <B>.BAK</B> extension from the
1710 <B>/usr/afs/bin</B> directory. Do not combine this flag with the
1711 <B>-all</B> flag.
1712 <P><DT><B>-old
1713 </B><DD>Removes all the files a .<B>OLD</B> extension from the
1714 <B>/usr/afs/bin</B> directory. Do not combine this flag with the
1715 <B>-all</B> flag.
1716 <P><DT><B>-core
1717 </B><DD>Removes all core files from the <B>/usr/afs/logs</B> directory.
1718 Do not combine this flag with the <B>-all</B> flag
1719 <P><DT><B>-all
1720 </B><DD>Combines the effect of the other three flags. Do not combine it
1721 with the other three flags.
1722 </DL>
1723 </OL>
1724 <P><H3><A NAME="HDRWQ117" HREF="auagd002.htm#ToC_137">Displaying A Binary File's Build Level</A></H3>
1725 <P>For the most consistent performance on a server machine, and
1726 cell-wide, it is best for all server processes to come from the same AFS
1727 distribution. Every AFS binary includes an ASCII string that specifies
1728 its version, or <I>build level</I>. To display it, use the
1729 <B>strings</B> and <B>grep</B> commands, which are included in most
1730 UNIX distributions.
1731 <A NAME="IDX6131"></A>
1732 <A NAME="IDX6132"></A>
1733 <A NAME="IDX6133"></A>
1734 <A NAME="IDX6134"></A>
1735 <P><H3><A NAME="Header_138" HREF="auagd002.htm#ToC_138">To display an AFS binary's build level</A></H3>
1736 <OL TYPE=1>
1737 <P><LI>Change to the directory that houses the binary file . If you are
1738 not sure where the binary resides, issue the <B>which</B> command.
1739 <PRE>   % <B>which</B> <VAR>binary_file</VAR>
1740    /<VAR>bin_dir_path</VAR>/<VAR>binary_file</VAR>
1741    % <B>cd</B> <VAR>bin_dir_path</VAR>
1742 </PRE>
1743 <P><LI>Issue the <B>strings</B> command to extract all ASCII strings from the
1744 binary file. Pipe the output to the <B>grep</B> command to locate
1745 the relevant line.
1746 <PRE>   % <B>strings ./</B><VAR>binary_file</VAR> <B>| grep Base</B>
1747 </PRE>
1748 <P>The output reports the AFS build level in a format like the
1749 following:
1750 <PRE>   @(#)Base configuration afs<VAR>version</VAR>  <VAR>build_level</VAR>
1751 </PRE>
1752 <P>For example, the following string indicates the binary is from AFS
1753 3.6 build 3.0:
1754 <PRE>   @(#)Base configuration afs3.6 3.0
1755 </PRE>
1756 </OL>
1757 <A NAME="IDX6135"></A>
1758 <A NAME="IDX6136"></A>
1759 <A NAME="IDX6137"></A>
1760 <A NAME="IDX6138"></A>
1761 <A NAME="IDX6139"></A>
1762 <HR><H2><A NAME="HDRWQ118" HREF="auagd002.htm#ToC_139">Maintaining the Server CellServDB File</A></H2>
1763 <P>Every file server machine maintains a list of its home
1764 cell's database server machines in the local disk file
1765 <B>/usr/afs/etc/CellServDB</B> on its local disk. Both database
1766 server processes and non-database server processes consult the file:
1767 <UL>
1768 <P><LI>The database server processes (the Authentication, Backup, Protection, and
1769 Volume Location Servers) maintain constant contact with their peers in order
1770 to keep their copies of the replicated administrative databases
1771 synchronized.
1772 <P>As detailed in <A HREF="#HDRWQ102">Replicating the AFS Administrative Databases</A>, the database server processes use the Ubik utility to
1773 synchronize the information in the databases they maintain. The Ubik
1774 coordinator at the synchronization site for each database maintains the single
1775 read/write copy of the database and distributes changes to the secondary sites
1776 as necessary. It must maintain contact with a majority of the secondary
1777 sites to remain the coordinator, and consults the <B>CellServDB</B> file
1778 to learn how many peers it has and on which machines they are running.
1779 <P>If the coordinator loses contact with the majority of its peers, they all
1780 cooperate to elect a new coordinator by majority vote. During the
1781 election, all of the Ubik processes consult the <B>CellServDB</B> file to
1782 learn where to send their votes, and what number constitutes a
1783 majority.
1784 <P><LI>The non-database server processes must know which machines are running the
1785 database server processes in order to retrieve information from the
1786 databases. For example, the first time that a user accesses an AFS
1787 file, the File Server that houses it contacts the Protection Server to obtain
1788 a list of the user's group memberships (the list is called a current
1789 protection subgroup, or CPS). The File Server uses the CPS as it
1790 determines if the access control list (ACL) protecting the file grants the
1791 required permissions to the user (for more details, see <A HREF="auagd019.htm#HDRWQ534">About the Protection Database</A>).
1792 </UL>
1793 <A NAME="IDX6140"></A>
1794 <P>The consequences of missing or incorrect information in the
1795 <B>CellServDB</B> file are as follows:
1796 <UL>
1797 <P><LI>If the file does not list a machine, then it is effectively not a database
1798 server machine even if the database server processes are running. The
1799 Ubik coordinator does not send it database updates or include it in the count
1800 that establishes a majority. It does not participate in Ubik elections,
1801 and so refuses to distribute database information to any client machines that
1802 happen to contact it (which they can do if their
1803 <B>/usr/vice/etc/CellServDB</B> file lists it). Users of the client
1804 machine must wait for a timeout before they can contact a correctly
1805 functioning database server machine.
1806 <P><LI>If the file lists a machine that is not running the database server
1807 processes, the consequences can be serious. The Ubik coordinator cannot
1808 send it database updates, but includes it in the count that establishes a
1809 majority. If valid secondary sites go down and stop sending their votes
1810 to the coordinator, it can wrongly appear that the coordinator no longer has
1811 the majority it needs. The resulting election of a new coordinator
1812 causes a service outage during which information from the database becomes
1813 unavailable. Furthermore, the lack of a vote from the incorrectly
1814 listed site can disturb the election, if it makes the other sites believe that
1815 a majority of sites are not voting for the new coordinator.
1816 <P>A more minor consequence is that non-database server processes attempt to
1817 contact the database server processes on the machine. They experience a
1818 timeout delay because the processes are not running.
1819 </UL>
1820 <P>Note that the <B>/usr/afs/etc/CellServDB</B> file on a server machine
1821 is not the same as the <B>/usr/vice/etc/CellServDB</B> file on client
1822 machine. The client version includes entries for foreign cells as well
1823 as the local cell. However, it is important to update both versions of
1824 the file whenever you change your cell's database server machines.
1825 A server machine that is also a client needs to have both files, and you need
1826 to update them both. For more information on maintaining the client
1827 version of the <B>CellServDB</B> file, see <A HREF="auagd015.htm#HDRWQ406">Maintaining Knowledge of Database Server Machines</A>.
1828 <A NAME="IDX6141"></A>
1829 <A NAME="IDX6142"></A>
1830 <A NAME="IDX6143"></A>
1831 <P><H3><A NAME="HDRWQ119" HREF="auagd002.htm#ToC_140">Distributing the Server CellServDB File</A></H3>
1832 <P>To avoid the negative consequences of incorrect information
1833 in the <B>/usr/afs/etc/CellServDB</B> file, you must update it on all of
1834 your cell's server machines every time you add or remove a database
1835 server machine. The <I>IBM AFS Quick Beginnings</I> provides
1836 complete instructions for installing or removing a database server machine and
1837 for updating the <B>CellServDB</B> file in that context. This
1838 section explains how to distribute the file to your server machines and how to
1839 make other cells aware of the changes if you participate in the AFS global
1840 name space.
1841 <P>If you use the United States edition of AFS, use the Update Server to
1842 distribute the central copy of the server <B>CellServDB</B> file stored on
1843 the cell's system control machine. If you use the international
1844 edition of AFS, instead change the file on each server machine
1845 individually. For further discussion of the system control machine and
1846 why international cells must not use it for files in the
1847 <B>/usr/afs/etc</B> directory, see <A HREF="#HDRWQ94">The System Control Machine</A>. For instructions on configuring
1848 the Update Server when using the United States version of AFS, see the
1849 <I>IBM AFS Quick Beginnings</I>.
1850 <P>To avoid formatting errors that can cause errors, always use the <B>bos
1851 addhost</B> and <B>bos removehost</B> commands, rather than editing the
1852 file directly. You must also restart the database server processes
1853 running on the machine, to initiate a coordinator election among the new set
1854 of database server machines. This step is included in the instructions
1855 that appear in <A HREF="#HDRWQ121">To add a database server machine to the CellServDB file</A> and <A HREF="#HDRWQ122">To remove a database server machine from the CellServDB file</A>. For instructions on displaying the
1856 contents of the file, see <A HREF="#HDRWQ120">To display a cell's database server machines</A>.
1857 <P>If you make your cell accessible to foreign users as part of the AFS global
1858 name space, you also need to inform other cells when you change your
1859 cell's database server machines. The AFS Support group maintains a
1860 <B>CellServDB</B> file that lists all cells that participate in the AFS
1861 global name space, and can change your cell's entry at your
1862 request. For further details, see <A HREF="auagd007.htm#HDRWQ38">Making Your Cell Visible to Others</A>.
1863 <P>Another way to advertise your cell's database server machines is to
1864 maintain a copy of the file at the conventional location in your AFS
1865 filespace,
1866 <B>/afs/</B><VAR>cell_name</VAR><B>/service/etc/CellServDB.local</B>.
1867 For further discussion, see <A HREF="auagd007.htm#HDRWQ43">The Third Level</A>.
1868 <A NAME="IDX6144"></A>
1869 <A NAME="IDX6145"></A>
1870 <A NAME="IDX6146"></A>
1871 <A NAME="IDX6147"></A>
1872 <A NAME="IDX6148"></A>
1873 <A NAME="IDX6149"></A>
1874 <P><H3><A NAME="HDRWQ120" HREF="auagd002.htm#ToC_141">To display a cell's database server machines</A></H3>
1875 <OL TYPE=1>
1876 <P><LI>Issue the <B>bos listhosts</B> command. If you have maintained
1877 the file properly, the output is the same on every server machine, but the
1878 <I>machine name</I> argument enables you to check various machines if you
1879 wish.
1880 <PRE>   % <B>bos listhosts</B> &lt;<VAR>machine&nbsp;name</VAR>> [&lt;<VAR>cell&nbsp;name</VAR>>]
1881 </PRE>
1882 <P>where
1883 <DL>
1884 <P><DT><B>listh
1885 </B><DD>Is the shortest acceptable abbreviation of <B>listhosts</B>.
1886 <P><DT><B><VAR>machine name</VAR>
1887 </B><DD>Specifies the server machine from which to display the
1888 <B>/usr/afs/etc/CellServDB</B> file.
1889 <P><DT><B><VAR>cell name</VAR>
1890 </B><DD>Specifies the complete Internet domain name of a foreign cell. You
1891 must already know the name of at least one server machine in the cell, to
1892 provide as the <B>machine name</B> argument.
1893 </DL>
1894 </OL>
1895 <P>The output lists the machines in the order they appear in the
1896 <B>CellServDB</B> file on the specified server machine. It assigns
1897 each one a <TT>Host</TT> index number, as in the following example.
1898 There is no implied relationship between the index and a machine's IP
1899 address, name, or role as Ubik coordinator or secondary site.
1900 <PRE>   % <B>bos listhosts fs1.abc.com</B>
1901    Cell name is abc.com
1902        Host 1 is fs1.abc.com
1903        Host 2 is fs7.abc.com
1904        Host 3 is fs4.abc.com
1905 </PRE>
1906 <P>The output lists machines by name rather than IP address as long as the
1907 naming service (such as the Domain Name Service or local host table) is
1908 functioning properly. To display IP addresses, login to a server
1909 machine as the local superuser <B>root</B> and use a text editor or
1910 display command, such as the <B>cat</B> command, to view the
1911 <B>/usr/afs/etc/CellServDB</B> file.
1912 <A NAME="IDX6150"></A>
1913 <A NAME="IDX6151"></A>
1914 <A NAME="IDX6152"></A>
1915 <A NAME="IDX6153"></A>
1916 <A NAME="IDX6154"></A>
1917 <A NAME="IDX6155"></A>
1918 <A NAME="IDX6156"></A>
1919 <A NAME="IDX6157"></A>
1920 <A NAME="IDX6158"></A>
1921 <A NAME="IDX6159"></A>
1922 <A NAME="IDX6160"></A>
1923 <A NAME="IDX6161"></A>
1924 <P><H3><A NAME="HDRWQ121" HREF="auagd002.htm#ToC_142">To add a database server machine to the CellServDB file</A></H3>
1925 <OL TYPE=1>
1926 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
1927 file. If necessary, issue the <B>bos listusers</B> command, which
1928 is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
1929 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1930 </PRE>
1931 <P><LI>Issue the <B>bos addhost</B> command to add each new database server
1932 machine to the <B>CellServDB</B> file. If you use the United States
1933 edition of AFS, specify the system control machine as <I>machine
1934 name</I>. (If you have forgotten which machine is the system control
1935 machine, see <A HREF="#HDRWQ99">The Output on the System Control Machine</A>.) If you use the international edition of AFS, repeat
1936 the command on each or your cell's server machines in turn by
1937 substituting its name for <I>machine name</I>.
1938 <PRE>   % <B>bos addhost </B> &lt;<VAR>machine&nbsp;name</VAR>>  &lt;<VAR>host&nbsp;name</VAR>><SUP>+</SUP>
1939 </PRE>
1940 <P>where
1941 <DL>
1942 <P><DT><B>addh
1943 </B><DD>Is the shortest acceptable abbreviation of <B>addhost</B>.
1944 <P><DT><B><VAR>machine name</VAR>
1945 </B><DD>Names the system control machine, if you are using the United States
1946 edition of AFS. If you are using the international edition of AFS, it
1947 names each of your server machines in turn.
1948 <P><DT><B><VAR>host name</VAR>
1949 </B><DD>Specifies the fully qualified hostname of each database server machine to
1950 add to the <B>CellServDB</B> file (for example:
1951 <B>fs4.abc.com</B>). The BOS Server uses the
1952 <B>gethostbyname(&nbsp;)</B> routine to obtain each machine's IP
1953 address and records both the name and address automatically.
1954 </DL>
1955 <P><LI>Restart the Authentication Server, Backup Server, Protection Server, and
1956 VL Server on every database server machine, so that the new set of machines
1957 participate in the election of a new Ubik coordinator. The instruction
1958 uses the conventional names for the processes; make the appropriate
1959 substitution if you use different process names. For complete syntax,
1960 see <A HREF="auagd009.htm#HDRWQ170">Stopping and Immediately Restarting Processes</A>.
1961 <P><B>Important:</B> Repeat the following command in quick
1962 succession on all of the database server machines.
1963 <PRE>   % <B>bos restart</B> &lt;<VAR>machine name</VAR>> <B>buserver kaserver ptserver vlserver</B>
1964 </PRE>
1965 <P><LI>Edit the <B>/usr/vice/etc/CellServDB</B> file on each of your
1966 cell's client machines. For instructions, see <A HREF="auagd015.htm#HDRWQ406">Maintaining Knowledge of Database Server Machines</A>.
1967 <P><LI>If you participate in the AFS global name space, please have one of your
1968 cell's designated site contacts register the changes you have made with
1969 the AFS Product Support group.
1970 <P>If you maintain a central copy of your cell's server
1971 <B>CellServDB</B> file in the conventional location
1972 (<B>/afs/</B><I>cell_name</I><B>/service/etc/CellServDB.local</B>),
1973 edit the file to reflect the change.
1974 </OL>
1975 <A NAME="IDX6162"></A>
1976 <A NAME="IDX6163"></A>
1977 <A NAME="IDX6164"></A>
1978 <A NAME="IDX6165"></A>
1979 <A NAME="IDX6166"></A>
1980 <A NAME="IDX6167"></A>
1981 <A NAME="IDX6168"></A>
1982 <A NAME="IDX6169"></A>
1983 <A NAME="IDX6170"></A>
1984 <A NAME="IDX6171"></A>
1985 <A NAME="IDX6172"></A>
1986 <P><H3><A NAME="HDRWQ122" HREF="auagd002.htm#ToC_143">To remove a database server machine from the CellServDB file</A></H3>
1987 <OL TYPE=1>
1988 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
1989 file. If necessary, issue the <B>bos listusers</B> command, which
1990 is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
1991 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1992 </PRE>
1993 <P><LI>Issue the <B>bos removehost</B> command to remove each database server
1994 machine from the <B>CellServDB</B> file. If you use the United
1995 States edition of AFS, specify the system control machine as <I>machine
1996 name</I>. (If you have forgotten which machine is the system control
1997 machine, see <A HREF="#HDRWQ99">The Output on the System Control Machine</A>.) If you use the international edition of AFS, repeat
1998 the command on each or your cell's server machines in turn by
1999 substituting its name for <I>machine name</I>.
2000 <PRE>   % <B>bos removehost</B> &lt;<VAR>machine&nbsp;name</VAR>>  &lt;<VAR>host&nbsp;name</VAR>><SUP>+</SUP>
2001 </PRE>
2002 <P>where
2003 <DL>
2004 <P><DT><B>removeh
2005 </B><DD>Is the shortest acceptable abbreviation of <B>removehost</B>.
2006 <P><DT><B><VAR>machine name</VAR>
2007 </B><DD>Names the system control machine, if you are using the United States
2008 edition of AFS. If you are using the international edition of AFS, it
2009 names each of your server machines in turn.
2010 <P><DT><B><VAR>host name</VAR>
2011 </B><DD>Specifies the fully qualified hostname of each database server machine to
2012 remove from the <B>CellServDB</B> file (for example:
2013 <B>fs4.abc.com</B>).
2014 </DL>
2015 <P><LI>Restart the Authentication Server, Backup Server, Protection Server, and
2016 VL Server on every database server machine, so that the new set of machines
2017 participate in the election of a new Ubik coordinator. The instruction
2018 uses the conventional names for the processes; make the appropriate
2019 substitution if you use different process names. For complete syntax,
2020 see <A HREF="auagd009.htm#HDRWQ170">Stopping and Immediately Restarting Processes</A>.
2021 <P><B>Important:</B> Repeat the following command in quick
2022 succession on all of the database server machines.
2023 <PRE>   % <B>bos restart</B> &lt;<VAR>machine name</VAR>> <B>buserver kaserver ptserver vlserver</B>
2024 </PRE>
2025 <P><LI>Edit the <B>/usr/vice/etc/CellServDB</B> file on each of your
2026 cell's client machines. For instructions, see <A HREF="auagd015.htm#HDRWQ406">Maintaining Knowledge of Database Server Machines</A>.
2027 <P><LI>If you participate in the AFS global name space, please have one of your
2028 cell's designated site contacts register the changes you have made with
2029 the AFS Product Support group.
2030 <P>If you maintain a central copy of your cell's server
2031 <B>CellServDB</B> file in the conventional location
2032 (<B>/afs/</B><I>cell_name</I><B>/service/etc/CellServDB.local</B>),
2033 edit the file to reflect the change.
2034 </OL>
2035 <HR><H2><A NAME="HDRWQ123" HREF="auagd002.htm#ToC_144">Managing Authentication and Authorization Requirements</A></H2>
2036 <P>This section describes how the AFS server processes
2037 guarantee that only properly authorized users perform privileged commands, by
2038 checking authorization checking and mutually authenticating with their
2039 clients. It explains how you can control authorization checking
2040 requirements on a per-machine or per-cell basis, and how to bypass mutual
2041 authentication when issuing commands.
2042 <A NAME="IDX6173"></A>
2043 <A NAME="IDX6174"></A>
2044 <A NAME="IDX6175"></A>
2045 <A NAME="IDX6176"></A>
2046 <A NAME="IDX6177"></A>
2047 <A NAME="IDX6178"></A>
2048 <P><H3><A NAME="HDRWQ124" HREF="auagd002.htm#ToC_145">Authentication versus Authorization</A></H3>
2049 <P>Many AFS commands are <I>privileged</I> in that the AFS
2050 server process invoked by the command performs it only for a properly
2051 authorized user. The server process performs the following two tests to
2052 determine if someone is properly authorized:
2053 <UL>
2054 <P><LI>In the <I>authentication</I> test, the server process mutually
2055 authenticates with the command interpreter, Cache Manager, or other client
2056 process that is acting on behalf of a user or application. The goal of
2057 this test is to determine who is issuing the command. The server
2058 process verifies that the issuer really is who he or she claims to be, by
2059 examining the server ticket and other components of the issuer's
2060 token. (Secondarily, it allows the client process to verify that the
2061 server process is genuine.) If the issuer has no token or otherwise
2062 fails the test, the server process assigns him or her the identity
2063 <B>anonymous</B>, a completely unprivileged user. For a more
2064 complete description of mutual authentication, see <A HREF="auagd007.htm#HDRWQ75">A More Detailed Look at Mutual Authentication</A>.
2065 <P>Many individual commands enable you to bypass the authentication test by
2066 assuming the <B>anonymous</B> identity without even attempting to mutually
2067 authenticate. Note, however, that this is futile if the command is
2068 privileged and the server process is still performing the authorization test,
2069 because in that case the process refuses to execute privileged commands for
2070 the <B>anonymous</B> user.
2071 <P><LI>In the <I>authorization</I> test, the server process determines if the
2072 issuer is authorized to use the command by consulting a list of privileged
2073 users. The goal of this test is to determine what the issuer is allowed
2074 to do. Different server processes consult different lists of users, as
2075 described in <A HREF="auagd021.htm#HDRWQ581">Managing Administrative Privilege</A>. The server process refuses to execute any privileged
2076 command for an unauthorized issuer. If a command has no privilege
2077 requirements, the server process skips this step and executes and
2078 immediately.
2079 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">Never place the <B>anonymous</B> user or the
2080 <B>system:anyuser</B> group on a privilege list; it makes
2081 authorization checking meaningless.
2082 <P>You can use the <B>bos setauth</B> command to control whether the
2083 server processes on a server machine check for authorization. Other
2084 server machines are not affected. Keep in mind that turning off
2085 authorization checking is a grave security risk, because the server processes
2086 on that machine perform any action for any user.
2087 </TD></TR></TABLE>
2088 </UL>
2089 <A NAME="IDX6179"></A>
2090 <A NAME="IDX6180"></A>
2091 <A NAME="IDX6181"></A>
2092 <A NAME="IDX6182"></A>
2093 <P><H3><A NAME="HDRWQ125" HREF="auagd002.htm#ToC_146">Controlling Authorization Checking on a Server Machine</A></H3>
2094 <P>Disabling authorization checking is a serious breach of
2095 security because it means that the AFS server processes on a file server
2096 machine performs any action for any user, even the <B>anonymous</B>
2097 user.
2098 <P>The only time it is common to disable authorization checking is when
2099 installing a new file server machine (see the <I>IBM AFS Quick
2100 Beginnings</I>). It is necessary then because it is not possible to
2101 configure all of the necessary security mechanisms before performing other
2102 actions that normally make use of them. For greatest security, work at
2103 the console of the machine you are installing and enable authorization
2104 checking as soon as possible.
2105 <P>During normal operation, the only reason to disable authorization checking
2106 is if an error occurs with the server encryption keys, leaving the servers
2107 unable to authenticate users properly. For instructions on handling
2108 key-related emergencies, see <A HREF="auagd014.htm#HDRWQ370">Handling Server Encryption Key Emergencies</A>.
2109 <P>You control authorization checking on each file server machine
2110 separately; turning it on or off on one machine does not affect the
2111 others. Because client machines generally choose a server process at
2112 random, it is hard to predict what authorization checking conditions prevail
2113 for a given command unless you make the requirement the same on all
2114 machines. To turn authorization checking on or off for the entire cell,
2115 you must repeat the appropriate command on every file server machine.
2116 <P>The server processes constantly monitor the directory
2117 <B>/usr/afs/local</B> on their local disks to determine if they need to
2118 check for authorization. If the file called <B>NoAuth</B> appears
2119 in that directory, then the servers do not check for authorization.
2120 When it is not present (the usual case), they perform authorization
2121 checking.
2122 <P>Control the presence of the <B>NoAuth</B> file through the BOS
2123 Server. When you disable authorization checking with the <B>bos
2124 setauth</B> command (or, during installation, by putting the
2125 <B>-noauth</B> flag on the command that starts up the BOS Server), the BOS
2126 Server creates the zero-length <B>NoAuth</B> file. When you
2127 reenable authorization checking, the BOS Server removes the file.
2128 <A NAME="IDX6183"></A>
2129 <A NAME="IDX6184"></A>
2130 <A NAME="IDX6185"></A>
2131 <A NAME="IDX6186"></A>
2132 <A NAME="IDX6187"></A>
2133 <P><H3><A NAME="HDRWQ126" HREF="auagd002.htm#ToC_147">To disable authorization checking on a server machine</A></H3>
2134 <OL TYPE=1>
2135 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
2136 file. If necessary, issue the <B>bos listusers</B> command, which
2137 is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
2138 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
2139 </PRE>
2140 <P><LI>Issue the <B>bos setauth</B> command to disable authorization
2141 checking.
2142 <PRE>   % <B>bos setauth</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>off</B>
2143 </PRE>
2144 <P>where
2145 <DL>
2146 <P><DT><B>seta
2147 </B><DD>Is the shortest acceptable abbreviation of <B>setauth</B>.
2148 <P><DT><B><VAR>machine name</VAR>
2149 </B><DD>Specifies the file server machine on which server processes do not check
2150 for authorization.
2151 </DL>
2152 </OL>
2153 <A NAME="IDX6188"></A>
2154 <A NAME="IDX6189"></A>
2155 <A NAME="IDX6190"></A>
2156 <P><H3><A NAME="HDRWQ127" HREF="auagd002.htm#ToC_148">To enable authorization checking on a server machine</A></H3>
2157 <OL TYPE=1>
2158 <P><LI>Reenable authorization checking. (No privilege is required because
2159 the machine is not currently checking for authorization.) For detailed
2160 syntax information, see the preceding section.
2161 <PRE>   % <B>bos setauth</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>on</B>
2162 </PRE>
2163 </OL>
2164 <A NAME="IDX6191"></A>
2165 <A NAME="IDX6192"></A>
2166 <P><H3><A NAME="HDRWQ128" HREF="auagd002.htm#ToC_149">Bypassing Mutual Authentication for an Individual Command</A></H3>
2167 <P>Several of the server processes allow any user (not just
2168 system administrators) to disable mutual authentication when issuing a
2169 command. The server process treats the issuer as the unauthenticated
2170 user <B>anonymous</B>.
2171 <P>The facilities for preventing mutual authentication are provided for use in
2172 emergencies (such as the key emergency discussed in <A HREF="auagd014.htm#HDRWQ370">Handling Server Encryption Key Emergencies</A>). During normal circumstances, authorization checking
2173 is turned on, making it useless to prevent authentication: the server
2174 processes refuse to perform privileged commands for the user
2175 <B>anonymous</B>.
2176 <P>It can be useful to prevent authentication when authorization checking is
2177 turned off. The very act of trying to authenticate can cause problems
2178 if the server cannot understand a particular encryption key, as is likely to
2179 happen in a key emergency.
2180 <A NAME="IDX6193"></A>
2181 <A NAME="IDX6194"></A>
2182 <A NAME="IDX6195"></A>
2183 <A NAME="IDX6196"></A>
2184 <A NAME="IDX6197"></A>
2185 <A NAME="IDX6198"></A>
2186 <A NAME="IDX6199"></A>
2187 <A NAME="IDX6200"></A>
2188 <P><H3><A NAME="HDRWQ129" HREF="auagd002.htm#ToC_150">To bypass mutual authentication for bos, kas, pts, and vos commands</A></H3>
2189 <P>Provide the <B>-noauth</B> flag which is available on
2190 many of the commands in the suites. To verify that a command accepts
2191 the flag, issue the <B>help</B> command in its suite, or consult the
2192 command's reference page in the <I>IBM AFS Administration
2193 Reference</I> (the reference page also specifies the shortest acceptable
2194 abbreviation for the flag on each command). The suites'
2195 <B>apropos</B> and <B>help</B> commands do not themselves accept the
2196 flag.
2197 <P>You can bypass mutual authentication for all <B>kas</B> commands issued
2198 during an interactive session by including the <B>-noauth</B> flag on the
2199 <B>kas interactive</B> command. If you have already entered
2200 interactive mode with an authenticated identity, issue the <B>(kas)
2201 noauthentication</B> command to assume the <B>anonymous</B>
2202 identity.
2203 <A NAME="IDX6201"></A>
2204 <P><H3><A NAME="Header_151" HREF="auagd002.htm#ToC_151">To bypass mutual authentication for fs commands</A></H3>
2205 <P>This is not possible, except by issuing the <B>unlog</B> command to
2206 discard your tokens before issuing the <B>fs</B> command.
2207 <HR><H2><A NAME="HDRWQ130" HREF="auagd002.htm#ToC_152">Adding or Removing Disks and Partitions</A></H2>
2208 <P>AFS makes it very easy to add storage space to your cell,
2209 just by adding disks to existing file server machines. This section
2210 explains how to install or remove a disk used to store AFS volumes.
2211 (Another way to add storage space is to install additional server machines, as
2212 instructed in the <I>IBM AFS Quick Beginnings</I>.)
2213 <P>Both adding and removing a disk cause at least a brief file system outage,
2214 because you must restart the <B>fs</B> process to have it recognize the
2215 new set of server partitions. Some operating systems require that you
2216 shut the machine off before adding or removing a disk, in which case you must
2217 shut down all of the AFS server processes first. Otherwise, the
2218 AFS-related aspects of adding or removing a disk are not complicated, so the
2219 duration of the outage depends mostly on how long it takes to install or
2220 remove the disk itself.
2221 <P>The following instructions for installing a new disk completely prepare it
2222 to house AFS volumes. You can then use the <B>vos create</B>
2223 command to create new volumes, or the <B>vos move</B> command to move
2224 existing ones from other partitions. For instructions, see <A HREF="auagd010.htm#HDRWQ185">Creating Read/write Volumes</A> and <A HREF="auagd010.htm#HDRWQ226">Moving Volumes</A>. The instructions for removing a
2225 disk are basically the reverse of the installation instructions, but include
2226 extra steps that protect against data loss.
2227 <P>A server machines can house 256 AFS server partitions, each one mounted at
2228 a directory with a name of the form <B>/vicep</B><I>index</I>, where
2229 <I>index</I> is one or two lowercase letters. By convention, the
2230 first partition on a machine is mounted at <B>/vicepa</B>, the second at
2231 <B>/vicepb</B>, and so on to the twenty-sixth at
2232 <B>/vicepz</B>. Additional partitions are mounted at
2233 <B>/vicepaa</B> through <B>/vicepaz</B> and so on up to
2234 <B>/vicepiv</B>. Using the letters consecutively is not required,
2235 but is simpler.
2236 <P>Mount each <B>/vicep</B> directory directly under the local file
2237 system's root directory ( <B>/</B> ), not as a subdirectory of any
2238 other directory; for example, <B>/usr/vicepa</B> is not an acceptable
2239 location. You must also map the directory to the partition's
2240 device name in the file server machine's file systems registry file
2241 (<B>/etc/fstab</B> or equivalent).
2242 <P>These instructions assume that the machine's AFS initialization file
2243 includes the following command to restart the BOS Server after each
2244 reboot. The BOS Server starts the other AFS server processes listed in
2245 the local <B>/usr/afs/local/BosConfig</B> file. For information on
2246 the <B>bosserver</B> command's optional arguments, see its reference
2247 page in the <I>IBM AFS Administration Reference</I>.
2248 <PRE>   /usr/afs/bin/bosserver &amp;
2249 </PRE>
2250 <A NAME="IDX6202"></A>
2251 <A NAME="IDX6203"></A>
2252 <A NAME="IDX6204"></A>
2253 <A NAME="IDX6205"></A>
2254 <A NAME="IDX6206"></A>
2255 <A NAME="IDX6207"></A>
2256 <A NAME="IDX6208"></A>
2257 <P><H3><A NAME="HDRWQ131" HREF="auagd002.htm#ToC_153">To add and mount a new disk to house AFS volumes</A></H3>
2258 <OL TYPE=1>
2259 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
2260 already, by issuing the <B>su</B> command.
2261 <PRE>   % <B>su root</B>
2262    Password: <VAR>root_password</VAR>
2263 </PRE>
2264 <P><LI>Decide how many AFS partitions to divide the new disk into and the names
2265 of the directories at which to mount them (the introduction to this section
2266 describes the naming conventions). To display the names of the existing
2267 server partitions on the machine, issue the <B>vos listpart</B>
2268 command. Include the <B>-localauth</B> flag because you are logged
2269 in as the local superuser <B>root</B> but do not necessarily have
2270 administrative tokens.
2271 <PRE>   # <B>vos listpart</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>-localauth</B>
2272 </PRE>
2273 <P>where
2274 <DL>
2275 <P><DT><B>listp
2276 </B><DD>Is the shortest acceptable abbreviation of <B>listpart</B>.
2277 <P><DT><B><VAR>machine name</VAR>
2278 </B><DD>Names the local file server machine.
2279 <P><DT><B>-localauth
2280 </B><DD>Constructs a server ticket using a key from the local
2281 <B>/usr/afs/etc/KeyFile</B> file. The <B>bos</B> command
2282 interpreter presents it to the BOS Server during mutual authentication.
2283 </DL>
2284 <P><LI>Create each directory at which to mount a partition.
2285 <PRE>   # <B>mkdir /vicep</B><VAR>x</VAR>[<VAR>x</VAR>]
2286 </PRE>
2287 <A NAME="IDX6209"></A>
2288 <A NAME="IDX6210"></A>
2289 <A NAME="IDX6211"></A>
2290 <A NAME="IDX6212"></A>
2291 <P><LI><A NAME="LIWQ132"></A>Using a text editor, create an entry in the machine's file
2292 systems registry file (<B>/etc/fstab</B> or equivalent) for each new disk
2293 partition, mapping its device name to the directory you created in the
2294 previous step. Refer to existing entries in the file to learn the
2295 proper format, which varies for different operating systems.
2296 <P><LI><A NAME="LIWQ133"></A>If the operating system requires that you shut off the machine
2297 to install a new disk, issue the <B>bos shutdown</B> command to shut down
2298 all AFS server processes other than the BOS Server (it terminates safely when
2299 you shut off the machine). Include the <B>-localauth</B> flag
2300 because you are logged in as the local superuser <B>root</B> but do not
2301 necessarily have administrative tokens. For a complete description of
2302 the command, see <A HREF="auagd009.htm#HDRWQ168">To stop processes temporarily</A>.
2303 <PRE>   # <B>bos shutdown</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>-localauth</B> [<B>-wait</B>]
2304 </PRE>
2305 <P><LI><A NAME="LIWQ134"></A>If necessary, shut off the machine. Install and format
2306 the new disk according to the instructions provided by the disk and operating
2307 system vendors. If necessary, edit the disk's partition table to
2308 reflect the changes you made to the files system registry file in step <A HREF="#LIWQ132">4</A>; consult the operating system documentation for
2309 instructions.
2310 <P><LI>If you shut off the machine down in step <A HREF="#LIWQ134">6</A>, turn it on. Otherwise, issue the <B>bos
2311 restart</B> command to restart the <B>fs</B> process, forcing it to
2312 recognize the new set of server partitions. Include the
2313 <B>-localauth</B> flag because you are logged in as the local superuser
2314 <B>root</B> but do not necessarily have administrative tokens. For
2315 complete instructions for the <B>bos restart</B> command, see <A HREF="auagd009.htm#HDRWQ170">Stopping and Immediately Restarting Processes</A>.
2316 <PRE>   # <B>bos restart</B> &lt;<VAR>machine&nbsp;name</VAR>>  <B>fs -localauth</B>
2317 </PRE>
2318 <P><LI>Issue the <B>bos status</B> command to verify that all server
2319 processes are running correctly. For more detailed instructions, see <A HREF="auagd009.htm#HDRWQ158">Displaying Process Status and Information from the BosConfig File</A>.
2320 <PRE>   # <B>bos status</B> &lt;<VAR>machine&nbsp;name</VAR>>
2321 </PRE>
2322 </OL>
2323 <A NAME="IDX6213"></A>
2324 <A NAME="IDX6214"></A>
2325 <A NAME="IDX6215"></A>
2326 <A NAME="IDX6216"></A>
2327 <A NAME="IDX6217"></A>
2328 <P><H3><A NAME="HDRWQ135" HREF="auagd002.htm#ToC_154">To unmount and remove a disk housing AFS volumes</A></H3>
2329 <OL TYPE=1>
2330 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
2331 file. If necessary, issue the <B>bos listusers</B> command, which
2332 is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
2333 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
2334 </PRE>
2335 <P><LI>Issue the <B>vos listvol</B> command to list the volumes housed on
2336 each partition of each disk you are about to remove, in preparation for
2337 removing them or moving them to other partitions. For detailed
2338 instructions, see <A HREF="auagd010.htm#HDRWQ219">Displaying Volume Headers</A>.
2339 <PRE>   % <B>vos listvol</B> &lt;<VAR>machine&nbsp;name</VAR>> [&lt;<VAR>partition&nbsp;name</VAR>>]
2340 </PRE>
2341 <P><LI>Move any volume you wish to retain in the file system to another
2342 partition. You can move only read/write volumes. For more
2343 detailed instructions, and for instructions on moving read-only and backup
2344 volumes, see <A HREF="auagd010.htm#HDRWQ226">Moving Volumes</A>.
2345 <PRE>   % <B>vos move</B>  &lt;<VAR>volume&nbsp;name&nbsp;or&nbsp;ID</VAR>>  \
2346         &lt;<VAR>machine&nbsp;name&nbsp;on&nbsp;source</VAR>> &lt;<VAR>partition&nbsp;name&nbsp;on&nbsp;source</VAR>>  \
2347         &lt;<VAR>machine&nbsp;name&nbsp;on&nbsp;destination</VAR>> &lt;<VAR>partition&nbsp;name&nbsp;on&nbsp;destination</VAR>>
2348 </PRE>
2349 <P><LI><B>(Optional)</B> If there are any volumes you do not wish to retain,
2350 back them up using the <B>vos dump</B> command or the AFS Backup
2351 System. See <A HREF="auagd010.htm#HDRWQ240">Dumping and Restoring Volumes</A> or <A HREF="auagd012.htm#HDRWQ296">Backing Up Data</A>, respectively.
2352 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
2353 already, by issuing the <B>su</B> command.
2354 <PRE>   % <B>su root</B>
2355    Password: <VAR>root_password</VAR>
2356 </PRE>
2357 <A NAME="IDX6218"></A>
2358 <A NAME="IDX6219"></A>
2359 <P><LI>Issue the <B>umount</B> command, repeating it for each partition on
2360 the disk to be removed.
2361 <PRE>   # <B>cd /</B>
2362    # <B>umount /dev/</B>&lt;<VAR>partition_block_device_name</VAR>>
2363 </PRE>
2364 <A NAME="IDX6220"></A>
2365 <P><LI><A NAME="LIWQ136"></A>Using a text editor, remove or comment out each
2366 partition's entry from the machine's file systems registry file
2367 (<B>/etc/fstab</B> or equivalent).
2368 <P><LI>Remove the <B>/vicep</B> directory associated with each
2369 partition.
2370 <PRE>   # <B>rmdir /vicep</B><VAR>xx</VAR>
2371 </PRE>
2372 <P><LI>If the operating system requires that you shut off the machine to remove a
2373 disk, issue the <B>bos shutdown</B> command to shut down all AFS server
2374 processes other than the BOS Server (it terminates safely when you shut off
2375 the machine). Include the <B>-localauth</B> flag because you are
2376 logged in as the local superuser <B>root</B> but do not necessarily have
2377 administrative tokens. For a complete description of the command, see <A HREF="auagd009.htm#HDRWQ168">To stop processes temporarily</A>.
2378 <PRE>   # <B>bos shutdown</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>-localauth</B> [<B>-wait</B>]
2379 </PRE>
2380 <P><LI><A NAME="LIWQ137"></A>If necessary, shut off the machine. Remove the disk
2381 according to the instructions provided by the disk and operating system
2382 vendors. If necessary, edit the disk's partition table to reflect
2383 the changes you made to the files system registry file in step <A HREF="#LIWQ136">7</A>; consult the operating system documentation for
2384 instructions.
2385 <P><LI>If you shut off the machine down in step <A HREF="#LIWQ137">10</A>, turn it on. Otherwise, issue the <B>bos
2386 restart</B> command to restart the <B>fs</B> process, forcing it to
2387 recognize the new set of server partitions. Include the
2388 <B>-localauth</B> flag because you are logged in as the local superuser
2389 <B>root</B> but do not necessarily have administrative tokens. For
2390 complete instructions for the <B>bos restart</B> command, see <A HREF="auagd009.htm#HDRWQ170">Stopping and Immediately Restarting Processes</A>.
2391 <PRE>   # <B>bos restart</B> &lt;<VAR>machine&nbsp;name</VAR>>  <B>fs -localauth</B>
2392 </PRE>
2393 <P><LI>Issue the <B>bos status</B> command to verify that all server
2394 processes are running correctly. For more detailed instructions, see <A HREF="auagd009.htm#HDRWQ158">Displaying Process Status and Information from the BosConfig File</A>.
2395 <PRE>   # <B>bos status</B> &lt;<VAR>machine&nbsp;name</VAR>>
2396 </PRE>
2397 </OL>
2398 <A NAME="IDX6221"></A>
2399 <A NAME="IDX6222"></A>
2400 <A NAME="IDX6223"></A>
2401 <A NAME="IDX6224"></A>
2402 <A NAME="IDX6225"></A>
2403 <A NAME="IDX6226"></A>
2404 <A NAME="IDX6227"></A>
2405 <A NAME="IDX6228"></A>
2406 <A NAME="IDX6229"></A>
2407 <A NAME="IDX6230"></A>
2408 <A NAME="IDX6231"></A>
2409 <HR><H2><A NAME="HDRWQ138" HREF="auagd002.htm#ToC_155">Managing Server IP Addresses and VLDB Server Entries</A></H2>
2410 <P>The AFS support for multihomed file server machines is
2411 largely automatic. The File Server process records the IP addresses of
2412 its file server machine's network interfaces in the local
2413 <B>/usr/afs/local/sysid</B> file and also registers them in a <I>server
2414 entry</I> in the Volume Location Database (VLDB). The
2415 <B>sysid</B> file and server entry are identified by the same unique
2416 number, which creates an association between them.
2417 <P>When the Cache Manager requests volume location information, the Volume
2418 Location (VL) Server provides all of the interfaces registered for each server
2419 machine that houses the volume. This enables the Cache Manager to make
2420 use of multiple addresses when accessing AFS data stored on a multihomed file
2421 server machine.
2422 <P>If you wish, you can control which interfaces the File Server registers in
2423 its VLDB server entry by creating two files in the local
2424 <B>/usr/afs/local</B> directory: <B>NetInfo</B> and
2425 <B>NetRestrict</B>. Each time the File Server restarts, it builds a
2426 list of the local machine's interfaces by reading the <B>NetInfo</B>
2427 file, if it exists. If you do not create the file, the File Server uses
2428 the list of network interfaces configured with the operating system. It
2429 then removes from the list any addresses that appear in the
2430 <B>NetRestrict</B> file, if it exists. The File Server records the
2431 resulting list in the <B>sysid</B> file and registers the interfaces in
2432 the VLDB server entry that has the same unique identifier.
2433 <P>On database server machines, the <B>NetInfo</B> and
2434 <B>NetRestrict</B> files also determine which interfaces the Ubik database
2435 synchronization library uses when communicating with the database server
2436 processes running on other database server machines.
2437 <P>There is a maximum number of IP addresses in each server entry, as
2438 documented in the <I>IBM AFS Release Notes</I>. If a multihomed
2439 file server machine has more interfaces than the maximum, AFS simply ignores
2440 the excess ones. It is probably appropriate for such machines to use
2441 the <B>NetInfo</B> and <B>NetRestrict</B> files to control which
2442 interfaces are registered.
2443 <P>If for some reason the <B>sysid</B> file no longer exists, the File
2444 Server creates a new one with a new unique identifier. When the File
2445 Server registers the contents of the new file, the Volume Location (VL) Server
2446 normally recognizes automatically that the new file corresponds to an existing
2447 server entry, and overwrites the existing server entry with the new file
2448 contents and identifier. However, it is best not to remove the
2449 <B>sysid</B> file if that can be avoided.
2450 <P>Similarly, it is important not to copy the <B>sysid</B> file from one
2451 file server machine to another. If you commonly copy the contents of
2452 the <B>/usr/afs</B> directory from an existing machine as part of
2453 installing a new file server machine, be sure to remove the <B>sysid</B>
2454 file from the <B>/usr/afs/local</B> directory on the new machine before
2455 starting the File Server.
2456 <P>There are certain cases where the VL Server cannot determine whether it is
2457 appropriate to overwrite an existing server entry with a new <B>sysid</B>
2458 file's contents and identifier. It then refuses to allow the File
2459 Server to register the interfaces, which prevents the File Server from
2460 starting. This can happen if, for example, a new <B>sysid</B> file
2461 includes two interfaces that currently are registered by themselves in
2462 separate server entries. In such cases, error messages in the
2463 <B>/usr/afs/log/VLLog</B> file on the VL Server machine and in the
2464 <B>/usr/afs/log/FileLog</B> file on the file server machine indicate that
2465 you need to use the <B>vos changeaddr</B> command to resolve the
2466 problem. Contact the AFS Product Support group for instructions and
2467 assistance.
2468 <P>Except in this type of rare error case, the only appropriate use of the
2469 <B>vos changeaddr</B> command is to remove a VLDB server entry completely
2470 when you remove a file server machine from service. The VLDB can
2471 accommodate a maximum number of server entries, as specified in the <I>IBM
2472 AFS Release Notes</I>. Removing obsolete entries makes it possible to
2473 allocate server entries for new file server machines as required. See
2474 the instructions that follow.
2475 <P>Do not use the <B>vos changeaddr</B> command to change the list of
2476 interfaces registered in a VLDB server entry. To change a file server
2477 machine's IP addresses and server entry, see the instructions that
2478 follow.
2479 <A NAME="IDX6232"></A>
2480 <A NAME="IDX6233"></A>
2481 <A NAME="IDX6234"></A>
2482 <P><H3><A NAME="Header_156" HREF="auagd002.htm#ToC_156">To create or edit the server NetInfo file</A></H3>
2483 <OL TYPE=1>
2484 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
2485 already, by issuing the <B>su</B> command.
2486 <PRE>   % <B>su root</B>
2487    Password: <VAR>root_password</VAR>
2488 </PRE>
2489 <P><LI>Using a text editor, open the <B>/usr/afs/local/NetInfo</B>
2490 file. Place one IP address in dotted decimal format (for example,
2491 <TT>192.12.107.33</TT>) on each line. The order
2492 of entries is not significant.
2493 <P><LI>If you want the File Server to start using the revised list immediately,
2494 use the <B>bos restart</B> command to restart the <B>fs</B>
2495 process. For instructions, see <A HREF="auagd009.htm#HDRWQ170">Stopping and Immediately Restarting Processes</A>.
2496 </OL>
2497 <A NAME="IDX6235"></A>
2498 <A NAME="IDX6236"></A>
2499 <A NAME="IDX6237"></A>
2500 <P><H3><A NAME="Header_157" HREF="auagd002.htm#ToC_157">To create or edit the server NetRestrict file</A></H3>
2501 <OL TYPE=1>
2502 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
2503 already, by issuing the <B>su</B> command.
2504 <PRE>   % <B>su root</B>
2505    Password: <VAR>root_password</VAR>
2506 </PRE>
2507 <P><LI>Using a text editor, open the <B>/usr/afs/local/NetRestrict</B>
2508 file. Place one IP address in dotted decimal format on each
2509 line. The order of the addresses is not significant. Use the
2510 value <B>255</B> as a wildcard that represents all possible addresses in
2511 that field. For example, the entry
2512 <TT>192.12.105.255</TT> indicates that the Cache
2513 Manager does not register any of the addresses in the 192.12.105
2514 subnet.
2515 <P><LI>If you want the File Server to start using the revised list immediately,
2516 use the <B>bos restart</B> command to restart the <B>fs</B>
2517 process. For instructions, see <A HREF="auagd009.htm#HDRWQ170">Stopping and Immediately Restarting Processes</A>.
2518 </OL>
2519 <A NAME="IDX6238"></A>
2520 <A NAME="IDX6239"></A>
2521 <P><H3><A NAME="Header_158" HREF="auagd002.htm#ToC_158">To display all server entries from the VLDB</A></H3>
2522 <OL TYPE=1>
2523 <P><LI>Issue the <B>vos listaddrs</B> command to display all server entries
2524 from the VLDB.
2525 <PRE>   % <B>vos listaddrs</B>
2526 </PRE>
2527 <P>where <B>lista</B> is the shortest acceptable abbreviation of
2528 <B>listaddrs</B>.
2529 <P>The output displays all server entries from the VLDB, each on its own
2530 line. If a file server machine is multihomed, all of its registered
2531 addresses appear on the line. The first one is the one reported as a
2532 volume's site in the output from the <B>vos examine</B> and <B>vos
2533 listvldb</B> commands.
2534 <P>VLDB server entries record IP addresses, and the command interpreter has
2535 the local name service (either a process like the Domain Name Service or a
2536 local host table) translate them to hostnames before displaying them.
2537 If an IP address appears in the output, it is not possible to translate
2538 it.
2539 <P>The existence of an entry does not necessarily indicate that the machine
2540 that is still an active file server machine. To remove obsolete server
2541 entries, see the following instructions.
2542 </OL>
2543 <A NAME="IDX6240"></A>
2544 <A NAME="IDX6241"></A>
2545 <P><H3><A NAME="Header_159" HREF="auagd002.htm#ToC_159">To remove obsolete server entries from the VLDB</A></H3>
2546 <OL TYPE=1>
2547 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
2548 file. If necessary, issue the <B>bos listusers</B> command, which
2549 is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
2550 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
2551 </PRE>
2552 <P><LI>Issue the <B>vos changeaddr</B> command to remove a server entry from
2553 the VLDB.
2554 <PRE>   % <B>vos changeaddr</B> &lt;<VAR>original&nbsp;IP&nbsp;address</VAR>> <B>-remove</B>
2555 </PRE>
2556 <P>where
2557 <DL>
2558 <P><DT><B>ch
2559 </B><DD>Is the shortest acceptable abbreviation of <B>changeaddr</B>.
2560 <P><DT><B><VAR>original IP address</VAR>
2561 </B><DD>Specifies one of the IP addresses currently registered for the file server
2562 machine in the VLDB. Any of a multihomed file server machine's
2563 addresses are acceptable to identify it.
2564 <P><DT><B>-remove
2565 </B><DD>Removes the server entry.
2566 </DL>
2567 </OL>
2568 <P><H3><A NAME="Header_160" HREF="auagd002.htm#ToC_160">To change a server machine's IP addresses</A></H3>
2569 <OL TYPE=1>
2570 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
2571 file. If necessary, issue the <B>bos listusers</B> command, which
2572 is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
2573 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
2574 </PRE>
2575 <P><LI>If the machine is the system control machine or a binary distribution
2576 machine, and you are also changing its hostname, redefine all relevant
2577 <B>upclient</B> processes on other server machines to refer to the new
2578 hostname. Use the <B>bos delete</B> and <B>bos create</B>
2579 commands as instructed in <A HREF="auagd009.htm#HDRWQ161">Creating and Removing Processes</A>.
2580 <P><LI>If the machine is a database server machine, edit its entry in the
2581 <B>/usr/afs/etc/CellServDB</B> file on every server machine in the cell to
2582 list one of the new IP addresses. If you use the United States edition
2583 of AFS, you can edit the file on the system control machine and wait the
2584 required time (by default, five minutes) for the Update Server to distribute
2585 the changed file to all server machines.
2586 <P><LI>If the machine is a database server machine, issue the <B>bos
2587 shutdown</B> command to stop all server processes. If the machine is
2588 also a file server, the volumes on it are inaccessible during this
2589 time. For a complete description of the command, see <A HREF="auagd009.htm#HDRWQ168">To stop processes temporarily</A>.
2590 <PRE>   % <B>bos shutdown</B> &lt;<VAR>machine&nbsp;name</VAR>>
2591 </PRE>
2592 <P><LI>Use the utilities provided with the operating system to change one or more
2593 of the machine's IP addresses.
2594 <P><LI>If appropriate, edit the <B>/usr/afs/local/NetInfo</B> file, the
2595 <B>/usr/afs/local/NetRestrict</B> file, or both, to reflect the changed
2596 addresses. Instructions appear earlier in this section.
2597 <P><LI>If the machine is a database server machine, issue the <B>bos
2598 restart</B> command to restart all server processes on the machine.
2599 For complete instructions for the <B>bos restart</B> command, see <A HREF="auagd009.htm#HDRWQ170">Stopping and Immediately Restarting Processes</A>.
2600 <PRE>   % <B>bos restart</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>-all</B>
2601 </PRE>
2602 <P>At the same time, issue the <B>bos restart</B> command on all other
2603 database server machines in the cell to restart the database server processes
2604 only (the Authentication, Backup, Protection, and Volume Location
2605 Servers). Issue the commands in quick succession so that all of the
2606 database server processes vote in the quorum election.
2607 <PRE>   % <B>bos restart</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>kaserver buserver ptserver vlserver</B>
2608 </PRE>
2609 <P>If you are changing IP addresses on every database server machine in the
2610 cell, you must also issue the <B>bos restart</B> command on every file
2611 server machine in the cell to restart the <B>fs</B> process.
2612 <P><LI>If the machine is not a database server machine, issue the <B>bos
2613 restart</B> command to restart the <B>fs</B> process (if the machine is
2614 a database server, you already restarted the process in the previous
2615 step). The File Server automatically compiles a new list of interfaces,
2616 records them in the <B>/usr/afs/local/sysid</B> file, and registers them
2617 in its VLDB server entry.
2618 <PRE>   % <B>bos restart</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>fs</B>
2619 </PRE>
2620 <P><LI>If the machine is a database server machine, edit its entry in the
2621 <B>/usr/vice/etc/CellServDB</B> file on every client machine in the cell
2622 to list one of the new IP addresses. Instructions appear in <A HREF="auagd015.htm#HDRWQ406">Maintaining Knowledge of Database Server Machines</A>.
2623 <P><LI>If there are machine entries in the Protection Database for the
2624 machine's previous IP addresses, use the <B>pts rename</B> command to
2625 change them to the new addresses. For instructions, see <A HREF="auagd019.htm#HDRWQ556">Changing a Protection Database Entry's Name</A>.
2626 </OL>
2627 <A NAME="IDX6242"></A>
2628 <A NAME="IDX6243"></A>
2629 <A NAME="IDX6244"></A>
2630 <HR><H2><A NAME="HDRWQ139" HREF="auagd002.htm#ToC_161">Rebooting a Server Machine</A></H2>
2631 <P>You can reboot a server machine either by typing the
2632 appropriate commands at its console or by issuing the <B>bos exec</B>
2633 command on a remote machine. Remote rebooting can be more convenient,
2634 because you do not need to leave your present location, but you cannot track
2635 the progress of the reboot as you can at the console. Remote rebooting
2636 is possible because the server machine's operating system recognizes the
2637 BOS Server, which executes the <B>bos exec</B> command, as the local
2638 superuser <B>root</B>.
2639 <P>Rebooting server machines is part of routine maintenance in some cells, and
2640 some instructions in the AFS documentation include it as a step. It is
2641 certainly not intended to be the standard method for recovering from
2642 AFS-related problems, however, but only a last resort when the machine is
2643 unresponsive and you have tried all other reasonable options.
2644 <P>Rebooting causes a service outage. If the machine stores volumes,
2645 they are all inaccessible until the reboot completes and the File Server
2646 reattaches them. If the machine is a database server machine,
2647 information from the databases can become unavailable during the reelection of
2648 the synchronization site for each database server process; the VL Server
2649 outage generally has the greatest impact, because the Cache Manager must be
2650 able to access the VLDB to fetch AFS data.
2651 <P>By convention, a server machine's AFS initialization file includes the
2652 following command to restart the BOS Server after each reboot. It
2653 starts the other AFS server processes listed in the local
2654 <B>/usr/afs/local/BosConfig</B> file. These instructions assume
2655 that the initialization file includes the command.
2656 <PRE>   /usr/afs/bin/bosserver &amp;
2657 </PRE>
2658 <P><H3><A NAME="HDRWQ140" HREF="auagd002.htm#ToC_162">To reboot a file server machine from its console</A></H3>
2659 <OL TYPE=1>
2660 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
2661 already, by issuing the <B>su</B> command.
2662 <PRE>   % <B>su root</B>
2663    Password: <VAR>root_password</VAR>
2664 </PRE>
2665 <P><LI>Issue the <B>bos shutdown</B> command to shut down all AFS server
2666 processes other than the BOS Server, which terminates safely when you reboot
2667 the machine. Include the <B>-localauth</B> flag because you are
2668 logged in as the local superuser <B>root</B> but do not necessarily have
2669 administrative tokens. For a complete description of the command, see <A HREF="auagd009.htm#HDRWQ168">To stop processes temporarily</A>.
2670 <PRE>   # <B>bos shutdown</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>-localauth</B> [<B>-wait</B>]
2671 </PRE>
2672 <P><LI>Reboot the machine. On many system types, the appropriate command
2673 is <B>shutdown</B>, but the appropriate options vary; consult your
2674 UNIX administrator's guide.
2675 <PRE>    # <B>shutdown</B>
2676 </PRE>
2677 </OL>
2678 <A NAME="IDX6245"></A>
2679 <A NAME="IDX6246"></A>
2680 <P><H3><A NAME="HDRWQ141" HREF="auagd002.htm#ToC_163">To reboot a file server machine remotely</A></H3>
2681 <OL TYPE=1>
2682 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B> file on
2683 the machine you are rebooting. If necessary, issue the <B>bos
2684 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
2685 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
2686 </PRE>
2687 <P><LI>Issue the <B>bos shutdown</B> to halt AFS server processes other than
2688 the BOS Server, which terminates safely when you turn off the machine.
2689 For a complete description of the command, see <A HREF="auagd009.htm#HDRWQ168">To stop processes temporarily</A>.
2690 <PRE>   % <B>bos shutdown</B> &lt;<VAR>machine&nbsp;name</VAR>>  [<B>-wait</B>]
2691 </PRE>
2692 <P><LI>Issue the <B>bos exec</B> command to reboot the machine
2693 remotely.
2694 <PRE>   % <B>bos exec</B> &lt;<VAR>machine&nbsp;name</VAR>> <VAR>reboot_command</VAR>
2695 </PRE>
2696 <P>where
2697 <DL>
2698 <P><DT><B><VAR>machine name</VAR>
2699 </B><DD>Names the file server machine to reboot.
2700 <P><DT><B><VAR>reboot_command</VAR>
2701 </B><DD>Is the rebooting command for the machine's operating system.
2702 The <B>shutdown</B> command is appropriate on many system types, but
2703 consult your operating system documentation.
2704 </DL>
2705 </OL>
2706 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auagd002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auagd007.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auagd009.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auagd026.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
2707 <!-- Begin Footer Records  ========================================== -->
2708 <P><HR><B>
2709 <br>&#169; <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A>  All Rights Reserved
2710 </B>
2711 <!-- End Footer Records  ============================================ -->
2712 <A NAME="Bot_Of_Page"></A>
2713 </BODY></HTML>