Index: openafs/doc/man-pages/Makefile.in
diff -c openafs/doc/man-pages/Makefile.in:1.6 openafs/doc/man-pages/Makefile.in:1.6.4.1
*** openafs/doc/man-pages/Makefile.in:1.6	Wed Jan 25 00:59:38 2006
--- openafs/doc/man-pages/Makefile.in	Mon May 18 19:38:15 2009
***************
*** 11,16 ****
--- 11,18 ----
  html:
  	perl generate-html
  
+ LINKEDPAGES = klog pagsh tokens
+ 
  dest:
  	chmod +x install-man
  	mkdir -p $(DEST)/man/man1 $(DEST)/man/man5 $(DEST)/man/man8
***************
*** 23,28 ****
--- 25,35 ----
  	set -e; cd man8 && for M in *.8 ; do \
  	    ../install-man $$M $(DEST)/man/man8/$$M ; \
  	done
+ 	set -e; for M in ${LINKEDPAGES}; do \
+ 	    NEWPAGE=$(DEST)/man/man1/$$M.krb.1 ; \
+ 	    test -h ${NEWPAGE} || ln -s $$M.1 ${NEWPAGE} ; \
+ 	done
+ 
  
  install: $(MAN1) $(MAN8)
  	chmod +x install-man
***************
*** 37,39 ****
--- 44,50 ----
  	set -e; cd man8 && for M in *.8 ; do \
  	    ../install-man $$M $(DESTDIR)$(mandir)/man8/$$M ; \
  	done
+ 	set -e; for M in ${LINKEDPAGES}; do \
+ 	    NEWPAGE=$(DESTDIR)$(mandir)/man1/$$M.krb.1 ; \
+ 	    test -h ${NEWPAGE} || ln -s $$M.1 ${NEWPAGE} ; \
+ 	done
Index: openafs/doc/man-pages/NTMakefile
diff -c openafs/doc/man-pages/NTMakefile:1.1.2.3 openafs/doc/man-pages/NTMakefile:1.1.2.5
*** openafs/doc/man-pages/NTMakefile:1.1.2.3	Sun Jun 29 00:54:27 2008
--- openafs/doc/man-pages/NTMakefile	Mon May 25 19:54:06 2009
***************
*** 27,36 ****
  
  !INCLUDE ..\..\src\config\NTMakefile.$(SYS_NAME)
  
! install: 
          @echo Building man pages in HTML format
          perl generate-html
  
  clean::
          $(CD) html
          $(DEL) /s *.html
--- 27,352 ----
  
  !INCLUDE ..\..\src\config\NTMakefile.$(SYS_NAME)
  
! PODS = \
!         pod1\afs.pod                   \
!         pod1\afsmonitor.pod            \
!         pod1\aklog.pod                 \
!         pod1\cmdebug.pod               \
!         pod1\compile_et.pod            \
!         pod1\copyauth.pod              \
!         pod1\dlog.pod                  \
!         pod1\dpass.pod                 \
!         pod1\fs.pod                    \
!         pod1\fs_apropos.pod            \
!         pod1\fs_checkservers.pod       \
!         pod1\fs_checkvolumes.pod       \
!         pod1\fs_cleanacl.pod           \
!         pod1\fs_copyacl.pod            \
!         pod1\fs_cscpolicy.pod          \
!         pod1\fs_diskfree.pod           \
!         pod1\fs_examine.pod            \
!         pod1\fs_exportafs.pod          \
!         pod1\fs_flush.pod              \
!         pod1\fs_flushall.pod           \
!         pod1\fs_flushmount.pod         \
!         pod1\fs_flushvolume.pod        \
!         pod1\fs_getcacheparms.pod      \
!         pod1\fs_getcalleraccess.pod    \
!         pod1\fs_getcellstatus.pod      \
!         pod1\fs_getclientaddrs.pod     \
!         pod1\fs_getcrypt.pod           \
!         pod1\fs_getfid.pod             \
!         pod1\fs_getserverprefs.pod     \
!         pod1\fs_help.pod               \
!         pod1\fs_listacl.pod            \
!         pod1\fs_listaliases.pod        \
!         pod1\fs_listcells.pod          \
!         pod1\fs_listquota.pod          \
!         pod1\fs_lsmount.pod            \
!         pod1\fs_memdump.pod            \
!         pod1\fs_messages.pod           \
!         pod1\fs_minidump.pod           \
!         pod1\fs_mkmount.pod            \
!         pod1\fs_monitor.pod            \
!         pod1\fs_newalias.pod           \
!         pod1\fs_newcell.pod            \
!         pod1\fs_quota.pod              \
!         pod1\fs_rmmount.pod            \
!         pod1\fs_rxstatpeer.pod         \
!         pod1\fs_rxstatproc.pod         \
!         pod1\fs_setacl.pod             \
!         pod1\fs_setcachesize.pod       \
!         pod1\fs_setcbaddr.pod          \
!         pod1\fs_setcell.pod            \
!         pod1\fs_setclientaddrs.pod     \
!         pod1\fs_setcrypt.pod           \
!         pod1\fs_setquota.pod           \
!         pod1\fs_setserverprefs.pod     \
!         pod1\fs_setvol.pod             \
!         pod1\fs_storebehind.pod        \
!         pod1\fs_sysname.pod            \
!         pod1\fs_trace.pod              \
!         pod1\fs_uuid.pod               \
!         pod1\fs_whereis.pod            \
!         pod1\fs_whichcell.pod          \
!         pod1\fs_wscell.pod             \
!         pod1\klog.krb5.pod             \
!         pod1\klog.pod                  \
!         pod1\knfs.pod                  \
!         pod1\kpasswd.pod               \
!         pod1\livesys.pod               \
!         pod1\package_test.pod          \
!         pod1\pagsh.pod                 \
!         pod1\pts.pod                   \
!         pod1\pts_adduser.pod           \
!         pod1\pts_apropos.pod           \
!         pod1\pts_chown.pod             \
!         pod1\pts_creategroup.pod       \
!         pod1\pts_createuser.pod        \
!         pod1\pts_delete.pod            \
!         pod1\pts_examine.pod           \
!         pod1\pts_help.pod              \
!         pod1\pts_interactive.pod       \
!         pod1\pts_listentries.pod       \
!         pod1\pts_listmax.pod           \
!         pod1\pts_listowned.pod         \
!         pod1\pts_membership.pod        \
!         pod1\pts_quit.pod              \
!         pod1\pts_removeuser.pod        \
!         pod1\pts_rename.pod            \
!         pod1\pts_setfields.pod         \
!         pod1\pts_setmax.pod            \
!         pod1\pts_sleep.pod             \
!         pod1\pts_source.pod            \
!         pod1\rxdebug.pod               \
!         pod1\rxgen.pod                 \
!         pod1\scout.pod                 \
!         pod1\symlink.pod               \
!         pod1\symlink_list.pod          \
!         pod1\symlink_make.pod          \
!         pod1\symlink_remove.pod        \
!         pod1\sys.pod                   \
!         pod1\tokens.pod                \
!         pod1\translate_et.pod          \
!         pod1\udebug.pod                \
!         pod1\unlog.pod                 \
!         pod1\up.pod                    \
!         pod1\vos.pod                   \
!         pod1\vos_addsite.pod           \
!         pod1\vos_apropos.pod           \
!         pod1\vos_backup.pod            \
!         pod1\vos_backupsys.pod         \
!         pod1\vos_changeaddr.pod        \
!         pod1\vos_changeloc.pod         \
!         pod1\vos_clone.pod             \
!         pod1\vos_convertROtoRW.pod     \
!         pod1\vos_copy.pod              \
!         pod1\vos_create.pod            \
!         pod1\vos_delentry.pod          \
!         pod1\vos_dump.pod              \
!         pod1\vos_examine.pod           \
!         pod1\vos_help.pod              \
!         pod1\vos_listaddrs.pod         \
!         pod1\vos_listpart.pod          \
!         pod1\vos_listvldb.pod          \
!         pod1\vos_listvol.pod           \
!         pod1\vos_lock.pod              \
!         pod1\vos_move.pod              \
!         pod1\vos_offline.pod           \
!         pod1\vos_online.pod            \
!         pod1\vos_partinfo.pod          \
!         pod1\vos_release.pod           \
!         pod1\vos_remove.pod            \
!         pod1\vos_remsite.pod           \
!         pod1\vos_rename.pod            \
!         pod1\vos_restore.pod           \
!         pod1\vos_setfields.pod         \
!         pod1\vos_shadow.pod            \
!         pod1\vos_size.pod              \
!         pod1\vos_status.pod            \
!         pod1\vos_syncserv.pod          \
!         pod1\vos_syncvldb.pod          \
!         pod1\vos_unlock.pod            \
!         pod1\vos_unlockvldb.pod        \
!         pod1\vos_zap.pod               \
!         pod1\xstat_cm_test.pod         \
!         pod1\xstat_fs_test.pod         \
!         pod5\afs.pod                   \
!         pod5\afsmonitor.pod            \
!         pod5\afszcm.cat.pod            \
!         pod5\afs_cache.pod             \
!         pod5\afs_volume_header.pod     \
!         pod5\AuthLog.dir.pod           \
!         pod5\AuthLog.pod               \
!         pod5\BackupLog.pod             \
!         pod5\bdb.DB0.pod               \
!         pod5\BosConfig.pod             \
!         pod5\BosLog.pod                \
!         pod5\butc.pod                  \
!         pod5\butc_logs.pod             \
!         pod5\cacheinfo.pod             \
!         pod5\CellAlias.pod             \
!         pod5\CellServDB.pod            \
!         pod5\FileLog.pod               \
!         pod5\fms.log.pod               \
!         pod5\FORCESALVAGE.pod          \
!         pod5\kaserver.DB0.pod          \
!         pod5\kaserverauxdb.pod         \
!         pod5\KeyFile.pod               \
!         pod5\krb.conf.pod              \
!         pod5\NetInfo.pod               \
!         pod5\NetRestrict.pod           \
!         pod5\NoAuth.pod                \
!         pod5\package.pod               \
!         pod5\prdb.DB0.pod              \
!         pod5\SALVAGE.fs.pod            \
!         pod5\salvage.lock.pod          \
!         pod5\SalvageLog.pod            \
!         pod5\sysid.pod                 \
!         pod5\tapeconfig.pod            \
!         pod5\ThisCell.pod              \
!         pod5\UserList.pod              \
!         pod5\uss.pod                   \
!         pod5\uss_bulk.pod              \
!         pod5\vldb.DB0.pod              \
!         pod5\VLLog.pod                 \
!         pod5\VolserLog.pod             \
!         pod8\afsd.pod                  \
!         pod8\asetkey.pod               \
!         pod8\backup.pod                \
!         pod8\backup_adddump.pod        \
!         pod8\backup_addhost.pod        \
!         pod8\backup_addvolentry.pod    \
!         pod8\backup_addvolset.pod      \
!         pod8\backup_apropos.pod        \
!         pod8\backup_dbverify.pod       \
!         pod8\backup_deldump.pod        \
!         pod8\backup_deletedump.pod     \
!         pod8\backup_delhost.pod        \
!         pod8\backup_delvolentry.pod    \
!         pod8\backup_delvolset.pod      \
!         pod8\backup_diskrestore.pod    \
!         pod8\backup_dump.pod           \
!         pod8\backup_dumpinfo.pod       \
!         pod8\backup_help.pod           \
!         pod8\backup_interactive.pod    \
!         pod8\backup_jobs.pod           \
!         pod8\backup_kill.pod           \
!         pod8\backup_labeltape.pod      \
!         pod8\backup_listdumps.pod      \
!         pod8\backup_listhosts.pod      \
!         pod8\backup_listvolsets.pod    \
!         pod8\backup_quit.pod           \
!         pod8\backup_readlabel.pod      \
!         pod8\backup_restoredb.pod      \
!         pod8\backup_savedb.pod         \
!         pod8\backup_scantape.pod       \
!         pod8\backup_setexp.pod         \
!         pod8\backup_status.pod         \
!         pod8\backup_volinfo.pod        \
!         pod8\backup_volrestore.pod     \
!         pod8\backup_volsetrestore.pod  \
!         pod8\bos.pod                   \
!         pod8\bosserver.pod             \
!         pod8\bos_addhost.pod           \
!         pod8\bos_addkey.pod            \
!         pod8\bos_adduser.pod           \
!         pod8\bos_apropos.pod           \
!         pod8\bos_create.pod            \
!         pod8\bos_delete.pod            \
!         pod8\bos_exec.pod              \
!         pod8\bos_getdate.pod           \
!         pod8\bos_getlog.pod            \
!         pod8\bos_getrestart.pod        \
!         pod8\bos_help.pod              \
!         pod8\bos_install.pod           \
!         pod8\bos_listhosts.pod         \
!         pod8\bos_listkeys.pod          \
!         pod8\bos_listusers.pod         \
!         pod8\bos_prune.pod             \
!         pod8\bos_removehost.pod        \
!         pod8\bos_removekey.pod         \
!         pod8\bos_removeuser.pod        \
!         pod8\bos_restart.pod           \
!         pod8\bos_salvage.pod           \
!         pod8\bos_setauth.pod           \
!         pod8\bos_setcellname.pod       \
!         pod8\bos_setrestart.pod        \
!         pod8\bos_shutdown.pod          \
!         pod8\bos_start.pod             \
!         pod8\bos_startup.pod           \
!         pod8\bos_status.pod            \
!         pod8\bos_stop.pod              \
!         pod8\bos_uninstall.pod         \
!         pod8\bos_util.pod              \
!         pod8\buserver.pod              \
!         pod8\butc.pod                  \
!         pod8\fileserver.pod            \
!         pod8\fms.pod                   \
!         pod8\fstrace.pod               \
!         pod8\fstrace_apropos.pod       \
!         pod8\fstrace_clear.pod         \
!         pod8\fstrace_dump.pod          \
!         pod8\fstrace_help.pod          \
!         pod8\fstrace_lslog.pod         \
!         pod8\fstrace_lsset.pod         \
!         pod8\fstrace_setlog.pod        \
!         pod8\fstrace_setset.pod        \
!         pod8\ka-forwarder.pod          \
!         pod8\kadb_check.pod            \
!         pod8\kas.pod                   \
!         pod8\kaserver.pod              \
!         pod8\kas_apropos.pod           \
!         pod8\kas_create.pod            \
!         pod8\kas_delete.pod            \
!         pod8\kas_examine.pod           \
!         pod8\kas_forgetticket.pod      \
!         pod8\kas_help.pod              \
!         pod8\kas_interactive.pod       \
!         pod8\kas_list.pod              \
!         pod8\kas_listtickets.pod       \
!         pod8\kas_noauthentication.pod  \
!         pod8\kas_quit.pod              \
!         pod8\kas_setfields.pod         \
!         pod8\kas_setpassword.pod       \
!         pod8\kas_statistics.pod        \
!         pod8\kas_stringtokey.pod       \
!         pod8\kas_unlock.pod            \
!         pod8\kdb.pod                   \
!         pod8\kpwvalid.pod              \
!         pod8\package.pod               \
!         pod8\prdb_check.pod            \
!         pod8\ptserver.pod              \
!         pod8\pt_util.pod               \
!         pod8\read_tape.pod             \
!         pod8\restorevol.pod            \
!         pod8\rmtsysd.pod               \
!         pod8\salvager.pod              \
!         pod8\salvageserver.pod         \
!         pod8\upclient.pod              \
!         pod8\upserver.pod              \
!         pod8\uss.pod                   \
!         pod8\uss_add.pod               \
!         pod8\uss_apropos.pod           \
!         pod8\uss_bulk.pod              \
!         pod8\uss_delete.pod            \
!         pod8\uss_help.pod              \
!         pod8\vldb_check.pod            \
!         pod8\vldb_convert.pod          \
!         pod8\vlserver.pod              \
!         pod8\voldump.pod               \
!         pod8\volinfo.pod               \
!         pod8\volserver.pod             \
!         pod8\vsys.pod                  \
!         pod8\xfs_size_check.pod
! 
! html\index.html: $(PODS)
          @echo Building man pages in HTML format
          perl generate-html
  
+ 
+ install: html\index.html
+ 
  clean::
          $(CD) html
          $(DEL) /s *.html
Index: openafs/doc/man-pages/README
diff -c openafs/doc/man-pages/README:1.8.2.24 openafs/doc/man-pages/README:1.8.2.35
*** openafs/doc/man-pages/README:1.8.2.24	Mon Mar 16 22:30:01 2009
--- openafs/doc/man-pages/README	Mon May 18 19:38:15 2009
***************
*** 229,261 ****
    don't just report the deficiency again, but any contributions towards
    fixing it are greatly appreciated.
  
-    * The following installed commands have no man pages:
- 
-        compile_et.afs
-        copyauth
-        fs cscpolicy
-        fs getfid
-        fs memdump
-        fs monitor
-        fs rxstatpeer
-        fs rxstatproc
-        fs setcbaddr
-        fs trace
-        klog.krb
-        krb.conf
-        pagsh.krb
-        restorevol
-        rmtsysd
-        tokens.krb
-        vsys
- 
     * Add -noresolve to the documentation of all the vos commands.
  
-    * klog.krb, pagsh.krb, and tokens.krb need to be listed as alternative
-      names in the NAME line of the non-.krb man pages, links should be
-      installed on man page installation, and the behavior of pagsh.krb
-      should be documented in the pagsh man page.
- 
     * Some of the documentation in fs getserverprefs needs minor updates to
       reflect what happens in the dynroot case.
  
--- 229,236 ----
***************
*** 278,285 ****
     * The salvager actually creates a bunch of SalvageLog files and then
       combines them, but the SalvageLog man page doesn't reflect this.
  
-    * The CellServDB documentation hasn't been updated for -dynroot.
- 
     * The aklog man page isn't in POD.  (Neither is the mpp man page, but
       I don't think we care about it and it's not currently installed.)
  
--- 253,258 ----
Index: openafs/doc/man-pages/pod1/compile_et.pod
diff -c /dev/null openafs/doc/man-pages/pod1/compile_et.pod:1.1.2.2
*** /dev/null	Sat May 30 21:40:41 2009
--- openafs/doc/man-pages/pod1/compile_et.pod	Mon May 18 19:33:02 2009
***************
*** 0 ****
--- 1,83 ----
+ =head1 NAME
+ 
+ compile_et - Produce error text tables for compilation
+ 
+ =head1 SYNOPSIS
+ 
+ =for html
+ <div class="synopsis">
+ 
+ B<compile_et> [B<-debug>] S<<< [B<-language> <I<lang>>] >>>
+     S<<< [B<-prefix> <I<prefix>>] >>> [B<-v> <I<version>>] <I<error_table>>
+ 
+ =for html
+ </div>
+ 
+ =head1 DESCRIPTION
+ 
+ The B<compile_et> command builds the error text tables for compilation.
+ This includes both a header file that contains a set of mappings between
+ error names and values and a F<.c> (or F<.msf>) file that provides a text
+ table of descriptions.
+ 
+ The <I<error_table>> argument specifies which error table to generate.
+ The error table specification should exist in the current working
+ directory or in the directory specified with B<-prefix> and should be
+ named F<error_table.et>.
+ 
+ =head1 CAUTIONS
+ 
+ This command is used internally within the build process for OpenAFS.
+ Most users will access this information via L<translate_et(1)> rather than
+ via B<compile_et>.
+ 
+ This command does not use the standard AFS command-line parsing package.
+ 
+ =head1 OPTIONS
+ 
+ =over 4
+ 
+ =item B<-debug>
+ 
+ Does nothing.  It neither adds debugging information to the output nor
+ provides additional information on its operation.
+ 
+ =item B<-language> <I<lang>>
+ 
+ Specifies the type of output to generate.  Currently, only ANSI C and K&R
+ are supported values (via the B<c> and B<k&r-c> values, respectively).
+ The default is ANSI C.  There is some support for C++ started, but that is
+ not yet supported.
+ 
+ =item B<-prefix <I<prefix>>
+ 
+ Specifies the directory to search for the F<error_table.et> file.
+ 
+ =item B<-v> <I<version>>
+ 
+ Specified the type of output file: valid values are 1 (the default, for C
+ files) or 2, for B<.msf> file generation.
+ 
+ =back
+ 
+ =head1 EXAMPLES
+ 
+ The following command generates the files F<pterror.h> and F<pterror.c>, 
+ suitable for use with C programs:
+ 
+    % compile_et -p path/to/src/ptserver pterror
+ 
+ The following command generates K&R style files instead:
+ 
+    % compile_et -p path/to/src/ptserver -lang 'k&r-c' pterror
+ 
+ =head1 SEE ALSO
+ 
+ L<translate_et(1)>
+ 
+ =head1 COPYRIGHT
+ 
+ Copyright 2009 Steven Jenkins <steven@endpoint.com>
+ 
+ This documentation is covered by the IBM Public License Version 1.0.  This
+ man page was written by Steven Jenkins for OpenAFS.
Index: openafs/doc/man-pages/pod1/copyauth.pod
diff -c /dev/null openafs/doc/man-pages/pod1/copyauth.pod:1.1.2.2
*** /dev/null	Sat May 30 21:40:41 2009
--- openafs/doc/man-pages/pod1/copyauth.pod	Mon May 18 19:33:26 2009
***************
*** 0 ****
--- 1,44 ----
+ =head1 NAME
+ 
+ copyauth - Copies user's AFS credentials to a new cell
+ 
+ =head1 SYNOPSIS
+ 
+ =for html
+ <div class="synopsis">
+ 
+ B<copyauth> S<<< <I<cell name>> >>> 
+ 
+ =for html
+ </div>
+ 
+ =head1 DESCRIPTION
+ 
+ The B<copyauth> command copies existing AFS credentials in the local
+ cell to the foreign cell specified on the command line.  
+ 
+ The functionality in this command is largely superseded by L<aklog(1)>.
+ 
+ =head1 CAUTIONS
+ 
+ This functionality only works if you have a shared AFS key across multiple
+ cells, which is strongly discouraged as it weakens security.  If you do
+ not understand those risks, you should not use this tool.
+ 
+ =head1 EXAMPLES
+ 
+    % copyauth other.cell.org
+ 
+ =head1 PRIVILEGE REQUIRED
+ 
+ None.
+ 
+ =head1 SEE ALSO
+ 
+ L<aklog(1)>,
+ L<tokens(1)>
+ 
+ =head1 COPYRIGHT
+ 
+ This documentation was written by Steven Jenkins and is covered 
+ by the IBM Public License Version 1.0. 
Index: openafs/doc/man-pages/pod1/fs.pod
diff -c openafs/doc/man-pages/pod1/fs.pod:1.4.2.4 openafs/doc/man-pages/pod1/fs.pod:1.4.2.7
*** openafs/doc/man-pages/pod1/fs.pod:1.4.2.4	Tue Dec 25 17:26:43 2007
--- openafs/doc/man-pages/pod1/fs.pod	Mon May 18 19:33:43 2009
***************
*** 23,28 ****
--- 23,29 ----
  L<B<fs getserverprefs>|fs_getserverprefs(1)>,
  L<B<fs listcells>|fs_listcells(1)>,
  L<B<fs newcell>|fs_newcell(1)>,
+ L<B<fs setcbaddr>|fs_setcbaddr(1)>,
  L<B<fs setcell>|fs_setcell(1)>,
  L<B<fs setcrypt>|fs_setcrypt(1)>,
  L<B<fs setserverprefs>|fs_setserverprefs(1)>,
***************
*** 45,50 ****
--- 46,52 ----
  given file or directory:
  L<B<fs diskfree>|fs_diskfree(1)>,
  L<B<fs examine>|fs_examine(1)>,
+ L<B<fs getfid>|fs_getfid(1)>,
  L<B<fs listquota>|fs_listquota(1)>,
  L<B<fs quota>|fs_quota(1)>,
  L<B<fs setquota>|fs_setquota(1)>,
***************
*** 56,61 ****
--- 58,64 ----
  
  Commands to administer the local client cache and related information:
  L<B<fs checkvolumes>|fs_checkvolumes(1)>,
+ L<B<fs cscpolicy>|fs_cscpolicy(1)>,
  L<B<fs flush>|fs_flush(1)>,
  L<B<fs flushall>|fs_flushall(1)>,
  L<B<fs flushvolume>|fs_flushvolume(1)>,
***************
*** 75,81 ****
  
  Commands to control monitoring and tracing:
  L<B<fs debug>|fs_debug(1)>,
! and L<B<fs messages>|fs_messages(1)>.
  
  =item *
  
--- 78,90 ----
  
  Commands to control monitoring and tracing:
  L<B<fs debug>|fs_debug(1)>,
! L<B<fs memdump>|fs_memdump(1)>,
! L<B<fs messages>|fs_messages(1)>,
! L<B<fs minidump>|fs_minidump(1)>,
! L<B<fs monitor>|fs_monitor(1)>,
! L<B<fs rxstatpeer>|fs_rxstatpeer(1)>,
! L<B<fs rxstatproc>|fs_rxstatproc(1)>,
! and L<B<fs trace>|fs_trace(1)>.
  
  =item *
  
***************
*** 184,189 ****
--- 193,199 ----
  L<fs_checkvolumes(1)>,
  L<fs_cleanacl(1)>,
  L<fs_copyacl(1)>,
+ L<fs_cscpolicy(1)>,
  L<fs_diskfree(1)>,
  L<fs_examine(1)>,
  L<fs_exportafs(1)>,
***************
*** 196,201 ****
--- 206,212 ----
  L<fs_getcellstatus(1)>,
  L<fs_getclientaddrs(1)>,
  L<fs_getcrypt(1)>,
+ L<fs_getfid(1)>,
  L<fs_getserverprefs(1)>,
  L<fs_help(1)>,
  L<fs_listacl(1)>,
***************
*** 203,216 ****
--- 214,233 ----
  L<fs_listcells(1)>,
  L<fs_listquota(1)>,
  L<fs_lsmount(1)>,
+ L<fs_memdump(1)>,
  L<fs_messages(1)>,
+ L<fs_minidump(1)>,
  L<fs_mkmount(1)>,
+ L<fs_monitor(1)>,
  L<fs_newalias(1)>,
  L<fs_newcell(1)>,
  L<fs_quota(1)>,
  L<fs_rmmount(1)>,
+ L<fs_rxstatpeer(1)>,
+ L<fs_rxstatproc(1)>,
  L<fs_setacl(1)>,
  L<fs_setcachesize(1)>,
+ L<fs_setcbattr(1)>,
  L<fs_setcell(1)>,
  L<fs_setclientaddrs(1)>,
  L<fs_setcrypt(1)>,
***************
*** 219,224 ****
--- 236,242 ----
  L<fs_setvol(1)>,
  L<fs_storebehind(1)>,
  L<fs_sysname(1)>,
+ L<fs_trace(1)>,
  L<fs_whereis(1)>,
  L<fs_whichcell(1)>,
  L<fs_wscell(1)>
Index: openafs/doc/man-pages/pod1/fs_cscpolicy.pod
diff -c /dev/null openafs/doc/man-pages/pod1/fs_cscpolicy.pod:1.1.2.2
*** /dev/null	Sat May 30 21:40:41 2009
--- openafs/doc/man-pages/pod1/fs_cscpolicy.pod	Sun May 17 23:40:27 2009
***************
*** 0 ****
--- 1,107 ----
+ =head1 NAME
+ 
+ fs_cscpolicy - Change client side caching policy for AFS shares
+ 
+ =head1 SYNOPSIS
+ 
+ =for html
+ <div class="synopsis">
+ 
+ B<fs cscpolicy> S<<< [B<-share> I<sharename> [B<-manual>|B<-programs>|B<-documents>|B<-disable>] ] >>>
+ 
+ =for html
+ </div>
+ 
+ =head1 DESCRIPTION
+ 
+ The fs cscpolicy command sets the client side caching policy for a
+ particular AFS share, or displays a list of policies.
+ 
+ This command can change the policy of only one share at a time.
+ 
+ Only one of the policy options B<-manual>, B<-programs>, B<-documents>, or
+ B<-disable>, may be selected.  The default policy is B<-manual>.
+ 
+ After changing the policy for a share, you must close all applications
+ that accessed files on this share, or restart AFS Client, for the change
+ to take effect.
+ 
+ =head1 CAUTIONS
+ 
+ This command is only available on Windows.
+ 
+ Use of this functionality is not recommended.  Windows Offline Folders do
+ not work well with AFS since the AFS server is always present.  When this
+ functionality was contributed and incorporated, it was believed to be safe
+ for the AFS cache manager to return BADNETPATH errors when a single file
+ server or volume was inaccessible.  It is now known that returning such
+ errors causes the Microsoft SMB redirector to drop the connection to the
+ AFS server resulting in serious side effects.
+ 
+ This functionality is specific to use with the Microsoft SMB redirector.
+ Client Side Caching (Offline Folders) is built into that driver and will
+ not be present in the native AFS redirector, so this functionality will be
+ removed at a future date.
+ 
+ =head1 OPTIONS
+ 
+ =over 4
+ 
+ =item B<-share> I<sharename>
+ 
+ The name of the share whose policy is to be changed.  (If omitted, no
+ share policy is changed.)
+ 
+ =item B<-manual>
+ 
+ Specifies manual caching of documents.
+ 
+ =item B<-programs>
+ 
+ Specifies automatic caching of programs and documents.
+ 
+ =item B<-documents>
+ 
+ Specifies automatic caching of documents.
+ 
+ =item B<-disable>
+ 
+ Disables caching.
+ 
+ =back
+ 
+ =head1 OUTPUT
+ 
+ When changing the policy of a share, the output is:
+ 
+    CSC policy on share "share" changed to "policy".
+    Close all applications that accessed files on this share or restart AFS Client for the change to take effect.
+ 
+ When displaying policies, the output is:
+ 
+    policyname = policy
+ 
+ =head1 EXAMPLES
+ 
+ The following command disables all caching on the share "AFS1":
+ 
+    % fs cscpolicy -share AFS1 -disable
+ 
+ The following command displays all policies currently in effect:
+ 
+    % fs cscpolicy
+ 
+ =head1 PRIVILEGE REQUIRED
+ 
+ The issuer must be have AFS Client Administrator access, either to display
+ or to set policies.
+ 
+ In addition, to change policies, the issuer must be a Windows
+ Administrator, since policy information is stored in a protected area of
+ the Windows Registry.
+ 
+ =head1 COPYRIGHT
+ 
+ This document was written by Mike Robinson, and is released under the IBM
+ Public License Version 1.0.  Jeffrey Altman made several corrections,
+ clarifications, and additions.
Index: openafs/doc/man-pages/pod1/fs_getfid.pod
diff -c /dev/null openafs/doc/man-pages/pod1/fs_getfid.pod:1.1.2.2
*** /dev/null	Sat May 30 21:40:41 2009
--- openafs/doc/man-pages/pod1/fs_getfid.pod	Sun May 17 23:40:27 2009
***************
*** 0 ****
--- 1,82 ----
+ =head1 NAME
+ 
+ fs_getfid - Display the fid for a given path in AFS
+ 
+ =head1 SYNOPSIS
+ 
+ =for html
+ <div class="synopsis">
+ 
+ B<fs getfid> S<<< [B<-path>] I<path> >>> [B<-help>]
+ 
+ =for html
+ </div>
+ 
+ =head1 DESCRIPTION
+ 
+ The fs getfid command displays the FID for a given path in AFS.  The FID
+ is the internal identifier used by AFS encoding the volume name and the
+ file within a volume.
+ 
+ =head1 CAUTIONS
+ 
+ This command is not available on Windows prior to version 1.5.60.
+ 
+ =head1 OPTIONS
+ 
+ =over 4
+ 
+ =item B<-path> I<path>
+ 
+ The path of the file (or directory).
+ 
+ =item B<-literal>
+ 
+ Windows only: for a symlink or mount point, evaluates the specified object
+ rather than the object it refers to.
+ 
+ =item B<-help>
+ 
+ Prints the online help for this command. All other valid options are
+ ignored.
+ 
+ =back
+ 
+ =head1 OUTPUT
+ 
+ The output contains the name of the file or directory, the FID, and the
+ volume containing the FID.  The Windows version also outputs the object
+ type instead of using "File" to describe all objects.
+ 
+ =head1 EXAMPLES
+ 
+ On Unix:
+ 
+    % fs getfid .
+    File . (536870918.1.1) contained in volume 536870918
+ 
+    % fs getfid /afs/example.com/foo 
+    File /afs/example.com/foo (536870918.20404.20997) contained in volume 536870918
+ 
+ On Windows:
+ 
+    % fs.exe getfid \\afs\example.edu\user\b\o\bob \
+        \\afs\example.org\usr\bob\linktests\broken
+    Directory \\afs\example.edu\user\b\o\bob (537235559.1.1) contained in cell example.edu
+    fs: File '\\afs\example.org\usr\bob\linktests\broken' doesn't exist
+ 
+    % fs.exe getfid \\afs\example.edu\user\b\o\bob \
+        \\afs\example.org\usr\bob\linktests\broken -literal
+    Mountpoint \\afs\example.edu\user\b\o\bob (536873032.1162.16997) contained in cell example.edu
+    Symlink \\afs\example.org\usr\bob\linktests\broken (536874416.27618.488969) contained in cell example.org
+ 
+ =head1 PRIVILEGE REQUIRED
+ 
+ The issuer must be have read access in the directory containing the path
+ to be resolved.
+ 
+ =head1 COPYRIGHT
+ 
+ This document was written by Steven Jenkins, and is released under the IBM
+ Public License Version 1.0.  Jeffrey Altman made several suggestions and
+ additions.
Index: openafs/doc/man-pages/pod1/fs_memdump.pod
diff -c /dev/null openafs/doc/man-pages/pod1/fs_memdump.pod:1.1.2.2
*** /dev/null	Sat May 30 21:40:41 2009
--- openafs/doc/man-pages/pod1/fs_memdump.pod	Sun May 17 23:40:27 2009
***************
*** 0 ****
--- 1,71 ----
+ =head1 NAME
+ 
+ fs_memdump - Dump AFS cache state and memory allocations
+ 
+ =head1 SYNOPSIS
+ 
+ =for html
+ <div class="synopsis">
+ 
+ B<fs memdump> S<<< [B<-begin>|B<-end>] >>>
+ 
+ =for html
+ </div>
+ 
+ =head1 DESCRIPTION
+ 
+ This command dumps the state of AFS cache manager objects and statistics.
+ If a checked build of the C run-time library is in use, memory allocations
+ will also be included.
+ 
+ =head1 CAUTIONS
+ 
+ This command is only available on Windows.
+ 
+ =head1 OPTIONS
+ 
+ (One of either B<-begin> or B<-end> must be specified.)
+ 
+ =over 4
+ 
+ =item B<-begin>
+ 
+ Set a memory checkpoint.
+ 
+ =item B<-end>
+ 
+ Create a dump-file containing information about memory allocation that has
+ taken place since the B<-begin> command was issued.
+ 
+ =back
+ 
+ =head1 OUTPUT
+ 
+ If successful, the output of this command (for B<-begin> I<or> B<-end>)
+ will be:
+ 
+    AFS memdump created
+ 
+ If unsuccessful:
+ 
+    AFS memdump failed
+ 
+ =head1 EXAMPLES
+ 
+ The following command starts a memory allocation dump:
+ 
+    % fs memdump -begin
+ 
+ The following command ends it:
+ 
+    % fs memdump -end
+ 
+ =head1 PRIVILEGE REQUIRED
+ 
+ The issuer must be have AFS Client Administrator access to issue this
+ command.
+ 
+ =head1 COPYRIGHT
+ 
+ This document was written by Mike Robinson, and is released under the IBM
+ Public License Version 1.0.
Index: openafs/doc/man-pages/pod1/fs_monitor.pod
diff -c /dev/null openafs/doc/man-pages/pod1/fs_monitor.pod:1.1.2.2
*** /dev/null	Sat May 30 21:40:41 2009
--- openafs/doc/man-pages/pod1/fs_monitor.pod	Mon May 18 19:33:44 2009
***************
*** 0 ****
--- 1,54 ----
+ =head1 NAME
+ 
+ fs_monitor - Enable client logging to a remote monitoring station
+ 
+ =head1 SYNOPSIS
+ 
+ =for html
+ <div class="synopsis">
+ 
+ B<fs monitor> S<<< [B<-server> <I<hostname/IP address or 'off'>>] >>> [B<-help>]
+ 
+ B<fs mariner> S<<< [B<-server> <I<hostname/IP address or 'off'>>] >>> [B<-help>]
+ 
+ =for html
+ </div>
+ 
+ =head1 DESCRIPTION
+ 
+ The B<fs monitor> command (aka B<mariner>) sets the cache monitor host
+ address (or turns it off).
+ 
+ =head1 CAUTIONS
+ 
+ This command is hidden since the necessary remote monitoring component,
+ B<venusmon>, is not part of OpenAFS.  This system is not currently
+ distributed or supported.
+ 
+ =head1 OPTIONS
+ 
+ =over 4
+ 
+ =item B<-server> <I<hostname/IP address or 'off'>>
+ 
+ Name (or address) of the B<venusmon> host that monitoring information
+ should be sent to.  Setting the server to I<off> turns off monitoring.
+ 
+ =item B<-help>
+ 
+ Prints the online help for this command.  All other valid options are
+ ignored.
+ 
+ =back
+ 
+ =head1 PRIVILEGE REQUIRED
+ 
+ The issuer must be super-user on the local machine.
+ 
+ =head1 COPYRIGHT
+ 
+ Copyright 2009 Steven Jenkins <steven@endpoint.com>
+ 
+ This documentation is covered by the BSD License as written in the
+ doc/LICENSE file. This man page was written by Steven Jenkins for
+ OpenAFS.
Index: openafs/doc/man-pages/pod1/fs_rxstatpeer.pod
diff -c openafs/doc/man-pages/pod1/fs_rxstatpeer.pod:1.1.2.3 openafs/doc/man-pages/pod1/fs_rxstatpeer.pod:1.1.2.4
*** openafs/doc/man-pages/pod1/fs_rxstatpeer.pod:1.1.2.3	Tue Dec 25 17:30:01 2007
--- openafs/doc/man-pages/pod1/fs_rxstatpeer.pod	Sun May 17 23:40:54 2009
***************
*** 1,6 ****
  =head1 NAME
  
! fs_rxstatpeer - Enables Rx packet logging in the OpenAFS kernel module
  
  =head1 SYNOPSIS
  
--- 1,6 ----
  =head1 NAME
  
! fs_rxstatpeer - Manage per-peer Rx statistics collection
  
  =head1 SYNOPSIS
  
***************
*** 57,62 ****
--- 57,63 ----
  =head1 SEE ALSO
  
  L<fs(1)>,
+ L<fs_rxstatproc(1)>,
  L<rxdebug(1)>
  
  =head1 COPYRIGHT
Index: openafs/doc/man-pages/pod1/fs_rxstatproc.pod
diff -c /dev/null openafs/doc/man-pages/pod1/fs_rxstatproc.pod:1.1.2.3
*** /dev/null	Sat May 30 21:40:41 2009
--- openafs/doc/man-pages/pod1/fs_rxstatproc.pod	Mon May 18 19:57:08 2009
***************
*** 0 ****
--- 1,65 ----
+ =head1 NAME
+ 
+ fs_rxstatproc - Manage per-process Rx statistics collection
+ 
+ =head1 SYNOPSIS
+ 
+ =for html
+ <div class="synopsis">
+ 
+ B<fs rxstatproc> [B<-enable>] [B<-disable>] [B<-clear>]
+ 
+ =for html
+ </div>
+ 
+ =head1 DESCRIPTION
+ 
+ This command enables or disables the updating of RPC statistics counters
+ related to the entire RX process, or sets the accumulated counter values
+ back to zero.
+ 
+ =head1 OPTIONS
+ 
+ One or more of the following options must be specified:
+ 
+ =over 4
+ 
+ =item B<-enable>
+ 
+ Enable the collection of process RPC statistics
+ 
+ =item B<-disable>
+ 
+ Enable the collection of process RPC statistics
+ 
+ =item B<-clear>
+ 
+ Resets all trace counters to zero.
+ 
+ =back
+ 
+ =head1 OUTPUT
+ 
+ This command produces no output other than error-messages.
+ 
+ =head1 EXAMPLES
+ 
+ The following command starts collecting statistics:
+ 
+    % fs rxstatproc -enable
+ 
+ =head1 PRIVILEGE REQUIRED
+ 
+ The issuer must be logged in as the local superuser root.
+ 
+ =head1 SEE ALSO
+ 
+ L<fs(1)>,
+ L<fs_rxstatpeer(1)>,
+ L<rxdebug(1)>
+ 
+ =head1 COPYRIGHT
+ 
+ Copyright 2008. This documentation is covered by the BSD License as
+ written in the doc/LICENSE file. This man page was written by Mike
+ Robinson (L<mike@endpoint.com>) for OpenAFS.
Index: openafs/doc/man-pages/pod1/fs_setcbaddr.pod
diff -c /dev/null openafs/doc/man-pages/pod1/fs_setcbaddr.pod:1.1.2.2
*** /dev/null	Sat May 30 21:40:41 2009
--- openafs/doc/man-pages/pod1/fs_setcbaddr.pod	Sun May 17 23:40:54 2009
***************
*** 0 ****
--- 1,49 ----
+ =head1 NAME
+ 
+ fs_setcbaddr - Configure IP address used for AFS callbacks
+ 
+ =head1 SYNOPSIS
+ 
+ =for html
+ <div class="synopsis">
+ 
+ B<fs setcbaddr> S<<< [B<-host> <I<address>>] >>>
+ 
+ =for html
+ </div>
+ 
+ =head1 DESCRIPTION
+ 
+ B<fs setcbaddr> changes the IP address used by the client for callbacks.
+ 
+ =head1 OPTIONS
+ 
+ =over 4
+ 
+ =item B<-host> <I<address>>]
+ 
+ The new callback address.
+ 
+ =back
+ 
+ =head1 OUTPUT
+ 
+ This command produces no output other than error messages.
+ 
+ =head1 EXAMPLES
+ 
+    % fs setcbaddr 10.2.4.23
+ 
+ =head1 PRIVILEGE REQUIRED
+ 
+ The issuer must be the local superuser.
+ 
+ =head1 SEE ALSO
+ 
+ L<fs(1)>
+ 
+ =head1 COPYRIGHT
+ 
+ Copyright 2008. This documentation is covered by the BSD License as
+ written in the doc/LICENSE file. This man page was written by Mike
+ Robinson (L<mike@endpoint.com>) for OpenAFS.
Index: openafs/doc/man-pages/pod1/fs_trace.pod
diff -c /dev/null openafs/doc/man-pages/pod1/fs_trace.pod:1.1.2.3
*** /dev/null	Sat May 30 21:40:41 2009
--- openafs/doc/man-pages/pod1/fs_trace.pod	Mon May 18 19:57:08 2009
***************
*** 0 ****
--- 1,86 ----
+ =head1 NAME
+ 
+ fs_trace - Enable or disable AFS Cache Manager tracing 
+ 
+ =head1 SYNOPSIS
+ 
+ =for html
+ <div class="synopsis">
+ 
+ B<fs trace> S<<< [B<-on>|B<-off>] >>> [B<-reset>] [B<-dump>]
+ 
+ =for html
+ </div>
+ 
+ =head1 DESCRIPTION
+ 
+ This command enables or disables AFS Cache Manager tracing, resets the
+ trace log, or dumps the log.  When you dump the log, two files are created
+ in the Windows Temporary directory:  F<afs-buffer.log> and F<afsd.log>.
+ Any existing files with those names will be replaced.
+ 
+ =head1 CAUTIONS
+ 
+ This command is only available on Windows.
+ 
+ =head1 OPTIONS
+ 
+ Any combination of the following options may be specified, except that
+ both B<-on> and B<-off> cannot be specified at the same time.
+ 
+ =over 4
+ 
+ =item B<-on>
+ 
+ Turn tracing on.
+ 
+ =item B<-off>
+ 
+ Turn tracing off.
+ 
+ =item B<-reset>
+ 
+ Resets the tracing information, discarding any trace-information collected
+ up to this time.
+ 
+ =item B<-dump>
+ 
+ Creates a dump file containing the trace information.
+ 
+ =back
+ 
+ =head1 OUTPUT
+ 
+ If successful, the output of this command (for any option) will be:
+ 
+    AFS tracing enabled
+ 
+ If unsuccessful:
+ 
+    AFS tracing disabled
+ 
+ =head1 EXAMPLES
+ 
+ The following command starts tracing:
+ 
+    % fs trace -on
+ 
+ The following dumps the current contents and resets the trace log, then
+ turns tracing off:
+ 
+    % fs trace -dump -reset -off
+ 
+ =head1 PRIVILEGE REQUIRED
+ 
+ The issuer must be have AFS Client Administrator access to issue this
+ command.
+ 
+ =head1 SEE ALSO
+ 
+ L<fs(1)>
+ 
+ =head1 COPYRIGHT
+ 
+ Copyright 2008. This documentation is covered by the BSD License as
+ written in the doc/LICENSE file. This man page was written by Mike
+ Robinson (L<mike@endpoint.com>) for OpenAFS.
Index: openafs/doc/man-pages/pod1/klog.pod
diff -c openafs/doc/man-pages/pod1/klog.pod:1.4.2.1 openafs/doc/man-pages/pod1/klog.pod:1.4.2.2
*** openafs/doc/man-pages/pod1/klog.pod:1.4.2.1	Fri Jul 27 14:00:25 2007
--- openafs/doc/man-pages/pod1/klog.pod	Mon May 18 19:38:15 2009
***************
*** 1,6 ****
  =head1 NAME
  
! klog - Authenticates with the Authentication Server
  
  =head1 SYNOPSIS
  
--- 1,6 ----
  =head1 NAME
  
! klog, klog.krb - Authenticates with the Authentication Server
  
  =head1 SYNOPSIS
  
***************
*** 19,24 ****
--- 19,31 ----
      [B<-pi>] [B<-si>] S<<< [B<-l> <I<ticket lifetime in hh[:mm[:ss]]>>] >>>
      [B<-se>] [B<-t>] [B<-h>]
  
+ B<klog.krb> [B<-x>] S<<< [B<-principal> <I<user name>>] >>>
+     [-password <I<user's password>>] S<<< [B<-cell> <I<cell name>>] >>>
+     S<<< [B<-servers> <I<explicit list of servers>>+] >>>
+     [B<-pipe>] [B<-silent>]
+     S<<< [B<-lifetime> <I<ticket lifetime in hh[:mm[:ss]]>>] >>>
+     [B<-setpag>] [B<-tmp>] [B<-help>]
+ 
  =for html
  </div>
  
***************
*** 54,60 ****
  B<aklog> instead of B<klog>.
  
  Sites using Kerberos v4 authentication (perhaps with the AFS
! Authentication Server) must use the Kerberos version of this command,
  B<klog.krb>, on all client machines. It automatically places the issuer's
  Kerberos tickets in the file named by the KRBTKFILE environment variable,
  which the B<pagsh.krb> command defines automatically as F</tmp/tktpI<X>>
--- 61,67 ----
  B<aklog> instead of B<klog>.
  
  Sites using Kerberos v4 authentication (perhaps with the AFS
! Authentication Server) should use the Kerberos version of this command,
  B<klog.krb>, on all client machines. It automatically places the issuer's
  Kerberos tickets in the file named by the KRBTKFILE environment variable,
  which the B<pagsh.krb> command defines automatically as F</tmp/tktpI<X>>
Index: openafs/doc/man-pages/pod1/pagsh.pod
diff -c openafs/doc/man-pages/pod1/pagsh.pod:1.4 openafs/doc/man-pages/pod1/pagsh.pod:1.4.2.1
*** openafs/doc/man-pages/pod1/pagsh.pod:1.4	Wed Mar  1 00:02:30 2006
--- openafs/doc/man-pages/pod1/pagsh.pod	Mon May 18 19:38:15 2009
***************
*** 1,6 ****
  =head1 NAME
  
! pagsh - Creates a new PAG
  
  =head1 SYNOPSIS
  
--- 1,6 ----
  =head1 NAME
  
! pagsh, pagsh.krb - Creates a new PAG
  
  =head1 SYNOPSIS
  
***************
*** 9,14 ****
--- 9,16 ----
  
  B<pagsh>
  
+ B<pagsh.krb>
+ 
  =for html
  </div>
  
***************
*** 24,32 ****
  
  Any tokens acquired subsequently (presumably for other cells) become
  associated with the PAG, rather than with the user's UNIX UID.  This
! method for distinguishing users has two advantages.
  
! =over 4
  
  =item *
  
--- 26,34 ----
  
  Any tokens acquired subsequently (presumably for other cells) become
  associated with the PAG, rather than with the user's UNIX UID.  This
! method for distinguishing users has two advantages:
  
! =over 2
  
  =item *
  
***************
*** 49,54 ****
--- 51,63 ----
  
  =back
  
+ The (mostly obsolete) B<pagsh.krb> command is the same as B<pagsh> except
+ that it also sets the KRBTKFILE environment variable, which controls the
+ default Kerberos v4 ticket cache, to F</tmp/tktpI<X>> where I<X> is the
+ number of the user's PAG.  This is only useful for AFS cells still using
+ Kerberos v4 outside of AFS and has no effect for cells using Kerberos v5
+ and B<aklog> or B<klog.krb5>.
+ 
  =head1 CAUTIONS
  
  Each PAG created uses two of the memory slots that the kernel uses to
***************
*** 98,103 ****
--- 107,113 ----
  
  =head1 SEE ALSO
  
+ L<aklog(1)>,
  L<fs_exportafs(1)>,
  L<klog(1)>,
  L<tokens(1)>
Index: openafs/doc/man-pages/pod1/pts.pod
diff -c openafs/doc/man-pages/pod1/pts.pod:1.2.6.2 openafs/doc/man-pages/pod1/pts.pod:1.2.6.3
*** openafs/doc/man-pages/pod1/pts.pod:1.2.6.2	Mon Feb  4 12:53:44 2008
--- openafs/doc/man-pages/pod1/pts.pod	Tue May 12 15:40:34 2009
***************
*** 129,134 ****
--- 129,140 ----
  and refuses to perform such an action even if the B<-noauth> flag is
  provided.
  
+ =item B<-encrypt>
+ 
+ Establishes an authenticated, encrypted connection to the Protection Server.
+ It is useful when it is desired to obscure network traffic related to the
+ transactions being done.
+ 
  =item B<-localauth>
  
  Constructs a server ticket using the server encryption key with the
Index: openafs/doc/man-pages/pod1/tokens.pod
diff -c openafs/doc/man-pages/pod1/tokens.pod:1.4 openafs/doc/man-pages/pod1/tokens.pod:1.4.2.1
*** openafs/doc/man-pages/pod1/tokens.pod:1.4	Wed Mar  1 00:02:30 2006
--- openafs/doc/man-pages/pod1/tokens.pod	Mon May 18 19:38:15 2009
***************
*** 1,6 ****
  =head1 NAME
  
! tokens - Displays the issuer's tokens
  
  =head1 SYNOPSIS
  
--- 1,6 ----
  =head1 NAME
  
! tokens, tokens.krb - Displays the issuer's tokens
  
  =head1 SYNOPSIS
  
***************
*** 11,26 ****
  
  B<tokens> [B<-h>]
  
  =for html
  </div>
  
  =head1 DESCRIPTION
  
! The tokens command displays all tokens (tickets) cached on the local
  machine for the issuer. AFS server processes require that their clients
  present a token as evidence that they have authenticated in the server's
  local cell.
  
  =head1 OPTIONS
  
  =over 4
--- 11,33 ----
  
  B<tokens> [B<-h>]
  
+ B<tokens.krb> [B<-help>]
+ 
+ B<tokens.krb> [B<-h>]
+ 
  =for html
  </div>
  
  =head1 DESCRIPTION
  
! The B<tokens> command displays all tokens (tickets) cached on the local
  machine for the issuer. AFS server processes require that their clients
  present a token as evidence that they have authenticated in the server's
  local cell.
  
+ The (mostly obsolete) B<tokens.krb> command is the same as B<tokens>
+ except that it also displays the user's Kerberos v4 ticket cache.
+ 
  =head1 OPTIONS
  
  =over 4
***************
*** 37,43 ****
  The output lists one token for each cell in which the user is
  authenticated. The output indicates the
  
! =over 4
  
  =item *
  
--- 44,50 ----
  The output lists one token for each cell in which the user is
  authenticated. The output indicates the
  
! =over 2
  
  =item *
  
Index: openafs/doc/man-pages/pod1/vos_dump.pod
diff -c openafs/doc/man-pages/pod1/vos_dump.pod:1.4.2.1 openafs/doc/man-pages/pod1/vos_dump.pod:1.4.2.3
*** openafs/doc/man-pages/pod1/vos_dump.pod:1.4.2.1	Sun Nov 11 18:51:05 2007
--- openafs/doc/man-pages/pod1/vos_dump.pod	Tue May 26 21:24:49 2009
***************
*** 9,20 ****
  
  B<vos dump> S<<< B<-id> <I<volume name or ID>> >>> S<<< [B<-time> <I<dump from time>>] >>>
      S<<< [B<-file> <I<dump file>>] >>> S<<< [B<-server> <I<server>>] >>>
!     S<<< [B<-partition> <I<partition>>] >>> S<<< [B<-cell> <I<cell name>>] >>>
!     [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-help>]
  
  B<vos du> S<<< B<-i> <I<volume name or ID>> >>> S<<< [B<-t> <I<dump from time>>] >>>
      S<<< [B<-f> <I<dump file>>] >>> S<<< [B<-s> <I<server>>] >>> S<<< [B<-p> <I<partition>>] >>>
!     S<<< [B<-c> <I<cell name>>] >>> [B<-n>] [B<-l>] [B<-v>] [B<-h>]
  
  =for html
  </div>
--- 9,22 ----
  
  B<vos dump> S<<< B<-id> <I<volume name or ID>> >>> S<<< [B<-time> <I<dump from time>>] >>>
      S<<< [B<-file> <I<dump file>>] >>> S<<< [B<-server> <I<server>>] >>>
!     S<<< [B<-partition> <I<partition>>] >>> [B<-clone>] [B<-omitdirs>]
!     S<<< [B<-cell> <I<cell name>>] >>> [B<-noauth>] [B<-localauth>]
!     [B<-verbose>] [B<-help>]
  
  B<vos du> S<<< B<-i> <I<volume name or ID>> >>> S<<< [B<-t> <I<dump from time>>] >>>
      S<<< [B<-f> <I<dump file>>] >>> S<<< [B<-s> <I<server>>] >>> S<<< [B<-p> <I<partition>>] >>>
!     [B<-cl>] [B<-o>] S<<< [B<-ce> <I<cell name>>] >>> [B<-n>] [B<-l>]
!     [B<-v>] [B<-h>]
  
  =for html
  </div>
***************
*** 130,135 ****
--- 132,154 ----
  Specifies the partition on which the volume resides. Provide the
  B<-server> argument along with this one.
  
+ =item B<-clone>
+ 
+ Normally, B<vos dump> locks the volume and dumps it, which blocks writes
+ to the volume while the dump is in progress.  If this flag is given, B<vos
+ dump> will instead clone the volume first (similar to what B<vos move>
+ would do) and then dumps the clone.  This can significantly decrease the
+ amount of time the volume is kept locked for dumps of large volumes.
+ 
+ =item B<-omitdirs>
+ 
+ By default, B<vos dump> includes all directory objects in an incremental
+ dump whether they've been changed or not.  If this option is given,
+ unchanged directories will be omitted.  This will reduce the size of the
+ dump and not cause problems if the incremental is restored, as expected,
+ on top of a volume containing the correct directory structure (such as one
+ created by restoring previous full and incremental dumps).
+ 
  =item B<-cell> <I<cell name>
  
  Names the cell in which to run the command. Do not combine this argument
***************
*** 187,192 ****
--- 206,212 ----
  
  =head1 SEE ALSO
  
+ L<restorevol(8)>,
  L<vos(1)>,
  L<vos_examine(1)>,
  L<vos_listvldb(1)>,
Index: openafs/doc/man-pages/pod1/vos_restore.pod
diff -c openafs/doc/man-pages/pod1/vos_restore.pod:1.4.2.1 openafs/doc/man-pages/pod1/vos_restore.pod:1.4.2.2
*** openafs/doc/man-pages/pod1/vos_restore.pod:1.4.2.1	Sun Nov 11 18:51:05 2007
--- openafs/doc/man-pages/pod1/vos_restore.pod	Mon May 18 19:34:07 2009
***************
*** 221,226 ****
--- 221,227 ----
  
  =head1 SEE ALSO
  
+ L<restorevol(8)>,
  L<vos(1)>,
  L<vos_dump(1)>,
  L<vos_examine(1)>,
Index: openafs/doc/man-pages/pod5/CellServDB.pod
diff -c openafs/doc/man-pages/pod5/CellServDB.pod:1.1.6.1 openafs/doc/man-pages/pod5/CellServDB.pod:1.1.6.2
*** openafs/doc/man-pages/pod5/CellServDB.pod:1.1.6.1	Sun Jul 13 19:53:51 2008
--- openafs/doc/man-pages/pod5/CellServDB.pod	Mon May 18 19:35:55 2009
***************
*** 15,24 ****
  Along with AFSDB entries in DNS, the client version of the CellServDB file
  lists the database server machines in the local cell and any foreign cell
  that is to be accessible from the local client machine. Database server
! machines run the Authentication Server (optional), Backup Server,
! Protection Server, and Volume Location (VL) Server (the B<kaserver>,
! B<buserver>, B<ptserver>, and B<vlserver>) processes, which maintain the
! cell's administrative AFS databases.
  
  The Cache Manager and other processes running on a client machine use the
  list of a cell's database server machines when performing several common
--- 15,24 ----
  Along with AFSDB entries in DNS, the client version of the CellServDB file
  lists the database server machines in the local cell and any foreign cell
  that is to be accessible from the local client machine. Database server
! machines run the Authentication Server (optional), Backup Server
! (optional), Protection Server, and Volume Location (VL) Server (the
! B<kaserver>, B<buserver>, B<ptserver>, and B<vlserver>) processes, which
! maintain the cell's administrative AFS databases.
  
  The Cache Manager and other processes running on a client machine use the
  list of a cell's database server machines when performing several common
***************
*** 33,48 ****
  
  =item *
  
! Authenticating users. Client-side authentication programs (such as an
! AFS-modified login utility or the B<klog> command interpreter) contact the
! Authentication Server to obtain a server ticket, which the AFS server
! processes accept as proof that the user is authenticated.
  
  =item *
  
! Creating protection groups. The B<pts> command interpreter contacts the
! Protection Server when users create protection groups or request
! information from the Protection Database.
  
  =back
  
--- 33,57 ----
  
  =item *
  
! Creating, viewing, and manipulating protection groups. The B<pts> command
! interpreter contacts the Protection Server when users create protection
! groups or request information from the Protection Database.
! 
! =item *
! 
! Populating the contents of the fake F<root.afs> volume mounted at F</afs>
! (or the alternative mount point specified in F<cacheinfo>) when B<afsd> is
! run in C<-dynroot> mode.  The default contents of this directory will
! match the cells listed in the client F<CellServDB> file.
  
  =item *
  
! Authenticating users. Client-side authentication programs (such as an
! AFS-modified login utility or the B<klog> command interpreter) contact the
! Authentication Server to obtain a server ticket, which the AFS server
! processes accept as proof that the user is authenticated. This only
! applies to AFS cells using the deprecated Authentication Server instead of
! Kerberos v5 and B<aklog>.
  
  =back
  
***************
*** 54,59 ****
--- 63,76 ----
  list of database server machines without rebooting, use the B<fs newcell>
  command.
  
+ If the client attempts to access an AFS cell not listed in F<CellServDB>
+ and B<afsd> was started with the B<-afsdb> option, the Cache Manager will
+ attempt an AFSDB DNS record lookup and dynamically add the database server
+ locations for that cell based on the result of the DNS query.  If the
+ B<-afsdb> option was not used, all AFS cells that will be accessed by a
+ client machine must either be listed in F<CellServDB> or added with the
+ B<fs newcell> command.
+ 
  The F<CellServDB> file is in ASCII format and must reside in the
  F</usr/vice/etc> directory on each AFS client machine. Use a text editor
  to create and maintain it.
***************
*** 69,83 ****
  
  The server version of the F<CellServDB> file lists the local cell's
  database server machines. These machines run the Authentication Server
! (optional), Backup Server, Protection Server, and Volume Location (VL)
! Server (the B<kaserver>, B<buserver>, B<ptserver>, and B<vlserver>)
! processes, which maintain the cell's administrative AFS databases. The
! initial version of the file is created with the B<bos setcellname> command
! during the installation of the cell's server machine, which is
! automatically recorded as the cell's first database server machine. When
! adding or removing database server machines, be sure to update this file
! appropriately. It must reside in the F</usr/afs/etc> directory on each AFS
! server machine.
  
  The database server processes consult the F<CellServDB> file to learn
  about their peers, with which they must maintain constant connections in
--- 86,100 ----
  
  The server version of the F<CellServDB> file lists the local cell's
  database server machines. These machines run the Authentication Server
! (optional), Backup Server (optional), Protection Server, and Volume
! Location (VL) Server (the B<kaserver>, B<buserver>, B<ptserver>, and
! B<vlserver>) processes, which maintain the cell's administrative AFS
! databases. The initial version of the file is created with the B<bos
! setcellname> command during the installation of the cell's server machine,
! which is automatically recorded as the cell's first database server
! machine. When adding or removing database server machines, be sure to
! update this file appropriately. It must reside in the F</usr/afs/etc>
! directory on each AFS server machine.
  
  The database server processes consult the F<CellServDB> file to learn
  about their peers, with which they must maintain constant connections in
Index: openafs/doc/man-pages/pod5/NetInfo.pod
diff -c openafs/doc/man-pages/pod5/NetInfo.pod:1.2.6.1 openafs/doc/man-pages/pod5/NetInfo.pod:1.2.6.2
*** openafs/doc/man-pages/pod5/NetInfo.pod:1.2.6.1	Tue Jun 19 05:08:41 2007
--- openafs/doc/man-pages/pod5/NetInfo.pod	Mon Apr 27 14:37:34 2009
***************
*** 80,88 ****
--- 80,103 ----
  appears on each line, in dotted decimal format. The order of the addresses
  is not significant.
  
+ Optionally, the File Server can be forced to use an IP address that does
+ not belong to one of the server interfaces. To do this, add a line to the
+ F<NetInfo> file with the IP address prefixed with "f" and a space. This is
+ useful when the File Server is on the interal side of a NAT firewall.
+ 
  To display the File Server interface addresses registered in the VLDB, use
  the B<vos listaddrs> command.
  
+ =head1 EXAMPLES
+ 
+ If the File Server is on the internal side of a NAT firewall, where it
+ serves internal clients using the IP address 192.168.1.123 and external
+ clients using the IP address 10.1.1.321, then the F<NetInfo> file should
+ contain the following:
+ 
+    192.168.1.123
+    f 10.1.1.321
+ 
  =head1 SEE ALSO
  
  L<NetRestrict(5)>,
Index: openafs/doc/man-pages/pod5/krb.conf.pod
diff -c openafs/doc/man-pages/pod5/krb.conf.pod:1.1.2.2 openafs/doc/man-pages/pod5/krb.conf.pod:1.1.2.3
*** openafs/doc/man-pages/pod5/krb.conf.pod:1.1.2.2	Sun Jul 13 19:53:51 2008
--- openafs/doc/man-pages/pod5/krb.conf.pod	Tue May 19 14:40:20 2009
***************
*** 4,10 ****
  
  =head1 DESCRIPTION
  
! /usr/vice/etc/krb.conf is an optional file that resides on an OpenAFS
  server and is used to specify which Kerberos5 realms are trusted to
  authenticate to the local AFS cell. The format of the file is one realm
  per line. If the Kerberos5 realm matches the AFS cell name
--- 4,10 ----
  
  =head1 DESCRIPTION
  
! /usr/afs/etc/krb.conf is an optional file that resides on an OpenAFS
  server and is used to specify which Kerberos5 realms are trusted to
  authenticate to the local AFS cell. The format of the file is one realm
  per line. If the Kerberos5 realm matches the AFS cell name
Index: openafs/doc/man-pages/pod8/afsd.pod
diff -c openafs/doc/man-pages/pod8/afsd.pod:1.6.2.7 openafs/doc/man-pages/pod8/afsd.pod:1.6.2.8
*** openafs/doc/man-pages/pod8/afsd.pod:1.6.2.7	Thu Mar 19 22:31:41 2009
--- openafs/doc/man-pages/pod8/afsd.pod	Sat May 30 21:22:39 2009
***************
*** 25,31 ****
       [B<-nosettime>]
       S<<< [B<-prealloc> <I<number of 'small' preallocated blocks>>] >>>
       [B<-rmtsys>] S<<< [B<-rootvol> <I<name of AFS root volume>>] >>>
!      [B<-rxbind>] S<<< [B<-rxpck> value for rx_extraPackets ] >>>
       [B<-settime>] [B<-shutdown>]
       S<<< [B<-splitcache> <I<RW/RO ratio>>] >>>
       S<<< [B<-stat> <I<number of stat entries>>] >>> [B<-verbose>]
--- 25,32 ----
       [B<-nosettime>]
       S<<< [B<-prealloc> <I<number of 'small' preallocated blocks>>] >>>
       [B<-rmtsys>] S<<< [B<-rootvol> <I<name of AFS root volume>>] >>>
!      [B<-rxbind>] S<<< [B<-rxmaxmtu> value for maximum MTU ] >>> 
!      S<<< [B<-rxpck> value for rx_extraPackets ] >>>
       [B<-settime>] [B<-shutdown>]
       S<<< [B<-splitcache> <I<RW/RO ratio>>] >>>
       S<<< [B<-stat> <I<number of stat entries>>] >>> [B<-verbose>]
***************
*** 628,633 ****
--- 629,641 ----
  
  Bind the Rx socket (one interface only).
  
+ =item B<-rxmaxmtu> <I<value for maximum MTU>>
+ 
+ Set a limit for the largest maximum transfer unit (network packet size) that
+ the AFS client on this machine will be willing to transmit. This switch can
+ be used where an artificial limit on the network precludes packets as large
+ as the discoverable MTU from being transmitted successfully.
+ 
  =item B<-rxpck> <I<value for rx_extraPackets>>
  
  Set rx_extraPackets to this value. This sets the number of extra Rx
Index: openafs/doc/man-pages/pod8/bosserver.pod
diff -c openafs/doc/man-pages/pod8/bosserver.pod:1.3.2.1 openafs/doc/man-pages/pod8/bosserver.pod:1.3.2.2
*** openafs/doc/man-pages/pod8/bosserver.pod:1.3.2.1	Tue Jan 22 23:18:10 2008
--- openafs/doc/man-pages/pod8/bosserver.pod	Tue May  5 08:30:34 2009
***************
*** 8,14 ****
  <div class="synopsis">
  
  B<bosserver> [B<-noauth>] [B<-log>] [B<-enable_peer_stats>]
!     [B<-enable_process_stats>] [B<-allow-dotted-principal>] [B<-help>]
  
  =for html
  </div>
--- 8,14 ----
  <div class="synopsis">
  
  B<bosserver> [B<-noauth>] [B<-log>] [B<-enable_peer_stats>]
!     [B<-enable_process_stats>] [B<-allow-dotted-principals>] [B<-help>]
  
  =for html
  </div>
***************
*** 108,114 ****
  other machines. To display or otherwise access the records, use the Rx
  Monitoring API.
  
! =item B<-allow-dotted-principal>
  
  By default, the RXKAD security layer will disallow access by Kerberos
  principals with a dot in the first component of their name. This is to avoid
--- 108,114 ----
  other machines. To display or otherwise access the records, use the Rx
  Monitoring API.
  
! =item B<-allow-dotted-principals>
  
  By default, the RXKAD security layer will disallow access by Kerberos
  principals with a dot in the first component of their name. This is to avoid
Index: openafs/doc/man-pages/pod8/fileserver.pod
diff -c openafs/doc/man-pages/pod8/fileserver.pod:1.5.2.14 openafs/doc/man-pages/pod8/fileserver.pod:1.5.2.16
*** openafs/doc/man-pages/pod8/fileserver.pod:1.5.2.14	Tue Nov 11 21:31:12 2008
--- openafs/doc/man-pages/pod8/fileserver.pod	Fri May 15 09:30:18 2009
***************
*** 139,145 ****
  
    Parameter (Argument)               Small (-S)     Medium   Large (-L)
    ---------------------------------------------------------------------
!   Number of LWPs (-p)                        6           9           12
    Number of cached dir blocks (-b)          70          90          120
    Number of cached large vnodes (-l)       200         400          600
    Number of cached small vnodes (-s)       200         400          600
--- 139,145 ----
  
    Parameter (Argument)               Small (-S)     Medium   Large (-L)
    ---------------------------------------------------------------------
!   Number of LWPs (-p)                        6           9          128
    Number of cached dir blocks (-b)          70          90          120
    Number of cached large vnodes (-l)       200         400          600
    Number of cached small vnodes (-s)       200         400          600
***************
*** 402,408 ****
  
  Force the fileserver to only bind to one IP address.
  
! =item B<-allow-dotted-principal>
  
  By default, the RXKAD security layer will disallow access by Kerberos
  principals with a dot in the first component of their name. This is to avoid
--- 402,408 ----
  
  Force the fileserver to only bind to one IP address.
  
! =item B<-allow-dotted-principals>
  
  By default, the RXKAD security layer will disallow access by Kerberos
  principals with a dot in the first component of their name. This is to avoid
Index: openafs/doc/man-pages/pod8/ptserver.pod
diff -c openafs/doc/man-pages/pod8/ptserver.pod:1.3.2.4 openafs/doc/man-pages/pod8/ptserver.pod:1.3.2.5
*** openafs/doc/man-pages/pod8/ptserver.pod:1.3.2.4	Sun Aug 24 21:15:03 2008
--- openafs/doc/man-pages/pod8/ptserver.pod	Tue May  5 08:30:34 2009
***************
*** 11,17 ****
      [B<-rebuildDB>] S<<< [B<-groupdepth> <I<# of nested groups>>] >>>
      S<<< [B<-default_access> <I<user access mask>> <I<group access mask>>] >>>
      [B<-restricted>] [B<-enable_peer_stats>]
!     [B<-enable_process_stats>] [B<-allow-dotted-principal>]
      [B<-rxbind>] S<<< [B<-auditlog> <I<file path>>] >>>
      S<<< [B<-syslog>[=<I<FACILITY>>]] >>> S<<< [B<-rxmaxmtu> <I<bytes>>] >>>
      [B<-help>]
--- 11,17 ----
      [B<-rebuildDB>] S<<< [B<-groupdepth> <I<# of nested groups>>] >>>
      S<<< [B<-default_access> <I<user access mask>> <I<group access mask>>] >>>
      [B<-restricted>] [B<-enable_peer_stats>]
!     [B<-enable_process_stats>] [B<-allow-dotted-principals>]
      [B<-rxbind>] S<<< [B<-auditlog> <I<file path>>] >>>
      S<<< [B<-syslog>[=<I<FACILITY>>]] >>> S<<< [B<-rxmaxmtu> <I<bytes>>] >>>
      [B<-help>]
***************
*** 129,135 ****
  other machines. To display or otherwise access the records, use the Rx
  Monitoring API.
  
! =item B<-allow-dotted-principal>
  
  By default, the RXKAD security layer will disallow access by Kerberos
  principals with a dot in the first component of their name. This is to
--- 129,135 ----
  other machines. To display or otherwise access the records, use the Rx
  Monitoring API.
  
! =item B<-allow-dotted-principals>
  
  By default, the RXKAD security layer will disallow access by Kerberos
  principals with a dot in the first component of their name. This is to
Index: openafs/doc/man-pages/pod8/restorevol.pod
diff -c /dev/null openafs/doc/man-pages/pod8/restorevol.pod:1.1.2.2
*** /dev/null	Sat May 30 21:40:41 2009
--- openafs/doc/man-pages/pod8/restorevol.pod	Mon May 18 19:34:08 2009
***************
*** 0 ****
--- 1,153 ----
+ =head1 NAME
+ 
+ restorevol - Restore a volume from vos dump to the local file system
+ 
+ =head1 SYNOPSIS
+ 
+ =for html
+ <div class="synopsis">
+ 
+ B<restorevol> S<<< [B<-file> <I<dump file>>] >>> S<<< [B<-dir> <I<restore dir>> ] >>>
+     S<<< [B<-extension> <I<name extension>>] >>>
+     S<<< [B<-mountpoint> <I<mount point root>>] >>>
+     S<<< [B<-umask> <I<mode mask>>] >>> [B<-verbose>] [B<-help>]
+ 
+ =for html
+ </div>
+ 
+ =head1 DESCRIPTION
+ 
+ B<restorevol> takes an AFS volume in the format produced by B<vos dump>
+ and restores it to the local file system.  Normally, the contents of a
+ volume are maintained by the AFS File Server in an opaque format and
+ copying a volume's raw data does not make it easily accessible.  This
+ utility will produce a directory tree that is equivalent to that seen via
+ an AFS client, but without preserving the AFS-specific Access Control
+ Lists (ACLs).  It's primary use is to recover data from a volume dump or
+ backup and make it available via a filesystem other than AFS.
+ 
+ The dump output will read from standard input, or from a file if B<-file>
+ is specified.
+ 
+ The restore process is as follows:
+ 
+ =over 4
+ 
+ =item 1. 
+ 
+ The dump file will be restored within the current directory or that
+ specified with B<-dir>.
+ 
+ =item 2. 
+ 
+ Within this directory, a subdir is created.  It's name is the RW volume
+ name that was dumped.  An extension can be appended to this directory name
+ with B<-extension>.
+ 
+ =item 3. 
+ 
+ All mountpoints will appear as symbolic links to the volume name.  The
+ path name to the volume will be either that in B<-mountpoint>, or B<-dir>.
+ Symbolic links remain untouched.
+ 
+ =item 4. 
+ 
+ You can change your umask during the restore with B<-umask>.  Otherwise,
+ B<restorevol> uses your current umask.  Mode bits for directories are 0777
+ (then AND'ed with the umask).  Mode bits for files are the owner mode bits
+ duplicated accross group and user (then AND'ed with the umask).
+ 
+ =item 5. 
+ 
+ For restores of full dumps, if a directory says it has a file and the file
+ is not found, then a symbolic link F<< AFSFile-<#> >> will appear in that
+ restored tree.  Restores of incremental dumps remove all these files at
+ the end (expensive because it is a tree search).
+ 
+ =item 6. 
+ 
+ If a file or directory was found in the dump but found not to be connected
+ to the hierarchical tree, then the file or directory will be connected at
+ the root of the tree as F<< __ORPHANEDIR__.<#> >> or F<<
+ __ORPHANFILE__.<#> >>.
+ 
+ =item 7. 
+ 
+ ACLs are not restored.
+ 
+ =back
+ 
+ =head1 CAUTIONS
+ 
+ Normally, use L<vos_restore(1)> instead of this command.  B<restorevol> is
+ a tool of last resort to try to extract data from the data structures
+ stored in a volume dumpfile and is not as regularly tested or used as the
+ normal L<vos_restore(1)> implementation.  Using B<restorevol> bypasses
+ checks done by the L<fileserver(8)> and L<salvager(8)>.
+ 
+ =head1 OPTIONS
+ 
+ =over 4
+ 
+ =item B<-file> <I<dump file>>
+ 
+ Specifies the output file for the dump.  If this option is not given, the
+ volume will be dumped to standard output.
+ 
+ =item B<-dir> <I<restore dir>>
+ 
+ Names the directory in which to create the restored filesystem.  The
+ current directory is used by default.  Note that any mountpoints inside
+ the volume will point to the same directory unless the B<-mountpoint>
+ option is also specified.
+ 
+ =item B<-extension> <I<name extension>>
+ 
+ By default, the name of the directory created matches the RW volume name
+ of the volume in the dump file.  If this option is used, the directory
+ name will be the RW volume name I<name extension> as the suffix.
+ 
+ =item B<-mountpoint> <I<mount point root>>
+ 
+ By default, mountpoints inside the volume being restored point to the
+ value given by I<-dir>.  This option allows mountpoints to be resolved
+ relative to another path.  A common use for this would be to specify a
+ path under F</afs> as the mount point root so that mountpoints inside the
+ restored volume would be resolved via AFS.
+ 
+ The I<mount point root> must exist, and the process running the command
+ have read access to that directory, or the command will fail.
+ 
+ =back
+ 
+ =head1 EXAMPLES
+ 
+ The following command restores the contents of the dumpfile in
+ F<sample.dump> to the directory F</tmp/sample.2009-05-17>, but having all
+ mountpoints inside the volume point to AFS (note that this requires
+ knowledge of where F<sample> is mounted in AFS):
+ 
+    % restorevol -file sample.dump -dir /tmp -extension .2009-05-17 \
+        -mountpoint /afs/example.org/sample
+    Restoring volume dump of 'sample' to directory '/tmp/sample.2009-05-17'
+ 
+ =head1 PRIVILEGE REQUIRED
+ 
+ The issuer must have read access to the dump file and write access to the
+ directory into which the dump is restored.  If the B<-mountpoint> flag is
+ given, the issuer must also have read access to that directory.
+ 
+ =head1 SEE ALSO
+ 
+ L<salvager(8)>,
+ L<voldump(8)>,
+ L<vos_dump(1)>,
+ L<vos_restore(1)>
+ 
+ =head1 COPYRIGHT
+ 
+ Copyright 2009 Steven Jenkins <steven@endpoint.com>
+ 
+ This documentation is covered by the BSD License as written in the
+ doc/LICENSE file. This man page was written by Steven Jenkins for
+ OpenAFS.
Index: openafs/doc/man-pages/pod8/rmtsysd.pod
diff -c /dev/null openafs/doc/man-pages/pod8/rmtsysd.pod:1.1.2.2
*** /dev/null	Sat May 30 21:40:41 2009
--- openafs/doc/man-pages/pod8/rmtsysd.pod	Mon May 18 19:34:56 2009
***************
*** 0 ****
--- 1,41 ----
+ =head1 NAME
+ 
+ rmtsysd - Daemon to execute AFS-specific system calls for remote hosts
+ 
+ =head1 SYNOPSIS
+ 
+ =for html
+ <div class="synopsis">
+ 
+ B<rmtsysd>
+ 
+ =for html
+ </div>
+ 
+ =head1 DESCRIPTION
+ 
+ B<rmtsysd> is a daemon to execute AFS-specific system calls on behalf of
+ NFS client machines.  This daemon only needs to be started if the machine
+ is an NFS/AFS translator server for users of NFS client machines who
+ execute AFS commands.
+ 
+ =head1 CAUTIONS
+ 
+ The protocol used by this daemon is not considered secure, so this should
+ not be used in an environment where security is important.
+ 
+ =head1 PRIVILEGE REQUIRED
+ 
+ The issuer must be logged in as the local superuser root.
+ 
+ =head1 SEE ALSO
+ 
+ L<afsd(8)>
+ 
+ =head1 COPYRIGHT
+ 
+ Copyright 2009 Steven Jenkins <steven@endpoint.com>
+ 
+ This documentation is covered by the BSD License as written in the
+ doc/LICENSE file. This man page was written by Steven Jenkins for
+ OpenAFS.
Index: openafs/doc/man-pages/pod8/vlserver.pod
diff -c openafs/doc/man-pages/pod8/vlserver.pod:1.3.2.3 openafs/doc/man-pages/pod8/vlserver.pod:1.3.2.4
*** openafs/doc/man-pages/pod8/vlserver.pod:1.3.2.3	Sun Aug 24 21:15:03 2008
--- openafs/doc/man-pages/pod8/vlserver.pod	Tue May  5 08:30:34 2009
***************
*** 8,14 ****
  <div class="synopsis">
  
  B<vlserver> S<<< [B<-p> <I<number of threads>>] >>> [B<-nojumbo>] [B<-jumbo>] [B<-rxbind>] S<<< [B<-d> <I<debug level>>] >>>
!     [B<-allow-dotted-principal>] [B<-enable_peer_stats>] [B<-enable_process_stats>] 
      [B<-help>]
  
  =for html
--- 8,14 ----
  <div class="synopsis">
  
  B<vlserver> S<<< [B<-p> <I<number of threads>>] >>> [B<-nojumbo>] [B<-jumbo>] [B<-rxbind>] S<<< [B<-d> <I<debug level>>] >>>
!     [B<-allow-dotted-principals>] [B<-enable_peer_stats>] [B<-enable_process_stats>] 
      [B<-help>]
  
  =for html
***************
*** 95,101 ****
  other machines. To display or otherwise access the records, use the Rx
  Monitoring API.
  
! =item B<-allow-dotted-principal>
  
  By default, the RXKAD security layer will disallow access by Kerberos
  principals with a dot in the first component of their name. This is to avoid
--- 95,101 ----
  other machines. To display or otherwise access the records, use the Rx
  Monitoring API.
  
! =item B<-allow-dotted-principals>
  
  By default, the RXKAD security layer will disallow access by Kerberos
  principals with a dot in the first component of their name. This is to avoid
Index: openafs/doc/man-pages/pod8/voldump.pod
diff -c openafs/doc/man-pages/pod8/voldump.pod:1.2 openafs/doc/man-pages/pod8/voldump.pod:1.2.2.1
*** openafs/doc/man-pages/pod8/voldump.pod:1.2	Wed Mar  1 00:02:32 2006
--- openafs/doc/man-pages/pod8/voldump.pod	Mon May 18 19:34:08 2009
***************
*** 86,91 ****
--- 86,92 ----
  =head1 SEE ALSO
  
  L<bos_shutdown(8)>,
+ L<restorevol(8)>,
  L<volserver(8)>,
  L<vos_dump(1)>,
  L<vos_restore(1)>
Index: openafs/doc/man-pages/pod8/volserver.pod
diff -c openafs/doc/man-pages/pod8/volserver.pod:1.4.2.2 openafs/doc/man-pages/pod8/volserver.pod:1.4.2.3
*** openafs/doc/man-pages/pod8/volserver.pod:1.4.2.2	Sun Aug 24 21:15:03 2008
--- openafs/doc/man-pages/pod8/volserver.pod	Tue May  5 08:30:34 2009
***************
*** 12,18 ****
      S<<< [B<-d> <I<debug level>>] >>>
      [B<-nojumbo>] [B<-jumbo>] 
      [B<-enable_peer_stats>] [B<-enable_process_stats>] 
!     [B<-allow-dotted-principal>] [B<-help>]
  
  =for html
  </div>
--- 12,18 ----
      S<<< [B<-d> <I<debug level>>] >>>
      [B<-nojumbo>] [B<-jumbo>] 
      [B<-enable_peer_stats>] [B<-enable_process_stats>] 
!     [B<-allow-dotted-principals>] [B<-help>]
  
  =for html
  </div>
***************
*** 99,105 ****
  other machines. To display or otherwise access the records, use the Rx
  Monitoring API.
  
! =item B<-allow-dotted-principal>
  
  By default, the RXKAD security layer will disallow access by Kerberos
  principals with a dot in the first component of their name. This is to avoid
--- 99,105 ----
  other machines. To display or otherwise access the records, use the Rx
  Monitoring API.
  
! =item B<-allow-dotted-principals>
  
  By default, the RXKAD security layer will disallow access by Kerberos
  principals with a dot in the first component of their name. This is to avoid
Index: openafs/doc/man-pages/pod8/vsys.pod
diff -c /dev/null openafs/doc/man-pages/pod8/vsys.pod:1.1.2.2
*** /dev/null	Sat May 30 21:40:41 2009
--- openafs/doc/man-pages/pod8/vsys.pod	Mon May 18 19:35:33 2009
***************
*** 0 ****
--- 1,51 ----
+ =head1 NAME
+ 
+ vsys - Make AFS system calls from the command line
+ 
+ =head1 SYNOPSIS
+ 
+ =for html
+ <div class="synopsis">
+ 
+ B<vsys> <I<call number>> <I<parms>>+
+ 
+ =for html
+ </div>
+ 
+ =head1 DESCRIPTION
+ 
+ B<vsys> is a development tool to make AFS system calls from the command
+ line.  <I<call number>> is the AFS system call to be invoked.  <I<parms>>+
+ are the values to pass to the system call.  Knowledge of the AFS system
+ call layer is required to know valid call numbers and parameters.
+ 
+ =head1 CAUTIONS
+ 
+ B<vsys> is intended for debugging AFS at a low level and is therefore
+ intended for AFS developers.  System Administrators and AFS users should
+ use the higher-level interfaces provided by L<fs(1)>, L<aklog(1)>,
+ L<klog(1)>, and L<pagsh(1)> instead.
+ 
+ B<vsys> provides a way to pass arbitrary data into the AFS system call
+ mechanism.  Caution should be taken when using or providing this binary on
+ a system, as incorrect use as a privileged user could cause a system to
+ panic, hang, or perform an unsafe operation.
+ 
+ =head1 PRIVILEGE REQUIRED
+ 
+ The issuer must be logged in as the local superuser root.
+ 
+ =head1 SEE ALSO
+ 
+ L<afsd(8)>,
+ L<aklog(1)>,
+ L<fs(1)>,
+ L<klog(1)>,
+ L<pagsh(1)>
+ 
+ =head1 COPYRIGHT
+ 
+ Copyright 2009 Steven Jenkins <steven@endpoint.com>
+ 
+ This documentation is covered by the BSD License as written in the
+ doc/LICENSE file. This man page was written by Steven Jenkins for OpenAFS.
Index: openafs/doc/txt/winnotes/afs-changes-since-1.2.txt
diff -c openafs/doc/txt/winnotes/afs-changes-since-1.2.txt:1.72.2.67 openafs/doc/txt/winnotes/afs-changes-since-1.2.txt:1.72.2.68
*** openafs/doc/txt/winnotes/afs-changes-since-1.2.txt:1.72.2.67	Mon Apr  6 13:15:12 2009
--- openafs/doc/txt/winnotes/afs-changes-since-1.2.txt	Mon May 25 23:50:03 2009
***************
*** 1,3 ****
--- 1,86 ----
+ Since 1.5.59
+  * A fix to the pioctl library to support drive substitution 
+    to UNC paths.  (SUBST <d:> <\\afs\cell\path>).
+ 
+  * On April 9th Microsoft released a Hot Fix for Windows Server 2003 SP2 
+    that corrects a deadlock in the smb redirector and also adds new 
+    functionality that permits the AFS SMB server to be given a longer 
+    timeout than is normally the case.  New functionality has been added 
+    to configure these additional LanmanWorkstation\Parameter values.
+    (This functionality has been backported to XP SP3 and is scheduled
+    to be released on June 5th.)
+    
+  * The BackConnectionHostNames registry value configuration was broken 
+    when dynamic re-establishment of Netbios Name registrations was added.
+    Restore it.
+ 
+  * Hidden vos commands are revealed.
+ 
+  * If the "DisableLoopbackCheck" registry value is set, do not unset 
+    it during the same service session.
+ 
+  * Reorganize code that prevents multiple Store operations to the same 
+    File.
+ 
+  * Modify IsPathInAfs test in Explorer Shell Extension and fs.exe to 
+    permit broken symlinks to be treated as being in AFS.
+ 
+  * Fix vos commands that output 64-bit integer values.
+ 
+  * Cygwin Import Libraries are provided in the SDK for all OpenAFS DLLs.
+    Permits building cygwin applications against OpenAFS libraries. 
+ 
+  * OpenAFS Release Notes, Administrator Guide and User Guide now installed 
+    as Windows HTML Help (.CHM) files.  
+ 
+  * NSIS installer does a much better job of cleaning up files left 
+    over from previous installs.
+ 
+  * Fix RT#124787, a race condition between "fs flush <dir>", "fs flushvolume", 
+    or "fs flushall" and on-going directory operations that can result in 
+    afsd_service.exe crashing.
+ 
+  * Add support for DNS SRV records in place of AFSDB records.  
+    _afs3-vlserver._udp.<cellname>.  Priority field is used.  
+    Weight is currently ignored.
+ 
+  * Add a method of specifying Client CellServDB information within the 
+    registry that can be used to either override the CellServDB file or 
+    force the use of DNS lookups for a given cell.
+ 
+    The registry schema is as follows:
+ 
+      HKLM\SOFTWARE\OpenAFS\{Client,Server}\CellServDB\[cellname]\
+        "LinkedCell" REG_SZ "[cellname]"
+        "Description" REG_SZ "[comment]"
+        "ForceDNS" DWORD {0,1}
+ 
+      HKLM\SOFTWARE\OpenAFS\{Client,Server}\CellServDB\[cellname]\[servername]\
+        "HostName" REG_SZ "[hostname]"  Default: [servername]
+        "IPv4Address" REG_SZ "[address]"  Used only if gethostbyname() fails.
+        "IPv6Address" REG_SZ "[address]" <future>
+        "Comment" REG_SZ "[comment]"
+        "Rank" DWORD "0..65535"  Default: 0
+        "Clone" DWORD "{0,1}" <future: server only>
+        "vlserver" DWORD "7003" <future>
+        "ptserver" DWORD ... <future>
+ 
+    ForceDNS is implied non-zero if there are no [servername]
+    keys under the [cellname] key. Otherwise, ForceDNS is zero.
+    If [servername] keys are specified and none of them evaluate
+    to a valid server configuration, the return code is success.
+    This prevents failover to the CellServDB file or DNS.
+    
+    Only one of "HostName" or "IPv4Address" is required.  "HostName"
+    is optional if [servername] is the host name.
+ 
+  * Extend registry based CellServDB functionality to 
+    afsconf_GetCellInfo() interface used by aklog and many 
+    other command line utilities.
+ 
+  * libafsconf.dll moved from OpenAFS\Client\Program to OpenAFS\Common
+    as it is now used by both client and server components.
+ 
  Since 1.5.58
   * PriorityClass of afsd_service.exe process raised to 
     "High" to match the priority of the system services 
Index: openafs/doc/xml/banner.gif
Index: openafs/doc/xml/books.gif
Index: openafs/doc/xml/down.gif
Index: openafs/doc/xml/home.gif
Index: openafs/doc/xml/index.gif
Index: openafs/doc/xml/index.html
diff -c /dev/null openafs/doc/xml/index.html:1.1.2.2
*** /dev/null	Sat May 30 21:40:41 2009
--- openafs/doc/xml/index.html	Wed May 13 22:25:59 2009
***************
*** 0 ****
--- 1,55 ----
+ <html>
+ <head>
+ <meta http-equiv=Content-Type content="text/html; charset=iso-8859-1">
+ <title>OpenAFS Documentation</title>
+ </head>
+ 
+ <body bgcolor=white lang=EN-US link=blue vlink=purple>
+ 
+ <div class=Section1>
+ 
+ <p>
+ <a href="http://www.openafs.org/">
+ <img border=0 width=201 height=139 src="logo.jpg" align=left title="www.openafs.org"></a>
+ <a name="Top_Of_Page"></a></p>
+ 
+ <p>&nbsp;</p>
+ <p>&nbsp;</p>
+ 
+ <h1>Documentation</h1>
+ 
+ <p>&nbsp;</p>
+ <p>&nbsp;</p>
+ 
+ <p>Welcome to the OpenAFS Documentation set!</p>
+ 
+ <h3>Documentation:</h3>
+ 
+ <ul>
+ <li>Release Notes:
+   <ul>
+ <!--    <li><a href="ReleaseNotesUnix/index.html">Unix</a></li> -->
+     <li><a href="ReleaseNotesWindows/index.html">Microsoft Windows</a></li>
+   </ul>
+ </li>
+ <li>Quick Start Guides:
+   <ul>
+     <li><a href="QuickStartUnix/index.html">Unix</a></li>
+     <li><a href="http://www.dementia.org/twiki/bin/view/AFSLore/WindowsEndUserQuickStartGuide">Microsoft Windows</a></li>
+   </ul>
+ </li>
+ <li><a href="UserGuide/index.html">User Guide</a></li>
+ <li><a href="AdminGuide/index.html">Administrator Guide</a></li>
+ <li><a href="Reference/index">Reference Manual</a></li>
+ </ul>
+ <a name="Bot_Of_Page"></a>
+ 
+ </div>
+ 
+ </body>
+ 
+ </html>
+ 
+ 
+ 
+ 
Index: openafs/doc/xml/logo.jpg
Index: openafs/doc/xml/next.gif
Index: openafs/doc/xml/prev.gif
Index: openafs/doc/xml/up.gif
Index: openafs/doc/xml/AdminGuide/Makefile.in
diff -c /dev/null openafs/doc/xml/AdminGuide/Makefile.in:1.1.2.2
*** /dev/null	Sat May 30 21:40:41 2009
--- openafs/doc/xml/AdminGuide/Makefile.in	Wed May 27 15:44:51 2009
***************
*** 0 ****
--- 1,42 ----
+ # Makefile to build the AFS Admin Guide for Unix.
+ #
+ # This makefile assumes that various utilities are available on the system.
+ # On Debian lenny, installing the packages:
+ #
+ #     dblatex
+ #     docbook-xsl
+ #     libxml2-utils
+ #     xsltproc
+ #
+ # gave me all the utilities needed.
+ #
+ # HTML_XSL is possibly specific to Debian and may need to be modified on other
+ # systems.
+ 
+ all: pdf html
+ 
+ include @TOP_OBJDIR@/src/config/Makefile.config
+ VERSFILE=version
+ include @TOP_OBJDIR@/src/config/Makefile.version
+ 
+ BOOK     = auagd000.xml
+ SRCS     = $(BOOK) auagd005.xml auagd006.xml auagd007.xml auagd008.xml \
+ 	   auagd009.xml auagd010.xml auagd011.xml auagd012.xml auagd013.xml \
+ 	   auagd014.xml auagd015.xml auagd016.xml auagd017.xml auagd018.xml \
+ 	   auagd019.xml auagd020.xml auagd021.xml auagd022.xml auagd023.xml \
+ 	   auagd024.xml auagd025.xml
+ HTML_XSL = @HTML_XSL@
+ XSLTPROC = @XSLTPROC@
+ 
+ html: $(SRCS) $(VERSFILE).xml
+ 	$(XSLTPROC) --param navig.graphics 1 \
+ 	    --stringparam navig.graphics.path ../ $(HTML_XSL) $(BOOK)
+ 
+ pdf: $(SRCS)
+ 	dblatex $(BOOK)
+ 
+ check:
+ 	xmllint --noout --valid $(BOOK)
+ 
+ clean:
+ 	rm -f *.html *.pdf
Index: openafs/doc/xml/AdminGuide/NTMakefile
diff -c /dev/null openafs/doc/xml/AdminGuide/NTMakefile:1.1.2.4
*** /dev/null	Sat May 30 21:40:41 2009
--- openafs/doc/xml/AdminGuide/NTMakefile	Thu May 21 13:52:13 2009
***************
*** 0 ****
--- 1,85 ----
+ # Copyright 2009, Secure Endpoints Inc.
+ # All Rights Reserved.
+ #
+ # Redistribution and use in source and binary forms, with or without
+ # modification, are permitted provided that the following conditions are met:
+ #
+ # - Redistributions of source code must retain the above copyright notice,
+ #   this list of conditions and the following disclaimer.
+ # - Redistributions in binary form must reproduce the above copyright notice,
+ #   this list of conditions and the following disclaimer in the documentation
+ #   and/or other materials provided with the distribution.
+ # - Neither the name of Secure Endpoints Inc. nor the names of its contributors
+ #   may be used to endorse or promote products derived from this software without
+ #   specific prior written permission from Secure Endpoints Inc..
+ #
+ # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ # AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ # TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+ # PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
+ # OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ # EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ # PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ # PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ # LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ 
+ VERSFILE = version
+ !INCLUDE ..\..\..\src\config\NTMakefile.$(SYS_NAME)
+ !INCLUDE ..\..\..\src\config\NTMakefile.version
+ 
+ !IFNDEF CYGWIN
+ CYGWIN     = c:/cygwin
+ !ENDIF
+ !IFNDEF DOCBOOK_XSL
+ DOCBOOK_XSL = $(CYGWIN)/usr/share/docbook-xsl
+ !ENDIF
+ XSLTPROC   = xsltproc.exe
+ HTML_XSL = $(DOCBOOK_XSL)/html/chunk.xsl
+ HTML_PARMS = --param navig.graphics 1 --stringparam navig.graphics.path ../
+ CHM_XSL    = $(DOCBOOK_XSL)/htmlhelp/htmlhelp.xsl
+ 
+ XMLSRCS = \
+         auagd000.xml \
+         auagd005.xml \
+         auagd006.xml \
+         auagd007.xml \
+         auagd008.xml \
+         auagd009.xml \
+         auagd010.xml \
+         auagd011.xml \
+         auagd012.xml \
+         auagd013.xml \
+         auagd014.xml \
+         auagd015.xml \
+         auagd016.xml \
+         auagd017.xml \
+         auagd018.xml \
+         auagd019.xml \
+         auagd020.xml \
+         auagd021.xml \
+         auagd022.xml \
+         auagd023.xml \
+         auagd024.xml \
+         auagd025.xml \
+         $(VERSFILE).xml
+ 
+ index.html: $(XMLSRCS)
+         @echo Building OpenAFS Administrator Guide in HTML format
+         $(XSLTPROC) $(HTML_PARMS) $(HTML_XSL) auagd000.xml 
+ 
+ htmlhelp.chm: $(XMLSRCS)
+         @echo Building OpenAFS Administrator Guide in HTML Help format
+         $(XSLTPROC) $(CHM_XSL) auagd000.xml
+         -hhc.exe htmlhelp.hhp
+         $(DEL) *.html
+         $(DEL) *.hh?
+         $(DEL) *.chw
+ 
+ install: htmlhelp.chm index.html
+ 
+ clean::
+         $(DEL) *.html
+         $(DEL) htmlhelp.chm
+         $(DEL) $(VERSFILE).xml
Index: openafs/doc/xml/AdminGuide/auagd000.xml
diff -c /dev/null openafs/doc/xml/AdminGuide/auagd000.xml:1.1.8.5
*** /dev/null	Sat May 30 21:40:41 2009
--- openafs/doc/xml/AdminGuide/auagd000.xml	Thu May 21 13:52:13 2009
***************
*** 0 ****
--- 1,109 ----
+ <?xml version="1.0" encoding="UTF-8"?>
+ <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.3//EN"
+         "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+ <!ENTITY version SYSTEM "version.xml">
+ <!ENTITY preface SYSTEM "auagd005.xml">
+ <!ENTITY chapter1 SYSTEM "auagd006.xml">
+ <!ENTITY chapter2 SYSTEM "auagd007.xml">
+ <!ENTITY chapter3 SYSTEM "auagd008.xml">
+ <!ENTITY chapter4 SYSTEM "auagd009.xml">
+ <!ENTITY chapter5 SYSTEM "auagd010.xml">
+ <!ENTITY chapter6 SYSTEM "auagd011.xml">
+ <!ENTITY chapter7 SYSTEM "auagd012.xml">
+ <!ENTITY chapter8 SYSTEM "auagd013.xml">
+ <!ENTITY chapter9 SYSTEM "auagd014.xml">
+ <!ENTITY chapter10 SYSTEM "auagd015.xml">
+ <!ENTITY chapter11 SYSTEM "auagd016.xml">
+ <!ENTITY chapter12 SYSTEM "auagd017.xml">
+ <!ENTITY chapter13 SYSTEM "auagd018.xml">
+ <!ENTITY chapter14 SYSTEM "auagd019.xml">
+ <!ENTITY chapter15 SYSTEM "auagd020.xml">
+ <!ENTITY chapter16 SYSTEM "auagd021.xml">
+ <!ENTITY appendixA SYSTEM "auagd022.xml">
+ <!ENTITY appendixB SYSTEM "auagd023.xml">
+ <!ENTITY appendixC SYSTEM "auagd024.xml">
+ <!ENTITY appendixD SYSTEM "auagd025.xml">
+ ]>
+ <book>
+   <bookinfo>
+     <title>OpenAFS Administration Guide</title>
+ 
+     <copyright>
+       <year>2000</year>
+ 
+       <holder>IBM Corporation. All Rights Reserved</holder>
+     </copyright>
+ 
+     <revhistory>
+       &version;
+                                   
+       <revision>
+         <revnumber>3.6</revnumber>
+ 
+         <date>April 2000</date>
+ 
+         <revremark>First IBM Edition, Document Number GC09-4563-00</revremark>
+       </revision>
+     </revhistory>
+ 
+     <abstract>
+       <para>This edition applies to: <simplelist>
+           <member>OpenAFS for AIX, Version M.m</member>
+           <member>OpenAFS for Digital Unix, Version M.m</member>
+           <member>OpenAFS for HP-UX, Version M.m</member>
+           <member>OpenAFS for Linux, Version M.m</member>
+           <member>OpenAFS for SGI IRIX, Version M.m</member>
+           <member>OpenAFS for Solaris, Version M.m</member>
+         </simplelist></para>
+ 
+       <para>and to all subsequent releases and modifications until otherwise
+       indicated in new editions.This softcopy version is based on the printed
+       edition of this book. Some formatting amendments have been made to make
+       this information more suitable for softcopy.</para>
+     </abstract>
+   </bookinfo>
+ 
+   &preface;
+ 
+   <part>
+     <title>Concepts and Configuration Issues</title>
+ 
+     &chapter1;
+     &chapter2;
+   </part>
+ 
+   <part>
+     <title>Managing File Server Machines</title>
+ 
+     &chapter3;
+     &chapter4;
+     &chapter5;
+     &chapter6;
+     &chapter7; 
+     &chapter8;
+     &chapter9;
+   </part>
+ 
+   <part>
+     <title>Managing Client Machines</title>
+ 
+     &chapter10;
+     &chapter11;
+   </part>
+ 
+   <part>
+     <title>Managing Users and Groups</title>
+ 
+     &chapter12;
+     &chapter13;
+     &chapter14;
+     &chapter15;
+     &chapter16;
+   </part>
+ 
+   &appendixA;
+   &appendixB;
+   &appendixC;
+   &appendixD;
+   <index></index>
+ </book>
Index: openafs/doc/xml/AdminGuide/auagd005.xml
diff -c /dev/null openafs/doc/xml/AdminGuide/auagd005.xml:1.1.8.3
*** /dev/null	Sat May 30 21:40:41 2009
--- openafs/doc/xml/AdminGuide/auagd005.xml	Wed May 13 22:25:59 2009
***************
*** 0 ****
--- 1,207 ----
+ <?xml version="1.0" encoding="UTF-8"?>
+ <preface id="Header_3">
+   <title>About This Guide</title>
+ 
+   <para>This section describes the purpose, organization, and conventions of this document.</para>
+ 
+   <sect1 id="HDRWQ1">
+     <title>Audience and Purpose</title>
+ 
+     <para>This guide describes the concepts and procedures that an AFS(R) system administrator needs to know. It assumes familiarity
+     with UNIX(R) administration, but no previous knowledge of AFS.</para>
+ 
+     <para>This document describes AFS commands in the context of specific tasks. Thus, it does not describe all commands in detail.
+     Refer to the OpenAFS Administration Reference for detailed command descriptions.</para>
+   </sect1>
+ 
+   <sect1 id="HDRWQ2">
+     <title>Document Organization</title>
+ 
+     <para>This document groups AFS administrative tasks into the following conceptual sections: <itemizedlist>
+         <listitem>
+           <para>Concepts and Configuration Issues</para>
+         </listitem>
+ 
+         <listitem>
+           <para>Managing File Server Machines</para>
+         </listitem>
+ 
+         <listitem>
+           <para>Managing Client Machines</para>
+         </listitem>
+ 
+         <listitem>
+           <para>Managing Users and Groups</para>
+         </listitem>
+       </itemizedlist></para>
+ 
+     <para>The individual chapters in each section contain the following: <itemizedlist>
+         <listitem>
+           <para>A chapter overview</para>
+         </listitem>
+ 
+         <listitem>
+           <para>A quick reference list of the tasks and commands described in the chapter</para>
+         </listitem>
+ 
+         <listitem>
+           <para>An introduction to concepts that pertain to all of the tasks described in the chapter</para>
+         </listitem>
+ 
+         <listitem>
+           <para>A set of sections devoted to specific tasks. Each section begins with a discussion of concepts specific to that
+           task, followed by step-by-step instructions for performing the task. The instructions are as specific as has been judged
+           practical. If two related procedures differ from one another in important details, separate sets of instructions are
+           usually provided.</para>
+         </listitem>
+       </itemizedlist></para>
+   </sect1>
+ 
+   <sect1 id="HDRWQ3">
+     <title>How to Use This Document</title>
+ 
+     <para>When you need to perform a specific administrative task, follow these steps:
+ 
+     <orderedlist>
+       <listitem>
+         <para>Determine if the task concerns file server machines, client machines, or users and groups. Turn to the appropriate
+         section in this document and then to the appropriate chapter.</para>
+       </listitem>
+ 
+       <listitem>
+         <para>Read or review the general introductory material at the beginning of the chapter.</para>
+       </listitem>
+ 
+       <listitem>
+         <para>Read or review the introductory material concerning the specific task you wish to perform.</para>
+       </listitem>
+ 
+       <listitem>
+         <para>Follow the step-by-step instructions for the task.</para>
+       </listitem>
+ 
+       <listitem>
+         <para>If necessary, refer to the OpenAFS Administration Reference for more detailed information about the commands.</para>
+       </listitem>
+     </orderedlist>
+ </para>
+   </sect1>
+ 
+   <sect1 id="HDRWQ4">
+     <title>Related Documents</title>
+ 
+     <para>The following documents are also included in the AFS documentation set.
+ 
+     <variablelist>
+       <varlistentry>
+         <term>OpenAFS Administration Reference</term>
+ 
+         <listitem>
+           <para>This reference manual details the syntax and effect of each AFS command. It is intended for the experienced AFS
+           administrator, programmer, or user. The OpenAFS Administration Reference lists AFS files and commands in alphabetical
+           order. The reference page for each command specifies its syntax, including the acceptable aliases and abbreviations. It
+           then describes the command's function, arguments, and output if any. Examples and a list of related commands are provided,
+           as are warnings where appropriate.</para>
+ 
+           <para>This manual complements the OpenAFS Administration Guide: it does not include procedural information, but describes
+           commands in more detail than the OpenAFS Administration Guide.</para>
+         </listitem>
+       </varlistentry>
+ 
+       <varlistentry>
+         <term>OpenAFS Quick Beginnings</term>
+ 
+         <listitem>
+           <para>This guide provides instructions for installing AFS server and client machines. It is assumed that the installer is
+           an experienced UNIX(R) system administrator.</para>
+ 
+           <para>For predictable performance, machines must be installed and configured in accordance with the instructions in this
+           guide.</para>
+         </listitem>
+       </varlistentry>
+ 
+       <varlistentry>
+         <term>OpenAFS Release Notes</term>
+ 
+         <listitem>
+           <para>This document provides information specific to each release of AFS, such as a list of new features and commands, a
+           list of requirements and limitations, and instructions for upgrading server and client machines.</para>
+         </listitem>
+       </varlistentry>
+ 
+       <varlistentry>
+         <term>OpenAFS User Guide</term>
+ 
+         <listitem>
+           <para>This guide presents the basic concepts and procedures necessary for using AFS effectively. It assumes that the
+           reader has some experience with UNIX, but does not require familiarity with networking or AFS.</para>
+ 
+           <para>The guide explains how to perform basic functions, including authenticating, changing a password, protecting AFS
+           data, creating groups, and troubleshooting. It provides illustrative examples for each function and describes some of the
+           differences between the UNIX file system and AFS.</para>
+         </listitem>
+       </varlistentry>
+     </variablelist>
+ </para>
+   </sect1>
+ 
+   <sect1 id="HDRTYPO_CONV">
+     <title>Typographical Conventions</title>
+ 
+     <para>This document uses the following typographical conventions:
+ 
+     <itemizedlist>
+       <listitem>
+         <para>Command and option names appear in <emphasis role="bold">bold type</emphasis> in syntax definitions, examples, and
+         running text. Names of directories, files, machines, partitions, volumes, and users also appear in <emphasis
+         role="bold">bold type</emphasis>.</para>
+       </listitem>
+ 
+       <listitem>
+         <para>Variable information appears in <emphasis>italic type</emphasis>. This includes user-supplied information on command
+         lines and the parts of prompts that differ depending on who issues the command. New terms also appear in <emphasis>italic
+         type</emphasis>.</para>
+       </listitem>
+ 
+       <listitem>
+         <para>Examples of screen output and file contents appear in <computeroutput>monospace type</computeroutput>.</para>
+       </listitem>
+     </itemizedlist>
+ </para>
+ 
+     <para>In addition, the following symbols appear in command syntax definitions, both in the documentation and in AFS online help
+     statements. When issuing a command, do not type these symbols. <itemizedlist>
+         <listitem>
+           <para>Square brackets <emphasis role="bold">[ ]</emphasis> surround optional items.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>Angle brackets <emphasis role="bold">&lt; &gt;</emphasis> surround user-supplied values in AFS commands.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>A superscripted plus sign <emphasis role="bold">+</emphasis> follows an argument that accepts more than one
+           value.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>The percent sign <computeroutput>%</computeroutput> represents the regular command shell prompt. Some operating systems possibly use a different
+           character for this prompt.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>The number sign <computeroutput>#</computeroutput> represents the command shell prompt for the local superuser <emphasis role="bold">root</emphasis>.
+           Some operating systems possibly use a different character for this prompt.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>The pipe symbol <emphasis role="bold">|</emphasis> in a command syntax statement separates mutually exclusive values
+           for an argument.</para>
+         </listitem>
+       </itemizedlist></para>
+ 
+     <para>For additional information on AFS commands, including a description of command string components, acceptable abbreviations
+     and aliases, and how to get online help for commands, see <link linkend="HDRCOMMANDS">Appendix B, Using AFS
+     Commands</link>.</para>
+   </sect1>
+ </preface>
Index: openafs/doc/xml/AdminGuide/auagd006.xml
diff -c /dev/null openafs/doc/xml/AdminGuide/auagd006.xml:1.1.8.3
*** /dev/null	Sat May 30 21:40:41 2009
--- openafs/doc/xml/AdminGuide/auagd006.xml	Wed May 13 22:25:59 2009
***************
*** 0 ****
--- 1,1154 ----
+ <?xml version="1.0" encoding="UTF-8"?>
+ <chapter id="HDRWQ5">
+   <title>An Overview of OpenAFS Administration</title>
+ 
+   <para>This chapter provides a broad overview of the concepts and organization of AFS. It is strongly recommended that anyone
+   involved in administering an AFS cell read this chapter before beginning to issue commands.</para>
+ 
+   <sect1 id="HDRWQ6">
+     <title>A Broad Overview of AFS</title>
+ 
+     <para>This section introduces most of the key terms and concepts necessary for a basic understanding of AFS. For a more detailed
+     discussion, see <link linkend="HDRWQ7">More Detailed Discussions of Some Basic Concepts</link>.</para>
+ 
+     <sect2 renderas="sect3">
+       <title>AFS: A Distributed File System</title>
+ 
+       <para>AFS is a distributed file system that enables users to share and access all of the files stored in a network of
+       computers as easily as they access the files stored on their local machines. The file system is called distributed for this
+       exact reason: files can reside on many different machines (be distributed across them), but are available to users on every
+       machine.</para>
+     </sect2>
+ 
+     <sect2 renderas="sect3">
+       <title>Servers and Clients</title>
+ 
+       <para>In fact, AFS stores files on a subset of the machines in a network, called file server machines. File server machines
+       provide file storage and delivery service, along with other specialized services, to the other subset of machines in the
+       network, the client machines. These machines are called clients because they make use of the servers' services while doing
+       their own work. In a standard AFS configuration, clients provide computational power, access to the files in AFS and other
+       "general purpose" tools to the users seated at their consoles. There are generally many more client workstations than file
+       server machines.</para>
+ 
+       <para>AFS file server machines run a number of server processes, so called because each provides a distinct specialized
+       service: one handles file requests, another tracks file location, a third manages security, and so on. To avoid confusion, AFS
+       documentation always refers to server machines and server processes, not simply to servers. For a more detailed description of
+       the server processes, see <link linkend="HDRWQ17">AFS Server Processes and the Cache Manager</link>.</para>
+     </sect2>
+ 
+     <sect2 renderas="sect3">
+       <title>Cells</title>
+ 
+       <para>A cell is an administratively independent site running AFS. As a cell's system administrator, you make many decisions
+       about configuring and maintaining your cell in the way that best serves its users, without having to consult the
+       administrators in other cells. For example, you determine how many clients and servers to have, where to put files, and how to
+       allocate client machines to users.</para>
+     </sect2>
+ 
+     <sect2 renderas="sect3">
+       <title>Transparent Access and the Uniform Namespace</title>
+ 
+       <para>Although your AFS cell is administratively independent, you probably want to organize the local collection of files
+       (your filespace or tree) so that users from other cells can also access the information in it. AFS enables cells to combine
+       their local filespaces into a global filespace, and does so in such a way that file access is transparent--users do not need
+       to know anything about a file's location in order to access it. All they need to know is the pathname of the file, which looks
+       the same in every cell. Thus every user at every machine sees the collection of files in the same way, meaning that AFS
+       provides a uniform namespace to its users.</para>
+     </sect2>
+ 
+     <sect2 renderas="sect3">
+       <title>Volumes</title>
+ 
+       <para>AFS groups files into volumes, making it possible to distribute files across many machines and yet maintain a uniform
+       namespace. A volume is a unit of disk space that functions like a container for a set of related files, keeping them all
+       together on one partition. Volumes can vary in size, but are (by definition) smaller than a partition.</para>
+ 
+       <para>Volumes are important to system administrators and users for several reasons. Their small size makes them easy to move
+       from one partition to another, or even between machines. The system administrator can maintain maximum efficiency by moving
+       volumes to keep the load balanced evenly. In addition, volumes correspond to directories in the filespace--most cells store
+       the contents of each user home directory in a separate volume. Thus the complete contents of the directory move together when
+       the volume moves, making it easy for AFS to keep track of where a file is at a certain time. Volume moves are recorded
+       automatically, so users do not have to keep track of file locations.</para>
+     </sect2>
+ 
+     <sect2 renderas="sect3">
+       <title>Efficiency Boosters: Replication and Caching</title>
+ 
+       <para>AFS incorporates special features on server machines and client machines that help make it efficient and
+       reliable.</para>
+ 
+       <para>On server machines, AFS enables administrators to replicate commonly-used volumes, such as those containing binaries for
+       popular programs. Replication means putting an identical read-only copy (sometimes called a clone) of a volume on more than
+       one file server machine. The failure of one file server machine housing the volume does not interrupt users' work, because the
+       volume's contents are still available from other machines. Replication also means that one machine does not become
+       overburdened with requests for files from a popular volume.</para>
+ 
+       <para>On client machines, AFS uses caching to improve efficiency. When a user on a client workstation requests a file, the
+       Cache Manager on the client sends a request for the data to the File Server process running on the proper file server machine.
+       The user does not need to know which machine this is; the Cache Manager determines file location automatically. The Cache
+       Manager receives the file from the File Server process and puts it into the cache, an area of the client machine's local disk
+       or memory dedicated to temporary file storage. Caching improves efficiency because the client does not need to send a request
+       across the network every time the user wants the same file. Network traffic is minimized, and subsequent access to the file is
+       especially fast because the file is stored locally. AFS has a way of ensuring that the cached file stays up-to-date, called a
+       callback.</para>
+     </sect2>
+ 
+     <sect2 renderas="sect3">
+       <title>Security: Mutual Authentication and Access Control Lists</title>
+ 
+       <para>Even in a cell where file sharing is especially frequent and widespread, it is not desirable that every user have equal
+       access to every file. One way AFS provides adequate security is by requiring that servers and clients prove their identities
+       to one another before they exchange information. This procedure, called mutual authentication, requires that both server and
+       client demonstrate knowledge of a "shared secret" (like a password) known only to the two of them. Mutual authentication
+       guarantees that servers provide information only to authorized clients and that clients receive information only from
+       legitimate servers.</para>
+ 
+       <para>Users themselves control another aspect of AFS security, by determining who has access to the directories they own. For
+       any directory a user owns, he or she can build an access control list (ACL) that grants or denies access to the contents of
+       the directory. An access control list pairs specific users with specific types of access privileges. There are seven separate
+       permissions and up to twenty different people or groups of people can appear on an access control list.</para>
+ 
+       <para>For a more detailed description of AFS's mutual authentication procedure, see <link linkend="HDRWQ75">A More Detailed
+       Look at Mutual Authentication</link>. For further discussion of ACLs, see <link linkend="HDRWQ562">Managing Access Control
+       Lists</link>.</para>
+     </sect2>
+   </sect1>
+ 
+   <sect1 id="HDRWQ7">
+     <title>More Detailed Discussions of Some Basic Concepts</title>
+ 
+     <para>The previous section offered a brief overview of the many concepts that an AFS system administrator needs to understand.
+     The following sections examine some important concepts in more detail. Although not all concepts are new to an experienced
+     administrator, reading this section helps ensure a common understanding of term and concepts.</para>
+ 
+     <sect2 id="HDRWQ8">
+       <title>Networks</title>
+ 
+       <indexterm>
+         <primary>network</primary>
+ 
+         <secondary>defined</secondary>
+       </indexterm>
+ 
+       <para>A <emphasis>network</emphasis> is a collection of interconnected computers able to communicate with each other and
+       transfer information back and forth.</para>
+ 
+       <para>A networked computing environment contrasts with two types of computing environments: <emphasis>mainframe</emphasis> and
+       <emphasis>personal</emphasis>. <indexterm>
+           <primary>network</primary>
+ 
+           <secondary>as computing environment</secondary>
+         </indexterm> <indexterm>
+           <primary>environment</primary>
+ 
+           <secondary>types compared</secondary>
+         </indexterm> <itemizedlist>
+           <listitem>
+             <para>A <emphasis>mainframe</emphasis> computing environment is the most traditional. It uses a single powerful computer
+             (the mainframe) to do the majority of the work in the system, both file storage and computation. It serves many users,
+             who access their files and issue commands to the mainframe via terminals, which generally have only enough computing
+             power to accept input from a keyboard and to display data on the screen.</para>
+ 
+             <indexterm>
+               <primary>mainframe</primary>
+ 
+               <secondary>computing environment</secondary>
+             </indexterm>
+           </listitem>
+ 
+           <listitem>
+             <para>A <emphasis>personal</emphasis> computing environment is a single small computer that serves one (or, at the most,
+             a few) users. Like a mainframe computer, the single computer stores all the files and performs all computation. Like a
+             terminal, the personal computer provides access to the computer through a keyboard and screen.</para>
+ 
+             <indexterm>
+               <primary>personal</primary>
+ 
+               <secondary>computing environment</secondary>
+             </indexterm>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <para>A network can connect computers of any kind, but the typical network running AFS connects high-function personal
+       workstations. Each workstation has some computing power and local disk space, usually more than a personal computer or
+       terminal, but less than a mainframe. For more about the classes of machines used in an AFS environment, see <link
+       linkend="HDRWQ10">Servers and Clients</link>.</para>
+     </sect2>
+ 
+     <sect2 id="HDRWQ9">
+       <title>Distributed File Systems</title>
+ 
+       <indexterm>
+         <primary>file system</primary>
+ 
+         <secondary>defined</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>distributed file system</primary>
+       </indexterm>
+ 
+       <para>A <emphasis>file system</emphasis> is a collection of files and the facilities (programs and commands) that enable users
+       to access the information in the files. All computing environments have file systems. In a mainframe environment, the file
+       system consists of all the files on the mainframe's storage disks, whereas in a personal computing environment it consists of
+       the files on the computer's local disk.</para>
+ 
+       <para>Networked computing environments often use <emphasis>distributed file systems</emphasis> like AFS. A distributed file
+       system takes advantage of the interconnected nature of the network by storing files on more than one computer in the network
+       and making them accessible to all of them. In other words, the responsibility for file storage and delivery is "distributed"
+       among multiple machines instead of relying on only one. Despite the distribution of responsibility, a distributed file system
+       like AFS creates the illusion that there is a single filespace.</para>
+     </sect2>
+ 
+     <sect2 id="HDRWQ10">
+       <title>Servers and Clients</title>
+ 
+       <indexterm>
+         <primary>server/client model</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>server</primary>
+ 
+         <secondary>definition</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>client</primary>
+ 
+         <secondary>definition</secondary>
+       </indexterm>
+ 
+       <para>AFS uses a server/client model. In general, a server is a machine, or a process running on a machine, that provides
+       specialized services to other machines. A client is a machine or process that makes use of a server's specialized service
+       during the course of its own work, which is often of a more general nature than the server's. The functional distinction
+       between clients and server is not always strict, however--a server can be considered the client of another server whose
+       service it is using.</para>
+ 
+       <para>AFS divides the machines on a network into two basic classes, <emphasis>file server machines</emphasis> and
+       <emphasis>client machines</emphasis>, and assigns different tasks and responsibilities to each.</para>
+ 
+       <formalpara>
+         <title>File Server Machines</title>
+ 
+         <indexterm>
+           <primary>file server machine</primary>
+         </indexterm>
+ 
+         <indexterm>
+           <primary>server</primary>
+ 
+           <secondary>process</secondary>
+ 
+           <tertiary>definition</tertiary>
+         </indexterm>
+ 
+         <para><emphasis>File server machines</emphasis> store the files in the distributed file system, and a <emphasis>server
+         process</emphasis> running on the file server machine delivers and receives files. AFS file server machines run a number of
+         <emphasis>server processes</emphasis>. Each process has a special function, such as maintaining databases important to AFS
+         administration, managing security or handling volumes. This modular design enables each server process to specialize in one
+         area, and thus perform more efficiently. For a description of the function of each AFS server process, see <link
+         linkend="HDRWQ17">AFS Server Processes and the Cache Manager</link>.</para>
+       </formalpara>
+ 
+       <para>Not all AFS server machines must run all of the server processes. Some processes run on only a few machines because the
+       demand for their services is low. Other processes run on only one machine in order to act as a synchronization site. See <link
+       linkend="HDRWQ90">The Four Roles for File Server Machines</link>.</para>
+ 
+       <formalpara>
+         <title>Client Machines</title>
+ 
+         <indexterm>
+           <primary>client</primary>
+ 
+           <secondary>machine</secondary>
+ 
+           <tertiary>definition</tertiary>
+         </indexterm>
+ 
+         <para>The other class of machines are the <emphasis>client machines</emphasis>, which generally work directly for users,
+         providing computational power and other general purpose tools. Clients also provide users with access to the files stored on
+         the file server machines. Clients do not run any special processes per se, but do use a modified kernel that enables them to
+         communicate with the AFS server processes running on the file server machines and to cache files. This collection of kernel
+         modifications is referred to as the Cache Manager; see <link linkend="HDRWQ28">The Cache Manager</link>. There are usually
+         many more client machines in a cell than file server machines.</para>
+       </formalpara>
+ 
+       <formalpara>
+         <title>Client and Server Configuration</title>
+ 
+         <indexterm>
+           <primary>personal</primary>
+ 
+           <secondary>workstation</secondary>
+ 
+           <tertiary>as typical AFS machine</tertiary>
+         </indexterm>
+ 
+         <para>In the most typical AFS configuration, both file server machines and client machines are high-function workstations
+         with disk drives. While this configuration is not required, it does have some advantages.</para>
+       </formalpara>
+ 
+       <para>There are several advantages to using personal workstations as file server machines. One is that it is easy to expand
+       the network by adding another file server machine. It is also easy to increase storage space by adding disks to existing
+       machines. Using workstations rather than more powerful mainframes makes it more economical to use multiple file server
+       machines rather than one. Multiple file server machines provide an increase in system availability and reliability if popular
+       files are available on more than one machine.</para>
+ 
+       <para>The advantage of using workstations as clients is that caching on the local disk speeds the delivery of files to
+       application programs. (For an explanation of caching, see <link linkend="HDRWQ16">Caching and Callbacks</link>.) Diskless
+       machines can access AFS if they are running NFS(R) and the NFS/AFS Translator, an optional component of the AFS
+       distribution.</para>
+     </sect2>
+ 
+     <sect2 id="HDRWQ11">
+       <title>Cells</title>
+ 
+       <indexterm>
+         <primary>cell</primary>
+       </indexterm>
+ 
+       <para>A <emphasis>cell</emphasis> is an independently administered site running AFS. In terms of hardware, it consists of a
+       collection of file server machines and client machines defined as belonging to the cell; a machine can only belong to one cell
+       at a time. Users also belong to a cell in the sense of having an account in it, but unlike machines can belong to (have an
+       account in) multiple cells. To say that a cell is administratively independent means that its administrators determine many
+       details of its configuration without having to consult administrators in other cells or a central authority. For example, a
+       cell administrator determines how many machines of different types to run, where to put files in the local tree, how to
+       associate volumes and directories, and how much space to allocate to each user.</para>
+ 
+       <para>The terms <emphasis>local cell</emphasis> and <emphasis>home cell</emphasis> are equivalent, and refer to the cell in
+       which a user has initially authenticated during a session, by logging onto a machine that belongs to that cell. All other
+       cells are referred to as <emphasis>foreign</emphasis> from the user's perspective. In other words, throughout a login session,
+       a user is accessing the filespace through a single Cache Manager--the one on the machine to which he or she initially logged
+       in--whose cell membership defines the local cell. All other cells are considered foreign during that login session, even if
+       the user authenticates in additional cells or uses the <emphasis role="bold">cd</emphasis> command to change directories into
+       their file trees.</para>
+ 
+       <indexterm>
+         <primary>local cell</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>cell</primary>
+ 
+         <secondary>local</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>foreign cell</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>cell</primary>
+ 
+         <secondary>foreign</secondary>
+       </indexterm>
+ 
+       <para>It is possible to maintain more than one cell at a single geographical location. For instance, separate departments on a
+       university campus or in a corporation can choose to administer their own cells. It is also possible to have machines at
+       geographically distant sites belong to the same cell; only limits on the speed of network communication determine how
+       practical this is.</para>
+ 
+       <para>Despite their independence, AFS cells generally agree to make their local filespace visible to other AFS cells, so that
+       users in different cells can share files if they choose. If your cell is to participate in the "global" AFS namespace, it must
+       comply with a few basic conventions governing how the local filespace is configured and how the addresses of certain file
+       server machines are advertised to the outside world.</para>
+     </sect2>
+ 
+     <sect2 id="HDRWQ12">
+       <title>The Uniform Namespace and Transparent Access</title>
+ 
+       <indexterm>
+         <primary>transparent access as AFS feature</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>access</primary>
+ 
+         <secondary>transparent (AFS feature)</secondary>
+       </indexterm>
+ 
+       <para>One of the features that makes AFS easy to use is that it provides transparent access to the files in a cell's
+       filespace. Users do not have to know which file server machine stores a file in order to access it; they simply provide the
+       file's pathname, which AFS automatically translates into a machine location.</para>
+ 
+       <para>In addition to transparent access, AFS also creates a <emphasis>uniform namespace</emphasis>--a file's pathname is
+       identical regardless of which client machine the user is working on. The cell's file tree looks the same when viewed from any
+       client because the cell's file server machines store all the files centrally and present them in an identical manner to all
+       clients.</para>
+ 
+       <para>To enable the transparent access and the uniform namespace features, the system administrator must follow a few simple
+       conventions in configuring client machines and file trees. For details, see <link linkend="HDRWQ39">Making Other Cells Visible
+       in Your Cell</link>.</para>
+     </sect2>
+ 
+     <sect2 id="HDRWQ13">
+       <title>Volumes</title>
+ 
+       <indexterm>
+         <primary>volume</primary>
+ 
+         <secondary>definition</secondary>
+       </indexterm>
+ 
+       <para>A <emphasis>volume</emphasis> is a conceptual container for a set of related files that keeps them all together on one
+       file server machine partition. Volumes can vary in size, but are (by definition) smaller than a partition. Volumes are the
+       main administrative unit in AFS, and have several characteristics that make administrative tasks easier and help improve
+       overall system performance. <itemizedlist>
+           <listitem>
+             <para>The relatively small size of volumes makes them easy to move from one partition to another, or even between
+             machines.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>You can maintain maximum system efficiency by moving volumes to keep the load balanced evenly among the different
+             machines. If a partition becomes full, the small size of individual volumes makes it easy to find enough room on other
+             machines for them.</para>
+ 
+             <indexterm>
+               <primary>volume</primary>
+ 
+               <secondary>in load balancing</secondary>
+             </indexterm>
+           </listitem>
+ 
+           <listitem>
+             <para>Each volume corresponds logically to a directory in the file tree and keeps together, on a single partition, all
+             the data that makes up the files in the directory. By maintaining (for example) a separate volume for each user's home
+             directory, you keep all of the user's files together, but separate from those of other users. This is an administrative
+             convenience that is impossible if the partition is the smallest unit of storage.</para>
+ 
+             <indexterm>
+               <primary>volume</primary>
+ 
+               <secondary>correspondence with directory</secondary>
+             </indexterm>
+ 
+             <indexterm>
+               <primary>directory</primary>
+ 
+               <secondary>correspondence with volume</secondary>
+             </indexterm>
+ 
+             <indexterm>
+               <primary>correspondence</primary>
+ 
+               <secondary>of volumes and directories</secondary>
+             </indexterm>
+           </listitem>
+ 
+           <listitem>
+             <para>The directory/volume correspondence also makes transparent file access possible, because it simplifies the process
+             of file location. All files in a directory reside together in one volume and in order to find a file, a file server
+             process need only know the name of the file's parent directory, information which is included in the file's pathname.
+             AFS knows how to translate the directory name into a volume name, and automatically tracks every volume's location, even
+             when a volume is moved from machine to machine. For more about the directory/volume correspondence, see <link
+             linkend="HDRWQ14">Mount Points</link>.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Volumes increase file availability through replication and backup.</para>
+ 
+             <indexterm>
+               <primary>volume</primary>
+ 
+               <secondary>as unit of</secondary>
+ 
+               <tertiary>replication</tertiary>
+             </indexterm>
+ 
+             <indexterm>
+               <primary>volume</primary>
+ 
+               <secondary>as unit of</secondary>
+ 
+               <tertiary>backup</tertiary>
+             </indexterm>
+           </listitem>
+ 
+           <listitem>
+             <para>Replication (placing copies of a volume on more than one file server machine) makes the contents more reliably
+             available; for details, see <link linkend="HDRWQ15">Replication</link>. Entire sets of volumes can be backed up to tape
+             and restored to the file system; see <link linkend="HDRWQ248">Configuring the AFS Backup System</link> and <link
+             linkend="HDRWQ283">Backing Up and Restoring AFS Data</link>. In AFS, backup also refers to recording the state of a
+             volume at a certain time and then storing it (either on tape or elsewhere in the file system) for recovery in the event
+             files in it are accidentally deleted or changed. See <link linkend="HDRWQ201">Creating Backup Volumes</link>.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Volumes are the unit of resource management. A space quota associated with each volume sets a limit on the maximum
+             volume size. See <link linkend="HDRWQ234">Setting and Displaying Volume Quota and Current Size</link>.</para>
+ 
+             <indexterm>
+               <primary>volume</primary>
+ 
+               <secondary>as unit of</secondary>
+ 
+               <tertiary>resource management</tertiary>
+             </indexterm>
+           </listitem>
+         </itemizedlist></para>
+     </sect2>
+ 
+     <sect2 id="HDRWQ14">
+       <title>Mount Points</title>
+ 
+       <indexterm>
+         <primary>mount point</primary>
+ 
+         <secondary>definition</secondary>
+       </indexterm>
+ 
+       <para>The previous section discussed how each volume corresponds logically to a directory in the file system: the volume keeps
+       together on one partition all the data in the files residing in the directory. The directory that corresponds to a volume is
+       called its <emphasis>root directory</emphasis>, and the mechanism that associates the directory and volume is called a
+       <emphasis>mount point</emphasis>. A mount point is similar to a symbolic link in the file tree that specifies which volume
+       contains the files kept in a directory. A mount point is not an actual symbolic link; its internal structure is
+       different.</para>
+ 
+       <note>
+         <para>You must not create a symbolic link to a file whose name begins with the number sign (#) or the percent sign (%),
+         because the Cache Manager interprets such a link as a mount point to a regular or read/write volume, respectively.</para>
+       </note>
+ 
+       <indexterm>
+         <primary>root directory</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>directory</primary>
+ 
+         <secondary>root</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>volume</primary>
+ 
+         <secondary>root directory of</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>volume</primary>
+ 
+         <secondary>mounting</secondary>
+       </indexterm>
+ 
+       <para>The use of mount points means that many of the elements in an AFS file tree that look and function just like standard
+       UNIX file system directories are actually mount points. In form, a mount point is a one-line file that names the volume
+       containing the data for files in the directory. When the Cache Manager (see <link linkend="HDRWQ28">The Cache Manager</link>)
+       encounters a mount point--for example, in the course of interpreting a pathname--it looks in the volume named in the mount
+       point. In the volume the Cache Manager finds an actual UNIX-style directory element--the volume's root directory--that lists
+       the files contained in the directory/volume. The next element in the pathname appears in that list.</para>
+ 
+       <para>A volume is said to be <emphasis>mounted</emphasis> at the point in the file tree where there is a mount point pointing
+       to the volume. A volume's contents are not visible or accessible unless it is mounted.</para>
+     </sect2>
+ 
+     <sect2 id="HDRWQ15">
+       <title>Replication</title>
+ 
+       <indexterm>
+         <primary>replication</primary>
+ 
+         <secondary>definition</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>clone</primary>
+       </indexterm>
+ 
+       <para><emphasis>Replication</emphasis> refers to making a copy, or <emphasis>clone</emphasis>, of a source read/write volume
+       and then placing the copy on one or more additional file server machines in a cell. One benefit of replicating a volume is
+       that it increases the availability of the contents. If one file server machine housing the volume fails, users can still
+       access the volume on a different machine. No one machine need become overburdened with requests for a popular file, either,
+       because the file is available from several machines.</para>
+ 
+       <para>Replication is not necessarily appropriate for cells with limited disk space, nor are all types of volumes equally
+       suitable for replication (replication is most appropriate for volumes that contain popular files that do not change very
+       often). For more details, see <link linkend="HDRWQ50">When to Replicate Volumes</link>.</para>
+     </sect2>
+ 
+     <sect2 id="HDRWQ16">
+       <title>Caching and Callbacks</title>
+ 
+       <indexterm>
+         <primary>caching</primary>
+       </indexterm>
+ 
+       <para>Just as replication increases system availability, <emphasis>caching</emphasis> increases the speed and efficiency of
+       file access in AFS. Each AFS client machine dedicates a portion of its local disk or memory to a cache where it stores data
+       temporarily. Whenever an application program (such as a text editor) running on a client machine requests data from an AFS
+       file, the request passes through the Cache Manager. The Cache Manager is a portion of the client machine's kernel that
+       translates file requests from local application programs into cross-network requests to the <emphasis>File Server
+       process</emphasis> running on the file server machine storing the file. When the Cache Manager receives the requested data
+       from the File Server, it stores it in the cache and then passes it on to the application program.</para>
+ 
+       <para>Caching improves the speed of data delivery to application programs in the following ways:</para>
+ 
+       <itemizedlist>
+         <listitem>
+           <para>When the application program repeatedly asks for data from the same file, it is already on the local disk. The
+           application does not have to wait for the Cache Manager to request and receive the data from the File Server.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>Caching data eliminates the need for repeated request and transfer of the same data, so network traffic is reduced.
+           Thus, initial requests and other traffic can get through more quickly.</para>
+ 
+           <indexterm>
+             <primary>AFS</primary>
+ 
+             <secondary>reducing traffic in</secondary>
+           </indexterm>
+ 
+           <indexterm>
+             <primary>network</primary>
+ 
+             <secondary>reducing traffic through caching</secondary>
+           </indexterm>
+ 
+           <indexterm>
+             <primary>slowed performance</primary>
+ 
+             <secondary>preventing in AFS</secondary>
+           </indexterm>
+         </listitem>
+       </itemizedlist>
+ 
+       <indexterm>
+         <primary>callback</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>consistency guarantees</primary>
+ 
+         <secondary>cached data</secondary>
+       </indexterm>
+ 
+       <para>While caching provides many advantages, it also creates the problem of maintaining consistency among the many cached
+       copies of a file and the source version of a file. This problem is solved using a mechanism referred to as a
+       <emphasis>callback</emphasis>.</para>
+ 
+       <para>A callback is a promise by a File Server to a Cache Manager to inform the latter when a change is made to any of the
+       data delivered by the File Server. Callbacks are used differently based on the type of file delivered by the File Server:
+       <itemizedlist>
+           <listitem>
+             <para>When a File Server delivers a writable copy of a file (from a read/write volume) to the Cache Manager, the File
+             Server sends along a callback with that file. If the source version of the file is changed by another user, the File
+             Server breaks the callback associated with the cached version of that file--indicating to the Cache Manager that it
+             needs to update the cached copy.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>When a File Server delivers a file from a read-only volume to the Cache Manager, the File Server sends along a
+             callback associated with the entire volume (so it does not need to send any more callbacks when it delivers additional
+             files from the volume). Only a single callback is required per accessed read-only volume because files in a read-only
+             volume can change only when a new version of the complete volume is released. All callbacks associated with the old
+             version of the volume are broken at release time.</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <para>The callback mechanism ensures that the Cache Manager always requests the most up-to-date version of a file. However, it
+       does not ensure that the user necessarily notices the most current version as soon as the Cache Manager has it. That depends
+       on how often the application program requests additional data from the File System or how often it checks with the Cache
+       Manager.</para>
+     </sect2>
+   </sect1>
+ 
+   <sect1 id="HDRWQ17">
+     <title>AFS Server Processes and the Cache Manager</title>
+ 
+     <indexterm>
+       <primary>AFS</primary>
+ 
+       <secondary>server processes used in</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>server</primary>
+ 
+       <secondary>process</secondary>
+ 
+       <tertiary>list of AFS</tertiary>
+     </indexterm>
+ 
+     <para>As mentioned in <link linkend="HDRWQ10">Servers and Clients</link>, AFS file server machines run a number of processes,
+     each with a specialized function. One of the main responsibilities of a system administrator is to make sure that processes are
+     running correctly as much of the time as possible, using the administrative services that the server processes provide.</para>
+ 
+     <para>The following list briefly describes the function of each server process and the Cache Manager; the following sections
+     then discuss the important features in more detail.</para>
+ 
+     <para>The <emphasis>File Server</emphasis>, the most fundamental of the servers, delivers data files from the file server
+     machine to local workstations as requested, and stores the files again when the user saves any changes to the files.</para>
+ 
+     <para>The <emphasis>Basic OverSeer Server (BOS Server)</emphasis> ensures that the other server processes on its server machine
+     are running correctly as much of the time as possible, since a server is useful only if it is available. The BOS Server relieves
+     system administrators of much of the responsibility for overseeing system operations.</para>
+ 
+     <para>The <emphasis>Authentication Server</emphasis> helps ensure that communications on the network are secure. It verifies
+     user identities at login and provides the facilities through which participants in transactions prove their identities to one
+     another (mutually authenticate). It maintains the Authentication Database.</para>
+ 
+     <para>The Protection Server helps users control who has access to their files and directories. Users can grant access to several
+     other users at once by putting them all in a group entry in the Protection Database maintained by the Protection Server.</para>
+ 
+     <para>The <emphasis>Volume Server</emphasis> performs all types of volume manipulation. It helps the administrator move volumes
+     from one server machine to another to balance the workload among the various machines.</para>
+ 
+     <para>The <emphasis>Volume Location Server (VL Server)</emphasis> maintains the Volume Location Database (VLDB), in which it
+     records the location of volumes as they move from file server machine to file server machine. This service is the key to
+     transparent file access for users.</para>
+ 
+     <para>The <emphasis>Update Server</emphasis> distributes new versions of AFS server process software and configuration
+     information to all file server machines. It is crucial to stable system performance that all server machines run the same
+     software.</para>
+ 
+     <para>The <emphasis>Backup Server</emphasis> maintains the Backup Database, in which it stores information related to the Backup
+     System. It enables the administrator to back up data from volumes to tape. The data can then be restored from tape in the event
+     that it is lost from the file system.</para>
+ 
+     <para>The <emphasis>Salvager</emphasis> is not a server in the sense that others are. It runs only after the File Server or
+     Volume Server fails; it repairs any inconsistencies caused by the failure. The system administrator can invoke it directly if
+     necessary.</para>
+ 
+     <para>The <emphasis>Network Time Protocol Daemon (NTPD)</emphasis> is not an AFS server process per se, but plays a vital role
+     nonetheless. It synchronizes the internal clock on a file server machine with those on other machines. Synchronized clocks are
+     particularly important for correct functioning of the AFS distributed database technology (known as Ubik); see <link
+     linkend="HDRWQ103">Configuring the Cell for Proper Ubik Operation</link>. The NTPD is controlled by the <emphasis
+     role="bold">runntp</emphasis> process.</para>
+ 
+     <para>The <emphasis>Cache Manager</emphasis> is the one component in this list that resides on AFS client rather than file
+     server machines. It not a process per se, but rather a part of the kernel on AFS client machines that communicates with AFS
+     server processes. Its main responsibilities are to retrieve files for application programs running on the client and to maintain
+     the files in the cache.</para>
+ 
+     <sect2 id="HDRWQ18">
+       <title>The File Server</title>
+ 
+       <indexterm>
+         <primary>File Server</primary>
+ 
+         <secondary>description</secondary>
+       </indexterm>
+ 
+       <para>The <emphasis>File Server</emphasis> is the most fundamental of the AFS server processes and runs on each file server
+       machine. It provides the same services across the network that the UNIX file system provides on the local disk: <itemizedlist>
+           <listitem>
+             <para>Delivering programs and data files to client workstations as requested and storing them again when the client
+             workstation finishes with them.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Maintaining the hierarchical directory structure that users create to organize their files.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Handling requests for copying, moving, creating, and deleting files and directories.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Keeping track of status information about each file and directory (including its size and latest modification
+             time).</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Making sure that users are authorized to perform the actions they request on particular files or
+             directories.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Creating symbolic and hard links between files.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Granting advisory locks (corresponding to UNIX locks) on request.</para>
+           </listitem>
+         </itemizedlist></para>
+     </sect2>
+ 
+     <sect2 id="HDRWQ19">
+       <title>The Basic OverSeer Server</title>
+ 
+       <indexterm>
+         <primary>BOS Server</primary>
+ 
+         <secondary>description</secondary>
+       </indexterm>
+ 
+       <para>The <emphasis>Basic OverSeer Server (BOS Server)</emphasis> reduces the demands on system administrators by constantly
+       monitoring the processes running on its file server machine. It can restart failed processes automatically and provides a
+       convenient interface for administrative tasks.</para>
+ 
+       <para>The BOS Server runs on every file server machine. Its primary function is to minimize system outages. It also</para>
+ 
+       <itemizedlist>
+         <listitem>
+           <para>Constantly monitors the other server processes (on the local machine) to make sure they are running
+           correctly.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>Automatically restarts failed processes, without contacting a human operator. When restarting multiple server
+           processes simultaneously, the BOS server takes interdependencies into account and initiates restarts in the correct
+           order.</para>
+ 
+           <indexterm>
+             <primary>system outages</primary>
+ 
+             <secondary>reducing</secondary>
+           </indexterm>
+ 
+           <indexterm>
+             <primary>outages</primary>
+ 
+             <secondary>BOS Server role in,</secondary>
+           </indexterm>
+         </listitem>
+ 
+         <listitem>
+           <para>Accepts requests from the system administrator. Common reasons to contact BOS are to verify the status of server
+           processes on file server machines, install and start new processes, stop processes either temporarily or permanently, and
+           restart dead processes manually.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>Helps system administrators to manage system configuration information. The BOS server automates the process of
+           adding and changing <emphasis>server encryption keys</emphasis>, which are important in mutual authentication. The BOS
+           Server also provides a simple interface for modifying two files that contain information about privileged users and
+           certain special file server machines. For more details about these configuration files, see <link linkend="HDRWQ85">Common
+           Configuration Files in the /usr/afs/etc Directory</link>.</para>
+         </listitem>
+       </itemizedlist>
+     </sect2>
+ 
+     <sect2 id="HDRWQ20">
+       <title>The Authentication Server</title>
+ 
+       <indexterm>
+         <primary>Authentication Server</primary>
+ 
+         <secondary>description</secondary>
+       </indexterm>
+ 
+       <para>The <emphasis>Authentication Server</emphasis> performs two main functions related to network security: <itemizedlist>
+           <listitem>
+             <para>Verifying the identity of users as they log into the system by requiring that they provide a password. The
+             Authentication Server grants the user a token as proof to AFS server processes that the user has authenticated. For more
+             on tokens, see <link linkend="HDRWQ76">Complex Mutual Authentication</link>.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Providing the means through which server and client processes prove their identities to each other (mutually
+             authenticate). This helps to create a secure environment in which to send cross-network messages.</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <para>In fulfilling these duties, the Authentication Server utilizes algorithms and other procedures known as
+       <emphasis>Kerberos</emphasis> (which is why many commands used to contact the Authentication Server begin with the letter
+       <emphasis role="bold">k</emphasis>). This technology was originally developed by the Massachusetts Institute of Technology's
+       Project Athena.</para>
+ 
+       <para>The Authentication Server also maintains the <emphasis>Authentication Database</emphasis>, in which it stores user
+       passwords converted into encryption key form as well as the AFS server encryption key. To learn more about the procedures AFS
+       uses to verify user identity and during mutual authentication, see <link linkend="HDRWQ75">A More Detailed Look at Mutual
+       Authentication</link>.</para>
+ 
+       <indexterm>
+         <primary>AFS</primary>
+ 
+         <secondary></secondary>
+ 
+         <see>AFS UID</see>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>username</primary>
+ 
+         <secondary>use by Kerberos</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>UNIX</primary>
+ 
+         <secondary>UID</secondary>
+ 
+         <tertiary>functional difference from AFS UID</tertiary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>Kerberos</primary>
+ 
+         <secondary>use of usernames</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ21">
+       <title>The Protection Server</title>
+ 
+       <indexterm>
+         <primary>protection</primary>
+ 
+         <secondary>in AFS</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>Protection Server</primary>
+ 
+         <secondary>description</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>protection</primary>
+ 
+         <secondary>in UNIX</secondary>
+       </indexterm>
+ 
+       <para>The <emphasis>Protection Server</emphasis> is the key to AFS's refinement of the normal UNIX methods for protecting
+       files and directories from unauthorized use. The refinements include the following: <itemizedlist>
+           <listitem>
+             <para>Defining seven access permissions rather than the standard UNIX file system's three. In conjunction with the UNIX
+             mode bits associated with each file and directory element, AFS associates an <emphasis>access control list
+             (ACL)</emphasis> with each directory. The ACL specifies which users have which of the seven specific permissions for the
+             directory and all the files it contains. For a definition of AFS's seven access permissions and how users can set them
+             on access control lists, see <link linkend="HDRWQ562">Managing Access Control Lists</link>.</para>
+ 
+             <indexterm>
+               <primary>access</primary>
+ 
+               <secondary></secondary>
+ 
+               <see>ACL</see>
+             </indexterm>
+           </listitem>
+ 
+           <listitem>
+             <para>Enabling users to grant permissions to numerous individual users--a different combination to each individual if
+             desired. UNIX protection distinguishes only between three user or groups: the owner of the file, members of a single
+             specified group, and everyone who can access the local file system.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Enabling users to define their own groups of users, recorded in the <emphasis>Protection Database</emphasis>
+             maintained by the Protection Server. The groups then appear on directories' access control lists as though they were
+             individuals, which enables the granting of permissions to many users simultaneously.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Enabling system administrators to create groups containing client machine IP addresses to permit access when it
+             originates from the specified client machines. These types of groups are useful when it is necessary to adhere to
+             machine-based licensing restrictions.</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <indexterm>
+         <primary>group</primary>
+ 
+         <secondary>definition</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>Protection Database</primary>
+       </indexterm>
+ 
+       <para>The Protection Server's main duty is to help the File Server determine if a user is authorized to access a file in the
+       requested manner. The Protection Server creates a list of all the groups to which the user belongs. The File Server then
+       compares this list to the ACL associated with the file's parent directory. A user thus acquires access both as an individual
+       and as a member of any groups.</para>
+ 
+       <para>The Protection Server also maps usernames (the name typed at the login prompt) to <emphasis>AFS user ID</emphasis>
+       numbers (<emphasis>AFS UIDs</emphasis>). These UIDs are functionally equivalent to UNIX UIDs, but operate in the domain of AFS
+       rather than in the UNIX file system on a machine's local disk. This conversion service is essential because the tokens that
+       the Authentication Server grants to authenticated users are stamped with usernames (to comply with Kerberos standards). The
+       AFS server processes identify users by AFS UID, not by username. Before they can understand whom the token represents, they
+       need the Protection Server to translate the username into an AFS UID. For further discussion of tokens, see <link
+       linkend="HDRWQ75">A More Detailed Look at Mutual Authentication</link>.</para>
+     </sect2>
+ 
+     <sect2 id="HDRWQ22">
+       <title>The Volume Server</title>
+ 
+       <indexterm>
+         <primary>Volume Server</primary>
+ 
+         <secondary>description</secondary>
+       </indexterm>
+ 
+       <para>The <emphasis>Volume Server</emphasis> provides the interface through which you create, delete, move, and replicate
+       volumes, as well as prepare them for archiving to tape or other media (backing up). <link linkend="HDRWQ13">Volumes</link>
+       explained the advantages gained by storing files in volumes. Creating and deleting volumes are necessary when adding and
+       removing users from the system; volume moves are done for load balancing; and replication enables volume placement on multiple
+       file server machines (for more on replication, see <link linkend="HDRWQ15">Replication</link>).</para>
+     </sect2>
+ 
+     <sect2 id="HDRWQ23">
+       <title>The Volume Location (VL) Server</title>
+ 
+       <indexterm>
+         <primary>VL Server</primary>
+ 
+         <secondary>description</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>VLDB</primary>
+       </indexterm>
+ 
+       <para>The <emphasis>VL Server</emphasis> maintains a complete list of volume locations in the <emphasis>Volume Location
+       Database (VLDB)</emphasis>. When the Cache Manager (see <link linkend="HDRWQ28">The Cache Manager</link>) begins to fill a
+       file request from an application program, it first contacts the VL Server in order to learn which file server machine
+       currently houses the volume containing the file. The Cache Manager then requests the file from the File Server process running
+       on that file server machine.</para>
+ 
+       <para>The VLDB and VL Server make it possible for AFS to take advantage of the increased system availability gained by using
+       multiple file server machines, because the Cache Manager knows where to find a particular file. Indeed, in a certain sense the
+       VL Server is the keystone of the entire file system--when the information in the VLDB is inaccessible, the Cache Manager
+       cannot retrieve files, even if the File Server processes are working properly. A list of the information stored in the VLDB
+       about each volume is provided in <link linkend="HDRWQ180">Volume Information in the VLDB</link>.</para>
+ 
+       <indexterm>
+         <primary>VL Server</primary>
+ 
+         <secondary>importance to transparent access</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ24">
+       <title>The Update Server</title>
+ 
+       <indexterm>
+         <primary>Update Server</primary>
+ 
+         <secondary>description</secondary>
+       </indexterm>
+ 
+       <para>The <emphasis>Update Server</emphasis> helps guarantee that all file server machines are running the same version of a
+       server process. System performance can be inconsistent if some machines are running one version of the BOS Server (for
+       example) and other machines were running another version.</para>
+ 
+       <para>To ensure that all machines run the same version of a process, install new software on a single file server machine of
+       each system type, called the <emphasis>binary distribution machine</emphasis> for that type. The binary distribution machine
+       runs the server portion of the Update Server, whereas all the other machines of that type run the client portion of the Update
+       Server. The client portions check frequently with the <emphasis>server portion</emphasis> to see if they are running the right
+       version of every process; if not, the <emphasis>client portion</emphasis> retrieves the right version from the binary
+       distribution machine and installs it locally. The system administrator does not need to remember to install new software
+       individually on all the file server machines: the Update Server does it automatically. For more on binary distribution
+       machines, see <link linkend="HDRWQ93">Binary Distribution Machines</link>.</para>
+ 
+       <indexterm>
+         <primary>Update Server</primary>
+ 
+         <secondary>server portion</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>Update Server</primary>
+ 
+         <secondary>client portion</secondary>
+       </indexterm>
+ 
+       <para>In cells that run the United States edition of AFS, the Update Server also distributes configuration files that all file
+       server machines need to store on their local disks (for a description of the contents and purpose of these files, see <link
+       linkend="HDRWQ85">Common Configuration Files in the /usr/afs/etc Directory</link>). As with server process software, the need
+       for consistent system performance demands that all the machines have the same version of these files. With the United States
+       edition, the system administrator needs to make changes to these files on one machine only, the cell's <emphasis>system
+       control machine</emphasis>, which runs a server portion of the Update Server. All other machines in the cell run a client
+       portion that accesses the correct versions of these configuration files from the system control machine. Cells running the
+       international edition of AFS do not use a system control machine to distribute configuration files. For more information, see
+       <link linkend="HDRWQ94">The System Control Machine</link>.</para>
+     </sect2>
+ 
+     <sect2 id="HDRWQ25">
+       <title>The Backup Server</title>
+ 
+       <indexterm>
+         <primary>Backup System</primary>
+ 
+         <secondary>Backup Server described</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>Backup Server</primary>
+ 
+         <secondary>description</secondary>
+       </indexterm>
+ 
+       <para>The <emphasis>Backup Server</emphasis> maintains the information in the <emphasis>Backup Database</emphasis>. The Backup
+       Server and the Backup Database enable administrators to back up data from AFS volumes to tape and restore it from tape to the
+       file system if necessary. The server and database together are referred to as the Backup System.</para>
+ 
+       <para>Administrators initially configure the Backup System by defining sets of volumes to be dumped together and the schedule
+       by which the sets are to be dumped. They also install the system's tape drives and define the drives' <emphasis>Tape
+       Coordinators</emphasis>, which are the processes that control the tape drives.</para>
+ 
+       <para>Once the Backup System is configured, user and system data can be dumped from volumes to tape. In the event that data is
+       ever lost from the system (for example, if a system or disk failure causes data to be lost), administrators can restore the
+       data from tape. If tapes are periodically archived, or saved, data can also be restored to its state at a specific time.
+       Additionally, because Backup System data is difficult to reproduce, the Backup Database itself can be backed up to tape and
+       restored if it ever becomes corrupted. For more information on configuring and using the Backup System, see <link
+       linkend="HDRWQ248">Configuring the AFS Backup System</link> and <link linkend="HDRWQ283">Backing Up and Restoring AFS
+       Data</link>.</para>
+     </sect2>
+ 
+     <sect2 id="HDRWQ26">
+       <title>The Salvager</title>
+ 
+       <indexterm>
+         <primary>Salvager</primary>
+ 
+         <secondary>description</secondary>
+       </indexterm>
+ 
+       <para>The <emphasis>Salvager</emphasis> differs from other AFS Servers in that it runs only at selected times. The BOS Server
+       invokes the Salvager when the File Server, Volume Server, or both fail. The Salvager attempts to repair disk corruption that
+       can result from a failure.</para>
+ 
+       <para>As a system administrator, you can also invoke the Salvager as necessary, even if the File Server or Volume Server has
+       not failed. See <link linkend="HDRWQ232">Salvaging Volumes</link>.</para>
+     </sect2>
+ 
+     <sect2 id="HDRWQ27">
+       <title>The Network Time Protocol Daemon</title>
+ 
+       <indexterm>
+         <primary>ntpd</primary>
+ 
+         <secondary>description</secondary>
+       </indexterm>
+ 
+       <para>The <emphasis>Network Time Protocol Daemon (NTPD)</emphasis> is not an AFS server process per se, but plays an important
+       role. It helps guarantee that all of the file server machines agree on the time. The NTPD on one file server machine acts as a
+       synchronization site, generally learning the correct time from a source outside the cell. The NTPDs on the other file server
+       machines refer to the synchronization site to set the internal clocks on their machines.</para>
+ 
+       <para>Keeping clocks synchronized is particularly important to the correct operation of AFS's distributed database technology,
+       which coordinates the copies of the Authentication, Backup, Protection, and Volume Location Databases; see <link
+       linkend="HDRWQ52">Replicating the OpenAFS Administrative Databases</link>. Client machines also refer to these clocks for the
+       correct time; therefore, it is less confusing if all file server machines have the same time. For more technical detail about
+       the NTPD, see <link linkend="HDRWQ151">The runntp Process</link>.</para>
+     </sect2>
+ 
+     <sect2 id="HDRWQ28">
+       <title>The Cache Manager</title>
+ 
+       <indexterm>
+         <primary>Cache Manager</primary>
+ 
+         <secondary>functions of</secondary>
+       </indexterm>
+ 
+       <para>As already mentioned in <link linkend="HDRWQ16">Caching and Callbacks</link>, the <emphasis>Cache Manager</emphasis> is
+       the one component in this section that resides on client machines rather than on file server machines. It is not technically a
+       stand-alone process, but rather a set of extensions or modifications in the client machine's kernel that enable communication
+       with the server processes running on server machines. Its main duty is to translate file requests (made by application
+       programs on client machines) into <emphasis>remote procedure calls (RPCs)</emphasis> to the File Server. (The Cache Manager
+       first contacts the VL Server to find out which File Server currently houses the volume that contains a requested file, as
+       mentioned in <link linkend="HDRWQ23">The Volume Location (VL) Server</link>). When the Cache Manager receives the requested
+       file, it caches it before passing data on to the application program.</para>
+ 
+       <para>The Cache Manager also tracks the state of files in its cache compared to the version at the File Server by storing the
+       callbacks sent by the File Server. When the File Server breaks a callback, indicating that a file or volume changed, the Cache
+       Manager requests a copy of the new version before providing more data to application programs.</para>
+     </sect2>
+   </sect1>
+ </chapter>
\ No newline at end of file
Index: openafs/doc/xml/AdminGuide/auagd007.xml
diff -c /dev/null openafs/doc/xml/AdminGuide/auagd007.xml:1.1.8.3
*** /dev/null	Sat May 30 21:40:41 2009
--- openafs/doc/xml/AdminGuide/auagd007.xml	Wed May 13 22:25:59 2009
***************
*** 0 ****
--- 1,4101 ----
+ <?xml version="1.0" encoding="UTF-8"?>
+ <chapter id="HDRWQ29">
+   <title>Issues in Cell Configuration and Administration</title>
+ 
+   <para>This chapter discusses many of the issues to consider when configuring and administering a cell, and directs you to detailed
+   related information available elsewhere in this guide. It is assumed you are already familiar with the material in <link
+   linkend="HDRWQ5">An Overview of OpenAFS Administration</link>.</para>
+ 
+   <para>It is best to read this chapter before installing your cell's first file server machine or performing any other
+   administrative task.</para>
+ 
+   <indexterm>
+     <primary>AFS</primary>
+ 
+     <secondary>differences from UNIX summarized</secondary>
+   </indexterm>
+ 
+   <indexterm>
+     <primary>UNIX</primary>
+ 
+     <secondary>differences from AFS summarized</secondary>
+   </indexterm>
+ 
+   <indexterm>
+     <primary>differences</primary>
+ 
+     <secondary>between AFS and UNIX, summarized</secondary>
+   </indexterm>
+ 
+   <sect1 id="HDRWQ30">
+     <title>Differences between AFS and UNIX: A Summary</title>
+ 
+     <para>AFS behaves like a standard UNIX file system in most respects, while also making file sharing easy within and between
+     cells. This section describes some differences between AFS and the UNIX file system, referring you to more detailed information
+     as appropriate.</para>
+ 
+     <indexterm>
+       <primary>protection</primary>
+ 
+       <secondary>AFS compared to UNIX</secondary>
+     </indexterm>
+ 
+     <sect2 id="Header_35">
+       <title>Differences in File and Directory Protection</title>
+ 
+       <para>AFS augments the standard UNIX file protection mechanism in two ways: it associates an <emphasis>access control list
+       (ACL)</emphasis> with each directory, and it enables users to define a large number of their own groups, which can be placed
+       on ACLs.</para>
+ 
+       <para>AFS uses ACLs to protect files and directories, rather than relying exclusively on the mode bits. This has several
+       implications, which are discussed further in the indicated sections: <itemizedlist>
+           <listitem>
+             <para>AFS ACLs use seven access permissions rather than the three UNIX mode bits. See <link linkend="HDRWQ567">The AFS
+             ACL Permissions</link>.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>For directories, AFS ignores the UNIX mode bits. For files, AFS uses only the first set of mode bits (the
+             <emphasis role="bold">owner</emphasis> bits) , and their meaning interacts with permissions on the directory's ACL. See
+             <link linkend="HDRWQ580">How AFS Interprets the UNIX Mode Bits</link>.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>A directory's ACL protects all of the files in a directory in the same manner. To apply a more restrictive set of
+             AFS permissions to certain file, place it in directory with a different ACL.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Moving a file to a different directory changes its protection. See <link linkend="HDRWQ566">Differences Between
+             UFS and AFS Data Protection</link>.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>An ACL can include about 20 entries granting different combinations of permissions to different users or groups,
+             rather than only the three UNIX entities represented by the three sets of mode bits. See <link
+             linkend="HDRWQ566">Differences Between UFS and AFS Data Protection</link>.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>You can designate an AFS file as write-only as in the UNIX file system, by setting only the <emphasis
+             role="bold">w</emphasis> (<emphasis role="bold">write</emphasis>) mode bit. You cannot designate an AFS directory as
+             write-only, because AFS ignores the mode bits on a directory. See <link linkend="HDRWQ580">How AFS Interprets the UNIX
+             Mode Bits</link>.</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <para>AFS enables users to define the groups of other users. Placing these groups on ACLs extends the same permissions to a
+       number of exactly specified users at the same time, which is much more convenient than placing the individuals on the ACLs
+       directly. See <link linkend="HDRWQ531">Administering the Protection Database</link>.</para>
+ 
+       <para>There are also system-defined groups, <emphasis role="bold">system:anyuser</emphasis> and <emphasis
+       role="bold">system:authuser</emphasis>, whose presence on an ACL extends access to a wide range of users at once. See <link
+       linkend="HDRWQ535">The System Groups</link> and <link linkend="HDRWQ571">Using Groups on ACLs</link>.</para>
+ 
+       <indexterm>
+         <primary>authentication</primary>
+ 
+         <secondary>AFS compared to UNIX</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>password</primary>
+ 
+         <secondary>AFS compared to UNIX</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ31">
+       <title>Differences in Authentication</title>
+ 
+       <para>Just as the AFS filespace is distinct from each machine's local file system, AFS authentication is separate from local
+       login. This has two practical implications, which are discussed further in <link linkend="HDRWQ65">Using an AFS-modified login
+       Utility</link>. <itemizedlist>
+           <listitem>
+             <para>To access AFS files, users must both log into the local machine's UNIX file system and authenticate with the AFS
+             authentication service. (Logging into the local UNIX file system is necessary because the AFS filespace is accessed
+             through the Cache Manager, which resides in the local machine's kernel.)</para>
+ 
+             <para>AFS provides a modified login utility for each system type that accomplishes both local login and AFS
+             authentication in one step, based on a single password. If you choose not to use the AFS-modified login utility, your
+             users must login and authenticate in separate steps, as detailed in the <emphasis>OpenAFS User Guide</emphasis>.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Passwords are stored in two separate places: the Authentication Database for AFS and each machine's local password
+             file (<emphasis role="bold">/etc/passwd</emphasis> or equivalent) for the UNIX file system. A user's passwords in the
+             two places can differ if desired, though the resulting behavior depends on whether and how the cell is using an
+             AFS-modified login utility.</para>
+           </listitem>
+         </itemizedlist></para>
+     </sect2>
+ 
+     <sect2 id="Header_37">
+       <title>Differences in the Semantics of Standard UNIX Commands</title>
+ 
+       <para>This section summarizes how AFS modifies the functionality of some UNIX commands. <variablelist>
+           <indexterm>
+             <primary>chmod command</primary>
+ 
+             <secondary>AFS compared to UNIX</secondary>
+           </indexterm>
+ 
+           <indexterm>
+             <primary>commands</primary>
+ 
+             <secondary>chmod (AFS compared to UNIX)</secondary>
+           </indexterm>
+ 
+           <indexterm>
+             <primary>setuid programs</primary>
+ 
+             <secondary>setting mode bits</secondary>
+           </indexterm>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">The chmod command</emphasis></term>
+ 
+             <listitem>
+               <para>Only members of the <emphasis role="bold">system:administrators</emphasis> group can use this command to turn on
+               the setuid, setgid or sticky mode bits on AFS files. For more information, see <link linkend="HDRWQ409">Determining if
+               a Client Can Run Setuid Programs</link>.</para>
+ 
+               <indexterm>
+                 <primary>chown command</primary>
+ 
+                 <secondary>AFS compared to UNIX</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>commands</primary>
+ 
+                 <secondary>chown (AFS compared to UNIX)</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">The chown command</emphasis></term>
+ 
+             <listitem>
+               <para>Only members of the <emphasis role="bold">system:administrators</emphasis> group can issue this command on AFS
+               files.</para>
+ 
+               <indexterm>
+                 <primary>chgrp command</primary>
+ 
+                 <secondary>AFS compared to UNIX</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>commands</primary>
+ 
+                 <secondary>chgrp (AFS compared to UNIX)</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">The chgrp command</emphasis></term>
+ 
+             <listitem>
+               <para>Only members of the <emphasis role="bold">system:administrators</emphasis> can issue this command on AFS files
+               and directories.</para>
+ 
+               <indexterm>
+                 <primary>ftpd command</primary>
+ 
+                 <secondary>AFS compared to UNIX</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>commands</primary>
+ 
+                 <secondary>ftpd (AFS compared to UNIX)</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">The ftpd daemon</emphasis></term>
+ 
+             <listitem>
+               <para>The AFS-modified version of this daemon attempts to authenticate remote issuers of the <emphasis
+               role="bold">ftp</emphasis> command with the local AFS authentication service. See <link linkend="HDRWQ78">Using UNIX
+               Remote Services in the AFS Environment</link>.</para>
+ 
+               <indexterm>
+                 <primary>groups command</primary>
+ 
+                 <secondary>AFS compared to UNIX</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>commands</primary>
+ 
+                 <secondary>groups (AFS compared to UNIX)</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">The groups command</emphasis></term>
+ 
+             <listitem>
+               <para>If the user's AFS tokens are associated with a process authentication group (PAG), the output of this command
+               sometimes includes two large numbers. To learn about PAGs, see <link linkend="HDRWQ64">Identifying AFS Tokens by
+               PAG</link>.</para>
+ 
+               <indexterm>
+                 <primary>inetd command</primary>
+ 
+                 <secondary>AFS compared to UNIX</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>commands</primary>
+ 
+                 <secondary>inetd (AFS compared to UNIX)</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">The inetd daemon</emphasis></term>
+ 
+             <listitem>
+               <para>The AFS-modified version of this daemon authenticates remote issuers of the AFS-modified <emphasis
+               role="bold">rcp</emphasis> and <emphasis role="bold">rsh</emphasis> commands with the local AFS authentication
+               service. See <link linkend="HDRWQ78">Using UNIX Remote Services in the AFS Environment</link>.</para>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">The login utility</emphasis></term>
+ 
+             <listitem>
+               <para>AFS-modified login utilities both log the issuer into the local file system and authenticate the user with the
+               AFS authentication service. See <link linkend="HDRWQ65">Using an AFS-modified login Utility</link>.</para>
+ 
+               <indexterm>
+                 <primary>ln command</primary>
+ 
+                 <secondary>AFS compared to UNIX</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>commands</primary>
+ 
+                 <secondary>ln (AFS compared to UNIX)</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">The ln command</emphasis></term>
+ 
+             <listitem>
+               <para>This command cannot create hard links between files in different AFS directories. See <link
+               linkend="HDRWQ32">Creating Hard Links</link>.</para>
+ 
+               <indexterm>
+                 <primary>rcp command</primary>
+ 
+                 <secondary>AFS compared to UNIX</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>commands</primary>
+ 
+                 <secondary>rcp (AFS compared to UNIX)</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">The rcp command</emphasis></term>
+ 
+             <listitem>
+               <para>The AFS-modified version of this command enables the issuer to access files on the remote machine as an
+               authenticated AFS user. See <link linkend="HDRWQ78">Using UNIX Remote Services in the AFS Environment</link>.</para>
+ 
+               <indexterm>
+                 <primary>rlogind command</primary>
+ 
+                 <secondary>AFS compared to UNIX</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>commands</primary>
+ 
+                 <secondary>rlogind (AFS compared to UNIX)</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">The rlogind daemon</emphasis></term>
+ 
+             <listitem>
+               <para>The AFS-modified version of this daemon authenticates remote issuers of the <emphasis
+               role="bold">rlogin</emphasis> command with the local AFS authentication service. See <link linkend="HDRWQ78">Using
+               UNIX Remote Services in the AFS Environment</link>.</para>
+ 
+               <para>The AFS distribution for some system types possibly does not include a modified <emphasis
+               role="bold">rlogind</emphasis> program. See the <emphasis>OpenAFS Release Notes</emphasis>.</para>
+ 
+               <indexterm>
+                 <primary>rsh command</primary>
+ 
+                 <secondary>AFS compared to UNIX</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>commands</primary>
+ 
+                 <secondary>rsh (AFS compared to UNIX)</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">The remsh or rsh command</emphasis></term>
+ 
+             <listitem>
+               <para>The AFS-modified version of this command enables the issuer to execute commands on the remote machine as an
+               authenticated AFS user. See <link linkend="HDRWQ78">Using UNIX Remote Services in the AFS Environment</link>.</para>
+             </listitem>
+           </varlistentry>
+         </variablelist></para>
+ 
+       <indexterm>
+         <primary>fsck command</primary>
+ 
+         <secondary>AFS compared to UNIX</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>commands</primary>
+ 
+         <secondary>fsck (AFS compared to UNIX)</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>fsck command</primary>
+ 
+         <secondary>AFS version</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>commands</primary>
+ 
+         <secondary>fsck (AFS version)</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>directories</primary>
+ 
+         <secondary>lost+found</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>lost+found directory</primary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="Header_38">
+       <title>The AFS version of the fsck Command</title>
+ 
+       <para>Never run the standard UNIX <emphasis role="bold">fsck</emphasis> command on an AFS file server machine. It does not
+       understand how the File Server organizes volume data on disk, and so moves all AFS data into the <emphasis
+       role="bold">lost+found</emphasis> directory on the partition.</para>
+ 
+       <para>Instead, use the version of the <emphasis role="bold">fsck</emphasis> program that is included in the AFS distribution.
+       The <emphasis>OpenAFS Quick Beginnings</emphasis> explains how to replace the vendor-supplied <emphasis
+       role="bold">fsck</emphasis> program with the AFS version as you install each server machine.</para>
+ 
+       <para>The AFS version functions like the standard <emphasis role="bold">fsck</emphasis> program on data stored on both UFS and
+       AFS partitions. The appearance of a banner like the following as the <emphasis role="bold">fsck</emphasis> program initializes
+       confirms that you are running the correct one:</para>
+ 
+       <programlisting>
+    --- AFS (R) version fsck---
+ </programlisting>
+ 
+       <para>where <emphasis>version</emphasis> is the AFS version. For correct results, it must match the AFS version of the server
+       binaries in use on the machine.</para>
+ 
+       <para>If you ever accidentally run the standard version of the program, contact AFS Product Support immediately. It is
+       sometimes possible to recover volume data from the <emphasis role="bold">lost+found</emphasis> directory.</para>
+ 
+       <indexterm>
+         <primary>hard link</primary>
+ 
+         <secondary>AFS restrictions on</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>restrictions</primary>
+ 
+         <secondary>on hard links in AFS</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ32">
+       <title>Creating Hard Links</title>
+ 
+       <para>AFS does not allow hard links (created with the UNIX <emphasis role="bold">ln</emphasis> command) between files that
+       reside in different directories, because in that case it is unclear which of the directory's ACLs to associate with the
+       link.</para>
+ 
+       <para>AFS also does not allow hard links to directories, in order to keep the file system organized as a tree.</para>
+ 
+       <para>It is possible to create symbolic links (with the UNIX <emphasis role="bold">ln -s</emphasis> command) between elements
+       in two different AFS directories, or even between an element in AFS and one in a machine's local UNIX file system. Do not
+       create a symbolic link to a file whose name begins with either a number sign (<emphasis role="bold">#</emphasis>) or a percent
+       sign (<emphasis role="bold">%</emphasis>), however. The Cache Manager interprets such links as a mount point to a regular or
+       read/write volume, respectively.</para>
+ 
+       <indexterm>
+         <primary>fsync system call</primary>
+ 
+         <secondary>for files saved on AFS client</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>close system call</primary>
+ 
+         <secondary>for files saved on AFS client</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>write</primary>
+ 
+         <secondary>system call for files saved on AFS client</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ33">
+       <title>AFS Implements Save on Close</title>
+ 
+       <para>When an application issues the UNIX <emphasis role="bold">close</emphasis> system call on a file, the Cache Manager
+       performs a synchronous write of the data to the File Server that maintains the central copy of the file. It does not return
+       control to the application until the File Server has acknowledged receipt of the data. For the <emphasis
+       role="bold">fsync</emphasis> system call, control does not return to the application until the File Server indicates that it
+       has written the data to non-volatile storage on the file server machine.</para>
+ 
+       <para>When an application issues the UNIX <emphasis role="bold">write</emphasis> system call, the Cache Manager writes
+       modifications to the local AFS client cache only. If the local machine crashes or an application program exits without issuing
+       the <emphasis role="bold">close</emphasis> system call, it is possible that the modifications are not recorded in the central
+       copy of the file maintained by the File Server. The Cache Manager does sometimes write this type of modified data from the
+       cache to the File Server without receiving the <emphasis role="bold">close</emphasis> or <emphasis
+       role="bold">fsync</emphasis> system call, for example if it needs to free cache chunks for new data. However, it is not
+       generally possible to predict when the Cache Manager transfers modified data to the File Server in this way.</para>
+ 
+       <para>The implication is that if an application's <emphasis role="bold">Save</emphasis> option invokes the <emphasis
+       role="bold">write</emphasis> system call rather than <emphasis role="bold">close</emphasis> or <emphasis
+       role="bold">fsync</emphasis>, the changes are not necessarily stored permanently on the File Server machine. Most application
+       programs issue the <emphasis role="bold">close</emphasis> system call for save operations, as well as when they finish
+       handling a file and when they exit.</para>
+     </sect2>
+ 
+     <sect2 id="Header_41">
+       <title>Setuid Programs</title>
+ 
+       <indexterm>
+         <primary>setuid programs</primary>
+ 
+         <secondary>restrictions on</secondary>
+       </indexterm>
+ 
+       <para>Set the UNIX setuid bit only for the local superuser <emphasis role="bold">root</emphasis>; this does not present an
+       automatic security risk: the local superuser has no special privilege in AFS, but only in the local machine's UNIX file system
+       and kernel.</para>
+ 
+       <para>Any file can be marked with the setuid bit, but only members of the <emphasis
+       role="bold">system:administrators</emphasis> group can issue the <emphasis role="bold">chown</emphasis> system call or the
+       <emphasis role="bold">/etc/chown</emphasis> command.</para>
+ 
+       <para>The <emphasis role="bold">fs setcell</emphasis> command determines whether setuid programs that originate in a foreign
+       cell can run on a given client machine. See <link linkend="HDRWQ409">Determining if a Client Can Run Setuid
+       Programs</link>.</para>
+ 
+       <indexterm>
+         <primary>cell</primary>
+ 
+         <secondary>name</secondary>
+ 
+         <tertiary>choosing</tertiary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>choosing</primary>
+ 
+         <secondary>name</secondary>
+ 
+         <tertiary>cell</tertiary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>conventions</primary>
+ 
+         <secondary>cell name</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>Internet</primary>
+ 
+         <secondary>conventions for cell name</secondary>
+       </indexterm>
+     </sect2>
+   </sect1>
+ 
+   <sect1 id="HDRWQ34">
+     <title>Choosing a Cell Name</title>
+ 
+     <para>This section explains how to choose a cell name and explains why choosing an appropriate cell name is important.</para>
+ 
+     <para>Your cell name must distinguish your cell from all others in the AFS global namespace. By conventions, the cell name is
+     the second element in any AFS pathname; therefore, a unique cell name guarantees that every AFS pathname uniquely identifies a
+     file, even if cells use the same directory names at lower levels in their local AFS filespace. For example, both the ABC
+     Corporation cell and the State University cell can have a home directory for the user <emphasis role="bold">pat</emphasis>,
+     because the pathnames are distinct: <emphasis role="bold">/afs/abc.com/usr/pat</emphasis> and <emphasis
+     role="bold">/afs/stateu.edu/usr/pat</emphasis>.</para>
+ 
+     <para>By convention, cell names follow the ARPA Internet Domain System conventions for site names. If you are already an
+     Internet site, then it is simplest to choose your Internet domain name as the cellname.</para>
+ 
+     <para>If you are not an Internet site, it is best to choose a unique Internet-style name, particularly if you plan to connect to
+     the Internet in the future. AFS Product Support is available for help in selecting an appropriate name. There are a few
+     constraints on AFS cell names: <itemizedlist>
+         <listitem>
+           <para>It can contain as many as 64 characters, but shorter names are better because the cell name frequently is part of
+           machine and file names. If your cell name is long, you can reduce pathname length by creating a symbolic link to the
+           complete cell name, at the second level in your file tree. See <link linkend="HDRWQ42">The Second (Cellname)
+           Level</link>.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>To guarantee it is suitable for different operating system types, the cell name can contain only lowercase
+           characters, numbers, underscores, dashes, and periods. Do not include command shell metacharacters.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>It can include any number of fields, which are conventionally separated by periods (see the examples below).</para>
+         </listitem>
+ 
+         <listitem>
+           <para>It must end in a suffix that indicates the type of institution it is, or the country in which it is situated. The
+           following are some of the standard suffixes: <variablelist>
+               <varlistentry>
+                 <term><emphasis role="bold">.com</emphasis></term>
+ 
+                 <listitem>
+                   <para>For businesses and other commercial organizations. Example: <emphasis role="bold">abc.com</emphasis> for the
+                   ABC Corporation cell.</para>
+                 </listitem>
+               </varlistentry>
+ 
+               <varlistentry>
+                 <term><emphasis role="bold">.edu</emphasis></term>
+ 
+                 <listitem>
+                   <para>For educational institutions such as universities. Example: <emphasis role="bold">stateu.edu</emphasis> for
+                   the State University cell.</para>
+                 </listitem>
+               </varlistentry>
+ 
+               <varlistentry>
+                 <term><emphasis role="bold">.gov</emphasis></term>
+ 
+                 <listitem>
+                   <para>For United States government institutions.</para>
+                 </listitem>
+               </varlistentry>
+ 
+               <varlistentry>
+                 <term><emphasis role="bold">.mil</emphasis></term>
+ 
+                 <listitem>
+                   <para>For United States military installations.</para>
+                 </listitem>
+               </varlistentry>
+             </variablelist></para>
+         </listitem>
+       </itemizedlist></para>
+ 
+     <indexterm>
+       <primary>Internet</primary>
+ 
+       <secondary>Network Information Center</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>Network Information Center (for Internet)</primary>
+     </indexterm>
+ 
+     <para>Other suffixes are available if none of these are appropriate. You can learn about suffixes by calling the Defense Data
+     Network [Internet] Network Information Center in the United States at (800) 235-3155. The NIC can also provide you with the
+     forms necessary for registering your cell name as an Internet domain name. Registering your name prevents another Internet site
+     from adopting the name later.</para>
+ 
+     <indexterm>
+       <primary>setting</primary>
+ 
+       <secondary>cell name</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>cell</primary>
+ 
+       <secondary>name</secondary>
+ 
+       <tertiary>setting</tertiary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>server machine</primary>
+ 
+       <secondary>setting home cell</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>client machine</primary>
+ 
+       <secondary>setting home cell</secondary>
+     </indexterm>
+ 
+     <sect2 id="Header_43">
+       <title>How to Set the Cell Name</title>
+ 
+       <para>The cell name is recorded in two files on the local disk of each file server and client machine. Among other functions,
+       these files define the machine's cell membership and so affect how programs and processes run on the machine; see <link
+       linkend="HDRWQ35">Why Choosing the Appropriate Cell Name is Important</link>. The procedure for setting the cell name is
+       different for the two types of machines.</para>
+ 
+       <para>For file server machines, the two files that record the cell name are the <emphasis
+       role="bold">/usr/afs/etc/ThisCell</emphasis> and <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> files. As described
+       more explicitly in the <emphasis>OpenAFS Quick Beginnings</emphasis>, you set the cell name in both by issuing the <emphasis
+       role="bold">bos setcellname</emphasis> command on the first file server machine you install in your cell. It is not usually
+       necessary to issue the command again. If you run the United States edition of AFS and use the Update Server, it distributes
+       its copy of the <emphasis role="bold">ThisCell</emphasis> and <emphasis role="bold">CellServDB</emphasis> files to additional
+       server machines that you install. If you use the international edition of AFS, the <emphasis>OpenAFS Quick
+       Beginnings</emphasis> explains how to copy the files manually.</para>
+ 
+       <para>For client machines, the two files that record the cell name are the <emphasis
+       role="bold">/usr/vice/etc/ThisCell</emphasis> and <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> files. You create
+       these files on a per-client basis, either with a text editor or by copying them onto the machine from a central source in AFS.
+       See <link linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link> for details.</para>
+ 
+       <para>Change the cell name in these files only when you want to transfer the machine to a different cell (it can only belong
+       to one cell at a time). If the machine is a file server, follow the complete set of instructions in the <emphasis>OpenAFS
+       Quick Beginnings</emphasis> for configuring a new cell. If the machine is a client, all you need to do is change the files
+       appropriately and reboot the machine. The next section explains further the negative consequences of changing the name of an
+       existing cell.</para>
+ 
+       <para>To set the default cell name used by most AFS commands without changing the local <emphasis
+       role="bold">/usr/vice/etc/ThisCell</emphasis> file, set the AFSCELL environment variable in the command shell. It is worth
+       setting this variable if you need to complete significant administrative work in a foreign cell.</para>
+ 
+       <note>
+         <para>The <emphasis role="bold">fs checkservers</emphasis> and <emphasis role="bold">fs mkmount</emphasis> commands do not
+         use the AFSCELL variable. The <emphasis role="bold">fs checkservers</emphasis> command always defaults to the cell named in
+         the <emphasis role="bold">ThisCell</emphasis> file, unless the <emphasis role="bold">-cell</emphasis> argument is used. The
+         <emphasis role="bold">fs mkmount</emphasis> command defaults to the cell in which the parent directory of the new mount
+         point resides.</para>
+       </note>
+ 
+       <indexterm>
+         <primary>ThisCell file (client)</primary>
+ 
+         <secondary>how used by programs</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ35">
+       <title>Why Choosing the Appropriate Cell Name is Important</title>
+ 
+       <para>Take care to select a cell name that is suitable for long-term use. Changing a cell name later is complicated. An
+       appropriate cell name is important because it is the second element in the pathname of all files in a cell's file tree.
+       Because each cell name is unique, its presence in an AFS pathname makes the pathname unique in the AFS global namespace, even
+       if multiple cells use similar filespace organization at lower levels. For instance, it means that every cell can have a home
+       directory called <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+       role="bold">/usr/pat</emphasis> without causing a conflict. The presence of the cell name in pathnames also means that users
+       in every cell use the same pathname to access a file, whether the file resides in their local cell or in a foreign
+       cell.</para>
+ 
+       <para>Another reason to choose the correct cell name early in the process of installing your cell is that the cell membership
+       defined in each machine's <emphasis role="bold">ThisCell</emphasis> file affects the performance of many programs and
+       processes running on the machine. For instance, AFS commands (<emphasis role="bold">fs</emphasis>, <emphasis
+       role="bold">kas</emphasis>, <emphasis role="bold">pts</emphasis> and <emphasis role="bold">vos</emphasis> commands) by default
+       execute in the cell of the machine on which they are issued. The command interpreters check the <emphasis
+       role="bold">ThisCell</emphasis> file on the local disk and then contact the database server machines listed in the <emphasis
+       role="bold">CellServDB</emphasis> file for the indicated cell (the <emphasis role="bold">bos</emphasis> commands work
+       differently because the issuer always has to name of the machine on which to run the command).</para>
+ 
+       <para>The <emphasis role="bold">ThisCell</emphasis> file also determines the cell for which a user receives an AFS token when
+       he or she logs in to a machine. The cell name also plays a role in security. As it converts a user password into an encryption
+       key for storage in the Authentication Database, the Authentication Server combines the password with the cell name found in
+       the <emphasis role="bold">ThisCell</emphasis> file. AFS-modified login utilities use the same algorithm to convert the user's
+       password into an encryption key before contacting the Authentication Server to obtain a token for the user. (For a description
+       of how AFS's security system uses encryption keys, see <link linkend="HDRWQ75">A More Detailed Look at Mutual
+       Authentication</link>.)</para>
+ 
+       <para>This method of converting passwords into encryption keys means that the same password results in different keys in
+       different cells. Even if a user uses the same password in multiple cells, obtaining a user's token from one cell does not
+       enable unauthorized access to the user's account in another cell.</para>
+ 
+       <para>If you change the cell name, you must change the <emphasis role="bold">ThisCell</emphasis> and <emphasis
+       role="bold">CellServDB</emphasis> files on every server and client machine. Failure to change them all can prevent login,
+       because the encryption keys produced by the login utility do not match the keys stored in the Authentication Database. In
+       addition, many commands from the AFS suites do not work as expected.</para>
+ 
+       <indexterm>
+         <primary>participation</primary>
+ 
+         <secondary>in AFS global namespace</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>AFS</primary>
+ 
+         <secondary>global namespace</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>global namespace</primary>
+       </indexterm>
+     </sect2>
+   </sect1>
+ 
+   <sect1 id="HDRWQ36">
+     <title>Participating in the AFS Global Namespace</title>
+ 
+     <para>Participating in the AFS global namespace makes your cell's local file tree visible to AFS users in foreign cells and
+     makes other cells' file trees visible to your local users. It makes file sharing across cells just as easy as sharing within a
+     cell. This section outlines the procedures necessary for participating in the global namespace. <itemizedlist>
+         <listitem>
+           <para>Participation in the global namespace is not mandatory. Some cells use AFS primarily to facilitate file sharing
+           within the cell, and are not interested in providing their users with access to foreign cells.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>Making your file tree visible does not mean making it vulnerable. You control how foreign users access your cell
+           using the same protection mechanisms that control local users' access. See <link linkend="HDRWQ40">Granting and Denying
+           Foreign Users Access to Your Cell</link>.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>The two aspects of participation are independent. A cell can make its file tree visible without allowing its users
+           to see foreign cells' file trees, or can enable its users to see other file trees without advertising its own.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>You make your cell visible to others by advertising your database server machines. See <link
+           linkend="HDRWQ38">Making Your Cell Visible to Others</link>.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>You control access to foreign cells on a per-client machine basis. In other words, it is possible to make a foreign
+           cell accessible from one client machine in your cell but not another. See <link linkend="HDRWQ39">Making Other Cells
+           Visible in Your Cell</link>.</para>
+         </listitem>
+       </itemizedlist></para>
+ 
+     <indexterm>
+       <primary>conventions</primary>
+ 
+       <secondary>AFS pathnames</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>AFS</primary>
+ 
+       <secondary>root directory (/afs)</secondary>
+ 
+       <tertiary>on client machine</tertiary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>directories</primary>
+ 
+       <secondary>/afs</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>directories</primary>
+ 
+       <secondary>/afs/<emphasis>cellname</emphasis></secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>cell</primary>
+ 
+       <secondary>name</secondary>
+ 
+       <tertiary>at second level in file tree</tertiary>
+     </indexterm>
+ 
+     <sect2 id="HDRWQ37">
+       <title>What the Global Namespace Looks Like</title>
+ 
+       <para>The AFS global namespace appears the same to all AFS cells that participate in it, because they all agree to follow a
+       small set of conventions in constructing pathnames.</para>
+ 
+       <para>The first convention is that all AFS pathnames begin with the string <emphasis role="bold">/afs</emphasis> to indicate
+       that they belong to the AFS global namespace.</para>
+ 
+       <para>The second convention is that the cell name is the second element in an AFS pathname; it indicates where the file
+       resides (that is, the cell in which a file server machine houses the file). As noted, the presence of a cell name in pathnames
+       makes the global namespace possible, because it guarantees that all AFS pathnames are unique even if cells use the same
+       directory names at lower levels in their AFS filespace.</para>
+ 
+       <para>What appears at the third and lower levels in an AFS pathname depends on how a cell has chosen to arrange its filespace.
+       There are some suggested conventional directories at the third level; see <link linkend="HDRWQ43">The Third
+       Level</link>.</para>
+ 
+       <indexterm>
+         <primary>cell</primary>
+ 
+         <secondary>making local visible to foreign</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>local cell</primary>
+ 
+         <secondary>making visible to foreign cells</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>foreign cell</primary>
+ 
+         <secondary>making local cell visible</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ38">
+       <title>Making Your Cell Visible to Others</title>
+ 
+       <para>You make your cell visible to others by advertising your cell name and database server machines. Just like client
+       machines in the local cell, the Cache Manager on machines in foreign cells use the information to reach your cell's Volume
+       Location (VL) Servers when they need volume and file location information. Similarly, client-side authentication programs
+       running in foreign cells use the information to contact your cell's authentication service.</para>
+ 
+       <para>There are two places you can make this information available: <itemizedlist>
+           <indexterm>
+             <primary>files</primary>
+ 
+             <secondary>global CellServDB</secondary>
+           </indexterm>
+ 
+           <indexterm>
+             <primary>CellServDB file maintained by AFS Product Support</primary>
+ 
+             <secondary>as global update source</secondary>
+           </indexterm>
+ 
+           <listitem>
+             <para>In the global <emphasis role="bold">CellServDB</emphasis> file maintained by the AFS Product Support group. This
+             file lists the name and database server machines of every cell that has agreed to make this information available to
+             other cells.</para>
+ 
+             <para>To add or change your cell's listing in this file, have the official support contact at your site call or write to
+             AFS Product Support. Changes to the file are frequent enough that AFS Product Support does not announce each one. It is
+             a good policy to check the file for changes on a regular schedule.</para>
+ 
+             <indexterm>
+               <primary>files</primary>
+ 
+               <secondary>CellServDB.local</secondary>
+             </indexterm>
+ 
+             <indexterm>
+               <primary>CellServDB.local file</primary>
+             </indexterm>
+           </listitem>
+ 
+           <listitem>
+             <para>A file called <emphasis role="bold">CellServDB.local</emphasis> in the <emphasis
+             role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/service/etc</emphasis> directory
+             of your cell's filespace. List only your cell's database server machines.</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <para>Update the files whenever you change the identity of your cell's database server machines. Also update the copies of the
+       <emphasis role="bold">CellServDB</emphasis> files on all of your server machines (in the <emphasis
+       role="bold">/usr/afs/etc</emphasis> directory) and client machines (in the <emphasis role="bold">/usr/vice/etc</emphasis>
+       directory). For instructions, see <link linkend="HDRWQ118">Maintaining the Server CellServDB File</link> and <link
+       linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link>.</para>
+ 
+       <para>Once you have advertised your database server machines, it can be difficult to make your cell invisible again. You can
+       remove the <emphasis role="bold">CellServDB.local</emphasis> file and ask AFS Product Support to remove your entry from the
+       global <emphasis role="bold">CellServDB</emphasis> file, but other cells probably have an entry for your cell in their local
+       <emphasis role="bold">CellServDB</emphasis> files already. To make those entries invalid, you must change the names or IP
+       addresses of your database server machines.</para>
+ 
+       <para>Your cell does not have to be invisible to be inaccessible, however. To make your cell completely inaccessible to
+       foreign users, remove the <emphasis role="bold">system:anyuser</emphasis> group from all ACLs at the top three levels of your
+       filespace; see <link linkend="HDRWQ40">Granting and Denying Foreign Users Access to Your Cell</link>.</para>
+ 
+       <indexterm>
+         <primary>cell</primary>
+ 
+         <secondary>making foreign visible to local</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>local cell</primary>
+ 
+         <secondary>making foreign cells visible in</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>foreign cell</primary>
+ 
+         <secondary>making visible in local cell</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>client machine</primary>
+ 
+         <secondary>making foreign cell visible</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ39">
+       <title>Making Other Cells Visible in Your Cell</title>
+ 
+       <para>To make a foreign cell's filespace visible on a client machine in your cell, perform the following three steps:
+       <orderedlist>
+           <listitem>
+             <para>Mount the cell's <emphasis role="bold">root.cell</emphasis> volume at the second level in your cell's filespace
+             just below the <emphasis role="bold">/afs</emphasis> directory. Use the <emphasis role="bold">fs mkmount</emphasis>
+             command with the <emphasis role="bold">-cell</emphasis> argument as instructed in <link linkend="HDRWQ213">To create a
+             cellular mount point</link>.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Mount AFS at the <emphasis role="bold">/afs</emphasis> directory on the client machine. The <emphasis
+             role="bold">afsd</emphasis> program, which initializes the Cache Manager, performs the mount automatically at the
+             directory named in the first field of the local <emphasis role="bold">/usr/vice/etc/cacheinfo</emphasis> file or by the
+             command's <emphasis role="bold">-mountdir</emphasis> argument. Mounting AFS at an alternate location makes it impossible
+             to reach the filespace of any cell that mounts its <emphasis role="bold">root.afs</emphasis> and <emphasis
+             role="bold">root.cell</emphasis> volumes at the conventional locations. See <link linkend="HDRWQ395">Displaying and
+             Setting the Cache Size and Location</link>.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Create an entry for the cell in the list of database server machines which the Cache Manager maintains in kernel
+             memory.</para>
+ 
+             <para>The <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on every client machine's local disk lists the
+             database server machines for the local and foreign cells. The <emphasis role="bold">afsd</emphasis> program reads the
+             contents of the <emphasis role="bold">CellServDB</emphasis> file into kernel memory as it initializes the Cache Manager.
+             You can also use the <emphasis role="bold">fs newcell</emphasis> command to add or alter entries in kernel memory
+             directly between reboots of the machine. See <link linkend="HDRWQ406">Maintaining Knowledge of Database Server
+             Machines</link>.</para>
+           </listitem>
+         </orderedlist></para>
+ 
+       <para>Note that making a foreign cell visible to client machines does not guarantee that your users can access its filespace.
+       The ACLs in the foreign cell must also grant them the necessary permissions.</para>
+ 
+       <indexterm>
+         <primary>cell</primary>
+ 
+         <secondary>granting local access to foreign users</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>local cell</primary>
+ 
+         <secondary>granting foreign users access to</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ40">
+       <title>Granting and Denying Foreign Users Access to Your Cell</title>
+ 
+       <para>Making your cell visible in the AFS global namespace does not take away your control over the way in which users from
+       foreign cells access your file tree.</para>
+ 
+       <para>By default, foreign users access your cell as the user <emphasis role="bold">anonymous</emphasis>, which means they have
+       only the permissions granted to the <emphasis role="bold">system:anyuser</emphasis> group on each directory's ACL. Normally
+       these permissions are limited to the <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) and
+       <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) permissions.</para>
+ 
+       <para>There are two ways to grant wider access to foreign users: <itemizedlist>
+           <listitem>
+             <para>Grant additional permissions to the <emphasis role="bold">system:anyuser</emphasis> group on certain ACLs. Keep in
+             mind, however, that all users can then access that directory in the indicated way (not just specific foreign users you
+             have in mind).</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Create a local authentication account for specific foreign users, by creating entries in the Protection and
+             Authentication Databases and local password file. It is not possible to place foreign usernames on ACLs, nor to
+             authenticate in a foreign cell without having an account in it.</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <indexterm>
+         <primary>cell</primary>
+ 
+         <secondary>filespace configuration issues</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>configuring</primary>
+ 
+         <secondary>filespace, issues</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>file tree</primary>
+ 
+         <secondary>conventions</secondary>
+ 
+         <tertiary>for configuring</tertiary>
+       </indexterm>
+     </sect2>
+   </sect1>
+ 
+   <sect1 id="HDRWQ41">
+     <title>Configuring Your AFS Filespace</title>
+ 
+     <para>This section summarizes the issues to consider when configuring your AFS filespace. For a discussion of creating volumes
+     that correspond most efficiently to the filespace's directory structure, see <link linkend="HDRWQ44">Creating Volumes to
+     Simplify Administration</link>.</para>
+ 
+     <note>
+       <para><emphasis role="bold">For Windows users:</emphasis> Windows uses a backslash (<emphasis role="bold">\</emphasis>) rather
+       than a forward slash (<emphasis role="bold">/</emphasis>) to separate the elements in a pathname. The hierarchical
+       organization of the filespace is however the same as on a UNIX machine.</para>
+     </note>
+ 
+     <para>AFS pathnames must follow a few conventions so the AFS global namespace looks the same from any AFS client machine. There
+     are corresponding conventions to follow in building your file tree, not just because pathnames reflect the structure of a file
+     tree, but also because the AFS Cache Manager expects a certain configuration.</para>
+ 
+     <indexterm>
+       <primary>AFS</primary>
+ 
+       <secondary>root directory (/afs)</secondary>
+ 
+       <tertiary>in cell filespace</tertiary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>directories</primary>
+ 
+       <secondary>/afs</secondary>
+     </indexterm>
+ 
+     <sect2 id="Header_51">
+       <title>The Top /afs Level</title>
+ 
+       <para>The first convention is that the top level in your file tree be called the <emphasis role="bold">/afs</emphasis>
+       directory. If you name it something else, then you must use the <emphasis role="bold">-mountdir</emphasis> argument with the
+       <emphasis role="bold">afsd</emphasis> program to get Cache Managers to mount AFS properly. You cannot participate in the AFS
+       global namespace in that case.</para>
+ 
+       <indexterm>
+         <primary>cell</primary>
+ 
+         <secondary>name</secondary>
+ 
+         <tertiary>at second level in file tree</tertiary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>directories</primary>
+ 
+         <secondary>/afs/<emphasis>cellname</emphasis></secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>symbolic link</primary>
+ 
+         <secondary>at second level of AFS pathname</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ42">
+       <title>The Second (Cellname) Level</title>
+ 
+       <para>The second convention is that just below the <emphasis role="bold">/afs</emphasis> directory you place directories
+       corresponding to each cell whose file tree is visible and accessible from the local cell. Minimally, there must be a directory
+       for the local cell. Each such directory is a mount point to the indicated cell's <emphasis role="bold">root.cell</emphasis>
+       volume. For example, in the ABC Corporation cell, <emphasis role="bold">/afs/abc.com</emphasis> is a mount point for the
+       cell's own <emphasis role="bold">root.cell</emphasis> volume and <emphasis role="bold">stateu.edu</emphasis> is a mount point
+       for the State University cell's <emphasis role="bold">root.cell</emphasis> volume. The <emphasis role="bold">fs
+       lsmount</emphasis> command displays the mount points.</para>
+ 
+       <programlisting>
+    % <emphasis role="bold">fs lsmount /afs/abc.com</emphasis> 
+    '/afs/abc.com' is a mount point for volume '#root.cell'
+    % <emphasis role="bold">fs lsmount /afs/stateu.edu</emphasis>
+    '/afs/stateu.edu' is a mount point for volume '#stateu.edu:root.cell'
+ </programlisting>
+ 
+       <para>To reduce the amount of typing necessary in pathnames, you can create a symbolic link with an abbreviated name to the
+       mount point of each cell your users frequently access (particularly the home cell). In the ABC Corporation cell, for instance,
+       <emphasis role="bold">/afs/abc</emphasis> is a symbolic link to the <emphasis role="bold">/afs/abc.com</emphasis> mount point,
+       as the <emphasis role="bold">fs lsmount</emphasis> command reveals.</para>
+ 
+       <programlisting>
+    % <emphasis role="bold">fs lsmount /afs/abc</emphasis>
+    '/afs/abc' is a symbolic link, leading to a mount point for volume '#root.cell'
+ </programlisting>
+ 
+       <indexterm>
+         <primary>file tree</primary>
+ 
+         <secondary>conventions</secondary>
+ 
+         <tertiary>third level</tertiary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>directories</primary>
+ 
+         <secondary>conventional under /afs/cellname</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ43">
+       <title>The Third Level</title>
+ 
+       <para>You can organize the third level of your cell's file tree any way you wish. The following list describes directories
+       that appear at this level in the conventional configuration: <variablelist>
+           <varlistentry>
+             <term><emphasis role="bold">common</emphasis></term>
+ 
+             <listitem>
+               <para>This directory contains programs and files needed by users working on machines of all system types, such as text
+               editors, online documentation files, and so on. Its <emphasis role="bold">/etc</emphasis> subdirectory is a logical
+               place to keep the central update sources for files used on all of your cell's client machines, such as the <emphasis
+               role="bold">ThisCell</emphasis> and <emphasis role="bold">CellServDB</emphasis> files.</para>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">public</emphasis></term>
+ 
+             <listitem>
+               <para>A directory accessible to anyone who can access your filespace, because its ACL grants the <emphasis
+               role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) and <emphasis role="bold">r</emphasis> (<emphasis
+               role="bold">read</emphasis>) permissions to the <emphasis role="bold">system:anyuser</emphasis> group. It is useful if
+               you want to enable your users to make selected information available to everyone, but do not want to grant foreign
+               users access to the contents of the <emphasis role="bold">usr</emphasis> directory which houses user home directories
+               (and is also at this level). It is conventional to create a subdirectory for each of your cell's users.</para>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">service</emphasis></term>
+ 
+             <listitem>
+               <para>This directory contains files and subdirectories that help cells coordinate resource sharing. For a list of the
+               proposed standard files and subdirectories to create, call or write to AFS Product Support.</para>
+ 
+               <para>As an example, files that other cells expect to find in this directory's <emphasis role="bold">etc</emphasis>
+               subdirectory can include the following: <itemizedlist>
+                   <listitem>
+                     <para><emphasis role="bold">CellServDB.export</emphasis>, a list of database server machines for many
+                     cells</para>
+                   </listitem>
+ 
+                   <listitem>
+                     <para><emphasis role="bold">CellServDB.local</emphasis>, a list of the cell's own database server
+                     machines</para>
+                   </listitem>
+ 
+                   <listitem>
+                     <para><emphasis role="bold">passwd</emphasis>, a copy of the local password file (<emphasis
+                     role="bold">/etc/passwd</emphasis> or equivalent) kept on the local disk of the cell's client machines</para>
+                   </listitem>
+ 
+                   <listitem>
+                     <para><emphasis role="bold">group</emphasis>, a copy of the local groups file (<emphasis
+                     role="bold">/etc/group</emphasis> or equivalent) kept on the local disk of the cell's client machines</para>
+                   </listitem>
+                 </itemizedlist></para>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis>sys_type</emphasis></term>
+ 
+             <listitem>
+               <para>A separate directory for storing the server and client binaries for each system type you use in the cell.
+               Configuration is simplest if you use the system type names assigned in the AFS distribution, particularly if you wish
+               to use the <emphasis role="bold">@sys</emphasis> variable in pathnames (see <link linkend="HDRWQ56">Using the @sys
+               Variable in Pathnames</link>). The <emphasis>OpenAFS Release Notes</emphasis> lists the conventional name for each
+               supported system type.</para>
+ 
+               <para>Within each such directory, create directories named <emphasis role="bold">bin</emphasis>, <emphasis
+               role="bold">etc</emphasis>, <emphasis role="bold">usr</emphasis>, and so on, to store the programs normally kept in
+               the <emphasis role="bold">/bin</emphasis>, <emphasis role="bold">/etc</emphasis> and <emphasis
+               role="bold">/usr</emphasis> directories on a local disk. Then create symbolic links from the local directories on
+               client machines into AFS; see <link linkend="HDRWQ55">Configuring the Local Disk</link>. Even if you do not choose to
+               use symbolic links in this way, it can be convenient to have central copies of system binaries in AFS. If binaries are
+               accidentally removed from a machine, you can recopy them onto the local disk from AFS rather than having to recover
+               them from tape</para>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">usr</emphasis></term>
+ 
+             <listitem>
+               <para>This directory contains home directories for your local users. As discussed in the previous entry for the
+               <emphasis role="bold">public</emphasis> directory, it is often practical to protect this directory so that only
+               locally authenticated users can access it. This keeps the contents of your user's home directories as secure as
+               possible.</para>
+ 
+               <para>If your cell is quite large, directory lookup can be slowed if you put all home directories in a single
+               <emphasis role="bold">usr</emphasis> directory. For suggestions on distributing user home directories among multiple
+               grouping directories, see <link linkend="HDRWQ59">Grouping Home Directories</link>.</para>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">wsadmin</emphasis></term>
+ 
+             <listitem>
+               <para>This directory contains prototype, configuration and library files for use with the <emphasis
+               role="bold">package</emphasis> program. See <link linkend="HDRWQ419">Configuring Client Machines with the package
+               Program</link>.</para>
+             </listitem>
+           </varlistentry>
+         </variablelist></para>
+ 
+       <indexterm>
+         <primary>volume name</primary>
+ 
+         <secondary>conventions for</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>conventions</primary>
+ 
+         <secondary>volume names</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>volume</primary>
+ 
+         <secondary>separate for each top level directory</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>file tree</primary>
+ 
+         <secondary>creating volumes to match top level directories</secondary>
+       </indexterm>
+     </sect2>
+   </sect1>
+ 
+   <sect1 id="HDRWQ44">
+     <title>Creating Volumes to Simplify Administration</title>
+ 
+     <para>This section discusses how to create volumes in ways that make administering your system easier.</para>
+ 
+     <para>At the top levels of your file tree (at least through the third level), each directory generally corresponds to a separate
+     volume. Some cells also configure the subdirectories of some third level directories as separate volumes. Common examples are
+     the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/common</emphasis> and
+     <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/usr</emphasis>
+     directories.</para>
+ 
+     <para>You do not have to create a separate volume for every directory level in a tree, but the advantage is that each volume
+     tends to be smaller and easier to move for load balancing. The overhead for a mount point is no greater than for a standard
+     directory, nor does the volume structure itself require much disk space. Most cells find that below the fourth level in the
+     tree, using a separate volume for each directory is no longer efficient. For instance, while each user's home directory (at the
+     fourth level in the tree) corresponds to a separate volume, all of the subdirectories in the home directory normally reside in
+     the same volume.</para>
+ 
+     <para>Keep in mind that only one volume can be mounted at a given directory location in the tree. In contrast, a volume can be
+     mounted at several locations, though this is not recommended because it distorts the hierarchical nature of the file tree,
+     potentially causing confusion.</para>
+ 
+     <indexterm>
+       <primary>volume name</primary>
+ 
+       <secondary>restrictions</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>restrictions</primary>
+ 
+       <secondary>on volume names</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>volume name</primary>
+ 
+       <secondary>two required</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>volume</primary>
+ 
+       <secondary>root (root.afs and root.cell)</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>root volumes (root.afs and root.cell)</primary>
+     </indexterm>
+ 
+     <sect2 id="Header_55">
+       <title>Assigning Volume Names</title>
+ 
+       <para>You can name your volumes anything you choose, subject to a few restrictions: <itemizedlist>
+           <listitem>
+             <para>Read/write volume names can be up to 22 characters in length. The maximum length for volume names is 31
+             characters, and there must be room to add the <emphasis role="bold">.readonly</emphasis> extension on read-only
+             volumes.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Do not add the <emphasis role="bold">.readonly</emphasis> and <emphasis role="bold">.backup</emphasis> extensions
+             to volume names yourself, even if they are appropriate. The Volume Server adds them automatically as it creates a
+             read-only or backup version of a volume.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>There must be volumes named <emphasis role="bold">root.afs</emphasis> and <emphasis
+             role="bold">root.cell</emphasis>, mounted respectively at the top (<emphasis role="bold">/afs</emphasis>) level in the
+             filespace and just below that level, at the cell's name (for example, at <emphasis role="bold">/afs/abc.com</emphasis>
+             in the ABC Corporation cell).</para>
+ 
+             <para>Deviating from these names only creates confusion and extra work. Changing the name of the <emphasis
+             role="bold">root.afs</emphasis> volume, for instance, means that you must use the <emphasis
+             role="bold">-rootvol</emphasis> argument to the <emphasis role="bold">afsd</emphasis> program on every client machine,
+             to name the alternate volume.</para>
+ 
+             <para>Similarly, changing the <emphasis role="bold">root.cell</emphasis> volume name prevents users in foreign cells
+             from accessing your filespace, if the mount point for your cell in their filespace refers to the conventional <emphasis
+             role="bold">root.cell</emphasis> name. Of course, this is one way to make your cell invisible to other cells.</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <para>It is best to assign volume names that indicate the type of data they contain, and to use similar names for volumes with
+       similar contents. It is also helpful if the volume name is similar to (or at least has elements in common with) the name of
+       the directory at which it is mounted. Understanding the pattern then enables you accurately to guess what a volume contains
+       and where it is mounted.</para>
+ 
+       <para>Many cells find that the most effective volume naming scheme puts a common prefix on the names of all related volumes.
+       <link linkend="TBLVOL-PREFIX">Table 1</link> describes the recommended prefixing scheme.</para>
+ 
+       <table id="TBLVOL-PREFIX" label="1">
+         <title>Suggested volume prefixes</title>
+ 
+         <tgroup cols="4">
+           <colspec colwidth="14*" />
+ 
+           <colspec colwidth="28*" />
+ 
+           <colspec colwidth="22*" />
+ 
+           <colspec colwidth="36*" />
+ 
+           <thead>
+             <row>
+               <entry><emphasis role="bold">Prefix</emphasis></entry>
+ 
+               <entry><emphasis role="bold">Contents</emphasis></entry>
+ 
+               <entry><emphasis role="bold">Example Name</emphasis></entry>
+ 
+               <entry><emphasis role="bold">Example Mount Point</emphasis></entry>
+             </row>
+           </thead>
+ 
+           <tbody>
+             <row>
+               <entry><emphasis role="bold">common.</emphasis></entry>
+ 
+               <entry>popular programs and files</entry>
+ 
+               <entry><emphasis role="bold">common.etc</emphasis></entry>
+ 
+               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+               role="bold">/common/etc</emphasis></entry>
+             </row>
+ 
+             <row>
+               <entry><emphasis role="bold">src.</emphasis></entry>
+ 
+               <entry>source code</entry>
+ 
+               <entry><emphasis role="bold">src.afs</emphasis></entry>
+ 
+               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+               role="bold">/src/afs</emphasis></entry>
+             </row>
+ 
+             <row>
+               <entry><emphasis role="bold">proj.</emphasis></entry>
+ 
+               <entry>project data</entry>
+ 
+               <entry><emphasis role="bold">proj.portafs</emphasis></entry>
+ 
+               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+               role="bold">/proj/portafs</emphasis></entry>
+             </row>
+ 
+             <row>
+               <entry><emphasis role="bold">test.</emphasis></entry>
+ 
+               <entry>testing or other temporary data</entry>
+ 
+               <entry><emphasis role="bold">test.smith</emphasis></entry>
+ 
+               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+               role="bold">/usr/smith/test</emphasis></entry>
+             </row>
+ 
+             <row>
+               <entry><emphasis role="bold">user.</emphasis></entry>
+ 
+               <entry>user home directory data</entry>
+ 
+               <entry><emphasis role="bold">user.terry</emphasis></entry>
+ 
+               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+               role="bold">/usr/terry</emphasis></entry>
+             </row>
+ 
+             <row>
+               <entry>sys_type<emphasis role="bold">.</emphasis></entry>
+ 
+               <entry>programs compiled for an operating system type</entry>
+ 
+               <entry><emphasis role="bold">rs_aix42.bin</emphasis></entry>
+ 
+               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+               role="bold">/rs_aix42/bin</emphasis></entry>
+             </row>
+           </tbody>
+         </tgroup>
+       </table>
+ 
+       <para><link linkend="TBLPREFIX-EXAMPLE">Table 2</link> is a more specific example for a cell's <emphasis
+       role="bold">rs_aix42</emphasis> system volumes and directories:</para>
+ 
+       <table id="TBLPREFIX-EXAMPLE" label="2">
+         <title>Example volume-prefixing scheme</title>
+ 
+         <tgroup cols="2">
+           <colspec colwidth="14*" />
+ 
+           <colspec colwidth="28*" />
+ 
+           <colspec colwidth="22*" />
+ 
+           <colspec colwidth="36*" />
+ 
+           <thead>
+             <row>
+               <entry><emphasis role="bold">Example Name</emphasis></entry>
+ 
+               <entry><emphasis role="bold">Example Mount Point</emphasis></entry>
+             </row>
+           </thead>
+ 
+           <tbody>
+             <row>
+               <entry><emphasis role="bold">rs_aix42.bin</emphasis></entry>
+ 
+               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+               role="bold">/rs_aix42/bin</emphasis>, <emphasis
+               role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/rs_aix42/bin</emphasis></entry>
+             </row>
+ 
+             <row>
+               <entry><emphasis role="bold">rs_aix42.etc</emphasis></entry>
+ 
+               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+               role="bold">/rs_aix42/etc</emphasis></entry>
+             </row>
+ 
+             <row>
+               <entry><emphasis role="bold">rs_aix42.usr</emphasis></entry>
+ 
+               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+               role="bold">/rs_aix42/usr</emphasis></entry>
+             </row>
+ 
+             <row>
+               <entry><emphasis role="bold">rs_aix42.usr.afsws</emphasis></entry>
+ 
+               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+               role="bold">/rs_aix42/usr/afsws</emphasis></entry>
+             </row>
+ 
+             <row>
+               <entry><emphasis role="bold">rs_aix42.usr.lib</emphasis></entry>
+ 
+               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+               role="bold">/rs_aix42/usr/lib</emphasis></entry>
+             </row>
+ 
+             <row>
+               <entry><emphasis role="bold">rs_aix42.usr.bin</emphasis></entry>
+ 
+               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+               role="bold">/rs_aix42/usr/bin</emphasis></entry>
+             </row>
+ 
+             <row>
+               <entry><emphasis role="bold">rs_aix42.usr.etc</emphasis></entry>
+ 
+               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+               role="bold">/rs_aix42/usr/etc</emphasis></entry>
+             </row>
+ 
+             <row>
+               <entry><emphasis role="bold">rs_aix42.usr.inc</emphasis></entry>
+ 
+               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+               role="bold">/rs_aix42/usr/inc</emphasis></entry>
+             </row>
+ 
+             <row>
+               <entry><emphasis role="bold">rs_aix42.usr.man</emphasis></entry>
+ 
+               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+               role="bold">/rs_aix42/usr/man</emphasis></entry>
+             </row>
+ 
+             <row>
+               <entry><emphasis role="bold">rs_aix42.usr.sys</emphasis></entry>
+ 
+               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+               role="bold">/rs_aix42/usr/sys</emphasis></entry>
+             </row>
+ 
+             <row>
+               <entry><emphasis role="bold">rs_aix42.usr.local</emphasis></entry>
+ 
+               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+               role="bold">/rs_aix42/usr/local</emphasis></entry>
+             </row>
+           </tbody>
+         </tgroup>
+       </table>
+ 
+       <para>There are several advantages to this scheme: <itemizedlist>
+           <listitem>
+             <para>The volume name is similar to the mount point name in the filespace. In all of the entries in <link
+             linkend="TBLPREFIX-EXAMPLE">Table 2</link>, for example, the only difference between the volume and mount point name is
+             that the former uses periods as separators and the latter uses slashes. Another advantage is that the volume name
+             indicates the contents, or at least suggests the directory on which to issue the <emphasis role="bold">ls</emphasis>
+             command to learn the contents.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>It makes it easy to manipulate groups of related volumes at one time. In particular, the <emphasis role="bold">vos
+             backupsys</emphasis> command's <emphasis role="bold">-prefix</emphasis> argument enables you to create a backup version
+             of every volume whose name starts with the same string of characters. Making a backup version of each volume is one of
+             the first steps in backing up a volume with the AFS Backup System, and doing it for many volumes with one command saves
+             you a good deal of typing. For instructions for creating backup volumes, see <link linkend="HDRWQ201">Creating Backup
+             Volumes</link>, For information on the AFS Backup System, see <link linkend="HDRWQ248">Configuring the AFS Backup
+             System</link> and <link linkend="HDRWQ283">Backing Up and Restoring AFS Data</link>.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>It makes it easy to group related volumes together on a partition. Grouping related volumes together has several
+             advantages of its own, discussed in <link linkend="HDRWQ49">Grouping Related Volumes on a Partition</link>.</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <indexterm>
+         <primary>volume</primary>
+ 
+         <secondary>grouping related on same partition</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>disk partition</primary>
+ 
+         <secondary>grouping related volumes on</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ49">
+       <title>Grouping Related Volumes on a Partition</title>
+ 
+       <para>If your cell is large enough to make it practical, consider grouping related volumes together on a partition. In
+       general, you need at least three file server machines for volume grouping to be effective. Grouping has several advantages,
+       which are most obvious when the file server machine becomes inaccessible: <itemizedlist>
+           <listitem>
+             <para>If you keep a hardcopy record of the volumes on a partition, you know which volumes are unavailable. You can keep
+             such a record without grouping related volumes, but a list composed of unrelated volumes is much harder to maintain.
+             Note that the record must be on paper, because the outage can prevent you from accessing an online copy or from issuing
+             the <emphasis role="bold">vos listvol</emphasis> command, which gives you the same information.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The effect of an outage is more localized. For example, if all of the binaries for a given system type are on one
+             partition, then only users of that system type are affected. If a partition houses binary volumes from several system
+             types, then an outage can affect more people, particularly if the binaries that remain available are interdependent with
+             those that are not available.</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <para>The advantages of grouping related volumes on a partition do not necessarily extend to the grouping of all related
+       volumes on one file server machine. For instance, it is probably unwise in a cell with two file server machines to put all
+       system volumes on one machine and all user volumes on the other. An outage of either machine probably affects everyone.</para>
+ 
+       <para>Admittedly, the need to move volumes for load balancing purposes can limit the practicality of grouping related volumes.
+       You need to weigh the complementary advantages case by case.</para>
+ 
+       <indexterm>
+         <primary>replication</primary>
+ 
+         <secondary>appropriate volumes</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>volume</primary>
+ 
+         <secondary>type to replicate</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>volume</primary>
+ 
+         <secondary>where to place replicated</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>read-only volume</primary>
+ 
+         <secondary>selecting site</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ50">
+       <title>When to Replicate Volumes</title>
+ 
+       <para>As discussed in <link linkend="HDRWQ15">Replication</link>, replication refers to making a copy, or clone, of a
+       read/write source volume and then placing the copy on one or more additional file server machines. Replicating a volume can
+       increase the availability of the contents. If one file server machine housing the volume becomes inaccessible, users can still
+       access the copy of the volume stored on a different machine. No one machine is likely to become overburdened with requests for
+       a popular file, either, because the file is available from several machines.</para>
+ 
+       <para>However, replication is not appropriate for all cells. If a cell does not have much disk space, replication can be
+       unduly expensive, because each clone not on the same partition as the read/write source takes up as much disk space as its
+       source volume did at the time the clone was made. Also, if you have only one file server machine, replication uses up disk
+       space without increasing availability.</para>
+ 
+       <para>Replication is also not appropriate for volumes that change frequently. You must issue the <emphasis role="bold">vos
+       release</emphasis> command every time you need to update a read-only volume to reflect changes in its read/write
+       source.</para>
+ 
+       <para>For both of these reasons, replication is appropriate only for popular volumes whose contents do not change very often,
+       such as system binaries and other volumes mounted at the upper levels of your filespace. User volumes usually exist only in a
+       read/write version since they change so often.</para>
+ 
+       <para>If you are replicating any volumes, you must replicate the <emphasis role="bold">root.afs</emphasis> and <emphasis
+       role="bold">root.cell</emphasis> volumes, preferably at two or three sites each (even if your cell only has two or three file
+       server machines). The Cache Manager needs to pass through the directories corresponding to the <emphasis
+       role="bold">root.afs</emphasis> and <emphasis role="bold">root.cell</emphasis> volumes as it interprets any pathname. The
+       unavailability of these volumes makes all other volumes unavailable too, even if the file server machines storing the other
+       volumes are still functioning.</para>
+ 
+       <para>Another reason to replicate the <emphasis role="bold">root.afs</emphasis> volume is that it can lessen the load on the
+       File Server machine. The Cache Manager has a bias to access a read-only version of the <emphasis
+       role="bold">root.afs</emphasis> volume if it is replicate, which puts the Cache Manager onto the <emphasis>read-only
+       path</emphasis> through the AFS filespace. While on the read-only path, the Cache Manager attempts to access a read-only copy
+       of replicated volumes. The File Server needs to track only one callback per Cache Manager for all of the data in a read-only
+       volume, rather than the one callback per file it must track for read/write volumes. Fewer callbacks translate into a smaller
+       load on the File Server.</para>
+ 
+       <para>If the <emphasis role="bold">root.afs</emphasis> volume is not replicated, the Cache Manager follows a read/write path
+       through the filespace, accessing the read/write version of each volume. The File Server distributes and tracks a separate
+       callback for each file in a read/write volume, imposing a greater load on it.</para>
+ 
+       <para>For more on read/write and read-only paths, see <link linkend="HDRWQ209">The Rules of Mount Point
+       Traversal</link>.</para>
+ 
+       <para>It also makes sense to replicate system binary volumes in many cases, as well as the volume corresponding to the
+       <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/usr</emphasis> directory and
+       the volumes corresponding to the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+       role="bold">/common</emphasis> directory and its subdirectories.</para>
+ 
+       <para>It is a good idea to place a replica on the same partition as the read/write source. In this case, the read-only volume
+       is a clone (like a backup volume): it is a copy of the source volume's vnode index, rather than a full copy of the volume
+       contents. Only if the read/write volume moves to another partition or changes substantially does the read-only volume consume
+       significant disk space. Read-only volumes kept on other partitions always consume the full amount of disk space that the
+       read/write source consumed when the read-only volume was created.</para>
+     </sect2>
+ 
+     <sect2 id="Header_58">
+       <title>The Default Quota and ACL on a New Volume</title>
+ 
+       <para>Every AFS volume has associated with it a quota that limits the amount of disk space the volume is allowed to use. To
+       set and change quota, use the commands described in <link linkend="HDRWQ234">Setting and Displaying Volume Quota and Current
+       Size</link>.</para>
+ 
+       <para>By default, every new volume is assigned a space quota of 5000 KB blocks unless you include the <emphasis
+       role="bold">-maxquota</emphasis> argument to the <emphasis role="bold">vos create</emphasis> command. Also by default, the ACL
+       on the root directory of every new volume grants all permissions to the members of the <emphasis
+       role="bold">system:administrators</emphasis> group. To learn how to change these values when creating an account with
+       individual commands, see <link linkend="HDRWQ503">To create one user account with individual commands</link>. When using
+       <emphasis role="bold">uss</emphasis> commands to create accounts, you can specify alternate ACL and quota values in the
+       template file's <emphasis role="bold">V</emphasis> instruction; see <link linkend="HDRWQ473">Creating a Volume with the V
+       Instruction</link>.</para>
+ 
+       <indexterm>
+         <primary>server machine</primary>
+ 
+         <secondary>configuration issues</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>configuring</primary>
+ 
+         <secondary>file server machine, issues</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>roles for server machine</primary>
+ 
+         <secondary>summary</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>server machine</primary>
+ 
+         <secondary>roles for</secondary>
+ 
+         <tertiary>summary</tertiary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>server machine</primary>
+ 
+         <secondary>first installed</secondary>
+       </indexterm>
+     </sect2>
+   </sect1>
+ 
+   <sect1 id="HDRWQ51">
+     <title>Configuring Server Machines</title>
+ 
+     <para>This section discusses some issues to consider when configuring server machines, which store AFS data, transfer it to
+     client machines on request, and house the AFS administrative databases. To learn about client machines, see <link
+     linkend="HDRWQ54">Configuring Client Machines</link>.</para>
+ 
+     <para>If your cell has more than one AFS server machine, you can configure them to perform specialized functions. A machine can
+     assume one or more of the roles described in the following list. For more details, see <link linkend="HDRWQ90">The Four Roles
+     for File Server Machines</link>. <itemizedlist>
+         <listitem>
+           <para>A <emphasis>simple file server</emphasis> machine runs only the processes that store and deliver AFS files to client
+           machines. You can run as many simple file server machines as you need to satisfy your cell's performance and disk space
+           requirements.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>A <emphasis>database server machine</emphasis> runs the four database server processes that maintain AFS's
+           replicated administrative databases: the Authentication, Backup, Protection, and Volume Location (VL) Server
+           processes.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>A <emphasis>binary distribution machine</emphasis> distributes the AFS server binaries for its system type to all
+           other server machines of that system type.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>The single <emphasis>system control machine</emphasis> distributes common server configuration files to all other
+           server machines in the cell, in a cell that runs the United States edition of AFS (cells that use the international
+           edition of AFS must not use the system control machine for this purpose). The machine conventionally also serves as the
+           time synchronization source for the cell, adjusting its clock according to a time source outside the cell.</para>
+         </listitem>
+       </itemizedlist></para>
+ 
+     <para>The <emphasis>OpenAFS Quick Beginnings</emphasis> explains how to configure your cell's first file server machine to
+     assume all four roles. The <emphasis>OpenAFS Quick Beginnings</emphasis> chapter on installing additional server machines also
+     explains how to configure them to perform one or more roles.</para>
+ 
+     <indexterm>
+       <primary>database server machine</primary>
+ 
+       <secondary>reason to run three</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>distribution</primary>
+ 
+       <secondary>of databases</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>databases, distributed</primary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>distributed databases</primary>
+     </indexterm>
+ 
+     <sect2 id="HDRWQ52">
+       <title>Replicating the OpenAFS Administrative Databases</title>
+ 
+       <para>The AFS administrative databases are housed on database server machines and store information that is crucial for
+       correct cell functioning. Both server processes and Cache Managers access the information frequently: <itemizedlist>
+           <listitem>
+             <para>Every time a Cache Manager fetches a file from a directory that it has not previously accessed, it must look up
+             the file's location in the Volume Location Database (VLDB).</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Every time a user obtains an AFS token from the Authentication Server, the server looks up the user's password in
+             the Authentication Database.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The first time that a user accesses a volume housed on a specific file server machine, the File Server contacts
+             the Protection Server for a list of the user's group memberships as recorded in the Protection Database.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Every time you back up a volume using the AFS Backup System, the Backup Server creates records for it in the
+             Backup Database.</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <para>Maintaining your cell is simplest if the first machine has the lowest IP address of any machine you plan to use as a
+       database server machine. If you later decide to use a machine with a lower IP address as a database server machine, you must
+       update the <emphasis role="bold">CellServDB</emphasis> file on all clients before introducing the new machine.</para>
+ 
+       <para>If your cell has more than one server machine, it is best to run more than one as a database server machine (but more
+       than three are rarely necessary). Replicating the administrative databases in this way yields the same benefits as replicating
+       volumes: increased availability and reliability. If one database server machine or process stops functioning, the information
+       in the database is still available from others. The load of requests for database information is spread across multiple
+       machines, preventing any one from becoming overloaded.</para>
+ 
+       <para>Unlike replicated volumes, however, replicated databases do change frequently. Consistent system performance demands
+       that all copies of the database always be identical, so it is not acceptable to record changes in only some of them. To
+       synchronize the copies of a database, the database server processes use AFS's distributed database technology, Ubik. See <link
+       linkend="HDRWQ102">Replicating the OpenAFS Administrative Databases</link>.</para>
+ 
+       <para>If your cell has only one file server machine, it must also serve as a database server machine. If you cell has two file
+       server machines, it is not always advantageous to run both as database server machines. If a server, process, or network
+       failure interrupts communications between the database server processes on the two machines, it can become impossible to
+       update the information in the database because neither of them can alone elect itself as the synchronization site.</para>
+ 
+       <indexterm>
+         <primary>server machine</primary>
+ 
+         <secondary>protecting directories on local disk</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>local disk</primary>
+ 
+         <secondary>protecting on file server machine</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ53">
+       <title>AFS Files on the Local Disk</title>
+ 
+       <para>It is generally simplest to store the binaries for all AFS server processes in the <emphasis
+       role="bold">/usr/afs/bin</emphasis> directory on every file server machine, even if some processes do not actively run on the
+       machine. This makes it easier to reconfigure a machine to fill a new role.</para>
+ 
+       <para>For security reasons, the <emphasis role="bold">/usr/afs</emphasis> directory on a file server machine and all of its
+       subdirectories and files must be owned by the local superuser <emphasis role="bold">root</emphasis> and have only the first
+       <emphasis role="bold">w</emphasis> (<emphasis role="bold">write</emphasis>) mode bit turned on. Some files even have only the
+       first <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) mode bit turned on (for example, the
+       <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> file, which lists the AFS server encryption keys). Each time the BOS
+       Server starts, it checks that the mode bits on certain files and directories match the expected values. For a list, see the
+       <emphasis>OpenAFS Quick Beginnings</emphasis> section about protecting sensitive AFS directories, or the discussion of the
+       output from the <emphasis role="bold">bos status</emphasis> command in <link linkend="HDRWQ159">To display the status of
+       server processes and their BosConfig entries</link>.</para>
+ 
+       <para>For a description of the contents of all AFS directories on a file server machine's local disk, see <link
+       linkend="HDRWQ80">Administering Server Machines</link>.</para>
+     </sect2>
+ 
+     <sect2 id="Header_62">
+       <title>Configuring Partitions to Store AFS Data</title>
+ 
+       <para>The partitions that house AFS volumes on a file server machine must be mounted at directories named</para>
+ 
+       <para><emphasis role="bold">/vicep</emphasis><emphasis>index</emphasis></para>
+ 
+       <para>where <emphasis>index</emphasis> is one or two lowercase letters. By convention, the first AFS partition created is
+       mounted at the <emphasis role="bold">/vicepa</emphasis> directory, the second at the <emphasis role="bold">/vicepb</emphasis>
+       directory, and so on through the <emphasis role="bold">/vicepz</emphasis> directory. The names then continue with <emphasis
+       role="bold">/vicepaa</emphasis> through <emphasis role="bold">/vicepaz</emphasis>, <emphasis role="bold">/vicepba</emphasis>
+       through <emphasis role="bold">/vicepbz</emphasis>, and so on, up to the maximum supported number of server partitions, which
+       is specified in the OpenAFS Release Notes.</para>
+ 
+       <para>Each <emphasis role="bold">/vicep</emphasis>x directory must correspond to an entire partition or logical volume, and
+       must be a subdirectory of the root directory (/). It is not acceptable to configure part of (for example) the <emphasis
+       role="bold">/usr</emphasis> partition as an AFS server partition and mount it on a directory called <emphasis
+       role="bold">/usr/vicepa</emphasis>.</para>
+ 
+       <para>Also, do not store non-AFS files on AFS server partitions. The File Server and Volume Server expect to have available
+       all of the space on the partition. Sharing space also creates competition between AFS and the local UNIX file system for
+       access to the partition, particularly if the UNIX files are frequently used.</para>
+ 
+       <indexterm>
+         <primary>server machine</primary>
+ 
+         <secondary>monitoring</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>file server machine</primary>
+ 
+         <secondary>rebooting, about</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>rebooting</primary>
+ 
+         <secondary>file server machine, limiting</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>weekly restart of BOS Server (automatic)</primary>
+ 
+         <secondary>about</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>restart times for BOS Server</primary>
+ 
+         <secondary>about</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="Header_63">
+       <title>Monitoring, Rebooting and Automatic Process Restarts</title>
+ 
+       <para>AFS provides several tools for monitoring the File Server, including the <emphasis role="bold">scout</emphasis> and
+       <emphasis role="bold">afsmonitor</emphasis> programs. You can configure them to alert you when certain threshold values are
+       exceeded, for example when a server partition is more than 95% full. See <link linkend="HDRWQ323">Monitoring and Auditing AFS
+       Performance</link>.</para>
+ 
+       <para>Rebooting a file server machine requires shutting down the AFS processes and so inevitably causes a service outage.
+       Reboot file server machines as infrequently as possible. For instructions, see <link linkend="HDRWQ139">Rebooting a Server
+       Machine</link>.</para>
+ 
+       <para>By default, the BOS Server on each file server machine stops and immediately restarts all AFS server processes on the
+       machine (including itself) once a week, at 4:00 a.m. on Sunday. This reduces the potential for the core leaks that can develop
+       as any process runs for an extended time.</para>
+ 
+       <para>The BOS Server also checks each morning at 5:00 a.m. for any newly installed binary files in the <emphasis
+       role="bold">/usr/afs/bin</emphasis> directory. It compares the timestamp on each binary file to the time at which the
+       corresponding process last restarted. If the timestamp on the binary is later, the BOS Server restarts the corresponding
+       process to start using it.</para>
+ 
+       <para>The default times are in the early morning hours when the outage that results from restarting a process is likely to
+       disturb the fewest number of people. You can display the restart times for each machine with the <emphasis role="bold">bos
+       getrestart</emphasis> command, and set them with the <emphasis role="bold">bos setrestart</emphasis> command. The latter
+       command enables you to disable automatic restarts entirely, by setting the time to <emphasis role="bold">never</emphasis>. See
+       <link linkend="HDRWQ171">Setting the BOS Server's Restart Times</link>.</para>
+ 
+       <indexterm>
+         <primary>client machine</primary>
+ 
+         <secondary>configuration issues</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>configuring</primary>
+ 
+         <secondary>client machine, issues</secondary>
+       </indexterm>
+     </sect2>
+   </sect1>
+ 
+   <sect1 id="HDRWQ54">
+     <title>Configuring Client Machines</title>
+ 
+     <para>This section summarizes issues to consider as you install and configure client machines in your cell.</para>
+ 
+     <indexterm>
+       <primary>client machine</primary>
+ 
+       <secondary>files required on local disk</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>local disk</primary>
+ 
+       <secondary>files required on client machine</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>file</primary>
+ 
+       <secondary>required on client machine local disk</secondary>
+     </indexterm>
+ 
+     <sect2 id="HDRWQ55">
+       <title>Configuring the Local Disk</title>
+ 
+       <para>You can often free up significant amounts of local disk space on AFS client machines by storing standard UNIX files in
+       AFS and creating symbolic links to them from the local disk. The <emphasis role="bold">@sys</emphasis> pathname variable can
+       be useful in links to system-specific files; see <link linkend="HDRWQ56">Using the @sys Variable in Pathnames</link>.</para>
+ 
+       <para>There are two types of files that must actually reside on the local disk: boot sequence files needed before the
+       <emphasis role="bold">afsd</emphasis> program is invoked, and files that can be helpful during file server machine
+       outages.</para>
+ 
+       <para>During a reboot, AFS is inaccessible until the <emphasis role="bold">afsd</emphasis> program executes and initializes
+       the Cache Manager. (In the conventional configuration, the AFS initialization file is included in the machine's initialization
+       sequence and invokes the <emphasis role="bold">afsd</emphasis> program.) Files needed during reboot prior to that point must
+       reside on the local disk. They include the following, but this list is not necessarily exhaustive. <itemizedlist>
+           <listitem>
+             <para>Standard UNIX utilities including the following or their equivalents: <itemizedlist>
+                 <listitem>
+                   <para>Machine initialization files (stored in the <emphasis role="bold">/etc</emphasis> or <emphasis
+                   role="bold">/sbin</emphasis> directory on many system types)</para>
+                 </listitem>
+ 
+                 <listitem>
+                   <para>The <emphasis role="bold">fstab</emphasis> file</para>
+                 </listitem>
+ 
+                 <listitem>
+                   <para>The <emphasis role="bold">mount</emphasis> command binary</para>
+                 </listitem>
+ 
+                 <listitem>
+                   <para>The <emphasis role="bold">umount</emphasis> command binary</para>
+                 </listitem>
+               </itemizedlist></para>
+           </listitem>
+ 
+           <listitem>
+             <para>All subdirectories and files in the <emphasis role="bold">/usr/vice</emphasis> directory, including the following:
+             <itemizedlist>
+                 <listitem>
+                   <para>The <emphasis role="bold">/usr/vice/cache</emphasis> directory</para>
+                 </listitem>
+ 
+                 <listitem>
+                   <para>The <emphasis role="bold">/usr/vice/etc/afsd</emphasis> command binary</para>
+                 </listitem>
+ 
+                 <listitem>
+                   <para>The <emphasis role="bold">/usr/vice/etc/cacheinfo</emphasis> file</para>
+                 </listitem>
+ 
+                 <listitem>
+                   <para>The <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file</para>
+                 </listitem>
+ 
+                 <listitem>
+                   <para>The <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> file</para>
+                 </listitem>
+               </itemizedlist></para>
+ 
+             <para>For more information on these files, see <link linkend="HDRWQ391">Configuration and Cache-Related Files on the
+             Local Disk</link>.</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <para>The other type of files and programs to retain on the local disk are those you need when diagnosing and fixing problems
+       caused by a file server outage, because the outage can make inaccessible the copies stored in AFS. Examples include the
+       binaries for a text editor (such as <emphasis role="bold">ed</emphasis> or <emphasis role="bold">vi</emphasis>) and for the
+       <emphasis role="bold">fs</emphasis> and <emphasis role="bold">bos</emphasis> commands. Store copies of AFS command binaries in
+       the <emphasis role="bold">/usr/vice/etc</emphasis> directory as well as including them in the <emphasis
+       role="bold">/usr/afsws</emphasis> directory, which is normally a link into AFS. Then place the <emphasis
+       role="bold">/usr/afsws</emphasis> directory before the <emphasis role="bold">/usr/vice/etc</emphasis> directory in users'
+       <envar>PATH</envar> environment variable definition. When AFS is functioning normally, users access the copy in the <emphasis
+       role="bold">/usr/afsws</emphasis> directory, which is more likely to be current than a local copy.</para>
+ 
+       <para>You can automate the configuration of client machine local disks by using the <emphasis role="bold">package</emphasis>
+       program, which updates the contents of the local disk to match a configuration file. See <link linkend="HDRWQ419">Configuring
+       Client Machines with the package Program</link>.</para>
+     </sect2>
+ 
+     <sect2 id="Header_66">
+       <title>Enabling Access to Foreign Cells</title>
+ 
+       <indexterm>
+         <primary>client machine</primary>
+ 
+         <secondary>enabling access to foreign cell</secondary>
+       </indexterm>
+ 
+       <para>As detailed in <link linkend="HDRWQ39">Making Other Cells Visible in Your Cell</link>, you enable the Cache Manager to
+       access a cell's AFS filespace by storing a list of the cell's database server machines in the local <emphasis
+       role="bold">/usr/vice/etc/CellServDB</emphasis> file. The Cache Manager reads the list into kernel memory at reboot for faster
+       retrieval. You can change the list in kernel memory between reboots by using the <emphasis role="bold">fs newcell</emphasis>
+       command. It is often practical to store a central version of the <emphasis role="bold">CellServDB</emphasis> file in AFS and
+       use the <emphasis role="bold">package</emphasis> program periodically to update each client's version with the source copy.
+       See <link linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link>.</para>
+ 
+       <para>Because each client machine maintains its own copy of the <emphasis role="bold">CellServDB</emphasis> file, you can in
+       theory enable access to different foreign cells on different client machines. This is not usually practical, however,
+       especially if users do not always work on the same machine.</para>
+ 
+       <indexterm>
+         <primary>at-sys (@sys) variable in pathnames</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>sys (@sys) variable in pathnames</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>variables</primary>
+ 
+         <secondary>@sys in pathnames</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ56">
+       <title>Using the @sys Variable in Pathnames</title>
+ 
+       <para>When creating symbolic links into AFS on the local disk, it is often practical to use the @sys variable in pathnames.
+       The Cache Manager automatically substitutes the local machine's AFS system name (CPU/operating system type) for the @sys
+       variable. This means you can place the same links on machines of various system types and still have each machine access the
+       binaries for its system type. For example, the Cache Manager on a machine running AIX 4.2 converts <emphasis
+       role="bold">/afs/abc.com/@sys</emphasis> to <emphasis role="bold">/afs/abc.com/rs_aix42</emphasis>, whereas a machine running
+       Solaris 7 converts it to <emphasis role="bold">/afs/abc.com/sun4x_57</emphasis>.</para>
+ 
+       <para>If you want to use the @sys variable, it is simplest to use the conventional AFS system type names as specified in the
+       OpenAFS Release Notes. The Cache Manager records the local machine's system type name in kernel memory during initialization.
+       If you do not use the conventional names, you must use the <emphasis role="bold">fs sysname</emphasis> command to change the
+       value in kernel memory from its default just after Cache Manager initialization, on every client machine of the relevant
+       system type. The <emphasis role="bold">fs sysname</emphasis> command also displays the current value; see <link
+       linkend="HDRWQ417">Displaying and Setting the System Type Name</link>.</para>
+ 
+       <para>In pathnames in the AFS filespace itself, use the @sys variable carefully and sparingly, because it can lead to
+       unexpected results. It is generally best to restrict its use to only one level in the filespace. The third level is a common
+       choice, because that is where many cells store the binaries for different machine types.</para>
+ 
+       <para>Multiple instances of the @sys variable in a pathname are especially dangerous to people who must explicitly change
+       directories (with the <emphasis role="bold">cd</emphasis> command, for example) into directories that store binaries for
+       system types other than the machine on which they are working, such as administrators or developers who maintain those
+       directories. After changing directories, it is recommended that such people verify they are in the desired directory.</para>
+     </sect2>
+ 
+     <sect2 id="Header_68">
+       <title>Setting Server Preferences</title>
+ 
+       <para>The Cache Manager stores a table of preferences for file server machines in kernel memory. A preference rank pairs a
+       file server machine interface's IP address with an integer in the range from 1 to 65,534. When it needs to access a file, the
+       Cache Manager compares the ranks for the interfaces of all machines that house the file, and first attempts to access the file
+       via the interface with the best rank. As it initializes, the Cache Manager sets default ranks that bias it to access files via
+       interfaces that are close to it in terms of network topology. You can adjust the preference ranks to improve performance if
+       you wish.</para>
+ 
+       <para>The Cache Manager also uses similar preferences for Volume Location (VL) Server machines. Use the <emphasis
+       role="bold">fs getserverprefs</emphasis> command to display preference ranks and the <emphasis role="bold">fs
+       setserverprefs</emphasis> command to set them. See <link linkend="HDRWQ414">Maintaining Server Preference Ranks</link>.</para>
+ 
+       <indexterm>
+         <primary>user account</primary>
+ 
+         <secondary>configuration issues</secondary>
+       </indexterm>
+     </sect2>
+   </sect1>
+ 
+   <sect1 id="HDRWQ57">
+     <title>Configuring AFS User Accounts</title>
+ 
+     <para>This section discusses some of the issues to consider when configuring AFS user accounts. Because AFS is separate from the
+     UNIX file system, a user's AFS account is separate from her UNIX account.</para>
+ 
+     <para>The preferred method for creating a user account is with the <emphasis role="bold">uss</emphasis> suite of commands. With
+     a single command, you can create all the components of one or many accounts, after you have prepared a template file that guides
+     the account creation. See <link linkend="HDRWQ449">Creating and Deleting User Accounts with the uss Command Suite</link>.</para>
+ 
+     <para>Alternatively, you can issue the individual commands that create each component of an account. For instructions, along
+     with instructions for removing user accounts and changing user passwords, user volume quotas and usernames, see <link
+     linkend="HDRWQ491">Administering User Accounts</link>.</para>
+ 
+     <para>When users leave your system, it is often good policy to remove their accounts. Instructions appear in <link
+     linkend="HDRWQ486">Deleting Individual Accounts with the uss delete Command</link> and <link linkend="HDRWQ524">Removing a User
+     Account</link>.</para>
+ 
+     <para>An AFS user account consists of the following components, which are described in greater detail in <link
+     linkend="HDRWQ494">The Components of an AFS User Account</link>. <itemizedlist>
+         <listitem>
+           <para>A Protection Database entry</para>
+         </listitem>
+ 
+         <listitem>
+           <para>An Authentication Database entry</para>
+         </listitem>
+ 
+         <listitem>
+           <para>A volume</para>
+         </listitem>
+ 
+         <listitem>
+           <para>A home directory at which the volume is mounted</para>
+         </listitem>
+ 
+         <listitem>
+           <para>Ownership of the home directory and full permissions on its ACL</para>
+         </listitem>
+ 
+         <listitem>
+           <para>An entry in the local password file (<emphasis role="bold">/etc/passwd</emphasis> or equivalent) of each machine the
+           user needs to log into</para>
+         </listitem>
+ 
+         <listitem>
+           <para>Optionally, standard files and subdirectories that make the account more useful</para>
+         </listitem>
+       </itemizedlist></para>
+ 
+     <para>By creating some components but not others, you can create accounts at different levels of functionality, using either
+     <emphasis role="bold">uss</emphasis> commands as described in <link linkend="HDRWQ449">Creating and Deleting User Accounts with
+     the uss Command Suite</link> or individual commands as described in <link linkend="HDRWQ491">Administering User Accounts</link>.
+     The levels of functionality include the following <itemizedlist>
+         <listitem>
+           <para>An authentication-only account enables the user to obtain AFS tokens and so to access protected AFS data and to
+           issue privileged commands. It consists only of entries in the Authentication and Protection Database. This type of account
+           is suitable for administrative accounts and for users from foreign cells who need to access protected data. Local users
+           generally also need a volume and home directory.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>A basic user account includes a volume for the user, in addition to Authentication and Protection Database entries.
+           The volume is mounted in the AFS filespace as the user's home directory, and provides a repository for the user's personal
+           files.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>A full account adds configuration files for basic functions such as logging in, printing, and mail delivery to a
+           basic account, making it more convenient and useful. For a discussion of some useful types of configuration files, see
+           <link linkend="HDRWQ60">Creating Standard Files in New AFS Accounts</link>.</para>
+         </listitem>
+       </itemizedlist></para>
+ 
+     <para>If your users have UNIX user accounts that predate the introduction of AFS in the cell, you possibly want to convert them
+     into AFS accounts. There are three main issues to consider: <itemizedlist>
+         <listitem>
+           <para>Making UNIX and AFS UIDs match</para>
+         </listitem>
+ 
+         <listitem>
+           <para>Setting the password field in the local password file appropriately</para>
+         </listitem>
+ 
+         <listitem>
+           <para>Moving files from the UNIX file system into AFS</para>
+         </listitem>
+       </itemizedlist></para>
+ 
+     <para>For further discussion, see <link linkend="HDRWQ459">Converting Existing UNIX Accounts with uss</link> or <link
+     linkend="HDRWQ498">Converting Existing UNIX Accounts</link>.</para>
+ 
+     <indexterm>
+       <primary>username</primary>
+ 
+       <secondary>choosing</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>user</primary>
+ 
+       <secondary>name</secondary>
+ 
+       <see>username</see>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>choosing</primary>
+ 
+       <secondary>name</secondary>
+ 
+       <tertiary>user</tertiary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>anonymous user</primary>
+ 
+       <secondary>AFS UID reserved</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>AFS UID</primary>
+ 
+       <secondary>reserved</secondary>
+ 
+       <tertiary>anonymous user</tertiary>
+     </indexterm>
+ 
+     <sect2 id="HDRWQ58">
+       <title>Choosing Usernames and Naming Other Account Components</title>
+ 
+       <para>This section suggests schemes for choosing usernames, AFS UIDs, user volume names and mount point names, and also
+       outlines some restrictions on your choices.</para>
+ 
+       <formalpara>
+         <title>Usernames</title>
+ 
+         <para>AFS imposes very few restrictions on the form of usernames. It is best to keep usernames short, both because many
+         utilities and applications can handle usernames of no more than eight characters and because by convention many components
+         of and AFS account incorporate the name. These include the entries in the Protection and Authentication Databases, the
+         volume, and the mount point. Depending on your electronic mail delivery system, the username can become part of the user's
+         mailing address. The username is also the string that the user types when logging in to a client machine.</para>
+       </formalpara>
+ 
+       <para>Some common choices for usernames are last names, first names, initials, or a combination, with numbers sometimes added.
+       It is also best to avoid using the following characters, many of which have special meanings to the command shell.
+       <itemizedlist>
+           <listitem>
+             <para>The comma (<emphasis role="bold">,</emphasis>)</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The colon (<emphasis role="bold">:</emphasis>), because AFS reserves it as a field separator in protection group
+             names; see <link linkend="HDRWQ62">The Two Types of User-Defined Groups</link></para>
+           </listitem>
+ 
+           <listitem>
+             <para>The semicolon (<emphasis role="bold">;</emphasis>)</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The "at-sign" (<emphasis role="bold">@</emphasis>); this character is reserved for Internet mailing
+             addresses</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Spaces</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The newline character</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The period (<emphasis role="bold">.</emphasis>); it is conventional to use this character only in the special
+             username that an administrator adopts while performing privileged tasks, such as <emphasis
+             role="bold">pat.admin</emphasis></para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <formalpara>
+         <title>AFS UIDs and UNIX UIDs</title>
+ 
+         <para>AFS associates a unique identification number, the AFS UID, with every username, recording the mapping in the user's
+         Protection Database entry. The AFS UID functions within AFS much as the UNIX UID does in the local file system: the AFS
+         server processes and the Cache Manager use it internally to identify a user, rather than the username.</para>
+       </formalpara>
+ 
+       <para>Every AFS user also must have a UNIX UID recorded in the local password file (<emphasis
+       role="bold">/etc/passwd</emphasis> or equivalent) of each client machine they log onto. Both administration and a user's AFS
+       access are simplest if the AFS UID and UNIX UID match. One important consequence of matching UIDs is that the owner reported
+       by the <emphasis role="bold">ls -l</emphasis> command matches the AFS username.</para>
+ 
+       <para>It is usually best to allow the Protection Server to allocate the AFS UID as it creates the Protection Database entry.
+       However, both the <emphasis role="bold">pts createuser</emphasis> command and the <emphasis role="bold">uss</emphasis>
+       commands that create user accounts enable you to assign AFS UIDs explicitly. This is appropriate in two cases: <itemizedlist>
+           <listitem>
+             <para>You wish to group together the AFS UIDs of related users</para>
+           </listitem>
+ 
+           <listitem>
+             <para>You are converting an existing UNIX account into an AFS account and want to make the AFS UID match the existing
+             UNIX UID</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <para>After the Protection Server initializes for the first time on a cell's first file server machine, it starts assigning
+       AFS UIDs at a default value. To change the default before creating any user accounts, or at any time, use the <emphasis
+       role="bold">pts setmax</emphasis> command to reset the <computeroutput>max user id counter</computeroutput>. To display the
+       counter, use the <emphasis role="bold">pts listmax</emphasis> command. See <link linkend="HDRWQ560">Displaying and Setting the
+       AFS UID and GID Counters</link>.</para>
+ 
+       <para>AFS reserves one AFS UID, 32766, for the user <emphasis role="bold">anonymous</emphasis>. The AFS server processes
+       assign this identity and AFS UID to any user who does not possess a token for the local cell. Do not assign this AFS UID to
+       any other user or hardcode its current value into any programs or a file's owner field, because it is subject to change in
+       future releases.</para>
+ 
+       <indexterm>
+         <primary>username</primary>
+ 
+         <secondary>part of volume name</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>choosing</primary>
+ 
+         <secondary>name</secondary>
+ 
+         <tertiary>user volume</tertiary>
+       </indexterm>
+ 
+       <formalpara>
+         <title>User Volume Names</title>
+ 
+         <para>Like any volume name, a user volume's base (read/write) name cannot exceed 22 characters in length or include the
+         <emphasis role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis> extension. See <link
+         linkend="HDRWQ44">Creating Volumes to Simplify Administration</link>. By convention, user volume names have the format
+         <emphasis role="bold">user.</emphasis>username. Using the <emphasis role="bold">user.</emphasis> prefix not only makes it
+         easy to identify the volume's contents, but also to create a backup version of all user volumes by issuing a single
+         <emphasis role="bold">vos backupsys</emphasis> command.</para>
+       </formalpara>
+ 
+       <indexterm>
+         <primary>mount point</primary>
+ 
+         <secondary>choosing name for user volume</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>choosing</primary>
+ 
+         <secondary>name</secondary>
+ 
+         <tertiary>user volume mount point</tertiary>
+       </indexterm>
+ 
+       <formalpara>
+         <title>Mount Point Names</title>
+ 
+         <para>By convention, the mount point for a user's volume is named after the username. Many cells follow the convention of
+         mounting user volumes in the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+         role="bold">/usr</emphasis> directory, as discussed in <link linkend="HDRWQ43">The Third Level</link>. Very large cells
+         sometimes find that mounting all user volumes in the same directory slows directory lookup, however; for suggested
+         alternatives, see the following section.</para>
+       </formalpara>
+ 
+       <indexterm>
+         <primary>directories</primary>
+ 
+         <secondary>for grouping user home directories</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>user account</primary>
+ 
+         <secondary>suggestions for grouping home directories</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ59">
+       <title>Grouping Home Directories</title>
+ 
+       <para>Mounting user volumes in the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+       role="bold">/usr</emphasis> directory is an AFS-appropriate variation on the standard UNIX practice of putting user home
+       directories under the <emphasis role="bold">/usr</emphasis> subdirectory. However, cells with more than a few hundred users
+       sometimes find that mounting all user volumes in a single directory results in slow directory lookup. The solution is to
+       distribute user volume mount points into several directories; there are a number of alternative methods to accomplish this.
+       <itemizedlist>
+           <listitem>
+             <para>Distribute user home directories into multiple directories that reflect organizational divisions, such as academic
+             or corporate departments. For example, a company can create group directories called <emphasis
+             role="bold">usr/marketing</emphasis>, <emphasis role="bold">usr/research</emphasis>, <emphasis
+             role="bold">usr/finance</emphasis>. A good feature of this scheme is that knowing a user's department is enough to find
+             the user's home directory. Also, it makes it easy to set the ACL to limit access to members of the department only. A
+             potential drawback arises if departments are of sufficiently unequal size that users in large departments experience
+             slower lookup than users in small departments. This scheme is also not appropriate in cells where users frequently
+             change between divisions.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Distribute home directories into alphabetic subdirectories of the <emphasis role="bold">usr</emphasis> directory
+             (the <emphasis role="bold">usr/a</emphasis> subdirectory, the <emphasis role="bold">usr/b</emphasis> subdirectory, and
+             so on), based on the first letter of the username. If the cell is very large, create subdirectories under each letter
+             that correspond to the second letter in the user name. This scheme has the same advantages and disadvantages of a
+             department-based scheme. Anyone who knows the user's username can find the user's home directory, but users with names
+             that begin with popular letters sometimes experience slower lookup.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Distribute home directories randomly but evenly into more than one grouping directory. One cell that uses this
+             scheme has over twenty such directories called the <emphasis role="bold">usr1</emphasis> directory, the <emphasis
+             role="bold">usr2</emphasis> directory, and so on. This scheme is especially appropriate in cells where the other two
+             schemes do not seem feasible. It eliminates the potential problem of differences in lookup speed, because all
+             directories are about the same size. Its disadvantage is that there is no way to guess which directory a given user's
+             volume is mounted in, but a solution is to create a symbolic link in the regular <emphasis role="bold">usr</emphasis>
+             directory that references the actual mount point. For example, if user <emphasis role="bold">smith</emphasis>'s volume
+             is mounted at the <emphasis role="bold">/afs/bigcell.com/usr17/smith</emphasis> directory, then the <emphasis
+             role="bold">/afs/bigcell.com/usr/smith</emphasis> directory is a symbolic link to the <emphasis
+             role="bold">../usr17/smith</emphasis> directory. This way, if someone does not know which directory the user <emphasis
+             role="bold">smith</emphasis> is in, he or she can access it through the link called <emphasis
+             role="bold">usr/smith</emphasis>; people who do know the appropriate directory save lookup time by specifying it.</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <para>For instructions on how to implement the various schemes when using the <emphasis role="bold">uss</emphasis> program to
+       create user accounts, see <link linkend="HDRWQ472">Evenly Distributing User Home Directories with the G Instruction</link> and
+       <link linkend="HDRWQ473">Creating a Volume with the V Instruction</link>.</para>
+     </sect2>
+ 
+     <sect2 id="Header_72">
+       <title>Making a Backup Version of User Volumes Available</title>
+ 
+       <para>Mounting the backup version of a user's volume is a simple way to enable users themselves to restore data they have
+       accidentally removed or deleted. It is conventional to mount the backup version at a subdirectory of the user's home directory
+       (called perhaps the <emphasis role="bold">OldFiles</emphasis> subdirectory), but other schemes are possible. Once per day you
+       create a new backup version to capture the changes made that day, overwriting the previous day's backup version with the new
+       one. Users can always retrieve the previous day's copy of a file without your assistance, freeing you to deal with more
+       pressing tasks.</para>
+ 
+       <para>Users sometimes want to delete the mount point to their backup volume, because they erroneously believe that the backup
+       volume's contents count against their quota. Remind them that the backup volume is separate, so the only space it uses in the
+       user volume is the amount needed for the mount point.</para>
+ 
+       <para>For further discussion of backup volumes, see <link linkend="HDRWQ77">Backing Up AFS Data</link> and <link
+       linkend="HDRWQ201">Creating Backup Volumes</link>.</para>
+ 
+       <indexterm>
+         <primary>file</primary>
+ 
+         <secondary>creating standard ones in new user account</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>user account</primary>
+ 
+         <secondary>creating</secondary>
+ 
+         <tertiary>standard files in</tertiary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>creating</primary>
+ 
+         <secondary>standard files in new user account</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ60">
+       <title>Creating Standard Files in New AFS Accounts</title>
+ 
+       <para>From your experience as a UNIX administrator, you are probably familiar with the use of login and shell initialization
+       files (such as the <emphasis role="bold">.login</emphasis> and <emphasis role="bold">.cshrc</emphasis> files) to make an
+       account easier to use.</para>
+ 
+       <para>It is often practical to add some AFS-specific directories to the definition of the user's <envar>PATH</envar>
+       environment variable, including the following: <itemizedlist>
+           <listitem>
+             <para>The path to a <emphasis role="bold">bin</emphasis> subdirectory in the user's home directory for binaries the user
+             has created (that is, <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+             role="bold">/usr/</emphasis><replaceable>username</replaceable><emphasis role="bold">/bin</emphasis>)</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The <emphasis role="bold">/usr/afsws/bin</emphasis> path, which conventionally includes programs like <emphasis
+             role="bold">fs</emphasis>, <emphasis role="bold">klog</emphasis>, <emphasis role="bold">kpasswd</emphasis>, <emphasis
+             role="bold">pts</emphasis>, <emphasis role="bold">tokens</emphasis>, and <emphasis role="bold">unlog</emphasis></para>
+           </listitem>
+ 
+           <listitem>
+             <para>The <emphasis role="bold">/usr/afsws/etc</emphasis> path, if the user is an administrator; it usually houses the
+             AFS command suites that require privilege (the <emphasis role="bold">backup</emphasis>, <emphasis
+             role="bold">butc</emphasis>, <emphasis role="bold">kas</emphasis>, <emphasis role="bold">uss</emphasis>, <emphasis
+             role="bold">vos</emphasis> commands), the <emphasis role="bold">package</emphasis> program, and others</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <para>If you are not using an AFS-modified login utility, it can be helpful to users to invoke the <emphasis
+       role="bold">klog</emphasis> command in their <emphasis role="bold">.login</emphasis> file so that they obtain AFS tokens as
+       part of logging in. In the following example command sequence, the first line echoes the string
+       <computeroutput>klog</computeroutput> to the standard output stream, so that the user understands the purpose of the
+       <computeroutput>Password:</computeroutput> prompt that appears when the second line is executed. The <emphasis
+       role="bold">-setpag</emphasis> flag associates the new tokens with a process authentication group (PAG), which is discussed
+       further in <link linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>.</para>
+ 
+       <programlisting>
+    echo -n "klog "
+    klog -setpag
+ </programlisting>
+ 
+       <para>The following sequence of commands has a similar effect, except that the <emphasis role="bold">pagsh</emphasis> command
+       forks a new shell with which the PAG and tokens are associated.</para>
+ 
+       <programlisting>
+    pagsh
+    echo -n "klog "
+    klog
+ </programlisting>
+ 
+       <para>If you use an AFS-modified login utility, this sequence is not necessary, because such utilities both log a user in
+       locally and obtain AFS tokens.</para>
+ 
+       <indexterm>
+         <primary>group</primary>
+ 
+         <secondary>AFS GID</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>group</primary>
+ 
+         <secondary>restrictions</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>group</primary>
+ 
+         <secondary>privacy flags</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>privacy flags on Protection Database entry</primary>
+       </indexterm>
+     </sect2>
+   </sect1>
+ 
+   <sect1 id="HDRWQ61">
+     <title>Using AFS Protection Groups</title>
+ 
+     <para>AFS enables users to define their own groups of other users or machines. The groups are placed on ACLs to grant the same
+     permissions to many users without listing each user individually. For group creation instructions, see <link
+     linkend="HDRWQ531">Administering the Protection Database</link>.</para>
+ 
+     <para>Groups have AFS ID numbers, just as users do, but an AFS group ID (GID) is a negative integer whereas a user's AFS UID is
+     a positive integer. By default, the Protection Server allocates a new group's AFS GID automatically, but members of the
+     <emphasis role="bold">system:administrators</emphasis> group can assign a GID when issuing the <emphasis role="bold">pts
+     creategroup</emphasis> command. Before explicitly assigning a GID, it is best to verify that it is not already in use.</para>
+ 
+     <para>A group cannot belong to another group, but it can own another group or even itself as long as it (the owning group) has
+     at least one member. The current owner of a group can transfer ownership of the group to another user or group, even without the
+     new owner's permission. At that point the former owner loses administrative control over the group.</para>
+ 
+     <para>By default, each user can create 20 groups. A system administrator can increase or decrease this group creation quota with
+     the <emphasis role="bold">pts setfields</emphasis> command.</para>
+ 
+     <para>Each Protection Database entry (group or user) is protected by a set of five privacy flagswhich limit who can administer
+     the entry and what they can do. The default privacy flags are fairly restrictive, especially for user entries. See <link
+     linkend="HDRWQ559">Setting the Privacy Flags on Database Entries</link>.</para>
+ 
+     <indexterm>
+       <primary>system:administrators group</primary>
+ 
+       <secondary>about</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>system:anyuser group</primary>
+ 
+       <secondary>about</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>system:authuser group</primary>
+ 
+       <secondary>about</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>group</primary>
+ 
+       <secondary>system-defined</secondary>
+     </indexterm>
+ 
+     <sect2 id="Header_75">
+       <title>The Three System Groups</title>
+ 
+       <para>As the Protection Server initializes for the first time on a cell's first database server machine, it automatically
+       creates three group entries: the <emphasis role="bold">system:anyuser</emphasis>, <emphasis
+       role="bold">system:authuser</emphasis>, and <emphasis role="bold">system:administrators</emphasis> groups.</para>
+ 
+       <indexterm>
+         <primary>AFS UID</primary>
+ 
+         <secondary>reserved</secondary>
+ 
+         <tertiary>system-defined groups</tertiary>
+       </indexterm>
+ 
+       <para>The first two system groups are unlike any other groups in the Protection Database in that they do not have a stable
+       membership: <itemizedlist>
+           <listitem>
+             <para>The <emphasis role="bold">system:anyuser</emphasis> group includes everyone who can access a cell's AFS filespace:
+             users who have tokens for the local cell, users who have logged in on a local AFS client machine but not obtained tokens
+             (such as the local superuser <emphasis role="bold">root</emphasis>), and users who have connected to a local machine
+             from outside the cell. Placing the <emphasis role="bold">system:anyuser</emphasis> group on an ACL grants access to the
+             widest possible range of users. It is the only way to extend access to users from foreign AFS cells that do not have
+             local accounts.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The <emphasis role="bold">system:authuser</emphasis> group includes everyone who has a valid token obtained from
+             the cell's AFS authentication service.</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <para>Because the groups do not have a stable membership, the <emphasis role="bold">pts membership</emphasis> command produces
+       no output for them. Similarly, they do not appear in the list of groups to which a user belongs.</para>
+ 
+       <para>The <emphasis role="bold">system:administrators</emphasis> group does have a stable membership, consisting of the cell's
+       privileged administrators. Members of this group can issue any <emphasis role="bold">pts</emphasis> command, and are the only
+       ones who can issue several other restricted commands (such as the <emphasis role="bold">chown</emphasis> command on AFS
+       files). By default, they also implicitly have the <emphasis role="bold">a</emphasis> (<emphasis
+       role="bold">administer</emphasis>) and <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>)
+       permissions on every ACL in the filespace. For information about changing this default, see <link
+       linkend="HDRWQ586">Administering the system:administrators Group</link>.</para>
+ 
+       <para>For a discussion of how to use system groups effectively on ACLs, see <link linkend="HDRWQ571">Using Groups on
+       ACLs</link>.</para>
+     </sect2>
+ 
+     <sect2 id="HDRWQ62">
+       <title>The Two Types of User-Defined Groups</title>
+ 
+       <para>All users can create regular groups. A regular group name has two fields separated by a colon, the first of which must
+       indicate the group's ownership. The Protection Server refuses to create or change the name of a group if the result does not
+       accurately indicate the ownership.</para>
+ 
+       <para>Members of the <emphasis role="bold">system:administrators</emphasis> group can create prefix-less groups whose names do
+       not have the first field that indicates ownership. For suggestions on using the two types of groups effectively, see <link
+       linkend="HDRWQ545">Using Groups Effectively</link>.</para>
+ 
+       <indexterm>
+         <primary>authentication</primary>
+ 
+         <secondary>AFS separate from UNIX</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>AFS</primary>
+ 
+         <secondary>authentication separate from UNIX</secondary>
+       </indexterm>
+     </sect2>
+   </sect1>
+ 
+   <sect1 id="HDRWQ63">
+     <title>Login and Authentication in AFS</title>
+ 
+     <para>As explained in <link linkend="HDRWQ31">Differences in Authentication</link>, AFS authentication is separate from UNIX
+     authentication because the two file systems are separate. The separation has two practical implications: <itemizedlist>
+         <listitem>
+           <para>To access AFS files, users must both log into the local file system and authenticate with the AFS authentication
+           service. (Logging into the local file system is necessary because the only way to access the AFS filespace is through a
+           Cache Manager, which resides in the local machine's kernel.)</para>
+         </listitem>
+ 
+         <listitem>
+           <para>Passwords are stored in two separate places: in the Authentication Database for AFS and in the each machine's local
+           password file (the <emphasis role="bold">/etc/passwd</emphasis> file or equivalent) for the local file system.</para>
+         </listitem>
+       </itemizedlist></para>
+ 
+     <para>When a user successfully authenticates, the AFS authentication service passes a token to the user's Cache Manager. The
+     token is a small collection of data that certifies that the user has correctly provided the password associated with a
+     particular AFS identity. The Cache Manager presents the token to AFS server processes along with service requests, as proof that
+     the user is genuine. To learn about the mutual authentication procedure they use to establish identity, see <link
+     linkend="HDRWQ75">A More Detailed Look at Mutual Authentication</link>.</para>
+ 
+     <para>The Cache Manager stores tokens in the user's credential structure in kernel memory. To distinguish one user's credential
+     structure from another's, the Cache Manager identifies each one either by the user's UNIX UID or by a process authentication
+     group (PAG), which is an identification number guaranteed to be unique in the cell. For further discussion, see <link
+     linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>.</para>
+ 
+     <indexterm>
+       <primary>tokens</primary>
+ 
+       <secondary>one-per-cell rule</secondary>
+     </indexterm>
+ 
+     <para>A user can have only one token per cell in each separately identified credential structure. To obtain a second token for
+     the same cell, the user must either log into a different machine or obtain another credential structure with a different
+     identifier than any existing credential structure, which is most easily accomplished by issuing the <emphasis
+     role="bold">pagsh</emphasis> command (see <link linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>). In a single credential
+     structure, a user can have one token for each of many cells at the same time. As this implies, authentication status on one
+     machine or PAG is independent of authentication status on another machine or PAG, which can be very useful to a user or system
+     administrator.</para>
+ 
+     <para>The AFS distribution includes library files that enable each system type's login utility to authenticate users with AFS
+     and log them into the local file system in one step. If you do not configure an AFS-modified login utility on a client machine,
+     its users must issue the <emphasis role="bold">klog</emphasis> command to authenticate with AFS after logging in.</para>
+ 
+     <note>
+       <para>The AFS-modified libraries do not necessarily support all features available in an operating system's proprietary login
+       utility. In some cases, it is not possible to support a utility at all. For more information about the supported utilities in
+       each AFS version, see the OpenAFS Release Notes.</para>
+     </note>
+ 
+     <indexterm>
+       <primary>commands</primary>
+ 
+       <secondary>pagsh</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>pagsh command</primary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>commands</primary>
+ 
+       <secondary>klog with -setpag flag</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>klog command</primary>
+ 
+       <secondary>with -setpag flag</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>PAG</primary>
+ 
+       <secondary>creating with klog or pagsh command</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>creating</primary>
+ 
+       <secondary>PAG with klog or pagsh command</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>process authentication group</primary>
+ 
+       <secondary></secondary>
+ 
+       <see>PAG</see>
+     </indexterm>
+ 
+     <sect2 id="HDRWQ64">
+       <title>Identifying AFS Tokens by PAG</title>
+ 
+       <para>As noted, the Cache Manager identifies user credential structures either by UNIX UID or by PAG. Using a PAG is
+       preferable because it guaranteed to be unique: the Cache Manager allocates it based on a counter that increments with each
+       use. In contrast, multiple users on a machine can share or assume the same UNIX UID, which creates potential security
+       problems. The following are two common such situations: <itemizedlist>
+           <listitem>
+             <para>The local superuser <emphasis role="bold">root</emphasis> can always assume any other user's UNIX UID simply by
+             issuing the <emphasis role="bold">su</emphasis> command, without providing the user's password. If the credential
+             structure is associated with the user's UNIX UID, then assuming the UID means inheriting the AFS tokens.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Two users working on different NFS client machines can have the same UNIX UID in their respective local file
+             systems. If they both access the same NFS/AFS Translator machine, and the Cache Manager there identifies them by their
+             UNIX UID, they become indistinguishable. To eliminate this problem, the Cache Manager on a translator machine
+             automatically generates a PAG for each user and uses it, rather than the UNIX UID, to tell users apart.</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <para>Yet another advantage of PAGs over UIDs is that processes spawned by the user inherit the PAG and so share the token;
+       thus they gain access to AFS as the authenticated user. In many environments, for example, printer and other daemons run under
+       identities (such as the local superuser <emphasis role="bold">root</emphasis>) that the AFS server processes recognize only as
+       the <emphasis role="bold">anonymous</emphasis> user. Unless PAGs are used, such daemons cannot access files for which the
+       <emphasis role="bold">system:anyuser</emphasis> group does not have the necessary ACL permissions.</para>
+ 
+       <para>Once a user has a PAG, any new tokens the user obtains are associated with the PAG. The PAG expires two hours after any
+       associated tokens expire or are discarded. If the user issues the <emphasis role="bold">klog</emphasis> command before the PAG
+       expires, the new token is associated with the existing PAG (the PAG is said to be recycled in this case).</para>
+ 
+       <para>AFS-modified login utilities automatically generate a PAG, as described in the following section. If you use a standard
+       login utility, your users must issue the <emphasis role="bold">pagsh</emphasis> command before the <emphasis
+       role="bold">klog</emphasis> command, or include the latter command's <emphasis role="bold">-setpag</emphasis> flag. For
+       instructions, see <link linkend="HDRWQ69">Using Two-Step Login and Authentication</link>.</para>
+ 
+       <para>Users can also use either command at any time to create a new PAG. The difference between the two commands is that the
+       <emphasis role="bold">klog</emphasis> command replaces the PAG associated with the current command shell and tokens. The
+       <emphasis role="bold">pagsh</emphasis> command initializes a new command shell before creating a new PAG. If the user already
+       had a PAG, any running processes or jobs continue to use the tokens associated with the old PAG whereas any new jobs or
+       processes use the new PAG and its associated tokens. When you exit the new shell (by pressing &lt;<emphasis
+       role="bold">Ctrl-d</emphasis>&gt;, for example), you return to the original PAG and shell. By default, the <emphasis
+       role="bold">pagsh</emphasis> command initializes a Bourne shell, but you can include the <emphasis role="bold">-c</emphasis>
+       argument to initialize a C shell (the <emphasis role="bold">/bin/csh</emphasis> program on many system types) or Korn shell
+       (the <emphasis role="bold">/bin/ksh</emphasis> program) instead.</para>
+ 
+       <indexterm>
+         <primary>login utility</primary>
+ 
+         <secondary>AFS version</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ65">
+       <title>Using an AFS-modified login Utility</title>
+ 
+       <para>As previously mentioned, an AFS-modified login utility simultaneously obtains an AFS token and logs the user into the
+       local file system. This section outlines the login and authentication process and its interaction with the value in the
+       password field of the local password file.</para>
+ 
+       <para>An AFS-modified login utility performs a sequence of steps similar to the following; details can vary for different
+       operating systems: <orderedlist>
+           <listitem>
+             <para>It checks the user's entry in the local password file (the <emphasis role="bold">/etc/passwd</emphasis> file or
+             equivalent).</para>
+           </listitem>
+ 
+           <listitem>
+             <para>If no entry exists, or if an asterisk (<computeroutput>*</computeroutput>) appears in the entry's password field,
+             the login attempt fails. If the entry exists, the attempt proceeds to the next step.</para>
+           </listitem>
+ 
+           <listitem>
+             <para><anchor id="LIWQ66" />The utility obtains a PAG.</para>
+           </listitem>
+ 
+           <listitem>
+             <para><anchor id="LIWQ67" />The utility converts the password provided by the user into an encryption key and encrypts a
+             packet of data with the key. It sends the packet to the AFS authentication service (the AFS Authentication Server in the
+             conventional configuration).</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The authentication service decrypts the packet and, depending on the success of the decryption, judges the
+             password to be correct or incorrect. (For more details, see <link linkend="HDRWQ75">A More Detailed Look at Mutual
+             Authentication</link>.) <itemizedlist>
+                 <listitem>
+                   <para>If the authentication service judges the password incorrect, the user does not receive an AFS token. The PAG
+                   is retained, ready to be associated with any tokens obtained later. The attempt proceeds to Step <link
+                   linkend="LIWQ68">6</link>.</para>
+                 </listitem>
+ 
+                 <listitem>
+                   <para>If the authentication service judges the password correct, it issues a token to the user as proof of AFS
+                   authentication. The login utility logs the user into the local UNIX file system. Some login utilities echo the
+                   following banner to the screen to alert the user to authentication with AFS. Step <link linkend="LIWQ68">6</link>
+                   is skipped. <programlisting>
+    AFS(R) version Login 
+ </programlisting></para>
+                 </listitem>
+               </itemizedlist></para>
+           </listitem>
+ 
+           <listitem>
+             <para><anchor id="LIWQ68" />If no AFS token was granted in Step <link linkend="LIWQ67">4</link>, the login utility
+             attempts to log the user into the local file system, by comparing the password provided to the local password file.
+             <itemizedlist>
+                 <listitem>
+                   <para>If the password is incorrect or any value other than an encrypted 13-character string appears in the
+                   password field, the login attempt fails.</para>
+                 </listitem>
+ 
+                 <listitem>
+                   <para>If the password is correct, the user is logged into the local file system only.</para>
+                 </listitem>
+               </itemizedlist></para>
+           </listitem>
+         </orderedlist></para>
+ 
+       <indexterm>
+         <primary>local password file</primary>
+ 
+         <secondary>when using AFS--modified login utility</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>login utility</primary>
+ 
+         <secondary>AFS version's interaction with local password file</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>password</primary>
+ 
+         <secondary>local password file</secondary>
+       </indexterm>
+ 
+       <para>As indicated, when you use an AFS-modified login utility, the password field in the local password file is no longer the
+       primary gate for access to your system. If the user provides the correct AFS password, then the program never consults the
+       local password file. However, you can still use the password field to control access, in the following way: <itemizedlist>
+           <listitem>
+             <para>To prevent both local login and AFS authentication, place an asterisk (<emphasis role="bold">*</emphasis>) in the
+             field. This is useful mainly in emergencies, when you want to prevent a certain user from logging into the
+             machine.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>To prevent login to the local file system if the user does not provide the correct AFS password, place a character
+             string of any length other than the standard thirteen characters in the field. This is appropriate if you want to permit
+             only people with local AFS accounts to login on your machines. A single <emphasis role="bold">X</emphasis> or other
+             character is the most easily recognizable way to do this.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>To enable a user to log into the local file system even after providing an incorrect AFS password, record a
+             standard UNIX encrypted password in the field by issuing the standard UNIX password-setting command (<emphasis
+             role="bold">passwd</emphasis> or equivalent).</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <para>Systems that use a Pluggable Authentication Module (PAM) for login and AFS authentication do not necessarily consult the
+       local password file at all, in which case they do not use the password field to control authentication and login attempts.
+       Instead, instructions in the PAM configuration file (on many system types, <emphasis role="bold">/etc/pam.conf</emphasis>)
+       fill the same function. See the instructions in the OpenAFS Quick Beginnings for installing AFS-modified login
+       utilities.</para>
+ 
+       <indexterm>
+         <primary>local password file</primary>
+ 
+         <secondary>when not using AFS-modified login utility</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ69">
+       <title>Using Two-Step Login and Authentication</title>
+ 
+       <para>In cells that do not use an AFS-modified login utility, users must issue separate commands to login and authenticate, as
+       detailed in the OpenAFS User Guide: <orderedlist>
+           <listitem>
+             <para>They use the standard <emphasis role="bold">login</emphasis> program to login to the local file system, providing
+             the password listed in the local password file (the <emphasis role="bold">/etc/passwd</emphasis> file or
+             equivalent).</para>
+           </listitem>
+ 
+           <listitem>
+             <para>They must issue the <emphasis role="bold">klog</emphasis> command to authenticate with the AFS authentication
+             service, including its <emphasis role="bold">-setpag</emphasis> flag to associate the new tokens with a process
+             authentication group (PAG).</para>
+           </listitem>
+         </orderedlist></para>
+ 
+       <para>As mentioned in <link linkend="HDRWQ60">Creating Standard Files in New AFS Accounts</link>, you can invoke the <emphasis
+       role="bold">klog -setpag</emphasis> command in a user's <emphasis role="bold">.login</emphasis> file (or equivalent) so that
+       the user does not have to remember to issue the command after logging in. The user still must type a password twice, once at
+       the prompt generated by the login utility and once at the <emphasis role="bold">klog</emphasis> command's prompt. This implies
+       that the two passwords can differ, but it is less confusing if they do not.</para>
+ 
+       <para>Another effect of not using an AFS-modified login utility is that the AFS servers recognize the standard <emphasis
+       role="bold">login</emphasis> program as the <emphasis role="bold">anonymous</emphasis> user. If the <emphasis
+       role="bold">login</emphasis> program needs to access any AFS files (such as the <emphasis role="bold">.login</emphasis> file
+       in a user's home directory), then the ACL that protects the file must include an entry granting the <emphasis
+       role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) and <emphasis role="bold">r</emphasis> (<emphasis
+       role="bold">read</emphasis>) permissions to the <emphasis role="bold">system:anyuser</emphasis> group.</para>
+ 
+       <para>When you do not use an AFS-modified login utility, an actual (scrambled) password must appear in the local password file
+       for each user. Use the <emphasis role="bold">/bin/passwd</emphasis> file to insert or change these passwords. It is simpler if
+       the password in the local password file matches the AFS password, but it is not required.</para>
+ 
+       <indexterm>
+         <primary>tokens</primary>
+ 
+         <secondary>displaying for user</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>tokens</primary>
+ 
+         <secondary>command</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>commands</primary>
+ 
+         <secondary>tokens</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>listing</primary>
+ 
+         <secondary>tokens held by issuer</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>commands</primary>
+ 
+         <secondary>klog</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>klog command</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>server process</primary>
+ 
+         <secondary>creating ticket (tokens) for</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>tickets</primary>
+ 
+         <secondary></secondary>
+ 
+         <see>tokens</see>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>tokens</primary>
+ 
+         <secondary>creating for server process</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>authenticated identity</primary>
+ 
+         <secondary>acquiring with klog command</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>unlog command</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>commands</primary>
+ 
+         <secondary>unlog</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>discarding</primary>
+ 
+         <secondary>tokens</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>tokens</primary>
+ 
+         <secondary>discarding with unlog command</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="Header_81">
+       <title>Obtaining, Displaying, and Discarding Tokens</title>
+ 
+       <para>Once logged in, a user can obtain a token at any time with the <emphasis role="bold">klog</emphasis> command. If a valid
+       token already exists, the new one overwrites it. If a PAG already exists, the new token is associated with it.</para>
+ 
+       <para>By default, the <emphasis role="bold">klog</emphasis> command authenticates the issuer using the identity currently
+       logged in to the local file system. To authenticate as a different identity, use the <emphasis
+       role="bold">-principal</emphasis> argument. To obtain a token for a foreign cell, use the <emphasis
+       role="bold">-cell</emphasis> argument (it can be combined with the <emphasis role="bold">-principal</emphasis> argument). See
+       the OpenAFS User Guide and the entry for the <emphasis role="bold">klog</emphasis> command in the OpenAFS Administration
+       Reference.</para>
+ 
+       <para>To discard either all tokens or the token for a particular cell, issue the <emphasis role="bold">unlog</emphasis>
+       command. The command affects only the tokens associated with the current command shell. See the OpenAFS User Guideand the
+       entry for the <emphasis role="bold">unlog</emphasis> command in the OpenAFS Administration Reference.</para>
+ 
+       <para>To display the tokens associated with the current command shell, issue the <emphasis role="bold">tokens</emphasis>
+       command. The following examples illustrate its output in various situations.</para>
+ 
+       <para>If the issuer is not authenticated in any cell:</para>
+ 
+       <programlisting>
+    % <emphasis role="bold">tokens</emphasis>
+    Tokens held by the Cache Manager:
+           --End of list--
+ </programlisting>
+ 
+       <para>The following shows the output for a user with AFS UID 1000 in the ABC Corporation cell:</para>
+ 
+       <programlisting>
+    % <emphasis role="bold">tokens</emphasis>
+    Tokens held by the Cache Manager: 
+    User's (AFS ID 1000) tokens for afs@abc.com  [Expires Jun  2 10:00]
+        --End of list--
+ </programlisting>
+ 
+       <para>The following shows the output for a user who is authenticated in ABC Corporation cell, the State University cell and
+       the DEF Company cell. The user has different AFS UIDs in the three cells. Tokens for the last cell are expired:</para>
+ 
+       <programlisting>
+    % <emphasis role="bold">tokens</emphasis>
+    Tokens held by the Cache Manager:
+    User's (AFS ID 1000) tokens for afs@abc.com  [Expires Jun  2 10:00]
+    User's (AFS ID 4286) tokens for afs@stateu.edu  [Expires Jun  3 1:34]
+    User's (AFS ID 22) tokens for afs@def.com  [&gt;&gt;Expired&lt;&lt;]
+        --End of list--
+ </programlisting>
+ 
+       <para>The Kerberos version of the <emphasis role="bold">tokens</emphasis> command (the <emphasis
+       role="bold">tokens.krb</emphasis> command), also reports information on the ticket-granting ticket, including the ticket's
+       owner, the ticket-granting service, and the expiration date, as in the following example. Also see <link
+       linkend="HDRWQ70">Support for Kerberos Authentication</link>.</para>
+ 
+       <programlisting>
+    % <emphasis role="bold">tokens.krb</emphasis>
+    Tokens held by the Cache Manager:
+    User's (AFS ID 1000) tokens for afs@abc.com [Expires Jun  2 10:00]
+    User smith's tokens for krbtgt.ABC.COM@abc.com [Expires Jun  2 10:00]
+      --End of list--
+ </programlisting>
+     </sect2>
+ 
+     <sect2 id="Header_82">
+       <title>Setting Default Token Lifetimes for Users</title>
+ 
+       <indexterm>
+         <primary>tokens</primary>
+ 
+         <secondary>setting default lifetimes for users</secondary>
+       </indexterm>
+ 
+       <para>The maximum lifetime of a user token is the smallest of the ticket lifetimes recorded in the following three
+       Authentication Database entries. The <emphasis role="bold">kas examine</emphasis> command reports the lifetime as
+       <computeroutput>Max ticket lifetime</computeroutput>. Administrators who have the <computeroutput>ADMIN</computeroutput> flag
+       on their Authentication Database entry can use the <emphasis role="bold">-lifetime</emphasis> argument to the <emphasis
+       role="bold">kas setfields</emphasis> command to set an entry's ticket lifetime. <itemizedlist>
+           <listitem>
+             <para>The <emphasis role="bold">afs</emphasis> entry, which corresponds to the AFS server processes. The default is 100
+             hours.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The <emphasis role="bold">krbtgt</emphasis>.cellname entry, which corresponds to the ticket-granting ticket used
+             internally in generating the token. The default is 720 hours (30 days).</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The entry for the user of the AFS-modified login utility or issuer of the <emphasis role="bold">klog</emphasis>
+             command. The default is 25 hours for user entries created using the AFS 3.1 or later version of the Authentication
+             Server, and 100 hours for user entries created using the AFS 3.0 version of the Authentication Server. A user can use
+             the <emphasis role="bold">kas examine</emphasis> command to display his or her own Authentication Database entry.</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <note>
+         <para>An AFS-modified login utility always grants a token with a lifetime calculated from the previously described three
+         values. When issuing the <emphasis role="bold">klog</emphasis> command, a user can request a lifetime shorter than the
+         default by using the <emphasis role="bold">-lifetime</emphasis> argument. For further information, see the OpenAFS User
+         Guide and the <emphasis role="bold">klog</emphasis> reference page in the OpenAFS Administration Reference.</para>
+       </note>
+     </sect2>
+ 
+     <sect2 id="Header_83">
+       <title>Changing Passwords</title>
+ 
+       <indexterm>
+         <primary>password</primary>
+ 
+         <secondary>changing in AFS</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>kpasswd command</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>commands</primary>
+ 
+         <secondary>kpasswd</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>kas commands</primary>
+ 
+         <secondary>setpassword</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>commands</primary>
+ 
+         <secondary>kas setpassword</secondary>
+       </indexterm>
+ 
+       <para>Regular AFS users can change their own passwords by using either the <emphasis role="bold">kpasswd</emphasis> or
+       <emphasis role="bold">kas setpassword</emphasis> command. The commands prompt for the current password and then twice for the
+       new password, to screen out typing errors.</para>
+ 
+       <para>Administrators who have the <computeroutput>ADMIN</computeroutput> flag on their Authentication Database entries can
+       change any user's password, either by using the <emphasis role="bold">kpasswd</emphasis> command (which requires knowing the
+       current password) or the <emphasis role="bold">kas setpassword</emphasis> command.</para>
+ 
+       <para>If your cell does not use an AFS-modified login utility, remember also to change the local password, using the operating
+       system's password-changing command. For more instructions on changing passwords, see <link linkend="HDRWQ516">Changing AFS
+       Passwords</link>.</para>
+     </sect2>
+ 
+     <sect2 id="Header_84">
+       <title>Imposing Restrictions on Passwords and Authentication Attempts</title>
+ 
+       <para>You can help to make your cell more secure by imposing restrictions on user passwords and authentication attempts. To
+       impose the restrictions as you create an account, use the <emphasis role="bold">A</emphasis> instruction in the <emphasis
+       role="bold">uss</emphasis> template file as described in <link linkend="HDRWQ478">Increasing Account Security with the A
+       Instruction</link>. To set or change the values on an existing account, use the <emphasis role="bold">kas setfields</emphasis>
+       command as described in <link linkend="HDRWQ515">Improving Password and Authentication Security</link>.</para>
+ 
+       <indexterm>
+         <primary>password</primary>
+ 
+         <secondary>expiration</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>password</primary>
+ 
+         <secondary>lifetime</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>kas commands</primary>
+ 
+         <secondary>setfields</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>commands</primary>
+ 
+         <secondary>kas setfields</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>Authentication Database</primary>
+ 
+         <secondary>password lifetime, setting</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>password</primary>
+ 
+         <secondary>restricting reuse</secondary>
+       </indexterm>
+ 
+       <para>By default, AFS passwords never expire. Limiting password lifetime can help improve security by decreasing the time the
+       password is subject to cracking attempts. You can choose an lifetime from 1 to 254 days after the password was last changed.
+       It automatically applies to each new password as it is set. When the user changes passwords, you can also insist that the new
+       password is not similar to any of the 20 passwords previously used.</para>
+ 
+       <indexterm>
+         <primary>password</primary>
+ 
+         <secondary>consequences of multiple failed authentication attempts</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>kas commands</primary>
+ 
+         <secondary>setfields</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>commands</primary>
+ 
+         <secondary>kas setfields</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>authentication</primary>
+ 
+         <secondary>consequences of multiple failures</secondary>
+       </indexterm>
+ 
+       <para>Unscrupulous users can try to gain access to your AFS cell by guessing an authorized user's password. To protect against
+       this type of attack, you can limit the number of times that a user can consecutively fail to provide the correct password.
+       When the limit is exceeded, the authentication service refuses further authentication attempts for a specified period of time
+       (the lockout time). To reenable authentication attempts before the lockout time expires, an administrator must issue the
+       <emphasis role="bold">kas unlock</emphasis> command.</para>
+ 
+       <indexterm>
+         <primary>password</primary>
+ 
+         <secondary>checking quality of</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>kpasswd command</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>commands</primary>
+ 
+         <secondary>kpasswd</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>kas commands</primary>
+ 
+         <secondary>setpassword</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>kpwvalid program</primary>
+       </indexterm>
+ 
+       <para>In addition to settings on user's authentication accounts, you can improve security by automatically checking the
+       quality of new user passwords. The <emphasis role="bold">kpasswd</emphasis> and <emphasis role="bold">kas
+       setpassword</emphasis> commands pass the proposed password to a program or script called <emphasis
+       role="bold">kpwvalid</emphasis>, if it exists. The <emphasis role="bold">kpwvalid</emphasis> performs quality checks and
+       returns a code to indicate whether the password is acceptable. You can create your own program or modified the sample program
+       included in the AFS distribution. See the <emphasis role="bold">kpwvalid</emphasis> reference page in the OpenAFS
+       Administration Reference.</para>
+ 
+       <para>There are several types of quality checks that can improve password quality. <itemizedlist>
+           <listitem>
+             <para>The password is a minimum length</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The password is not a word</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The password contains both numbers and letters</para>
+           </listitem>
+         </itemizedlist></para>
+     </sect2>
+ 
+     <sect2 id="HDRWQ70">
+       <title>Support for Kerberos Authentication</title>
+ 
+       <indexterm>
+         <primary>Kerberos</primary>
+ 
+         <secondary>support for in AFS</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>commands</primary>
+ 
+         <secondary>klog.krb</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>commands</primary>
+ 
+         <secondary>pagsh.krb</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>commands</primary>
+ 
+         <secondary>tokens.krb</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>klog.krb command</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>pagsh.krb command</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>tokens.krb command</primary>
+       </indexterm>
+ 
+       <para>If your site is using standard Kerberos authentication rather than the AFS Authentication Server, use the modified
+       versions of the <emphasis role="bold">klog</emphasis>, <emphasis role="bold">pagsh</emphasis>, and <emphasis
+       role="bold">tokens</emphasis> commands that support Kerberos authentication. The binaries for the modified version of these
+       commands have the same name as the standard binaries with the addition of a <emphasis role="bold">.krb</emphasis>
+       extension.</para>
+ 
+       <para>Use either the Kerberos version or the standard command throughout the cell; do not mix the two versions. AFS Product
+       Support can provide instructions on installing the Kerberos version of these four commands. For information on the differences
+       between the two versions of these commands, see the OpenAFS Administration Reference.</para>
+     </sect2>
+   </sect1>
+ 
+   <sect1 id="HDRWQ71">
+     <title>Security and Authorization in AFS</title>
+ 
+     <para>AFS incorporates several features to ensure that only authorized users gain access to data. This section summarizes the
+     most important of them and suggests methods for improving security in your cell.</para>
+ 
+     <sect2 id="HDRWQ72">
+       <title>Some Important Security Features</title>
+ 
+       <indexterm>
+         <primary>security</primary>
+ 
+         <secondary>AFS features</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>AFS</primary>
+ 
+         <secondary>security features</secondary>
+       </indexterm>
+ 
+       <formalpara>
+         <title>ACLs on Directories</title>
+ 
+         <para>Files in AFS are protected by the access control list (ACL) associated with their parent directory. The ACL defines
+         which users or groups can access the data in the directory, and in what way. See <link linkend="HDRWQ562">Managing Access
+         Control Lists</link>.</para>
+       </formalpara>
+ 
+       <formalpara>
+         <title>Mutual Authentication Between Client and Server</title>
+ 
+         <para>When an AFS client and server process communicate, each requires the other to prove its identity during mutual
+         authentication, which involves the exchange of encrypted information that only valid parties can decrypt and respond to. For
+         a detailed description of the mutual authentication process, see <link linkend="HDRWQ75">A More Detailed Look at Mutual
+         Authentication</link>.</para>
+       </formalpara>
+ 
+       <para>AFS server processes mutually authenticate both with one another and with processes that represent human users. After
+       mutual authentication is complete, the server and client have established an authenticated connection, across which they can
+       communicate repeatedly without having to authenticate again until the connection expires or one of the parties closes it.
+       Authenticated connections have varying lifetimes.</para>
+ 
+       <formalpara>
+         <title>Tokens</title>
+ 
+         <para>In order to access AFS files, users must prove their identities to the AFS authentication service by providing the
+         correct AFS password. If the password is correct, the authentication service sends the user a token as evidence of
+         authenticated status. See <link linkend="HDRWQ63">Login and Authentication in AFS</link>.</para>
+       </formalpara>
+ 
+       <para>Servers assign the user identity <emphasis role="bold">anonymous</emphasis> to users and processes that do not have a
+       valid token. The <emphasis role="bold">anonymous</emphasis> identity has only the access granted to the <emphasis
+       role="bold">system:anyuser</emphasis> group on ACLs.</para>
+ 
+       <formalpara>
+         <title>Authorization Checking</title>
+ 
+         <para>Mutual authentication establishes that two parties communicating with one another are actually who they claim to be.
+         For many functions, AFS server processes also check that the client whose identity they have verified is also authorized to
+         make the request. Different requests require different kinds of privilege. See <link linkend="HDRWQ73">Three Types of
+         Privilege</link>.</para>
+       </formalpara>
+ 
+       <formalpara>
+         <title>Encrypted Network Communications</title>
+ 
+         <indexterm>
+           <primary>network</primary>
+ 
+           <secondary>encrypted communication in AFS</secondary>
+         </indexterm>
+ 
+         <indexterm>
+           <primary>encrypted network communication</primary>
+         </indexterm>
+ 
+         <indexterm>
+           <primary>security</primary>
+ 
+           <secondary>encrypted network communication</secondary>
+         </indexterm>
+ 
+         <para>The AFS server processes encrypt particularly sensitive information before sending it back to clients. Even if an
+         unauthorized party is able to eavesdrop on an authenticated connection, they cannot decipher encrypted data without the
+         proper key.</para>
+       </formalpara>
+ 
+       <para>The following AFS commands encrypt data because they involve server encryption keys and passwords: <itemizedlist>
+           <listitem>
+             <para>The <emphasis role="bold">bos addkey</emphasis> command, which adds a server encryption key to the <emphasis
+             role="bold">/usr/afs/etc/KeyFile</emphasis> file</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The <emphasis role="bold">bos listkeys</emphasis> command, which lists the server encryption keys from the
+             <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> file</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The <emphasis role="bold">kpasswd</emphasis> command, which changes a password in the Authentication
+             Database</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Most commands in the <emphasis role="bold">kas</emphasis> command suite</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <para>In addition, the United States edition of the Update Server encrypts sensitive information (such as the contents of
+       <emphasis role="bold">KeyFile</emphasis>) when distributing it. Other commands in the <emphasis role="bold">bos</emphasis>
+       suite and the commands in the <emphasis role="bold">fs</emphasis>, <emphasis role="bold">pts</emphasis> and <emphasis
+       role="bold">vos</emphasis> suites do not encrypt data before transmitting it.</para>
+     </sect2>
+ 
+     <sect2 id="HDRWQ73">
+       <title>Three Types of Privilege</title>
+ 
+       <para>AFS uses three separate types of privilege for the reasons discussed in <link linkend="HDRWQ585">The Reason for Separate
+       Privileges</link>. <itemizedlist>
+           <listitem>
+             <para>Membership in the <emphasis role="bold">system:administrators</emphasis> group. Members are entitled to issue any
+             <emphasis role="bold">pts</emphasis> command and those <emphasis role="bold">fs</emphasis> commands that set volume
+             quota. By default, they also implicitly have the <emphasis role="bold">a</emphasis> (<emphasis
+             role="bold">administer</emphasis>) and <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>)
+             permissions on every ACL in the file tree even if the ACL does not include an entry for them.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The <computeroutput>ADMIN</computeroutput> flag on the Authentication Database entry. An administrator with this
+             flag can issue any <emphasis role="bold">kas</emphasis> command.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Inclusion in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. An administrator whose username
+             appears in this file can issue any <emphasis role="bold">bos</emphasis>, <emphasis role="bold">vos</emphasis>, or
+             <emphasis role="bold">backup</emphasis> command (although some <emphasis role="bold">backup</emphasis> commands require
+             additional privilege as described in <link linkend="HDRWQ260">Granting Administrative Privilege to Backup
+             Operators</link>).</para>
+           </listitem>
+         </itemizedlist></para>
+     </sect2>
+ 
+     <sect2 id="Header_89">
+       <title>Authorization Checking versus Authentication</title>
+ 
+       <para>AFS distinguishes between authentication and authorization checking. Authentication refers to the process of proving
+       identity. Authorization checking refers to the process of verifying that an authenticated identity is allowed to perform a
+       certain action.</para>
+ 
+       <para>AFS implements authentication at the level of connections. Each time two parties establish a new connection, they
+       mutually authenticate. In general, each issue of an AFS command establishes a new connection between AFS server process and
+       client.</para>
+ 
+       <para>AFS implements authorization checking at the level of server machines. If authorization checking is enabled on a server
+       machine, then all of the server processes running on it provide services only to authorized users. If authorization checking
+       is disabled on a server machine, then all of the server processes perform any action for anyone. Obviously, disabling
+       authorization checking is an extreme security exposure. For more information, see <link linkend="HDRWQ123">Managing
+       Authentication and Authorization Requirements</link>.</para>
+     </sect2>
+ 
+     <sect2 id="HDRWQ74">
+       <title>Improving Security in Your Cell</title>
+ 
+       <indexterm>
+         <primary>security</primary>
+ 
+         <secondary>suggestions for improving</secondary>
+       </indexterm>
+ 
+       <para>You can improve the level of security in your cell by configuring user accounts, server machines, and system
+       administrator accounts in the indicated way.</para>
+ 
+       <formalpara>
+         <title>User Accounts</title>
+ 
+         <para><itemizedlist>
+             <listitem>
+               <para>Use an AFS-modified login utility, or include the <emphasis role="bold">-setpag</emphasis> flag to the <emphasis
+               role="bold">klog</emphasis> command, to associate the credential structure that houses tokens with a PAG rather than a
+               UNIX UID. This prevents users from inheriting someone else's tokens by assuming their UNIX identity. For further
+               discussion, see <link linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>.</para>
+             </listitem>
+ 
+             <listitem>
+               <para>Encourage users to issue the <emphasis role="bold">unlog</emphasis> command to destroy their tokens before
+               logging out. This forestalls attempts to access tokens left behind kernel memory. Consider including the <emphasis
+               role="bold">unlog</emphasis> command in every user's <emphasis role="bold">.logout</emphasis> file or
+               equivalent.</para>
+             </listitem>
+           </itemizedlist></para>
+       </formalpara>
+ 
+       <formalpara>
+         <title>Server Machines</title>
+ 
+         <para><itemizedlist>
+             <listitem>
+               <para>Disable authorization checking only in emergencies or for very brief periods of time. It is best to work at the
+               console of the affected machine during this time, to prevent anyone else from accessing the machine through the
+               keyboard.</para>
+             </listitem>
+ 
+             <listitem>
+               <para>Change the AFS server encryption key on a frequent and regular schedule. Make it difficult to guess (a long
+               string including nonalphabetic characters, for instance). Unlike user passwords, the password from which the AFS key
+               is derived can be longer than eight characters, because it is never used during login. The <emphasis role="bold">kas
+               setpassword</emphasis> command accepts a password hundreds of characters long. For instructions, see <link
+               linkend="HDRWQ355">Managing Server Encryption Keys</link>.</para>
+             </listitem>
+ 
+             <listitem>
+               <para>As much as possible, limit the number of people who can login at a server machine's console or remotely.
+               Imposing this limit is an extra security precaution rather than a necessity. The machine cannot serve as an AFS client
+               in this case.</para>
+             </listitem>
+ 
+             <listitem>
+               <para>Particularly limit access to the local superuser <emphasis role="bold">root</emphasis> account on a server
+               machine. The local superuser <emphasis role="bold">root</emphasis> has free access to important administrative
+               subdirectories of the <emphasis role="bold">/usr/afs</emphasis> directory, as described in <link linkend="HDRWQ53">AFS
+               Files on the Local Disk</link>.</para>
+ 
+               <indexterm>
+                 <primary>root superuser</primary>
+ 
+                 <secondary>limiting logins</secondary>
+               </indexterm>
+             </listitem>
+ 
+             <listitem>
+               <para>As in any computing environment, server machines must be located in a secured area. Any other security measures
+               are effectively worthless if unauthorized people can access the computer hardware.</para>
+             </listitem>
+           </itemizedlist></para>
+       </formalpara>
+ 
+       <formalpara>
+         <title>System Administrators</title>
+ 
+         <para><itemizedlist>
+             <listitem>
+               <para>Limit the number of system administrators in your cell. Limit the use of system administrator accounts on
+               publicly accessible workstations. Such machines are not secure, so unscrupulous users can install programs that try to
+               steal tokens or passwords. If administrators must use publicly accessible workstations at times, they must issue the
+               <emphasis role="bold">unlog</emphasis> command before leaving the machine.</para>
+             </listitem>
+ 
+             <listitem>
+               <para>Create an administrative account for each administrator separate from the personal account, and assign AFS
+               privileges only to the administrative account. The administrators must authenticate to the administrative accounts to
+               perform duties that require privilege, which provides a useful audit trail as well.</para>
+             </listitem>
+ 
+             <listitem>
+               <para>Administrators must not leave a machine unattended while they have valid tokens. Issue the <emphasis
+               role="bold">unlog</emphasis> command before leaving.</para>
+             </listitem>
+ 
+             <listitem>
+               <para>Use the <emphasis role="bold">-lifetime</emphasis> argument to the <emphasis role="bold">kas
+               setfields</emphasis> command to set the token lifetime for administrative accounts to a fairly short amount of time.
+               The default lifetime for AFS tokens is 25 hours, but 30 or 60 minutes is possibly a more reasonable lifetime for
+               administrative tokens. The tokens for administrators who initiate AFS Backup System operations must last somewhat
+               longer, because it can take several hours to complete some dump operations, depending on the speed of the tape device
+               and the network connecting it to the file server machines that house the volumes is it accessing.</para>
+             </listitem>
+ 
+             <listitem>
+               <para>Limit administrators' use of the <emphasis role="bold">telnet</emphasis> program. It sends unencrypted passwords
+               across the network. Similarly, limit use of other remote programs such as <emphasis role="bold">rsh</emphasis> and
+               <emphasis role="bold">rcp</emphasis>, which send unencrypted tokens across the network.</para>
+             </listitem>
+           </itemizedlist></para>
+       </formalpara>
+     </sect2>
+ 
+     <sect2 id="HDRWQ75">
+       <title>A More Detailed Look at Mutual Authentication</title>
+ 
+       <indexterm>
+         <primary>mutual authentication</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>distributed file system</primary>
+ 
+         <secondary>security issues</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>shared secret</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>server encryption key</primary>
+ 
+         <secondary>defined</secondary>
+       </indexterm>
+ 
+       <para>As in any file system, security is a prime concern in AFS. A file system that makes file sharing easy is not useful if
+       it makes file sharing mandatory, so AFS incorporates several features that prevent unauthorized users from accessing data.
+       Security in a networked environment is difficult because almost all procedures require transmission of information across
+       wires that almost anyone can tap into. Also, many machines on networks are powerful enough that unscrupulous users can monitor
+       transactions or even intercept transmissions and fake the identity of one of the participants.</para>
+ 
+       <para>The most effective precaution against eavesdropping and information theft or fakery is for servers and clients to accept
+       the claimed identity of the other party only with sufficient proof. In other words, the nature of the network forces all
+       parties on the network to assume that the other party in a transaction is not genuine until proven so. Mutual authentication
+       is the means through which parties prove their genuineness.</para>
+ 
+       <para>Because the measures needed to prevent fakery must be quite sophisticated, the implementation of mutual authentication
+       procedures is complex. The underlying concept is simple, however: parties prove their identities by demonstrating knowledge of
+       a shared secret. A shared secret is a piece of information known only to the parties who are mutually authenticating (they can
+       sometimes learn it in the first place from a trusted third party or some other source). The party who originates the
+       transaction presents the shared secret and refuses to accept the other party as valid until it shows that it knows the secret
+       too.</para>
+ 
+       <para>The most common form of shared secret in AFS transactions is the encryption key, also referred to simply as a key. The
+       two parties use their shared key to encrypt the packets of information they send and to decrypt the ones they receive.
+       Encryption using keys actually serves two related purposes. First, it protects messages as they cross the network, preventing
+       anyone who does not know the key from eavesdropping. Second, ability to encrypt and decrypt messages successfully indicates
+       that the parties are using the key (it is their shared secret). If they are using different keys, messages remain scrambled
+       and unintelligible after decryption.</para>
+ 
+       <para>The following sections describe AFS's mutual authentication procedures in more detail. Feel free to skip these sections
+       if you are not interested in the mutual authentication process.</para>
+ 
+       <sect3 id="Header_92">
+         <title>Simple Mutual Authentication</title>
+ 
+         <para>Simple mutual authentication involves only one encryption key and two parties, generally a client and server. The
+         client contacts the server by sending a challenge message encrypted with a key known only to the two of them. The server
+         decrypts the message using its key, which is the same as the client's if they really do share the same secret. The server
+         responds to the challenge and uses its key to encrypt its response. The client uses its key to decrypt the server's
+         response, and if it is correct, then the client can be sure that the server is genuine: only someone who knows the same key
+         as the client can decrypt the challenge and answer it correctly. On its side, the server concludes that the client is
+         genuine because the challenge message made sense when the server decrypted it.</para>
+ 
+         <para>AFS uses simple mutual authentication to verify user identities during the first part of the login procedure. In that
+         case, the key is based on the user's password.</para>
+       </sect3>
+ 
+       <sect3 id="HDRWQ76">
+         <title>Complex Mutual Authentication</title>
+ 
+         <para>Complex mutual authentication involves three encryption keys and three parties. All secure AFS transactions (except
+         the first part of the login process) employ complex mutual authentication.</para>
+ 
+         <indexterm>
+           <primary>ticket-granter</primary>
+         </indexterm>
+ 
+         <indexterm>
+           <primary>server encryption key</primary>
+         </indexterm>
+ 
+         <indexterm>
+           <primary>tokens</primary>
+ 
+           <secondary>data in</secondary>
+         </indexterm>
+ 
+         <para>When a client wishes to communicate with a server, it first contacts a third party called a ticket-granter. The
+         ticket-granter and the client mutually authenticate using the simple procedure. When they finish, the ticket-granter gives
+         the client a server ticket (or simply ticket) as proof that it (the ticket-granter) has preverified the identity of the
+         client. The ticket-granter encrypts the ticket with the first of the three keys, called the server encryption key because it
+         is known only to the ticket-granter and the server the client wants to contact. The client does not know this key.</para>
+ 
+         <para>The ticket-granter sends several other pieces of information along with the ticket. They enable the client to use the
+         ticket effectively despite being unable to decrypt the ticket itself. Along with the ticket, the items constitute a token:
+         <itemizedlist>
+             <listitem>
+               <para>A session key, which is the second encryption key involved in mutual authentication. The ticket-granter invents
+               the session key at random as the shared secret between client and server. For reasons explained further below, the
+               ticket-granter also puts a copy of the session key inside the ticket. The client and server use the session key to
+               encrypt messages they send to one another during their transactions. The ticket-granter invents a different session
+               key for each connection between a client and a server (there can be several transactions during a single
+               connection).</para>
+ 
+               <indexterm>
+                 <primary>session key</primary>
+               </indexterm>
+             </listitem>
+ 
+             <listitem>
+               <para>The name of the server for which the ticket is valid (and so which server encryption key encrypts the ticket
+               itself).</para>
+             </listitem>
+ 
+             <listitem>
+               <para>A ticket lifetime indicator. The default lifetime of AFS server tickets is 100 hours. If the client wants to
+               contact the server again after the ticket expires, it must contact the ticket-granter to get a new ticket.</para>
+             </listitem>
+           </itemizedlist></para>
+ 
+         <para>The ticket-granter seals the entire token with the third key involved in complex mutual authentication--the key known
+         only to it (the ticket-granter) and the client. In some cases, this third key is derived from the password of the human user
+         whom the client represents.</para>
+ 
+         <para>Now that the client has a valid server ticket, it is ready to contact the server. It sends the server two things:
+         <itemizedlist>
+             <listitem>
+               <para>The server ticket. This is encrypted with the server encryption key.</para>
+             </listitem>
+ 
+             <listitem>
+               <para>Its request message, encrypted with the session key. Encrypting the message protects it as it crosses the
+               network, since only the server/client pair for whom the ticket-granter invented the session key know it.</para>
+             </listitem>
+           </itemizedlist></para>
+ 
+         <para>At this point, the server does not know the session key, because the ticket-granter just created it. However, the
+         ticket-granter put a copy of the session key inside the ticket. The server uses the server encryption key to decrypts the
+         ticket and learns the session key. It then uses the session key to decrypt the client's request message. It generates a
+         response and sends it to the client. It encrypts the response with the session key to protect it as it crosses the
+         network.</para>
+ 
+         <para>This step is the heart of mutual authentication between client and server, because it proves to both parties that they
+         know the same secret: <itemizedlist>
+             <listitem>
+               <para>The server concludes that the client is authorized to make a request because the request message makes sense
+               when the server decrypts it using the session key. If the client uses a different session key than the one the server
+               finds inside the ticket, then the request message remains unintelligible even after decryption. The two copies of the
+               session key (the one inside the ticket and the one the client used) can only be the same if they both came from the
+               ticket-granter. The client cannot fake knowledge of the session key because it cannot look inside the ticket, sealed
+               as it is with the server encryption key known only to the server and the ticket-granter. The server trusts the
+               ticket-granter to give tokens only to clients with whom it (the ticket-granter) has authenticated, so the server
+               decides the client is legitimate.</para>
+ 
+               <para>(Note that there is no direct communication between the ticket-granter and the server, even though their
+               relationship is central to ticket-based mutual authentication. They interact only indirectly, via the client's
+               possession of a ticket sealed with their shared secret.)</para>
+             </listitem>
+ 
+             <listitem>
+               <para>The client concludes that the server is genuine and trusts the response it gets back from the server, because
+               the response makes sense after the client decrypts it using the session key. This indicates that the server encrypted
+               the response with the same session key as the client knows. The only way for the server to learn that matching session
+               key is to decrypt the ticket first. The server can only decrypt the ticket because it shares the secret of the server
+               encryption key with the ticket-granter. The client trusts the ticket-granter to give out tickets only for legitimate
+               servers, so the client accepts a server that can decrypt the ticket as genuine, and accepts its response.</para>
+             </listitem>
+           </itemizedlist></para>
+       </sect3>
+     </sect2>
+   </sect1>
+ 
+   <sect1 id="HDRWQ77">
+     <title>Backing Up AFS Data</title>
+ 
+     <para>AFS provides two related facilities that help the administrator back up AFS data: backup volumes and the AFS Backup
+     System.</para>
+ 
+     <sect2 id="Header_95">
+       <title>Backup Volumes</title>
+ 
+       <para>The first facility is the backup volume, which you create by cloning a read/write volume. The backup volume is read-only
+       and so preserves the state of the read/write volume at the time the clone is made.</para>
+ 
+       <para>Backup volumes can ease administration if you mount them in the file system and make their contents available to users.
+       For example, it often makes sense to mount the backup version of each user volume as a subdirectory of the user's home
+       directory. A conventional name for this mount point is <emphasis role="bold">OldFiles</emphasis>. Create a new version of the
+       backup volume (that is, reclone the read/write) once a day to capture any changes that were made since the previous backup. If
+       a user accidentally removes or changes data, the user can restore it from the backup volume, rather than having to ask you to
+       restore it.</para>
+ 
+       <para>The OpenAFS User Guide does not mention backup volumes, so regular users do not know about them if you decide not to use
+       them. This implies that if you <emphasis role="bold">do</emphasis> make backup versions of user volumes, you need to tell your
+       users about how the backup works and where you have mounted it.</para>
+ 
+       <para>Users are often concerned that the data in a backup volume counts against their volume quota and some of them even want
+       to remove the <emphasis role="bold">OldFiles</emphasis> mount point. It does not, because the backup volume is a separate
+       volume. The only amount of space it uses in the user's volume is the amount needed for the mount point, which is about the
+       same as the amount needed for a standard directory element.</para>
+ 
+       <para>Backup volumes are discussed in detail in <link linkend="HDRWQ201">Creating Backup Volumes</link>.</para>
+     </sect2>
+ 
+     <sect2 id="Header_96">
+       <title>The AFS Backup System</title>
+ 
+       <para>Backup volumes can reduce restoration requests, but they reside on disk and so do not protect data from loss due to
+       hardware failure. Like any file system, AFS is vulnerable to this sort of data loss.</para>
+ 
+       <para>To protect your cell's users from permanent loss of data, you are strongly urged to back up your file system to tape on
+       a regular and frequent schedule. The AFS Backup System is available to ease the administration and performance of backups. For
+       detailed information about the AFS Backup System, see <link linkend="HDRWQ248">Configuring the AFS Backup System</link> and
+       <link linkend="HDRWQ283">Backing Up and Restoring AFS Data</link>.</para>
+ 
+       <indexterm>
+         <primary>remote services</primary>
+ 
+         <secondary>modifications for AFS</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>commands</primary>
+ 
+         <secondary>ftp (AFS compared to UNIX)</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>ftpd command</primary>
+ 
+         <secondary>AFS compared to UNIX</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>commands</primary>
+ 
+         <secondary>ftpd (AFS compared to UNIX)</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>inetd command</primary>
+ 
+         <secondary>AFS compared to UNIX</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>commands</primary>
+ 
+         <secondary>inetd (AFS compared to UNIX)</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>rcp command</primary>
+ 
+         <secondary>AFS compared to UNIX</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>commands</primary>
+ 
+         <secondary>rcp (AFS compared to UNIX)</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>rlogind command</primary>
+ 
+         <secondary>AFS compared to UNIX</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>commands</primary>
+ 
+         <secondary>rlogind (AFS compared to UNIX)</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>rsh command</primary>
+ 
+         <secondary>AFS compared to UNIX</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>commands</primary>
+ 
+         <secondary>rsh (AFS compared to UNIX)</secondary>
+       </indexterm>
+     </sect2>
+   </sect1>
+ 
+   <sect1 id="HDRWQ78">
+     <title>Using UNIX Remote Services in the AFS Environment</title>
+ 
+     <para>The AFS distribution includes modified versions of several standard UNIX commands, daemons and programs that provide
+     remote services, including the following: <itemizedlist>
+         <listitem>
+           <para>The <emphasis role="bold">ftpd</emphasis> program</para>
+         </listitem>
+ 
+         <listitem>
+           <para>The <emphasis role="bold">inetd</emphasis> daemon</para>
+         </listitem>
+ 
+         <listitem>
+           <para>The <emphasis role="bold">rcp</emphasis> program</para>
+         </listitem>
+ 
+         <listitem>
+           <para>The <emphasis role="bold">rlogind</emphasis> daemon</para>
+         </listitem>
+ 
+         <listitem>
+           <para>The <emphasis role="bold">rsh</emphasis> command</para>
+         </listitem>
+       </itemizedlist></para>
+ 
+     <para>These modifications enable the commands to handle AFS authentication information (tokens). This enables issuers to be
+     recognized on the remote machine as an authenticated AFS user.</para>
+ 
+     <para>Replacing the standard versions of these programs in your file tree with the AFS-modified versions is optional. It is
+     likely that AFS's transparent access reduces the need for some of the programs anyway, especially those involved in transferring
+     files from machine to machine, like the <emphasis role="bold">ftpd</emphasis> and <emphasis role="bold">rcp</emphasis>
+     programs.</para>
+ 
+     <para>If you decide to use the AFS versions of these commands, be aware that several of them are interdependent. For example,
+     the passing of AFS authentication information works correctly with the <emphasis role="bold">rcp</emphasis> command only if you
+     are using the AFS version of both the <emphasis role="bold">rcp</emphasis> and <emphasis role="bold">inetd</emphasis>
+     commands.</para>
+ 
+     <para>The conventional installation location for the modified remote commands are the <emphasis
+     role="bold">/usr/afsws/bin</emphasis> and <emphasis role="bold">/usr/afsws/etc</emphasis> directories. To learn more about
+     commands' functionality, see their reference pages in the OpenAFS Administration Reference.</para>
+   </sect1>
+ 
+   <sect1 id="HDRWQ79">
+     <title>Accessing AFS through NFS</title>
+ 
+     <para>Users of NFS client machines can access the AFS filespace by mounting the <emphasis role="bold">/afs</emphasis> directory
+     of an AFS client machine that is running the NFS/AFS Translator. This is a particular advantage in cells already running NFS who
+     want to access AFS using client machines for which AFS is not available. See <link linkend="HDRWQ595">Appendix A, Managing the
+     NFS/AFS Translator</link>.</para>
+   </sect1>
+ </chapter>
Index: openafs/doc/xml/AdminGuide/auagd008.xml
diff -c /dev/null openafs/doc/xml/AdminGuide/auagd008.xml:1.1.8.3
*** /dev/null	Sat May 30 21:40:41 2009
--- openafs/doc/xml/AdminGuide/auagd008.xml	Wed May 13 22:25:59 2009
***************
*** 0 ****
--- 1,5711 ----
+ <?xml version="1.0" encoding="UTF-8"?>
+ <chapter id="HDRWQ80">
+   <title>Administering Server Machines</title>
+ 
+   <indexterm>
+     <primary>server machine</primary>
+ 
+     <secondary>administering</secondary>
+   </indexterm>
+ 
+   <indexterm>
+     <primary>administering</primary>
+ 
+     <secondary>server machine</secondary>
+   </indexterm>
+ 
+   <para>This chapter describes how to administer an AFS server machine. It describes the following configuration information and
+   administrative tasks: <itemizedlist>
+       <listitem>
+         <para>The binary and configuration files that must reside in the subdirectories of the <emphasis
+         role="bold">/usr/afs</emphasis> directory on every server machine's local disk; see <link linkend="HDRWQ83">Local Disk Files
+         on a Server Machine</link>.</para>
+       </listitem>
+ 
+       <listitem>
+         <para>The various <emphasis>roles</emphasis> or functions that an AFS server machine can perform, and how to determine which
+         machines are taking a role; see <link linkend="HDRWQ90">The Four Roles for File Server Machines</link>.</para>
+       </listitem>
+ 
+       <listitem>
+         <para>How to maintain database server machines; see <link linkend="HDRWQ101">Administering Database Server
+         Machines</link>.</para>
+       </listitem>
+ 
+       <listitem>
+         <para>How to maintain the list of database server machines in the <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis>
+         file; see <link linkend="HDRWQ118">Maintaining the Server CellServDB File</link>.</para>
+       </listitem>
+ 
+       <listitem>
+         <para>How to control authorization checking on a server machine; see <link linkend="HDRWQ123">Managing Authentication and
+         Authorization Requirements</link>.</para>
+       </listitem>
+ 
+       <listitem>
+         <para>How to install new disks or partitions on a file server machine; see <link linkend="HDRWQ130">Adding or Removing Disks
+         and Partitions</link>.</para>
+       </listitem>
+ 
+       <listitem>
+         <para>How to change a server machine's IP addresses and manager VLDB server entries; see <link linkend="HDRWQ138">Managing
+         Server IP Addresses and VLDB Server Entries</link>.</para>
+       </listitem>
+ 
+       <listitem>
+         <para>How to reboot a file server machine; see <link linkend="HDRWQ139">Rebooting a Server Machine</link>.</para>
+       </listitem>
+     </itemizedlist></para>
+ 
+   <para>To learn how to install and configure a new server machine, see the <emphasis>OpenAFS Quick Beginnings</emphasis>.</para>
+ 
+   <para>To learn how to administer the server processes themselves, see <link linkend="HDRWQ142">Monitoring and Controlling Server
+   Processes</link>.</para>
+ 
+   <para>To learn how to administer volumes, see <link linkend="HDRWQ174">Managing Volumes</link>.</para>
+ 
+   <sect1 id="HDRWQ81">
+     <title>Summary of Instructions</title>
+ 
+     <para>This chapter explains how to perform the following tasks by using the indicated commands:</para>
+ 
+     <informaltable frame="none">
+       <tgroup cols="2">
+         <colspec colwidth="70*" />
+ 
+         <colspec colwidth="30*" />
+ 
+         <tbody>
+           <row>
+             <entry>Install new binaries</entry>
+ 
+             <entry><emphasis role="bold">bos install</emphasis></entry>
+           </row>
+ 
+           <row>
+             <entry>Examine binary check-and-restart time</entry>
+ 
+             <entry><emphasis role="bold">bos getrestart</emphasis></entry>
+           </row>
+ 
+           <row>
+             <entry>Set binary check-and-restart time</entry>
+ 
+             <entry><emphasis role="bold">bos setrestart</emphasis></entry>
+           </row>
+ 
+           <row>
+             <entry>Examine compilation dates on binary files</entry>
+ 
+             <entry><emphasis role="bold">bos getdate</emphasis></entry>
+           </row>
+ 
+           <row>
+             <entry>Restart a process to use new binaries</entry>
+ 
+             <entry><emphasis role="bold">bos restart</emphasis></entry>
+           </row>
+ 
+           <row>
+             <entry>Revert to old version of binaries</entry>
+ 
+             <entry><emphasis role="bold">bos uninstall</emphasis></entry>
+           </row>
+ 
+           <row>
+             <entry>Remove obsolete <emphasis role="bold">.BAK</emphasis> and <emphasis role="bold">.OLD</emphasis> versions</entry>
+ 
+             <entry><emphasis role="bold">bos prune</emphasis></entry>
+           </row>
+ 
+           <row>
+             <entry>List partitions on a file server machine</entry>
+ 
+             <entry><emphasis role="bold">vos listpart</emphasis></entry>
+           </row>
+ 
+           <row>
+             <entry>Shutdown AFS server processes</entry>
+ 
+             <entry><emphasis role="bold">bos shutdown</emphasis></entry>
+           </row>
+ 
+           <row>
+             <entry>List volumes on a partition</entry>
+ 
+             <entry><emphasis role="bold">vos listvldb</emphasis></entry>
+           </row>
+ 
+           <row>
+             <entry>Move read/write volumes</entry>
+ 
+             <entry><emphasis role="bold">vos move</emphasis></entry>
+           </row>
+ 
+           <row>
+             <entry>List a cell's database server machines</entry>
+ 
+             <entry><emphasis role="bold">bos listhosts</emphasis></entry>
+           </row>
+ 
+           <row>
+             <entry>Add a database server machine to server <emphasis role="bold">CellServDB</emphasis> file</entry>
+ 
+             <entry><emphasis role="bold">bos addhost</emphasis></entry>
+           </row>
+ 
+           <row>
+             <entry>Remove a database server machine from server <emphasis role="bold">CellServDB</emphasis> file</entry>
+ 
+             <entry><emphasis role="bold">bos removehost</emphasis></entry>
+           </row>
+ 
+           <row>
+             <entry>Set authorization checking requirements</entry>
+ 
+             <entry><emphasis role="bold">bos setauth</emphasis></entry>
+           </row>
+ 
+           <row>
+             <entry>Prevent authentication for <emphasis role="bold">bos</emphasis>, <emphasis role="bold">pts</emphasis>, and
+             <emphasis role="bold">vos</emphasis> commands</entry>
+ 
+             <entry>Include <emphasis role="bold">-noauth</emphasis> flag</entry>
+           </row>
+ 
+           <row>
+             <entry>Prevent authentication for kas commands</entry>
+ 
+             <entry>Include <emphasis role="bold">-noauth</emphasis> flag on some commands or issue <emphasis
+             role="bold">noauthentication</emphasis> while in interactive mode</entry>
+           </row>
+ 
+           <row>
+             <entry>Display all VLDB server entries</entry>
+ 
+             <entry><emphasis role="bold">vos listaddrs</emphasis></entry>
+           </row>
+ 
+           <row>
+             <entry>Remove a VLDB server entry</entry>
+ 
+             <entry><emphasis role="bold">vos changeaddr</emphasis></entry>
+           </row>
+ 
+           <row>
+             <entry>Reboot a server machine remotely</entry>
+ 
+             <entry><emphasis role="bold">bos exec</emphasis> <emphasis>reboot_command</emphasis></entry>
+           </row>
+         </tbody>
+       </tgroup>
+     </informaltable>
+   </sect1>
+ 
+   <sect1 id="HDRWQ83">
+     <title>Local Disk Files on a Server Machine</title>
+ 
+     <para>Several types of files must reside in the subdirectories of the <emphasis role="bold">/usr/afs</emphasis> directory on an
+     AFS server machine's local disk. They include binaries, configuration files, the administrative database files (on database
+     server machines), log files, and volume header files.</para>
+ 
+     <para><emphasis role="bold">Note for Windows users:</emphasis> Some files described in this document possibly do not exist on
+     machines that run a Windows operating system. Also, Windows uses a backslash (<emphasis role="bold">\</emphasis>) rather than a
+     forward slash (<emphasis role="bold">/</emphasis>) to separate the elements in a pathname.</para>
+ 
+     <indexterm>
+       <primary>usr/afs/bin directory on server machines</primary>
+ 
+       <secondary>contents listed</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>directory</primary>
+ 
+       <secondary>/usr/afs/bin on server machines</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>server process binaries</primary>
+ 
+       <secondary>in /usr/afs/bin</secondary>
+     </indexterm>
+ 
+     <sect2 id="HDRWQ84">
+       <title>Binaries in the /usr/afs/bin Directory</title>
+ 
+       <para>The <emphasis role="bold">/usr/afs/bin</emphasis> directory stores the AFS server process and command suite binaries
+       appropriate for the machine's system (CPU and operating system) type. If a process has both a server portion and a client
+       portion (as with the Update Server) or if it has separate components (as with the <emphasis role="bold">fs</emphasis>
+       process), each component resides in a separate file.</para>
+ 
+       <para>To ensure predictable system performance, all file server machines must run the same AFS build version of a given
+       process. To maintain consistency easily, use the Update Server process to distribute binaries from a binary distribution
+       machine of each system type, as described further in <link linkend="HDRWQ93">Binary Distribution Machines</link>.</para>
+ 
+       <para>It is best to keep the binaries for all processes in the <emphasis role="bold">/usr/afs/bin</emphasis> directory, even
+       if you do not run the process actively on the machine. It simplifies the process of reconfiguring machines (for example,
+       adding database server functionality to an existing file server machine). Similarly, it is best to keep the command suite
+       binaries in the directory, even if you do not often issue commands while working on the server machine. It enables you to
+       issue commands during recovery from server and machine outages.</para>
+ 
+       <para>The following lists the binary files in the <emphasis role="bold">/usr/afs/bin</emphasis> directory that are directly
+       related to the AFS server processes or command suites. Other binaries (for example, for the <emphasis
+       role="bold">klog</emphasis> command) sometimes appear in this directory on a particular file server machine's disk or in an
+       AFS distribution. <variablelist>
+           <indexterm>
+             <primary>files</primary>
+ 
+             <secondary>backup command binary</secondary>
+           </indexterm>
+ 
+           <indexterm>
+             <primary>backup commands</primary>
+ 
+             <secondary>binary in /usr/afs/bin</secondary>
+           </indexterm>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">backup</emphasis></term>
+ 
+             <listitem>
+               <para>The command suite for the AFS Backup System (the binary for the Backup Server is <emphasis
+               role="bold">buserver</emphasis>).</para>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>bos command binary</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>bos commands</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">bos</emphasis></term>
+ 
+             <listitem>
+               <para>The command suite for communicating with the Basic OverSeer (BOS) Server (the binary for the BOS Server is
+               <emphasis role="bold">bosserver</emphasis>).</para>
+ 
+               <indexterm>
+                 <primary>bosserver</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>bosserver</primary>
+ 
+                 <secondary></secondary>
+ 
+                 <see>BOS Server</see>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>bosserver binary</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>programs</primary>
+ 
+                 <secondary>bosserver</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>processes</primary>
+ 
+                 <secondary>BOS Server, binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>BOS Server</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">bosserver</emphasis></term>
+ 
+             <listitem>
+               <para>The binary for the Basic OverSeer (BOS) Server process.</para>
+ 
+               <indexterm>
+                 <primary>buserver</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>buserver</primary>
+ 
+                 <secondary></secondary>
+ 
+                 <see>Backup Server</see>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>buserver</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>programs</primary>
+ 
+                 <secondary>buserver</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>processes</primary>
+ 
+                 <secondary>Backup Server, binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>Backup Server</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">buserver</emphasis></term>
+ 
+             <listitem>
+               <para>The binary for the Backup Server process.</para>
+ 
+               <indexterm>
+                 <primary>fileserver</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>fileserver</primary>
+ 
+                 <secondary></secondary>
+ 
+                 <see>File Server</see>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>fileserver</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>programs</primary>
+ 
+                 <secondary>fileserver</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>processes</primary>
+ 
+                 <secondary>File Server, binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>File Server</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">fileserver</emphasis></term>
+ 
+             <listitem>
+               <para>The binary for the File Server component of the <emphasis role="bold">fs</emphasis> process.</para>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>kas command binary</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>kas commands</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">kas</emphasis></term>
+ 
+             <listitem>
+               <para>The command suite for communicating with the Authentication Server (the binary for the Authentication Server is
+               <emphasis role="bold">kaserver</emphasis>).</para>
+ 
+               <indexterm>
+                 <primary>kaserver process</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>kaserver process</primary>
+ 
+                 <secondary></secondary>
+ 
+                 <see>Authentication Server</see>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>kaserver binary file</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>programs</primary>
+ 
+                 <secondary>kaserver</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>processes</primary>
+ 
+                 <secondary>Authentication Server, binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>Authentication Server</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">kaserver</emphasis></term>
+ 
+             <listitem>
+               <para>The binary for the Authentication Server process.</para>
+ 
+               <indexterm>
+                 <primary>ntpd</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>ntpd</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>programs</primary>
+ 
+                 <secondary>ntpd</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>processes</primary>
+ 
+                 <secondary>NTPD, binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>NTPD</primary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>Network Time Protocol Daemon</primary>
+ 
+                 <secondary></secondary>
+ 
+                 <see>NTPD</see>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">ntpd</emphasis></term>
+ 
+             <listitem>
+               <para>The binary for the Network Time Protocol Daemon (NTPD). AFS redistributes this binary and uses the <emphasis
+               role="bold">runntp</emphasis> program to configure and initialize the NTPD process.</para>
+ 
+               <indexterm>
+                 <primary>ntpdc</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>ntpdc</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>programs</primary>
+ 
+                 <secondary>ntpdc</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">ntpdc</emphasis></term>
+ 
+             <listitem>
+               <para>A debugging utility furnished with the <emphasis role="bold">ntpd</emphasis> program.</para>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>pts command binary</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>pts commands</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">pts</emphasis></term>
+ 
+             <listitem>
+               <para>The command suite for communicating with the Protection Server process (the binary for the Protection Server is
+               <emphasis role="bold">ptserver</emphasis>).</para>
+ 
+               <indexterm>
+                 <primary>ptserver process</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>ptserver process</primary>
+ 
+                 <secondary></secondary>
+ 
+                 <see>Protection Server</see>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>ptserver binary</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>programs</primary>
+ 
+                 <secondary>ptserver</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>processes</primary>
+ 
+                 <secondary>Protection Server, binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>Protection Server</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">ptserver</emphasis></term>
+ 
+             <listitem>
+               <para>The binary for the Protection Server process.</para>
+ 
+               <indexterm>
+                 <primary>runntp</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>runntp</primary>
+ 
+                 <secondary></secondary>
+ 
+                 <see>NTPD</see>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>runntp</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>programs</primary>
+ 
+                 <secondary>runntp</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">runntp</emphasis></term>
+ 
+             <listitem>
+               <para>The binary for the program used to configure NTPD most appropriately for use with AFS.</para>
+ 
+               <indexterm>
+                 <primary>Salvager</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>Salvager</primary>
+ 
+                 <secondary></secondary>
+ 
+                 <see>Salvager</see>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>salvager</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>programs</primary>
+ 
+                 <secondary>salvager</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>processes</primary>
+ 
+                 <secondary>Salvager, binary in /usr/afs/bin</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">salvager</emphasis></term>
+ 
+             <listitem>
+               <para>The binary for the Salvager component of the <emphasis role="bold">fs</emphasis> process.</para>
+ 
+               <indexterm>
+                 <primary>udebug</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>udebug</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>commands</primary>
+ 
+                 <secondary>udebug</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>programs</primary>
+ 
+                 <secondary>udebug</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">udebug</emphasis></term>
+ 
+             <listitem>
+               <para>The binary for a program that reports the status of AFS's distributed database technology, Ubik.</para>
+ 
+               <indexterm>
+                 <primary>upclient</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>upclient</primary>
+ 
+                 <secondary></secondary>
+ 
+                 <see>Update Server</see>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>upclient</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>programs</primary>
+ 
+                 <secondary>upclient</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>processes</primary>
+ 
+                 <secondary>Update Server, binaries in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>Update Server</primary>
+ 
+                 <secondary>binaries in /usr/afs/bin</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">upclient</emphasis></term>
+ 
+             <listitem>
+               <para>The binary for the client portion of the Update Server process.</para>
+ 
+               <indexterm>
+                 <primary>upserver</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>upserver</primary>
+ 
+                 <secondary></secondary>
+ 
+                 <see>Update Server</see>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>upserver</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>programs</primary>
+ 
+                 <secondary>upserver</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">upserver</emphasis></term>
+ 
+             <listitem>
+               <para>The binary for the server portion of the Update Server process.</para>
+ 
+               <indexterm>
+                 <primary>vlserver</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>vlserver</primary>
+ 
+                 <secondary></secondary>
+ 
+                 <see>VL Server</see>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>vlserver</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>programs</primary>
+ 
+                 <secondary>vlserver</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>processes</primary>
+ 
+                 <secondary>VL Server, binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>VL Server</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>Volume Location Server</primary>
+ 
+                 <secondary></secondary>
+ 
+                 <see>VL Server</see>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">vlserver</emphasis></term>
+ 
+             <listitem>
+               <para>The binary for the Volume Location (VL) Server process.</para>
+ 
+               <indexterm>
+                 <primary>volserver</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>volserver</primary>
+ 
+                 <secondary></secondary>
+ 
+                 <see>Volume Server</see>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>volserver</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>programs</primary>
+ 
+                 <secondary>volserver</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>processes</primary>
+ 
+                 <secondary>Volume Server, binary in /usr/afs/bin</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>Volume Server</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">volserver</emphasis></term>
+ 
+             <listitem>
+               <para>The binary for the Volume Server component of the <emphasis role="bold">fs</emphasis> process.</para>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>vos command binary</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>vos commands</primary>
+ 
+                 <secondary>binary in /usr/afs/bin</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">vos</emphasis></term>
+ 
+             <listitem>
+               <para>The command suite for communicating with the Volume and VL Server processes (the binaries for the servers are
+               <emphasis role="bold">volserver</emphasis> and <emphasis role="bold">vlserver</emphasis>, respectively).</para>
+             </listitem>
+           </varlistentry>
+         </variablelist></para>
+ 
+       <indexterm>
+         <primary>usr/afs/etc directory on server machines</primary>
+ 
+         <secondary>contents listed</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>directory</primary>
+ 
+         <secondary>/usr/afs/etc</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>files</primary>
+ 
+         <secondary>server configuration, in /usr/afs/etc directory</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>common configuration files (server)</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>server machine</primary>
+ 
+         <secondary>configuration files in /usr/afs/etc</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ85">
+       <title>Common Configuration Files in the /usr/afs/etc Directory</title>
+ 
+       <para>The directory <emphasis role="bold">/usr/afs/etc</emphasis> on every file server machine's local disk contains
+       configuration files in ASCII and machine-independent binary format. For predictable AFS performance throughout a cell, all
+       server machines must have the same version of each configuration file: <itemizedlist>
+           <indexterm>
+             <primary>Update Server</primary>
+ 
+             <secondary>distributing server configuration files</secondary>
+           </indexterm>
+ 
+           <listitem>
+             <para>Cells that run the United States edition of AFS conventionally use the Update Server to distribute a common
+             version of each file from the cell's system control machine to other server machines (for more on the system control
+             machine, see <link linkend="HDRWQ94">The System Control Machine</link>). Run the Update Server's server portion on the
+             system control machine, and the client portion on all other server machines. Update the files on the system control
+             machine only, except as directed by instructions for dealing with emergencies.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Cells that run the international edition of AFS must not use the Update Server to distribute the contents of the
+             <emphasis role="bold">/usr/afs/etc</emphasis> directory. Due to United States government regulations, the data
+             encryption routines that AFS uses to protect the files in this directory as they cross the network are not available to
+             the Update Server in the international edition of AFS. You must instead update the files on each server machine
+             individually, taking extra care to issue exactly the same <emphasis role="bold">bos</emphasis> command for each machine.
+             The necessary data encryption routines are available to the <emphasis role="bold">bos</emphasis> commands, so
+             information is safe as it crosses the network from the machine where the <emphasis role="bold">bos</emphasis> command is
+             issued to the server machines.</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <para>Never directly edit any of the files in the <emphasis role="bold">/usr/afs/etc</emphasis> directory, except as directed
+       by instructions for dealing with emergencies. In normal circumstances, use the appropriate <emphasis
+       role="bold">bos</emphasis> commands to change the files. The following list includes pointers to instructions.</para>
+ 
+       <para>The files in this directory include: <variablelist>
+           <indexterm>
+             <primary>CellServDB file (server)</primary>
+ 
+             <secondary>about</secondary>
+           </indexterm>
+ 
+           <indexterm>
+             <primary>files</primary>
+ 
+             <secondary>CellServDB (server)</secondary>
+           </indexterm>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">CellServDB</emphasis></term>
+ 
+             <listitem>
+               <para>An ASCII file that names the cell's database server machines, which run the Authentication, Backup, Protection,
+               and VL Server processes. You create the initial version of this file by issuing the <emphasis role="bold">bos
+               setcellname</emphasis> command while installing your cell's first server machine. It is very important to update this
+               file when you change the identity of your cell's database server machines.</para>
+ 
+               <para>The server <emphasis role="bold">CellServDB</emphasis> file is not the same as the <emphasis
+               role="bold">CellServDB</emphasis> file stored in the <emphasis role="bold">/usr/vice/etc</emphasis> directory on
+               client machines. The client version lists the database server machines for every AFS cell that you choose to make
+               accessible from the client machine. The server <emphasis role="bold">CellServDB</emphasis> file lists only the local
+               cell's database server machines, because server processes never contact processes in other cells.</para>
+ 
+               <para>For instructions on maintaining this file, see <link linkend="HDRWQ118">Maintaining the Server CellServDB
+               File</link>.</para>
+ 
+               <indexterm>
+                 <primary>KeyFile file</primary>
+ 
+                 <secondary>function of</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>KeyFile</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>server encryption key</primary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">KeyFile</emphasis></term>
+ 
+             <listitem>
+               <para>A machine-independent, binary-format file that lists the server encryption keys the AFS server processes use to
+               encrypt and decrypt tickets. The information in this file is the basis for secure communication in the cell, and so is
+               extremely sensitive. The file is specially protected so that only privileged users can read or change it.</para>
+ 
+               <para>For instructions on maintaining this file, see <link linkend="HDRWQ355">Managing Server Encryption
+               Keys</link>.</para>
+ 
+               <indexterm>
+                 <primary>ThisCell file (server)</primary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>ThisCell (server)</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">ThisCell</emphasis></term>
+ 
+             <listitem>
+               <para>An ASCII file that consists of a single line defining the complete Internet domain-style name of the cell (such
+               as <computeroutput>abc.com</computeroutput>). You create this file with the <emphasis role="bold">bos
+               setcellname</emphasis> command during the installation of your cell's first file server machine, as instructed in the
+               <emphasis>OpenAFS Quick Beginnings</emphasis>.</para>
+ 
+               <para>Note that changing this file is only one step in changing your cell's name. For discussion, see <link
+               linkend="HDRWQ34">Choosing a Cell Name</link>.</para>
+ 
+               <indexterm>
+                 <primary>UserList file</primary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>UserList</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">UserList</emphasis></term>
+ 
+             <listitem>
+               <para>An ASCII file that lists the usernames of the system administrators authorized to issue privileged <emphasis
+               role="bold">bos</emphasis>, <emphasis role="bold">vos</emphasis>, and <emphasis role="bold">backup</emphasis>
+               commands. For instructions on maintaining the file, see <link linkend="HDRWQ592">Administering the UserList
+               File</link>.</para>
+             </listitem>
+           </varlistentry>
+         </variablelist></para>
+ 
+       <indexterm>
+         <primary>usr/afs/local directory on server machines</primary>
+ 
+         <secondary>contents listed</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>directory</primary>
+ 
+         <secondary>/usr/afs/local on server machines</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>local configuration files (server)</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>file server machine</primary>
+ 
+         <secondary>configuration files in /usr/afs/local</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ86">
+       <title>Local Configuration Files in the /usr/afs/local Directory</title>
+ 
+       <para>The directory <emphasis role="bold">/usr/afs/local</emphasis> contains configuration files that are different for each
+       file server machine in a cell. Thus, they are not updated automatically from a central source like the files in <emphasis
+       role="bold">/usr/afs/bin</emphasis> and <emphasis role="bold">/usr/afs/etc</emphasis> directories. The most important file is
+       the <emphasis role="bold">BosConfig</emphasis> file; it defines which server processes are to run on that machine.</para>
+ 
+       <para>As with the common configuration files in <emphasis role="bold">/usr/afs/etc</emphasis>, you must not edit these files
+       directly. Use commands from the <emphasis role="bold">bos</emphasis> command suite where appropriate; some files never need to
+       be altered.</para>
+ 
+       <para>The files in this directory include the following: <variablelist>
+           <indexterm>
+             <primary>BosConfig file</primary>
+           </indexterm>
+ 
+           <indexterm>
+             <primary>files</primary>
+ 
+             <secondary>BosConfig</secondary>
+           </indexterm>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">BosConfig</emphasis></term>
+ 
+             <listitem>
+               <para>This file lists the server processes to run on the server machine, by defining which processes the BOS Server
+               monitors and what it does if the process fails. It also defines the times at which the BOS Server automatically
+               restarts processes for maintenance purposes.</para>
+ 
+               <para>As you create server processes during a file server machine's installation, their entries are defined in this
+               file automatically. The <emphasis>OpenAFS Quick Beginnings</emphasis> outlines the <emphasis
+               role="bold">bos</emphasis> commands to use. For a more complete description of the file, and instructions for
+               controlling process status by editing the file with commands from the <emphasis role="bold">bos</emphasis> suite, see
+               <link linkend="HDRWQ142">Monitoring and Controlling Server Processes</link>.</para>
+ 
+               <indexterm>
+                 <primary>NetInfo file (server version)</primary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>NetInfo (server version)</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">NetInfo</emphasis></term>
+ 
+             <listitem>
+               <para>This optional ASCII file lists one or more of the network interface addresses on the server machine. If it
+               exists when the File Server initializes, the File Server uses it as the basis for the list of interfaces that it
+               registers in its Volume Location Database (VLDB) server entry. See <link linkend="HDRWQ138">Managing Server IP
+               Addresses and VLDB Server Entries</link>.</para>
+ 
+               <indexterm>
+                 <primary>NetRestrict file (server version)</primary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>NetRestrict (server version)</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">NetRestrict</emphasis></term>
+ 
+             <listitem>
+               <para>This optional ASCII file lists one or more network interface addresses. If it exists when the File Server
+               initializes, the File Server removes the specified addresses from the list of interfaces that it registers in its VLDB
+               server entry. See <link linkend="HDRWQ138">Managing Server IP Addresses and VLDB Server Entries</link>.</para>
+ 
+               <indexterm>
+                 <primary>NoAuth file</primary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>NoAuth</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">NoAuth</emphasis></term>
+ 
+             <listitem>
+               <para>This zero-length file instructs all AFS server processes running on the machine not to perform authorization
+               checking. Thus, they perform any action for any user, even <emphasis role="bold">anonymous</emphasis>. This very
+               insecure state is useful only in rare instances, mainly during the installation of the machine.</para>
+ 
+               <para>The file is created automatically when you start the initial <emphasis role="bold">bosserver</emphasis> process
+               with the <emphasis role="bold">-noauth</emphasis> flag, or issue the <emphasis role="bold">bos setauth</emphasis>
+               command to turn off authentication requirements. When you use the <emphasis role="bold">bos setauth</emphasis> command
+               to turn on authentication, the BOS Server removes this file. For more information, see <link
+               linkend="HDRWQ123">Managing Authentication and Authorization Requirements</link>.</para>
+ 
+               <indexterm>
+                 <primary>SALVAGE.fs file</primary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>SALVAGE.fs</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">SALVAGE.fs</emphasis></term>
+ 
+             <listitem>
+               <para>This zero-length file controls how the BOS Server handles a crash of the File Server component of the <emphasis
+               role="bold">fs</emphasis> process. The BOS Server creates this file each time it starts or restarts the <emphasis
+               role="bold">fs</emphasis> process. If the file is present when the File Server crashes, then the BOS Server runs the
+               Salvager before restarting the File Server and Volume Server again. When the File Server exits normally, the BOS
+               Server removes the file so that the Salvager does not run.</para>
+ 
+               <para>Do not create or remove this file yourself; the BOS Server does so automatically. If necessary, you can salvage
+               a volume or partition by using the <emphasis role="bold">bos salvage</emphasis> command; see <link
+               linkend="HDRWQ232">Salvaging Volumes</link>.</para>
+ 
+               <indexterm>
+                 <primary>salvage.lock file</primary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>salvage.lock</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">salvage.lock</emphasis></term>
+ 
+             <listitem>
+               <para>This file guarantees that only one Salvager process runs on a file server machine at a time (the single process
+               can fork multiple subprocesses to salvage multiple partitions in parallel). As the Salvager initiates (when invoked by
+               the BOS Server or by issue of the <emphasis role="bold">bos salvage</emphasis> command), it creates this zero-length
+               file and issues the <emphasis role="bold">flock</emphasis> system call on it. It removes the file when it completes
+               the salvage operation. Because the Salvager must lock the file in order to run, only one Salvager can run at a
+               time.</para>
+ 
+               <indexterm>
+                 <primary>sysid file</primary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>sysid</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>File Server</primary>
+ 
+                 <secondary>interfaces registered in VLDB</secondary>
+ 
+                 <tertiary>listed in sysid file</tertiary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>VLDB</primary>
+ 
+                 <secondary>server machine interfaces registered</secondary>
+ 
+                 <tertiary>listed in sysid file</tertiary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">sysid</emphasis></term>
+ 
+             <listitem>
+               <para>This file records the network interface addresses that the File Server (<emphasis
+               role="bold">fileserver</emphasis> process) registers in its VLDB server entry. When the Cache Manager requests volume
+               location information, the Volume Location (VL) Server provides all of the interfaces registered for each server
+               machine that houses the volume. This enables the Cache Manager to make use of multiple addresses when accessing AFS
+               data stored on a multihomed file server machine. For further information, see <link linkend="HDRWQ138">Managing Server
+               IP Addresses and VLDB Server Entries</link>.</para>
+             </listitem>
+           </varlistentry>
+         </variablelist></para>
+ 
+       <indexterm>
+         <primary>usr/afs/db directory on server machines</primary>
+ 
+         <secondary>contents listed</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>directory</primary>
+ 
+         <secondary>/usr/afs/db on server machines</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>database files</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>replicated database files</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>log files</primary>
+ 
+         <secondary>for replicated databases</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>file server machine</primary>
+ 
+         <secondary>database files in /usr/afs/db</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ87">
+       <title>Replicated Database Files in the /usr/afs/db Directory</title>
+ 
+       <para>The directory <emphasis role="bold">/usr/afs/db</emphasis> contains two types of files pertaining to the four replicated
+       databases in the cell--the Authentication Database, Backup Database, Protection Database, and Volume Location Database (VLDB):
+       <itemizedlist>
+           <listitem>
+             <para>A file that contains each database, with a <emphasis role="bold">.DB0</emphasis> extension.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>A log file for each database, with a <emphasis role="bold">.DBSYS1</emphasis> extension. The database server
+             process logs each database operation in this file before performing it. If the operation is interrupted, the process
+             consults this file to learn how to finish it.</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <para>Each database server process (Authentication, Backup, Protection, or VL Server) maintains its own database and log
+       files. The database files are in binary format, so you must always access or alter them using commands from the <emphasis
+       role="bold">kas</emphasis> suite (for the Authentication Database), <emphasis role="bold">backup</emphasis> suite (for the
+       Backup Database), <emphasis role="bold">pts</emphasis> suite (for the Protection Database), or <emphasis
+       role="bold">vos</emphasis> suite (for the VLDB).</para>
+ 
+       <para>If a cell runs more than one database server machine, each database server process keeps its own copy of its database on
+       its machine's hard disk. However, it is important that all the copies of a given database are the same. To synchronize them,
+       the database server processes call on AFS's distributed database technology, Ubik, as described in <link
+       linkend="HDRWQ102">Replicating the OpenAFS Administrative Databases</link>.</para>
+ 
+       <para>The files listed here appear in this directory only on database server machines. On non-database server machines, this
+       directory is empty. <variablelist>
+           <indexterm>
+             <primary>files</primary>
+ 
+             <secondary>bdb.DB0</secondary>
+           </indexterm>
+ 
+           <indexterm>
+             <primary>bdb.DB0 file</primary>
+           </indexterm>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">bdb.DB0</emphasis></term>
+ 
+             <listitem>
+               <para>The Backup Database file.</para>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>bdb.DBSYS1</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>bdb.DBSYS1 file</primary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">bdb.DBSYS1</emphasis></term>
+ 
+             <listitem>
+               <para>The Backup Database log file.</para>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>kaserver.DB0</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>kaserver.DB0 file</primary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">kaserver.DB0</emphasis></term>
+ 
+             <listitem>
+               <para>The Authentication Database file.</para>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>kaserver.DBSYS1</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>kaserver.DBSYS1 file</primary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">kaserver.DBSYS1</emphasis></term>
+ 
+             <listitem>
+               <para>The Authentication Database log file.</para>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>prdb.DB0</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>prdb.DB0 file</primary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">prdb.DB0</emphasis></term>
+ 
+             <listitem>
+               <para>The Protection Database file.</para>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>prdb.DBSYS1</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>prdb.DBSYS1 file</primary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">prdb.DBSYS1</emphasis></term>
+ 
+             <listitem>
+               <para>The Protection Database log file.</para>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>vldb.DB0</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>vldb.DB0 file</primary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">vldb.DB0</emphasis></term>
+ 
+             <listitem>
+               <para>The Volume Location Database file.</para>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>vldb.DBSYS1</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>vldb.DBSYS1 file</primary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">vldb.DBSYS1</emphasis></term>
+ 
+             <listitem>
+               <para>The Volume Location Database log file.</para>
+             </listitem>
+           </varlistentry>
+         </variablelist></para>
+ 
+       <indexterm>
+         <primary>usr/afs/logs directory on server machines</primary>
+ 
+         <secondary>contents listed</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>directory</primary>
+ 
+         <secondary>/usr/afs/logs on server machines</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>file server machine</primary>
+ 
+         <secondary>core files in /usr/afs/logs</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>file server machine</primary>
+ 
+         <secondary>log files in /usr/afs/logs</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>log files</primary>
+ 
+         <secondary>for server processes</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>core files</primary>
+ 
+         <secondary>for server processes</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ88">
+       <title>Log Files in the /usr/afs/logs Directory</title>
+ 
+       <para>The <emphasis role="bold">/usr/afs/logs</emphasis> directory contains log files from various server processes. The files
+       detail interesting events that occur during normal operations. For instance, the Volume Server can record volume moves in the
+       <emphasis role="bold">VolserLog</emphasis> file. Events are recorded at completion, so the server processes do not use these
+       files to reconstruct failed operations unlike the ones in the <emphasis role="bold">/usr/afs/db</emphasis> directory.</para>
+ 
+       <para>The information in log files can be very useful as you evaluate process failures and other problems. For instance, if
+       you receive a timeout message when you try to access a volume, checking the <emphasis role="bold">FileLog</emphasis> file
+       possibly provides an explanation, showing that the File Server was unable to attach the volume. To examine a log file
+       remotely, use the <emphasis role="bold">bos getlog</emphasis> command as described in <link linkend="HDRWQ173">Displaying
+       Server Process Log Files</link>.</para>
+ 
+       <para>This directory also contains the core image files generated if a process being monitored by the BOS Server crashes. The
+       BOS Server attempts to add an extension to the standard <emphasis role="bold">core</emphasis> name to indicate which process
+       generated the core file (for example, naming a core file generated by the Protection Server <emphasis
+       role="bold">core.ptserver</emphasis>). The BOS Server cannot always assign the correct extension if two processes fail at
+       about the same time, so it is not guaranteed to be correct.</para>
+ 
+       <para>The directory contains the following files: <variablelist>
+           <indexterm>
+             <primary>AuthLog file</primary>
+           </indexterm>
+ 
+           <indexterm>
+             <primary>files</primary>
+ 
+             <secondary>AuthLog</secondary>
+           </indexterm>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">AuthLog</emphasis></term>
+ 
+             <listitem>
+               <para>The Authentication Server's log file.</para>
+ 
+               <indexterm>
+                 <primary>BackupLog file</primary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>BackupLog</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">BackupLog</emphasis></term>
+ 
+             <listitem>
+               <para>The Backup Server's log file.</para>
+ 
+               <indexterm>
+                 <primary>BosLog file</primary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>BosLog</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">BosLog</emphasis></term>
+ 
+             <listitem>
+               <para>The BOS Server's log file.</para>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>FileLog</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>FileLog file</primary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">FileLog</emphasis></term>
+ 
+             <listitem>
+               <para>The File Server's log file.</para>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>SalvageLog</secondary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>SalvageLog file</primary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">SalvageLog</emphasis></term>
+ 
+             <listitem>
+               <para>The Salvager's log file.</para>
+ 
+               <indexterm>
+                 <primary>VLLog file</primary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>VLLog</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">VLLog</emphasis></term>
+ 
+             <listitem>
+               <para>The Volume Location (VL) Server's log file.</para>
+ 
+               <indexterm>
+                 <primary>VolserLog file</primary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>VolserLog</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">VolserLog</emphasis></term>
+ 
+             <listitem>
+               <para>The Volume Server's log file.</para>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">core.process</emphasis></term>
+ 
+             <listitem>
+               <para>If present, a core image file produced as an AFS server process on the machine crashed (probably the process
+               named by process).</para>
+             </listitem>
+           </varlistentry>
+         </variablelist></para>
+ 
+       <note>
+         <para>To prevent log files from growing unmanageably large, restart the server processes periodically, particularly the
+         database server processes. To avoid restarting the processes, use the UNIX <emphasis role="bold">rm</emphasis> command to
+         remove the file as the process runs; it re-creates it automatically.</para>
+       </note>
+ 
+       <indexterm>
+         <primary>vicep directory on server machines</primary>
+ 
+         <secondary>contents listed</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>directory</primary>
+ 
+         <secondary>/vicep on server machines</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>volume header</primary>
+ 
+         <secondary>in /vicep directories</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>partition</primary>
+ 
+         <secondary>housing AFS volumes</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>file server machine</primary>
+ 
+         <secondary>partitions, naming</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ89">
+       <title>Volume Headers on Server Partitions</title>
+ 
+       <para>A partition that houses AFS volumes must be mounted at a subdirectory of the machine's root ( / ) directory (not, for
+       instance under the <emphasis role="bold">/usr</emphasis> directory). The file server machine's file system registry file
+       (<emphasis role="bold">/etc/fstab</emphasis> or equivalent) must correctly map the directory name and the partition's device
+       name. The directory name is of the form <emphasis role="bold">/vicep</emphasis>index, where each index is one or two lowercase
+       letters. By convention, the first AFS partition on a machine is mounted at <emphasis role="bold">/vicepa</emphasis>, the
+       second at <emphasis role="bold">/vicepb</emphasis>, and so on. If there are more than 26 partitions, continue with <emphasis
+       role="bold">/vicepaa</emphasis>, <emphasis role="bold">/vicepab</emphasis> and so on. The <emphasis>OpenAFS Release
+       Notes</emphasis> specifies the number of supported partitions per server machine.</para>
+ 
+       <para>Do not store non-AFS files on AFS partitions. The File Server and Volume Server expect to have available all of the
+       space on the partition.</para>
+ 
+       <para>The <emphasis role="bold">/vicep</emphasis> directories contain two types of files: <variablelist>
+           <indexterm>
+             <primary>V.<emphasis>vol_ID</emphasis>.vol file</primary>
+           </indexterm>
+ 
+           <indexterm>
+             <primary>files</primary>
+ 
+             <secondary>V.<emphasis>vol_ID</emphasis>.vol</secondary>
+           </indexterm>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">Vvol_ID.vol</emphasis></term>
+ 
+             <listitem>
+               <para>Each such file is a volume header. The vol_ID corresponds to the volume ID number displayed in the output from
+               the <emphasis role="bold">vos examine</emphasis>, <emphasis role="bold">vos listvldb</emphasis>, and <emphasis
+               role="bold">vos listvol</emphasis> commands.</para>
+ 
+               <indexterm>
+                 <primary>FORCESALVAGE file</primary>
+               </indexterm>
+ 
+               <indexterm>
+                 <primary>files</primary>
+ 
+                 <secondary>FORCESALVAGE</secondary>
+               </indexterm>
+             </listitem>
+           </varlistentry>
+ 
+           <varlistentry>
+             <term><emphasis role="bold">FORCESALVAGE</emphasis></term>
+ 
+             <listitem>
+               <para>This zero-length file triggers the Salvager to salvage the entire partition. The AFS-modified version of the
+               <emphasis role="bold">fsck</emphasis> program creates this file if it discovers corruption.</para>
+             </listitem>
+           </varlistentry>
+         </variablelist></para>
+ 
+       <note>
+         <para>For most system types, it is important never to run the standard <emphasis role="bold">fsck</emphasis> program
+         provided with the operating system on an AFS file server machine. It removes all AFS volume data from server partitions
+         because it does not recognize their format.</para>
+       </note>
+ 
+       <indexterm>
+         <primary>roles for server machine</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>server machine</primary>
+ 
+         <secondary>roles summarized</secondary>
+       </indexterm>
+     </sect2>
+   </sect1>
+ 
+   <sect1 id="HDRWQ90">
+     <title>The Four Roles for File Server Machines</title>
+ 
+     <para>In cells that have more than one server machine, not all server machines have to perform exactly the same functions. The
+     are four possible <emphasis>roles</emphasis> a machine can assume, determined by which server processes it is running. A machine
+     can assume more than one role by running all of the relevant processes. The following list summarizes the four roles, which are
+     described more completely in subsequent sections. <itemizedlist>
+         <listitem>
+           <para>A <emphasis>simple file server</emphasis> machine runs only the processes that store and deliver AFS files to client
+           machines. You can run as many simple file server machines as you need to satisfy your cell's performance and disk space
+           requirements.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>A <emphasis>database server machine</emphasis> runs the four database server processes that maintain AFS's
+           replicated administrative databases: the Authentication, Backup, Protection, and Volume Location (VL) Server
+           processes.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>A <emphasis>binary distribution machine</emphasis> distributes the AFS server binaries for its system type to all
+           other server machines of that system type.</para>
+         </listitem>
+ 
+         <listitem>
+           <para>The single <emphasis>system control machine</emphasis> distributes common server configuration files to all other
+           server machines in the cell, in a cell that runs the United States edition of AFS (cells that use the international
+           edition of AFS must not use the system control machine for this purpose). The machine conventionally also serves as the
+           time synchronization source for the cell, adjusting its clock according to a time source outside the cell.</para>
+         </listitem>
+       </itemizedlist></para>
+ 
+     <para>If a cell has a single server machine, it assumes the simple file server and database server roles. The instructions in
+     the <emphasis>OpenAFS Quick Beginnings</emphasis> also have you configure it as the system control machine and binary
+     distribution machine for its system type, but it does not actually perform those functions until you install another server
+     machine.</para>
+ 
+     <para>It is best to keep the binaries for all of the AFS server processes in the <emphasis role="bold">/usr/afs/bin</emphasis>
+     directory, even if not all processes are running. You can then change which roles a machine assumes simply by starting or
+     stopping the processes that define the role.</para>
+ 
+     <indexterm>
+       <primary>simple file server machine</primary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>server machine</primary>
+ 
+       <secondary>simple file server role</secondary>
+     </indexterm>
+ 
+     <sect2 id="HDRWQ91">
+       <title>Simple File Server Machines</title>
+ 
+       <para>A <emphasis>simple file server machine</emphasis> runs only the server processes that store and deliver AFS files to
+       client machines, monitor process status, and pick up binaries and configuration files from the cell's binary distribution and
+       system control machines.</para>
+ 
+       <para>In general, only cells with more than three server machines need to run simple file server machines. In cells with three
+       or fewer machines, all of them are usually database server machines (to benefit from replicating the administrative
+       databases); see <link linkend="HDRWQ92">Database Server Machines</link>.</para>
+ 
+       <para>The following processes run on a simple file server machine: <itemizedlist>
+           <listitem>
+             <para>The BOS Server (<emphasis role="bold">bosserver</emphasis> process)</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The <emphasis role="bold">fs</emphasis> process, which combines the File Server, Volume Server, and Salvager
+             processes so that they can coordinate their operations on the data in volumes and avoid the inconsistencies that can
+             result from multiple simultaneous operations on the same data</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The NTP coordinator (<emphasis role="bold">runntp</emphasis> process), which helps keep the machine's clock
+             synchronized with the clocks on the other server machines in the cell</para>
+           </listitem>
+ 
+           <listitem>
+             <para>A client portion of the Update Server that picks up binary files from the binary distribution machine of its AFS
+             system type (the <emphasis role="bold">upclientbin</emphasis> process)</para>
+           </listitem>
+ 
+           <listitem>
+             <para>A client portion of the Update Server that picks up common configuration files from the system control machine, in
+             cells running the United States edition of AFS (the <emphasis role="bold">upclientetc</emphasis> process)</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <indexterm>
+         <primary>database server machine</primary>
+ 
+         <secondary>defined</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>server machine</primary>
+ 
+         <secondary>database server role</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>Backup Server</primary>
+ 
+         <secondary>runs on database server machine</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>Authentication Server</primary>
+ 
+         <secondary>runs on database server machine</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>Protection Server</primary>
+ 
+         <secondary>runs on database server machine</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>VL Server</primary>
+ 
+         <secondary>runs on database server machine</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ92">
+       <title>Database Server Machines</title>
+ 
+       <para>A <emphasis>database server machine</emphasis> runs the four processes that maintain the AFS replicated administrative
+       databases: the Authentication Server, Backup Server, Protection Server, and Volume Location (VL) Server, which maintain the
+       Authentication Database, Backup Database, Protection Database, and Volume Location Database (VLDB), respectively. To review
+       the functions of these server processes and their databases, see <link linkend="HDRWQ17">AFS Server Processes and the Cache
+       Manager</link>.</para>
+ 
+       <para>If a cell has more than one server machine, it is best to run more than one database server machine, but more than three
+       are rarely necessary. Replicating the databases in this way yields the same benefits as replicating volumes: increased
+       availability and reliability of information. If one database server machine or process goes down, the information in the
+       database is still available from others. The load of requests for database information is spread across multiple machines,
+       preventing any one from becoming overloaded.</para>
+ 
+       <para>Unlike replicated volumes, however, replicated databases do change frequently. Consistent system performance demands
+       that all copies of the database always be identical, so it is not possible to record changes in only some of them. To
+       synchronize the copies of a database, the database server processes use AFS's distributed database technology, Ubik. See <link
+       linkend="HDRWQ102">Replicating the OpenAFS Administrative Databases</link>.</para>
+ 
+       <para>It is critical that the AFS server processes on every server machine in a cell know which machines are the database
+       server machines. The database server processes in particular must maintain constant contact with their peers in order to
+       coordinate the copies of the database. The other server processes often need information from the databases. Every file server
+       machine keeps a list of its cell's database server machines in its local <emphasis
+       role="bold">/usr/afs/etc/CellServDB</emphasis> file. Cells that use the States edition of AFS can use the system control
+       machine to distribute this file (see <link linkend="HDRWQ94">The System Control Machine</link>).</para>
+ 
+       <para>The following processes define a database server machine: <itemizedlist>
+           <listitem>
+             <para>The Authentication Server (<emphasis role="bold">kaserver</emphasis> process)</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The Backup Server (<emphasis role="bold">buserver</emphasis> process)</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The Protection Server (<emphasis role="bold">ptserver</emphasis> process)</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The VL Server (<emphasis role="bold">vlserver</emphasis> process)</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <para>Database server machines can also run the processes that define a simple file server machine, as listed in <link
+       linkend="HDRWQ91">Simple File Server Machines</link>. One database server machine can act as the cell's system control
+       machine, and any database server machine can serve as the binary distribution machine for its system type; see <link
+       linkend="HDRWQ94">The System Control Machine</link> and <link linkend="HDRWQ93">Binary Distribution Machines</link>.</para>
+ 
+       <indexterm>
+         <primary>binary distribution machine</primary>
+ 
+         <secondary>defined</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>server machine</primary>
+ 
+         <secondary>binary distribution role</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>Update Server</primary>
+ 
+         <secondary>server portion</secondary>
+ 
+         <tertiary>on binary distribution machine</tertiary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>Update Server</primary>
+ 
+         <secondary>client portion</secondary>
+ 
+         <tertiary>for binaries</tertiary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ93">
+       <title>Binary Distribution Machines</title>
+ 
+       <para>A <emphasis>binary distribution machine</emphasis> stores and distributes the binary files for the AFS processes and
+       command suites to all other server machines of its system type. Each file server machine keeps its own copy of AFS server
+       process binaries on its local disk, by convention in the <emphasis role="bold">/usr/afs/bin</emphasis> directory. For
+       consistent system performance, however, all server machines must run the same version (build level) of a process. For
+       instructions for checking a binary's build level, see <link linkend="HDRWQ117">Displaying A Binary File's Build Level</link>.
+       The easiest way to keep the binaries consistent is to have a binary distribution machine of each system type distribute them
+       to its system-type peers.</para>
+ 
+       <para>The process that defines a binary distribution machine is the server portion of the Update Server (<emphasis
+       role="bold">upserver</emphasis> process). The client portion of the Update Server (<emphasis
+       role="bold">upclientbin</emphasis> process) runs on the other server machines of that system type and references the binary
+       distribution machine.</para>
+ 
+       <para>Binary distribution machines usually also run the processes that define a simple file server machine, as listed in <link
+       linkend="HDRWQ91">Simple File Server Machines</link>. One binary distribution machine can act as the cell's system control
+       machine, and any binary distribution machine can serve as a database server machine; see <link linkend="HDRWQ94">The System
+       Control Machine</link> and <link linkend="HDRWQ92">Database Server Machines</link>.</para>
+ 
+       <indexterm>
+         <primary>system control machine</primary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>configuration files</primary>
+ 
+         <secondary>server machine, common</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>server machine</primary>
+ 
+         <secondary>system control role</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ94">
+       <title>The System Control Machine</title>
+ 
+       <para>In cells that run the United States edition of AFS, the <emphasis>system control machine</emphasis> stores and
+       distributes system configuration files shared by all of the server machines in the cell. Each file server machine keeps its
+       own copy of the configuration files on its local disk, by convention in the <emphasis role="bold">/usr/afs/etc</emphasis>
+       directory. For consistent system performance, however, all server machines must use the same files. The easiest way to keep
+       the files consistent is to have the system control machine distribute them. You make changes only to the copy stored on the
+       system control machine, as directed by the instructions in this document. The United States edition of AFS is available to
+       cells in the United States and Canada and to selected institutions in other countries, as determined by United States
+       government regulations.</para>
+ 
+       <para>Cells that run the international version of AFS do not use the system control machine to distribute system configuration
+       files. Some of the files contain information that is too sensitive to cross the network unencrypted, and United States
+       government regulations forbid the export of the necessary encryption routines in the form that the Update Server uses. You
+       must instead update the configuration files on each file server machine individually. The <emphasis role="bold">bos</emphasis>
+       commands that you use to update the files encrypt the information using an exportable form of the encryption routines.</para>
+ 
+       <para>For a list of the configuration files stored in the <emphasis role="bold">/usr/afs/etc</emphasis> directory, see <link
+       linkend="HDRWQ85">Common Configuration Files in the /usr/afs/etc Directory</link>.</para>
+ 
+       <para>The <emphasis>OpenAFS Quick Beginnings</emphasis> configures a cell's first server machine as the system control
+       machine. If you wish, you can reassign the role to a different machine that you install later, but you must then change the
+       client portion of the Update Server (<emphasis role="bold">upclientetc</emphasis>) process running on all other server
+       machines to refer to the new system control machine.</para>
+ 
+       <para>The following processes define the system control machine: <itemizedlist>
+           <indexterm>
+             <primary>Update Server</primary>
+ 
+             <secondary>server portion</secondary>
+ 
+             <tertiary>on system control machine</tertiary>
+           </indexterm>
+ 
+           <indexterm>
+             <primary>Update Server</primary>
+ 
+             <secondary>client portion</secondary>
+ 
+             <tertiary>for configuration files</tertiary>
+           </indexterm>
+ 
+           <listitem>
+             <para>The server portion of the Update Server (<emphasis role="bold">upserver</emphasis>) process, in cells using the
+             United States edition of AFS. The client portion of the Update Server (<emphasis role="bold">upclientetc</emphasis>
+             process) runs on the other server machines and references the system control machine.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The NTP coordinator (<emphasis role="bold">runntp</emphasis> process) which points to a time source outside the
+             cell, if the cell uses NTPD to synchronize its clocks. The <emphasis role="bold">runntp</emphasis> process on other
+             machines reference the system control machine as their main time source.</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <para>The system control machine can also run the processes that define a simple file server machine, as listed in <link
+       linkend="HDRWQ91">Simple File Server Machines</link>. It can also server as a database server machine, and by convention acts
+       as the binary distribution machine for its system type. A single <emphasis role="bold">upserver</emphasis> process can
+       distribute both configuration files and binaries. See <link linkend="HDRWQ92">Database Server Machines</link> and <link
+       linkend="HDRWQ93">Binary Distribution Machines</link>.</para>
+ 
+       <indexterm>
+         <primary>determining</primary>
+ 
+         <secondary>roles taken by server machine</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>identifying</primary>
+ 
+         <secondary>roles taken by server machine</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>server machine</primary>
+ 
+         <secondary>determining roles</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>roles for server machine</primary>
+ 
+         <secondary>determining</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>database server machine</primary>
+ 
+         <secondary>identifying with bos status</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>determining</primary>
+ 
+         <secondary>identity of database server machines</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>identifying</primary>
+ 
+         <secondary>database server machine</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ95">
+       <title>To locate database server machines</title>
+ 
+       <orderedlist>
+         <listitem>
+           <para>Issue the <emphasis role="bold">bos listhosts</emphasis> command. <programlisting>
+    % <emphasis role="bold">bos listhosts</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
+ </programlisting></para>
+ 
+           <para>The machines listed in the output are the cell's database server machines. For complete instructions and example
+           output, see <link linkend="HDRWQ120">To display a cell's database server machines</link>.</para>
+         </listitem>
+ 
+         <listitem>
+           <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">bos status</emphasis> command to verify
+           that a machine listed in the output of the <emphasis role="bold">bos listhosts</emphasis> command is actually running the
+           processes that define it as a database server machine. For complete instructions, see <link linkend="HDRWQ158">Displaying
+           Process Status and Information from the BosConfig File</link>. <programlisting>
+    % <emphasis role="bold">bos status</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">buserver kaserver ptserver vlserver</emphasis>
+ </programlisting></para>
+ 
+           <para>If the specified machine is a database server machine, the output from the <emphasis role="bold">bos
+           status</emphasis> command includes the following lines:</para>
+ 
+           <programlisting>
+    Instance buserver, currently running normally.
+    Instance kaserver, currently running normally.
+    Instance ptserver, currently running normally.
+    Instance vlserver, currently running normally.
+ </programlisting>
+         </listitem>
+       </orderedlist>
+ 
+       <indexterm>
+         <primary>system control machine</primary>
+ 
+         <secondary>identifying with bos status</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>determining</primary>
+ 
+         <secondary>identity of system control machine</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>identifying</primary>
+ 
+         <secondary>system control machine</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ96">
+       <title>To locate the system control machine</title>
+ 
+       <orderedlist>
+         <listitem>
+           <para>Issue the <emphasis role="bold">bos status</emphasis> command for any server machine. Complete instructions appear
+           in <link linkend="HDRWQ158">Displaying Process Status and Information from the BosConfig File</link>. <programlisting>
+    % <emphasis role="bold">bos status</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">upserver upclientbin upclientetc</emphasis> <emphasis
+                 role="bold">-long</emphasis>
+ </programlisting></para>
+ 
+           <para>The output you see depends on the machine you have contacted: a simple file server machine, the system control
+           machine, or a binary distribution machine. See <link linkend="HDRWQ98">Interpreting the Output from the bos status
+           Command</link>.</para>
+         </listitem>
+       </orderedlist>
+ 
+       <indexterm>
+         <primary>binary distribution machine</primary>
+ 
+         <secondary>identifying with bos status</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>determining</primary>
+ 
+         <secondary>identity of binary distribution machine</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>identifying</primary>
+ 
+         <secondary>binary distribution machine</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ97">
+       <title>To locate the binary distribution machine for a system type</title>
+ 
+       <orderedlist>
+         <listitem>
+           <para>Issue the <emphasis role="bold">bos status</emphasis> command for a file server machine of the system type you are
+           checking (to determine a machine's system type, issue the <emphasis role="bold">fs sysname</emphasis> or <emphasis
+           role="bold">sys</emphasis> command as described in <link linkend="HDRWQ417">Displaying and Setting the System Type
+           Name</link>. Complete instructions for the <emphasis role="bold">bos status</emphasis> command appear in <link
+           linkend="HDRWQ158">Displaying Process Status and Information from the BosConfig File</link>. <programlisting>
+    % <emphasis role="bold">bos status</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">upserver upclientbin upclientetc -long</emphasis>
+ </programlisting></para>
+ 
+           <para>The output you see depends on the machine you have contacted: a simple file server machine, the system control
+           machine, or a binary distribution machine. See <link linkend="HDRWQ98">Interpreting the Output from the bos status
+           Command</link>.</para>
+         </listitem>
+       </orderedlist>
+ 
+       <indexterm>
+         <primary>simple file server machine</primary>
+ 
+         <secondary>identifying with bos status</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>determining</primary>
+ 
+         <secondary>identity of:</secondary>
+ 
+         <tertiary>simple file server machines</tertiary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>identifying</primary>
+ 
+         <secondary>simple file server machine</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ98">
+       <title>Interpreting the Output from the bos status Command</title>
+ 
+       <para>Interpreting the output of the <emphasis role="bold">bos status</emphasis> command is most straightforward for a simple
+       file server machine. There is no <emphasis role="bold">upserver</emphasis> process, so the output includes the following
+       message:</para>
+ 
+       <programlisting>
+    bos: failed to get instance info for 'upserver' (no such entity)
+ </programlisting>
+ 
+       <para>A simple file server machine runs the <emphasis role="bold">upclientbin</emphasis> process, so the output includes a
+       message like the following. It indicates that <emphasis role="bold">fs7.abc.com</emphasis> is the binary distribution machine
+       for this system type.</para>
+ 
+       <programlisting>
+    Instance upclientbin, (type is simple) currently running normally.
+    Process last started at Wed Mar 10  23:37:09 1999 (1 proc start)
+    Command 1 is '/usr/afs/bin/upclient fs7.abc.com -t 60 /usr/afs/bin'
+ </programlisting>
+ 
+       <para>If you run the United States edition of AFS, a simple file server machine also runs the <emphasis
+       role="bold">upclientetc</emphasis> process, so the output includes a message like the following. It indicates that <emphasis
+       role="bold">fs1.abc.com</emphasis> is the system control machine.</para>
+ 
+       <programlisting>
+    Instance upclientetc, (type is simple) currently running normally.
+    Process last started at Mon Mar 22  05:23:49 1999 (1 proc start)
+    Command 1 is '/usr/afs/bin/upclient fs1.abc.com -t 60 /usr/afs/etc'
+ </programlisting>
+ 
+       <sect3 id="HDRWQ99">
+         <title>The Output on the System Control Machine</title>
+ 
+         <para>If you run the United States edition of AFS and have issued the <emphasis role="bold">bos status</emphasis> command
+         for the system control machine, the output includes an entry for the <emphasis role="bold">upserver</emphasis> process
+         similar to the following:</para>
+ 
+         <programlisting>
+    Instance upserver, (type is simple) currently running normally.
+    Process last started at Mon Mar 22 05:23:54 1999 (1 proc start)
+    Command 1 is '/usr/afs/bin/upserver'
+ </programlisting>
+ 
+         <para>If you are using the default configuration recommended in the <emphasis>OpenAFS Quick Beginnings</emphasis>, the
+         system control machine is also the binary distribution machine for its system type, and a single <emphasis
+         role="bold">upserver</emphasis> process distributes both kinds of updates. In that case, the output includes the following
+         messages:</para>
+ 
+         <programlisting>
+    bos: failed to get instance info for 'upclientbin' (no such entity)
+    bos: failed to get instance info for 'upclientetc' (no such entity)
+ </programlisting>
+ 
+         <para>If the system control machine is not a binary distribution machine, the output includes an error message for the
+         <emphasis role="bold">upclientetc</emphasis> process, but a complete a listing for the <emphasis
+         role="bold">upclientbin</emphasis> process (in this case it refers to the machine <emphasis
+         role="bold">fs5.abc.com</emphasis> as the binary distribution machine):</para>
+ 
+         <programlisting>
+    Instance upclientbin, (type is simple) currently running normally.
+    Process last started at Mon Mar 22  05:23:49 1999 (1 proc start)
+    Command 1 is '/usr/afs/bin/upclient fs5.abc.com -t 60 /usr/afs/bin'
+    bos: failed to get instance info for 'upclientetc' (no such entity)
+ </programlisting>
+       </sect3>
+ 
+       <sect3 id="HDRWQ100">
+         <title>The Output on a Binary Distribution Machine</title>
+ 
+         <para>If you have issued the <emphasis role="bold">bos status</emphasis> command for a binary distribution machine, the
+         output includes an entry for the <emphasis role="bold">upserver</emphasis> process similar to the following and error
+         message for the <emphasis role="bold">upclientbin</emphasis> process:</para>
+ 
+         <programlisting>
+    Instance upserver, (type is simple) currently running normally.
+    Process last started at Mon Apr 5 05:23:54 1999 (1 proc start)
+    Command 1 is '/usr/afs/bin/upserver'
+    bos: failed to get instance info for 'upclientbin' (no such entity)
+ </programlisting>
+ 
+         <para>Unless this machine also happens to be the system control machine, a message like the following references the system
+         control machine (in this case, <emphasis role="bold">fs3.abc.com</emphasis>):</para>
+ 
+         <programlisting>
+    Instance upclientetc, (type is simple) currently running normally.
+    Process last started at Mon Apr 5 05:23:49 1999 (1 proc start)
+    Command 1 is '/usr/afs/bin/upclient fs3.abc.com -t 60 /usr/afs/etc'
+ </programlisting>
+       </sect3>
+     </sect2>
+   </sect1>
+ 
+   <sect1 id="HDRWQ101">
+     <title>Administering Database Server Machines</title>
+ 
+     <para>This section explains how to administer database server machines. For installation instructions, see the <emphasis>OpenAFS
+     Quick Beginnings</emphasis>.</para>
+ 
+     <indexterm>
+       <primary>distribution</primary>
+ 
+       <secondary>of databases</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>database, distributed</primary>
+ 
+       <secondary></secondary>
+ 
+       <see>administrative database</see>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>distributed database</primary>
+ 
+       <secondary></secondary>
+ 
+       <see>administrative database</see>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>administrative database</primary>
+ 
+       <secondary>about replicating</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>database server machine</primary>
+ 
+       <secondary>maintaining</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>Ubik</primary>
+ 
+       <secondary>operation described</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>synchronization site (Ubik)</primary>
+ 
+       <secondary>defined</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>secondary site (Ubik)</primary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>coordinator (Ubik)</primary>
+ 
+       <secondary>defined</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>Ubik</primary>
+ 
+       <secondary>automatic updates</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>automatic</primary>
+ 
+       <secondary>update to admin. databases by Ubik</secondary>
+     </indexterm>
+ 
+     <sect2 id="HDRWQ102">
+       <title>Replicating the OpenAFS Administrative Databases</title>
+ 
+       <para>There are several benefits to replicating the AFS administrative databases (the Authentication, Backup, Protection, and
+       Volume Location Databases), as discussed in <link linkend="HDRWQ52">Replicating the OpenAFS Administrative Databases</link>. For
+       correct cell functioning, the copies of each database must be identical at all times. To keep the databases synchronized, AFS
+       uses library of utilities called <emphasis>Ubik</emphasis>. Each database server process runs an associated lightweight Ubik
+       process, and client-side programs call Ubik's client-side subroutines when they submit requests to read and change the
+       databases.</para>
+ 
+       <para>Ubik is designed to work with minimal administrator intervention, but there are several configuration requirements, as
+       detailed in <link linkend="HDRWQ103">Configuring the Cell for Proper Ubik Operation</link>. The following brief overview of
+       Ubik's operation is helpful for understanding the requirements. For more details, see <link linkend="HDRWQ104">How Ubik
+       Operates Automatically</link>.</para>
+ 
+       <para>Ubik is designed to distribute changes made in an AFS administrative database to all copies as quickly as possible. Only
+       one copy of the database, the <emphasis>synchronization site</emphasis>, accepts change requests from clients; the lightweight
+       Ubik process running there is the <emphasis>Ubik coordinator</emphasis>. To maintain maximum availability, there is a separate
+       Ubik coordinator for each database, and the synchronization site for each of the four databases can be on a different machine.
+       The synchronization site for a database can also move from machine to machine in response to process, machine, or network
+       outages.</para>
+ 
+       <para>The other copies of a database, and the Ubik processes that maintain them, are termed <emphasis>secondary</emphasis>.
+       The secondary sites do not accept database changes directly from client-side programs, but only from the synchronization
+       site.</para>
+ 
+       <para>After the Ubik coordinator records a change in its copy of a database, it immediately sends the change to the secondary
+       sites. During the brief distribution period, clients cannot access any of the copies of the database, even for reading. If the
+       coordinator cannot reach a majority of the secondary sites, it halts the distribution and informs the client that the
+       attempted change failed.</para>
+ 
+       <para>To avoid distribution failures, the Ubik processes maintain constant contact by exchanging time-stamped messages. As
+       long as a majority of the secondary sites respond to the coordinator's messages, there is a <emphasis>quorum</emphasis> of
+       sites that are synchronized with the coordinator. If a process, machine, or network outage breaks the quorum, the Ubik
+       processes attempt to elect a new coordinator in order to establish a new quorum among the highest possible number of sites.
+       See <link linkend="HDRWQ106">A Flexible Coordinator Boosts Availability</link>.</para>
+ 
+       <indexterm>
+         <primary>Ubik</primary>
+ 
+         <secondary>requirements summarized</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>database server process</primary>
+ 
+         <secondary>need to run all on every database server machine</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>CellServDB file (server)</primary>
+ 
+         <secondary>importance to Ubik operation</secondary>
+       </indexterm>
+ 
+       <sect3 id="HDRWQ103">
+         <title>Configuring the Cell for Proper Ubik Operation</title>
+ 
+         <para>This section describes how to configure your cell to maintain proper Ubik operation. <itemizedlist>
+             <listitem>
+               <para>Run all four database server processes--Authentication Server, Backup Server, Protection Server, and VL
+               Server--on all database server machines.</para>
+ 
+               <para>Both the client and server portions of Ubik expect that all the database server machines listed in the <emphasis
+               role="bold">CellServDB</emphasis> file are running all of the database server processes. There is no mechanism for
+               indicating that only some database server processes are running on a machine.</para>
+             </listitem>
+ 
+             <listitem>
+               <para>Maintain correct information in the <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> file at all
+               times.</para>
+ 
+               <para>Ubik consults the <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> file to determine the sites with
+               which to establish and maintain a quorum. Incorrect information can result in unsynchronized databases or election of
+               a coordinator in each of several subgroups of machines, because the Ubik processes on various machines do not agree on
+               which machines need to participate in the quorum.</para>
+ 
+               <para>If you run the United States version of AFS and use the Update Server, it is simplest to maintain the <emphasis
+               role="bold">/usr/afs/etc/CellServDB</emphasis> file on the system control machine, which distributes its copy to all
+               other server machines. The <emphasis>OpenAFS Quick Beginnings</emphasis> explains how to configure the Update Server.
+               If you run the international version of AFS, you must update the file on each machine individually.</para>
+ 
+               <para>The only reason to alter the file is when configuring or decommissioning a database server machine. Use the
+               appropriate <emphasis role="bold">bos</emphasis> commands rather than editing the file by hand. For instructions, see
+               <link linkend="HDRWQ118">Maintaining the Server CellServDB File</link>. The instructions in <link
+               linkend="HDRWQ142">Monitoring and Controlling Server Processes</link> for stopping and starting processes remind you
+               to alter the <emphasis role="bold">CellServDB</emphasis> file when appropriate, as do the instructions in the
+               <emphasis>OpenAFS Quick Beginnings</emphasis> for installing or decommissioning a database server machine.</para>
+ 
+               <para>(Client processes and the server processes that do not maintain databases also rely on correct information in
+               the <emphasis role="bold">CellServDB</emphasis> file for proper operation, but their use of the information does not
+               affect Ubik's operation. See <link linkend="HDRWQ118">Maintaining the Server CellServDB File</link> and <link
+               linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link>.)</para>
+ 
+               <indexterm>
+                 <primary>clocks</primary>
+ 
+                 <secondary>need to synchronize for Ubik</secondary>
+               </indexterm>
+             </listitem>
+ 
+             <listitem>
+               <para>Keep the clocks synchronized on all machines in the cell, especially the database server machines.</para>
+ 
+               <para>In the conventional configuration specified in the <emphasis>OpenAFS Quick Beginnings</emphasis>, you run the
+               <emphasis role="bold">runntp</emphasis> process to supervise the local Network Time Protocol Daemon (NTPD) on every
+               AFS server machine. The NTPD on the system control machine synchronizes its clock with a reliable source outside the
+               cell and broadcasts the time to the NTPDs on the other server machines. You can choose to run a different time
+               synchronization protocol if you wish.</para>
+ 
+               <para>Keeping clocks synchronized is important because the Ubik processes at a database's sites timestamp the messages
+               which they exchange to maintain constant contact. Timestamping the messages is necessary because in a networked
+               environment it is not safe to assume that a message reaches its destination instantly. Ubik compares the timestamp on
+               an incoming message with the current time. If the difference is too great, it is possible that an outage is preventing
+               reliable communication between the Ubik sites, which can possibly result in unsynchronized databases. Ubik considers
+               the message invalid, which can prompt it to attempt election of a different coordinator.</para>
+ 
+               <para>Electing a new coordinator is appropriate if a timestamped message is expired due to actual interruption of
+               communication, but not if a message appears expired only because the sender and recipient do not share the same time.
+               For detailed examples of how unsynchronized clocks can destabilize Ubik operation, see <link linkend="HDRWQ105">How
+               Ubik Uses Timestamped Messages</link>.</para>
+             </listitem>
+           </itemizedlist></para>
+ 
+         <indexterm>
+           <primary>Ubik</primary>
+ 
+           <secondary>features summarized</secondary>
+         </indexterm>
+ 
+         <indexterm>
+           <primary>process</primary>
+ 
+           <secondary>lightweight Ubik</secondary>
+         </indexterm>
+ 
+         <indexterm>
+           <primary>Ubik</primary>
+ 
+           <secondary>server and client portions</secondary>
+         </indexterm>
+       </sect3>
+ 
+       <sect3 id="HDRWQ104">
+         <title>How Ubik Operates Automatically</title>
+ 
+         <para>The following Ubik features help keep its maintenance requirements to a minimum: <itemizedlist>
+             <listitem>
+               <para>Ubik's server and client portions operate automatically.</para>
+ 
+               <para>Each database server process runs a lightweight process to call on the server portion of the Ubik library. It is
+               common to refer to this lightweight process itself as Ubik. Because it is lightweight, the Ubik process does not
+               appear in process listings such as those generated by the UNIX <emphasis role="bold">ps</emphasis> command.
+               Client-side programs that need to read and change the databases directly call the subroutines in the Ubik library's
+               client portion, rather than running a separate lightweight process. Examples of such programs are the <emphasis
+               role="bold">klog</emphasis> command and the commands in the <emphasis role="bold">pts</emphasis> suite.</para>
+             </listitem>
+ 
+             <listitem>
+               <para>Ubik tracks database version numbers.</para>
+ 
+               <para>As the coordinator records a change to a database, it increments the database's version number. The version
+               number makes it easy for the coordinator to determine if a site has the most recent version or not. The version number
+               speeds the return to normal functioning after election of a new coordinator or when communication is restored after an
+               outage, because it makes it easy to determine which site has the most current database and which need to be
+               updated.</para>
+             </listitem>
+ 
+             <listitem>
+               <para>Ubik's use of timestamped messages guarantees that database copies are always synchronized during normal
+               operation.</para>
+ 
+               <para>Replicating a database to increase data availability is pointless if all copies of the database are not the
+               same. Inconsistent performance can result if clients receive different information depending on which copy of the
+               database they access. As previously noted, Ubik sites constantly track the status of their peers by exchanging
+               timestamped messages. For a detailed description, see <link linkend="HDRWQ105">How Ubik Uses Timestamped
+               Messages</link>.</para>
+             </listitem>
+ 
+             <listitem>
+               <para>The ability to move the coordinator maximizes database availability.</para>
+ 
+               <para>Suppose, for example, that in a cell with three database server machines a network partition separates the two
+               secondary sites from the coordinator. The coordinator retires because it is no longer in contact with a majority of
+               the sites listed in the <emphasis role="bold">CellServDB</emphasis> file. The two sites on the other side of the
+               partition can elect a new coordinator among themselves, and it can then accept database changes from clients. If the
+               coordinator cannot move in this way, the database has to be read-only until the network partition is repaired. For a
+               detailed description of Ubik's election procedure, see <link linkend="HDRWQ106">A Flexible Coordinator Boosts
+               Availability</link>.</para>
+             </listitem>
+           </itemizedlist></para>
+ 
+         <indexterm>
+           <primary>consistency guarantees</primary>
+ 
+           <secondary>administrative databases</secondary>
+         </indexterm>
+ 
+         <indexterm>
+           <primary>Ubik</primary>
+ 
+           <secondary>consistency guarantees</secondary>
+         </indexterm>
+ 
+         <sect4 id="HDRWQ105">
+           <title>How Ubik Uses Timestamped Messages</title>
+ 
+           <para>Ubik synchronizes the copies of a database by maintaining constant contact between the synchronization site and the
+           secondary sites. The Ubik coordinator frequently sends a time-stamped <emphasis>guarantee</emphasis> message to each of
+           the secondary sites. When the secondary site receives the message, it concludes that it is in contact with the
+           coordinator. It considers its copy of the database to be valid until time <emphasis>T</emphasis>, which is usually 60
+           seconds from the time the coordinator sent the message. In response, the secondary site returns a
+           <emphasis>vote</emphasis> message that acknowledges the coordinator as valid until a certain time X, which is usually 120
+           seconds in the future.</para>
+ 
+           <para>The coordinator sends guarantee messages more frequently than every <emphasis>T</emphasis> seconds, so that the
+           expiration periods overlap. There is no danger of expiration unless a network partition or other outage actually
+           interrupts communication. If the guarantee expires, the secondary site's copy of the database it not necessarily current.
+           Nonetheless, the database server continues to service client requests. It is considered better for overall cell
+           functioning that a secondary site remains accessible even if the information it is distributing is possibly out of date.
+           Most of the AFS administrative databases do not change that frequently, in any case, and making a database inaccessible
+           causes a timeout for clients that happen to access that copy.</para>
+ 
+           <para>As previously mentioned, Ubik's use of timestamped messages makes it vital to synchronize the clocks on database
+           server machines. There are two ways that skewed clocks can interrupt normal Ubik functioning, depending on which clock is
+           ahead of the others.</para>
+ 
+           <para>Suppose, for example, that the Ubik coordinator's clock is ahead of the secondary sites: the coordinator's clock
+           says 9:35:30, but the secondary clocks say 9:31:30. The secondary sites send votes messages that acknowledge the
+           coordinator as valid until 9:33:30. This is two minutes in the future according to the secondary clocks, but is already in
+           the past from the coordinator's perspective. The coordinator concludes that it no longer has enough support to remain
+           coordinator and forces election of a new coordinator. Election takes about three minutes, during which time no copy of the
+           database accepts changes.</para>
+ 
+           <para>The opposite possibility is that a secondary site's clock (14:50:00) is ahead of the coordinator's (14:46:30). When
+           the coordinator sends a guarantee message good until 14:47:30), it has already expired according to the secondary clock.
+           Believing that it is out of contact with the coordinator, the secondary site stops sending votes for the coordinator and
+           tries get itself elected as coordinator. This is appropriate if the coordinator has actually failed, but is inappropriate
+           when there is no actual outage.</para>
+ 
+           <para>The attempt of a single secondary site to get elected as the new coordinator usually does not affect the performance
+           of the other sites. As long as their clocks agree with the coordinator's, they ignore the other secondary site's request
+           for votes and continue voting for the current coordinator. However, if enough of the secondary sites's clocks get ahead of
+           the coordinator's, they can force election of a new coordinator even though the current one is actually working
+           fine.</para>
+ 
+           <indexterm>
+             <primary>Ubik</primary>
+ 
+             <secondary>election of coordinator</secondary>
+           </indexterm>
+ 
+           <indexterm>
+             <primary>coordinator (Ubik)</primary>
+ 
+             <secondary>election procedure described</secondary>
+           </indexterm>
+ 
+           <indexterm>
+             <primary>election of Ubik coordinator</primary>
+           </indexterm>
+ 
+           <indexterm>
+             <primary>flexible synchronization site (Ubik)</primary>
+           </indexterm>
+ 
+           <indexterm>
+             <primary>synchronization site (Ubik)</primary>
+ 
+             <secondary>flexibility</secondary>
+           </indexterm>
+ 
+           <indexterm>
+             <primary>Ubik</primary>
+ 
+             <secondary>majority defined</secondary>
+           </indexterm>
+ 
+           <indexterm>
+             <primary>majority</primary>
+ 
+             <secondary>defined for Ubik</secondary>
+           </indexterm>
+ 
+           <indexterm>
+             <primary>outages</primary>
+ 
+             <secondary>due to Ubik election</secondary>
+           </indexterm>
+ 
+           <indexterm>
+             <primary>system outages</primary>
+ 
+             <secondary>due to Ubik election</secondary>
+           </indexterm>
+         </sect4>
+ 
+         <sect4 id="HDRWQ106">
+           <title>A Flexible Coordinator Boosts Availability</title>
+ 
+           <para>Ubik uses timestamped messages to determine when coordinator election is necessary, just as it does to keep the
+           database copies synchronized. As long as the coordinator receives vote messages from a majority of the sites (it
+           implicitly votes for itself), it is appropriate for it to continue as coordinator because it is successfully distributing
+           database changes. A majority is defined as more than 50% of all database sites when there are an odd number of sites; with
+           an even number of sites, the site with the lowest Internet address has an extra vote for breaking ties as necessary.If the
+           coordinator is not receiving sufficient votes, it retires and the Ubik sites elect a new coordinator. This does not happen
+           spontaneously, but only when the coordinator really fails or stops receiving a majority of the votes. The secondary sites
+           have a built-in bias to continue voting for an existing coordinator, which prevents undue elections.</para>
+ 
+           <para>The election of the new coordinator is by majority vote. The Ubik subprocesses have a bias to vote for the site with
+           the lowest Internet address, which helps it gather the necessary majority quicker than if all the sites were competing to
+           receive votes themselves. During the election (which normally lasts less than three minutes), clients can read information
+           from the database, but cannot make any changes.</para>
+ 
+           <para>Ubik's election procedure makes it possible for each database server process's coordinator to be on a different
+           machine. For example, if the Ubik coordinators for all four processes start out on machine A and the Protection Server on
+           machine A fails for some reason, then a different site (say machine B) must be elected as the new Protection Database Ubik
+           coordinator. Machine B remains the coordinator for the Protection Database even after the Protection Server on machine A
+           is working again. The failure of the Protection Server has no effect on the Authentication, Backup, or VL Servers, so
+           their coordinators remain on machine A.</para>
+         </sect4>
+       </sect3>
+     </sect2>
+ 
+     <sect2 id="HDRWQ107">
+       <title>Backing Up and Restoring the Administrative Databases</title>
+ 
+       <para>The AFS administrative databases store information that is critical for AFS operation in your cell. If a database
+       becomes corrupted due to a hardware failure or other problem on a database server machine, it likely to be difficult and
+       time-consuming to recreate all of the information from scratch. To protect yourself against loss of data, back up the
+       administrative databases to a permanent media, such as tape, on a regular basis. The recommended method is to use a standard
+       local disk backup utility such as the UNIX <emphasis role="bold">tar</emphasis> command.</para>
+ 
+       <para>When deciding how often to back up a database, consider the amount of data that you are willing to recreate by hand if
+       it becomes necessary to restore the database from a backup copy. In most cells, the databases differ quite a bit in how often
+       and how much they change. Changes to the Authentication Database are probably the least frequent, and consist mostly of
+       changed user passwords. Protection Database and VLDB changes are probably more frequent, as users add or delete groups and
+       change group memberships, and as you and other administrators create or move volumes. The number and frequency of changes is
+       probably greatest in the Backup Database, particularly if you perform backups every day.</para>
+ 
+       <para>The ease with which you can recapture lost changes also differs for the different databases: <itemizedlist>
+           <listitem>
+             <para>If regular users make a large proportion of the changes to the Authentication Database and Protection Database in
+             your cell, then recovering them possibly requires a large amount of detective work and interviewing of users, assuming
+             that they can even remember what changes they made at what time.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>Recovering lost changes to the VLDB is more straightforward, because you can use the <emphasis role="bold">vos
+             syncserv</emphasis> and <emphasis role="bold">vos syncvldb</emphasis> commands to correct any discrepancies between the
+             VLDB and the actual state of volumes on server machines. Running these commands can be time-consuming, however.</para>
+           </listitem>
+ 
+           <listitem>
+             <para>The configuration information in the Backup Database (Tape Coordinator port offsets, volume sets and entries, the
+             dump hierarchy, and so on) probably does not change that often, in which case it is not that hard to recover a few
+             recent changes. In contrast, there are likely to be a large number of new dump records resulting from dump operations.
+             You can recover these records by using the <emphasis role="bold">-dbadd</emphasis> argument to the <emphasis
+             role="bold">backup scantape</emphasis> command, reading in information from the backup tapes themselves. This can take a
+             long time and require numerous tape changes, however, depending on how much data you back up in your cell and how you
+             append dumps. Furthermore, the <emphasis role="bold">backup scantape</emphasis> command is subject to several
+             restrictions. The most basic is that it halts if it finds that an existing dump record in the database has the same dump
+             ID number as a dump on the tape it is scanning. If you want to continue with the scanning operation, you must locate and
+             remove the existing record from the database. For further discussion, see the <emphasis role="bold">backup
+             scantape</emphasis> command's reference page in the <emphasis>OpenAFS Administration Reference</emphasis>.</para>
+           </listitem>
+         </itemizedlist></para>
+ 
+       <para>These differences between the databases possibly suggest backing up the database at different frequencies, ranging from
+       every few days or weekly for the Backup Database to every few weeks for the Authentication Database. On the other hand, it is
+       probably simpler from a logistical standpoint to back them all up at the same time (and frequently), particularly if tape
+       consumption is not a major concern. Also, it is not generally necessary to keep backup copies of the databases for a long
+       time, so you can recycle the tapes fairly frequently.</para>
+ 
+       <indexterm>
+         <primary>administrative database</primary>
+ 
+         <secondary>backing up</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>backing up</primary>
+ 
+         <secondary>administrative databases</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ108">
+       <title>To back up the administrative databases</title>
+ 
+       <orderedlist>
+         <listitem>
+           <para>Log in as the local superuser <emphasis role="bold">root</emphasis> on a database server machine that is not the
+           synchronization site. The machine with the highest IP address is normally the best choice, since it is least likely to
+           become the synchronization site in an election.</para>
+         </listitem>
+ 
+         <listitem>
+           <para><anchor id="LIDBBK_SHUTDOWN" />Issue the <emphasis role="bold">bos shutdown</emphasis> command to shut down the
+           relevant server process on the local machine. For a complete description of the command, see <link linkend="HDRWQ168">To
+           stop processes temporarily</link>.</para>
+ 
+           <para>For the <emphasis role="bold">-instance</emphasis> argument, specify one or more database server process names
+           (<emphasis role="bold">buserver</emphasis> for the Backup Server, <emphasis role="bold">kaserver</emphasis> for the
+           Authentication Server, <emphasis role="bold">ptserver</emphasis> for the Protection Server, or <emphasis
+           role="bold">vlserver</emphasis> for the Volume Location Server. Include the <emphasis role="bold">-localauth</emphasis>
+           flag because you are logged in as the local superuser <emphasis role="bold">root</emphasis> but do not necessarily have
+           administrative tokens.</para>
+ 
+           <programlisting>
+    # <emphasis role="bold">bos shutdown</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-instance</emphasis> &lt;<replaceable>instances</replaceable>&gt;+ <emphasis
+               role="bold">-localauth</emphasis> [<emphasis role="bold">-wait</emphasis>]
+ </programlisting>
+         </listitem>
+ 
+         <listitem>
+           <para>Use a local disk backup utility, such as the UNIX <emphasis role="bold">tar</emphasis> command, to transfer one or
+           more database files to tape. If the local database server machine does not have a tape device attached, use a remote copy
+           command to transfer the file to a machine with a tape device, then use the <emphasis role="bold">tar</emphasis> command
+           there.</para>
+ 
+           <para>The following command sequence backs up the complete contents of the <emphasis role="bold">/usr/afs/db</emphasis>
+           directory</para>
+ 
+           <programlisting>
+    # <emphasis role="bold">cd /usr/afs/db</emphasis>
+    # <emphasis role="bold">tar cvf</emphasis>  tape_device <emphasis role="bold">.</emphasis>
+ </programlisting>
+ 
+           <para>To back up individual database files, substitute their names for the period in the preceding <emphasis
+           role="bold">tar</emphasis> command: <itemizedlist>
+               <listitem>
+                 <para><emphasis role="bold">bdb.DB0</emphasis> for the Backup Database</para>
+               </listitem>
+ 
+               <listitem>
+                 <para><emphasis role="bold">kaserver.DB0</emphasis> for the Authentication Database</para>
+               </listitem>
+ 
+               <listitem>
+                 <para><emphasis role="bold">prdb.DB0</emphasis> for the Protection Database</para>
+               </listitem>
+ 
+               <listitem>
+                 <para><emphasis role="bold">vldb.DB0</emphasis> for the VLDB</para>
+               </listitem>
+             </itemizedlist></para>
+         </listitem>
+ 
+         <listitem>
+           <para>Issue the <emphasis role="bold">bos start</emphasis> command to restart the server processes on the local machine.
+           For a complete description of the command, see <link linkend="HDRWQ166">To start processes by changing their status flags
+           to Run</link>. Provide the same values for the <emphasis role="bold">-instance</emphasis> argument as in Step <link
+           linkend="LIDBBK_SHUTDOWN">2</link>, and the <emphasis role="bold">-localauth</emphasis> flag for the same reason.
+           <programlisting>
+    # <emphasis role="bold">bos start</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-instance</emphasis> &lt;<replaceable>server process name</replaceable>&gt;+ <emphasis
+                 role="bold">-localauth</emphasis>
+ </programlisting></para>
+         </listitem>
+       </orderedlist>
+ 
+       <indexterm>
+         <primary>administrative database</primary>
+ 
+         <secondary>restoring</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>restoring</primary>
+ 
+         <secondary>administrative databases</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="HDRWQ109">
+       <title>To restore an administrative database</title>
+ 
+       <orderedlist>
+         <listitem>
+           <para>Log in as the local superuser <emphasis role="bold">root</emphasis> on each database server machine in the
+           cell.</para>
+         </listitem>
+ 
+         <listitem>
+           <para><anchor id="LIDBREST_SHUTDOWN" />Working on one of the machines, issue the <emphasis role="bold">bos
+           shutdown</emphasis> command once for each database server machine, to shut down the relevant server process on all of
+           them. For a complete description of the command, see <link linkend="HDRWQ168">To stop processes temporarily</link>.</para>
+ 
+           <para>For the <emphasis role="bold">-instance</emphasis> argument, specify one or more database server process names
+           (<emphasis role="bold">buserver</emphasis> for the Backup Server, <emphasis role="bold">kaserver</emphasis> for the
+           Authentication Server, <emphasis role="bold">ptserver</emphasis> for the Protection Server, or <emphasis
+           role="bold">vlserver</emphasis> for the Volume Location Server. Include the <emphasis role="bold">-localauth</emphasis>
+           flag because you are logged in as the local superuser <emphasis role="bold">root</emphasis> but do not necessarily have
+           administrative tokens.</para>
+ 
+           <programlisting>
+    # <emphasis role="bold">bos shutdown</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-instance</emphasis> &lt;<replaceable>instances</replaceable>&gt;+ <emphasis
+               role="bold">-localauth</emphasis> [<emphasis role="bold">-wait</emphasis>]
+ </programlisting>
+         </listitem>
+ 
+         <listitem>
+           <para>Remove the database from each database server machine, by issuing the following commands on each one.
+           <programlisting>
+    # <emphasis role="bold">cd /usr/afs/db</emphasis>
+ </programlisting></para>
+ 
+           <para>For the Backup Database:</para>
+ 
+           <programlisting>
+    # <emphasis role="bold">rm bdb.DB0</emphasis>
+    # <emphasis role="bold">rm bdb.DBSYS1</emphasis>
+ </programlisting>
+ 
+           <para>For the Authentication Database:</para>
+ 
+           <programlisting>
+    # <emphasis role="bold">rm kaserver.DB0</emphasis>
+    # <emphasis role="bold">rm kaserver.DBSYS1</emphasis>
+ </programlisting>
+ 
+           <para>For the Protection Database:</para>
+ 
+           <programlisting>
+    # <emphasis role="bold">rm prdb.DB0</emphasis>
+    # <emphasis role="bold">rm prdb.DBSYS1</emphasis>
+ </programlisting>
+ 
+           <para>For the VLDB:</para>
+ 
+           <programlisting>
+    # <emphasis role="bold">rm vldb.DB0</emphasis>
+    # <emphasis role="bold">rm vldb.DBSYS1</emphasis>
+ </programlisting>
+         </listitem>
+ 
+         <listitem>
+           <para>Using the local disk backup utility that you used to back up the database, copy the most recently backed-up version
+           of it to the appropriate file on the database server machine with the lowest IP address. The following is an appropriate
+           <emphasis role="bold">tar</emphasis> command if the synchronization site has a tape device attached: <programlisting>
+    # <emphasis role="bold">cd /usr/afs/db</emphasis>
+    # <emphasis role="bold">tar xvf</emphasis> tape_device  database_file
+ </programlisting></para>
+ 
+           <para>where <emphasis>database_file</emphasis> is one of the following: <itemizedlist>
+               <listitem>
+                 <para><emphasis role="bold">bdb.DB0</emphasis> for the Backup Database</para>
+               </listitem>
+ 
+               <listitem>
+                 <para><emphasis role="bold">kaserver.DB0</emphasis> for the Authentication Database</para>
+               </listitem>
+ 
+               <listitem>
+                 <para><emphasis role="bold">prdb.DB0</emphasis> for the Protection Database</para>
+               </listitem>
+ 
+               <listitem>
+                 <para><emphasis role="bold">vldb.DB0</emphasis> for the VLDB</para>
+               </listitem>
+             </itemizedlist></para>
+         </listitem>
+ 
+         <listitem>
+           <para>Working on one of the machines, issue the <emphasis role="bold">bos start</emphasis> command to restart the server
+           process on each of the database server machines in turn. Start with the machine with the lowest IP address, which becomes
+           the synchronization site for the Backup Database. Wait for it to establish itself as the synchronization site before
+           repeating the command to restart the process on the other database server machines. For a complete description of the
+           command, see <link linkend="HDRWQ166">To start processes by changing their status flags to Run</link>. Provide the same
+           values for the <emphasis role="bold">-instance</emphasis> argument as in Step <link linkend="LIDBREST_SHUTDOWN">2</link>,
+           and the <emphasis role="bold">-localauth</emphasis> flag for the same reason. <programlisting>
+    # <emphasis role="bold">bos start</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-instance</emphasis>  &lt;<replaceable>server process name</replaceable>&gt;+  <emphasis
+                 role="bold">-localauth</emphasis>
+ </programlisting></para>
+         </listitem>
+ 
+         <listitem>
+           <para>If the database has changed since you last backed it up, issue the appropriate commands from the instructions in the
+           indicated sections to recreate the information in the restored database. If issuing <emphasis role="bold">pts</emphasis>
+           commands, you must first obtain administrative tokens. The <emphasis role="bold">backup</emphasis> and <emphasis
+           role="bold">vos</emphasis> commands accept the <emphasis role="bold">-localauth</emphasis> flag if you are logged in as
+           the local superuser <emphasis role="bold">root</emphasis>, so you do not need administrative tokens. The Authentication
+           Server always performs a separate authentication anyway, so you only need to include the <emphasis
+           role="bold">-admin</emphasis> argument if issuing <emphasis role="bold">kas</emphasis> commands. <itemizedlist>
+               <listitem>
+                 <para>To define or remove volume sets and volume entries in the Backup Database, see <link
+                 linkend="HDRWQ265">Defining and Displaying Volume Sets and Volume Entries</link>.</para>
+               </listitem>
+ 
+               <listitem>
+                 <para>To edit the dump hierarchy in the Backup Database, see <link linkend="HDRWQ267">Defining and Displaying the
+                 Dump Hierarchy</link>.</para>
+               </listitem>
+ 
+               <listitem>
+                 <para>To define or remove Tape Coordinator port offset entries in the Backup Database, see <link
+                 linkend="HDRWQ261">Configuring Tape Coordinator Machines and Tape Devices</link>.</para>
+               </listitem>
+ 
+               <listitem>
+                 <para>To restore dump records in the Backup Database, see <link linkend="HDRWQ305">To scan the contents of a
+                 tape</link>.</para>
+               </listitem>
+ 
+               <listitem>
+                 <para>To recreate Authentication Database entries or password changes for users, see the appropriate section of
+                 <link linkend="HDRWQ491">Administering User Accounts</link>.</para>
+               </listitem>
+ 
+               <listitem>
+                 <para>To recreate Protection Database entries or group membership information, see the appropriate section of <link
+                 linkend="HDRWQ531">Administering the Protection Database</link>.</para>
+               </listitem>
+ 
+               <listitem>
+                 <para>To synchronize the VLDB with volume headers, see <link linkend="HDRWQ227">Synchronizing the VLDB and Volume
+                 Headers</link>.</para>
+               </listitem>
+             </itemizedlist></para>
+         </listitem>
+       </orderedlist>
+ 
+       <indexterm>
+         <primary>installing</primary>
+ 
+         <secondary>server process binaries, about</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>server process binaries</primary>
+ 
+         <secondary>installing</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>BOS Server</primary>
+ 
+         <secondary>maintainer of server process binaries</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>server process</primary>
+ 
+         <secondary>binaries</secondary>
+ 
+         <see>server process binaries</see>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>directories (server)</primary>
+ 
+         <secondary>/usr/afs/bin</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>server machine</primary>
+ 
+         <secondary>need for consistent version of software</secondary>
+       </indexterm>
+     </sect2>
+   </sect1>
+ 
+   <sect1 id="HDRWQ110">
+     <title>Installing Server Process Software</title>
+ 
+     <para>This section explains how to install new server process binaries on file server machines, how to revert to a previous
+     version if the current version is not working properly, and how to install new disks to house AFS volumes on a file server
+     machine.</para>
+ 
+     <para>The most frequent reason to replace a server process's binaries is to upgrade AFS to a new version. In general,
+     installation instructions accompany the updated software, but this chapter provides an additional reference.</para>
+ 
+     <para>Each AFS server machine must store the server process binaries in a local disk directory, called <emphasis
+     role="bold">/usr/afs/bin</emphasis> by convention. For predictable system performance, it is best that all server machines run
+     the same build level, or at least the same version, of the server software. For instructions on checking AFS build level, see
+     <link linkend="HDRWQ117">Displaying A Binary File's Build Level</link>.</para>
+ 
+     <para>The Update Server makes it easy to distribute a consistent version of software to all server machines. You designate one
+     server machine of each system type as the <emphasis>binary distribution machine</emphasis> by running the server portion of the
+     Update Server (<emphasis role="bold">upserver</emphasis> process) on it. All other server machines of that system type run the
+     client portion of the Update Server (<emphasis role="bold">upclientbin</emphasis> process) to retrieve updated software from the
+     binary distribution machine. The <emphasis>OpenAFS Quick Beginnings</emphasis> explains how to install the appropriate
+     processes. For more on binary distribution machines, see <link linkend="HDRWQ93">Binary Distribution Machines</link>.</para>
+ 
+     <para>When you use the Update Server, you install new binaries on binary distribution machines only. If you install binaries
+     directly on a machine that is running the <emphasis role="bold">upclientbin</emphasis> process, they are overwritten the next
+     time the process compares the contents of the local <emphasis role="bold">/usr/afs/bin</emphasis> directory to the contents on
+     the system control machine, by default within five minutes.</para>
+ 
+     <para>The following instructions explain how to use the appropriate commands from the <emphasis role="bold">bos</emphasis> suite
+     to install and uninstall server binaries.</para>
+ 
+     <indexterm>
+       <primary>installing</primary>
+ 
+       <secondary>server binaries</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>server process binaries</primary>
+ 
+       <secondary>installing</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>command suite</primary>
+ 
+       <secondary>binaries</secondary>
+ 
+       <tertiary>installing</tertiary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>file server machine</primary>
+ 
+       <secondary>installing command and process binaries</secondary>
+     </indexterm>
+ 
+     <indexterm>
+       <primary>server process</primary>
+ 
+       <secondary>restarting for changed binaries</secondary>
+     </indexterm>
+ 
+     <sect2 id="HDRWQ111">
+       <title>Installing New Binaries</title>
+ 
+       <para>An AFS server process does not automatically switch to a new process binary file as soon as it is installed in the
+       <emphasis role="bold">/usr/afs/bin</emphasis> directory. The process continues to use the previous version of the binary file
+       until it (the process) next restarts. By default, the BOS Server restarts processes for which there are new binary files every
+       day at 5:00 a.m., as specified in the <emphasis role="bold">/usr/afs/local/BosConfig</emphasis> file. To display or change
+       this <emphasis>binary restart time</emphasis>, use the <emphasis role="bold">bos getrestart</emphasis> and <emphasis
+       role="bold">bos setrestart</emphasis> commands, as described in <link linkend="HDRWQ171">Setting the BOS Server's Restart
+       Times</link>.</para>
+ 
+       <para>You can force the server machine to start using new server process binaries immediately by issuing the <emphasis
+       role="bold">bos restart</emphasis> command as described in the following instructions.</para>
+ 
+       <para>You do not need to restart processes when you install new command suite binaries. The new binary is invoked
+       automatically the next time a command from the suite is issued.</para>
+ 
+       <indexterm>
+         <primary>file extension</primary>
+ 
+         <secondary>.BAK</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>file extension</primary>
+ 
+         <secondary>.OLD</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>BAK version of binary file</primary>
+ 
+         <secondary>created by bos install command</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>OLD version of binary file</primary>
+ 
+         <secondary>created by bos install command</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>saving</primary>
+ 
+         <secondary>previous version of server binaries</secondary>
+       </indexterm>
+ 
+       <para>When you use the <emphasis role="bold">bos install</emphasis> command, the BOS Server automatically saves the current
+       version of a binary file by adding a <emphasis role="bold">.BAK</emphasis> extension to its name. It renames the current
+       <emphasis role="bold">.BAK</emphasis> version, if any, to the <emphasis role="bold">.OLD</emphasis> version, if there is no
+       <emphasis role="bold">.OLD</emphasis> version already. If there is a current <emphasis role="bold">.OLD</emphasis> version,
+       the current <emphasis role="bold">.BAK</emphasis> version must be at least seven days old to replace it.</para>
+ 
+       <para>It is best to store AFS binaries in the <emphasis role="bold">/usr/afs/bin</emphasis> directory, because that is the
+       only directory the BOS Server automatically checks for new binaries. You can, however, use the <emphasis role="bold">bos
+       install</emphasis> command's <emphasis role="bold">-dir</emphasis> argument to install non-AFS binaries into other directories
+       on a server machine's local disk. See the command's reference page in the <emphasis>OpenAFS Administration
+       Reference</emphasis> for further information.</para>
+ 
+       <indexterm>
+         <primary>bos commands</primary>
+ 
+         <secondary>install</secondary>
+       </indexterm>
+ 
+       <indexterm>
+         <primary>commands</primary>
+ 
+         <secondary>bos install</secondary>
+       </indexterm>
+     </sect2>
+ 
+     <sect2 id="Header_130">
+       <title>To install new server binaries</title>
+ 
+       <orderedlist>
+         <listitem>
+           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
+           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
+           display the users in the UserList file</link>. <programlisting>
+    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
+ </programlisting></para>
+         </listitem>
+ 
+         <listitem>
+           <para>Verify that the binaries are available in the source directory from which you are installing them. If the machine is
+           also an AFS client, you can retrieve the binaries from a central directory in AFS. Otherwise, you can obtain them directly
+           from the AFS distribution media, from a local disk directory where you previously installed them, or from a remote machine
+           using a transfer utility such as the <emphasis role="bold">ftp</emphasis> command.</para>
+         </listitem>
+ 
+         <listitem>
+           <para><anchor id="LIWQ112" />Issue the <emphasis role="bold">bos install</emphasis> command for the binary distribution
+           machine. (If you have forgotten which machine is performing that role, see <link linkend="HDRWQ97">To locate the binary
+           distribution machine for a system type</link>.) <programlisting>
+    % <emphasis role="bold">bos install</emphasis> &lt;<replaceabl