man5-editing-pass-20051213
authorRuss Allbery <rra@stanford.edu>
Wed, 14 Dec 2005 01:30:20 +0000 (01:30 +0000)
committerRuss Allbery <rra@stanford.edu>
Wed, 14 Dec 2005 01:30:20 +0000 (01:30 +0000)
This completes the first editing pass of the man pages.  Very little
content editing has been done, but the server and client versions of
various man pages have been combined into a single man page for the
file (affects CellServDB, ThisCell, NetInfo, and NetRestrict), the
descriptions of the various AFS cache files have been combined into one
afs_cache man page, and the descriptions of the two butc log files have
been combined into one butc_logs man page.

For man pages for databases with two files, symlinks are now created on
installation for the secondary file name.

All of the man pages should now be ready for public review, additional
editing and cleanup, and content editing.

55 files changed:
doc/man-pages/README
doc/man-pages/pod1/fs.pod
doc/man-pages/pod5/AuthLog.dir.pod
doc/man-pages/pod5/AuthLog.pod
doc/man-pages/pod5/BackupLog.pod
doc/man-pages/pod5/BosConfig.pod
doc/man-pages/pod5/BosLog.pod
doc/man-pages/pod5/CacheItems.pod [deleted file]
doc/man-pages/pod5/CellServDB.pod [new file with mode: 0644]
doc/man-pages/pod5/FORCESALVAGE.pod
doc/man-pages/pod5/FileLog.pod
doc/man-pages/pod5/KeyFile.pod
doc/man-pages/pod5/NetInfo.pod [new file with mode: 0644]
doc/man-pages/pod5/NetRestrict.pod [new file with mode: 0644]
doc/man-pages/pod5/NoAuth.pod
doc/man-pages/pod5/SALVAGE.fs.pod
doc/man-pages/pod5/SalvageLog.pod
doc/man-pages/pod5/ThisCell.pod [new file with mode: 0644]
doc/man-pages/pod5/UserList.pod
doc/man-pages/pod5/VLLog.pod
doc/man-pages/pod5/VolserLog.pod
doc/man-pages/pod5/VolumeItems.pod [deleted file]
doc/man-pages/pod5/afs.pod [new file with mode: 0644]
doc/man-pages/pod5/afs_cache.pod [new file with mode: 0644]
doc/man-pages/pod5/afs_volume_header.pod
doc/man-pages/pod5/afsmonitor.pod
doc/man-pages/pod5/afszcm.cat.pod
doc/man-pages/pod5/bdb.DB0.pod
doc/man-pages/pod5/butc.pod [new file with mode: 0644]
doc/man-pages/pod5/butc_logs.pod [new file with mode: 0644]
doc/man-pages/pod5/cacheinfo.pod
doc/man-pages/pod5/fms.log.pod
doc/man-pages/pod5/kaserver.DB0.pod
doc/man-pages/pod5/kaserverauxdb.pod
doc/man-pages/pod5/package.pod
doc/man-pages/pod5/prdb.DB0.pod
doc/man-pages/pod5/salvage.lock.pod
doc/man-pages/pod5/sysid.pod
doc/man-pages/pod5/tapeconfig.pod
doc/man-pages/pod5/uss.pod
doc/man-pages/pod5/uss_bulk.pod
doc/man-pages/pod5/vldb.DB0.pod
doc/man-pages/pod8/afsd.pod
doc/man-pages/pod8/backup.pod
doc/man-pages/pod8/backup_diskrestore.pod
doc/man-pages/pod8/backup_dump.pod
doc/man-pages/pod8/backup_dumpinfo.pod
doc/man-pages/pod8/backup_labeltape.pod
doc/man-pages/pod8/backup_readlabel.pod
doc/man-pages/pod8/backup_restoredb.pod
doc/man-pages/pod8/backup_savedb.pod
doc/man-pages/pod8/backup_scantape.pod
doc/man-pages/pod8/backup_volrestore.pod
doc/man-pages/pod8/backup_volsetrestore.pod
doc/man-pages/pod8/butc.pod

index 4bcfaef..682993b 100644 (file)
@@ -234,7 +234,8 @@ Known Problems
      multiple different paths, but it would be good to at least
      acknowledge the issue.
 
-   * bos listkeys assumes that you're using the kaserver.
+   * bos listkeys and the KeyFile man page assume that you're using the
+     kaserver.
 
    * I'm fairly sure that the fileserver man page no longer documents all
      of the fileserver options.
@@ -249,6 +250,11 @@ Known Problems
      use.  Also, all of the manual references refer to the "IBM" manual.
      We should decide how to handle this terminology-wise.
 
+   * 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.
+
   If you notice other problems, please send them to the openafs-doc list
   even if you don't have time to fix them.  Someone else might, and we
   want to track all of the issues.
index 0c65b4b..7b315ee 100644 (file)
@@ -143,10 +143,9 @@ No privilege. Many B<fs> commands simply list information.
 
 =head1 SEE ALSO
 
-L<CacheItems(5)>,
+L<afs_cache(5)>,
 L<CellServDB(5)>,
 L<ThisCell(5)>
-L<VolumeItems(5)>,
 L<cacheinfo(5)>,
 L<fs_apropos(1)>,
 L<fs_checkservers(1)>,
index c4e2fdc..d618b86 100644 (file)
@@ -1,30 +1,29 @@
 =head1 NAME
 
-AuthLog.dir, AuthLog.pag - Records privileged operations performed by the Authentication Server
+AuthLog.dir, AuthLog.pag - Log of Authentication Server privileged operations
 
 =head1 DESCRIPTION
 
-The B<AuthLog.dir> and AuthLog.pag files
-record a trace of privileged operations performed by the Authentication Server
-(B<kaserver> process) on the local machine. If the files do not
-exist when the Authentication Server starts, it creates them in the
-B</usr/afs/logs> directory as necessary.
+The F<AuthLog.dir> and F<AuthLog.pag> files record a trace of privileged
+operations performed by the Authentication Server (B<kaserver> process) on
+the local machine. If the files do not exist when the Authentication
+Server starts, it creates them in the F</usr/afs/logs> directory as
+necessary.
 
-The files are in binary format. To display their contents, use the
-B<kdb> command, which requires being logged in to the local machine as
-the local superuser B<root>.
+The files are in binary format. To display their contents, use the B<kdb>
+command, which requires being logged in to the local machine as the local
+superuser C<root>.
 
 =head1 CAUTIONS
 
 The Authentication Server is possibly unable to create these files on some
-operating systems that AFS otherwise supports, making the B<kdb>
-command inoperative. See the I<IBM AFS Release Notes> for
-details.
+operating systems that AFS otherwise supports, making the B<kdb> command
+inoperative. See the I<IBM AFS Release Notes> for details.
 
 =head1 SEE ALSO
 
-L<kaserver(1)>,
-L<kdb(1)>
+L<kaserver(8)>,
+L<kdb(8)>
 
 =head1 COPYRIGHT
 
index e694b03..fa3a1f6 100644 (file)
@@ -4,35 +4,33 @@ AuthLog - Traces Authentication Server operations
 
 =head1 DESCRIPTION
 
-The AuthLog file records a trace of Authentication Server
-(B<kaserver> process) operations on the local machine and describes
-any error conditions it encounters.
+The F<AuthLog> file records a trace of Authentication Server (B<kaserver>
+process) operations on the local machine and describes any error
+conditions it encounters.
 
-If the AuthLog file does not exist in the
-B</usr/afs/logs> directory when the Authentication Server starts, the
-server process creates it and writes initial start-up messages to it.
-If there is an existing file, the Authentication Server renames it to
-B<AuthLog.old>, overwriting the existing
-B<AuthLog.old> file if it exists.
+If the F<AuthLog> file does not exist in the F</usr/afs/logs> directory
+when the Authentication Server starts, the server process creates it and
+writes initial start-up messages to it.  If there is an existing file, the
+Authentication Server renames it to F<AuthLog.old>, overwriting the
+existing F<AuthLog.old> file if it exists.
 
 The file is in ASCII format. Administrators listed in the
-B</usr/afs/etc/UserList> file can use the B<bos getlog>
-command to display its contents. Alternatively, log onto the server
-machine and use a text editor or a file display command such as the UNIX
-B<cat> command. By default, the mode bits on the
-B<AuthLog> file grant the required B<r> (B<read>)
-permission to all users.
-
-The Authentication Server records operations only as it completes them, and
-cannot recover from failures by reviewing the file. The log contents
+F</usr/afs/etc/UserList> file can use the B<bos getlog> command to display
+its contents. Alternatively, log onto the server machine and use a text
+editor or a file display command such as the UNIX B<cat> command. By
+default, the mode bits on the F<AuthLog> file grant the required C<r>
+(read) permission to all users.
+
+The Authentication Server records operations only as it completes them,
+and cannot recover from failures by reviewing the file. The log contents
 are useful for administrative evaluation of process failures and other
 problems.
 
 =head1 SEE ALSO
 
-L<UserList(1)>,
-L<bos_getlog(1)>,
-L<kaserver(1)>
+L<UserList(5)>,
+L<bos_getlog(8)>,
+L<kaserver(8)>
 
 =head1 COPYRIGHT
 
index d5de6e2..3905d11 100644 (file)
@@ -4,35 +4,33 @@ BackupLog - Traces Backup Server operations
 
 =head1 DESCRIPTION
 
-The BackupLog file records a trace of Backup Server
-(B<buserver> process) operations on the local machine and describes
-any error conditions it encounters.
+The F<BackupLog> file records a trace of Backup Server (B<buserver>
+process) operations on the local machine and describes any error
+conditions it encounters.
 
-If the BackupLog file does not already exist in the
-B</usr/afs/logs> directory when the Backup Server starts, the server
-process creates it and writes initial start-up messages to it. If there
-is an existing file, the Backup Server renames it to
-B<BackupLog.old>, overwriting the existing
-B<BackupLog.old> file if it exists.
+If the F<BackupLog> file does not already exist in the F</usr/afs/logs>
+directory when the Backup Server starts, the server process creates it and
+writes initial start-up messages to it. If there is an existing file, the
+Backup Server renames it to F<BackupLog.old>, overwriting the existing
+F<BackupLog.old> file if it exists.
 
 The file is in ASCII format. Administrators listed in the
-B</usr/afs/etc/UserList> file can use the B<bos getlog>
-command to display its contents. Alternatively, log on to the machine
-and use a text editor or a file display command such as the UNIX
-B<cat> command. By default, the mode bits on the
-B<BackupLog> file grant the required B<r> (B<read>)
+F</usr/afs/etc/UserList> file can use the B<bos getlog> command to display
+its contents. Alternatively, log on to the machine and use a text editor
+or a file display command such as the UNIX B<cat> command. By default, the
+mode bits on the F<BackupLog> file grant the required C<r> (read)
 permission to all users.
 
 The Backup Server records operations only as it completes them, and so
-cannot recover from failures by reviewing the file. The log contents
-are useful for administrative evaluation of process failures and other
+cannot recover from failures by reviewing the file. The log contents are
+useful for administrative evaluation of process failures and other
 problems.
 
 =head1 SEE ALSO
 
-L<UserList(1)>,
-L<bos_getlog(1)>,
-L<buserver(1)>
+L<UserList(5)>,
+L<bos_getlog(8)>,
+L<buserver(8)>
 
 =head1 COPYRIGHT
 
index e6c7263..4d24bc8 100644 (file)
@@ -4,253 +4,216 @@ BosConfig - Defines server processes for the BOS Server to monitor
 
 =head1 DESCRIPTION
 
-The BosConfig file lists the processes that the Basic OverSeer
-(BOS) Server monitors on its server machine, and thus defines which AFS server
-processes run on the machine. It specifies how the BOS Server reacts
-when a process fails, and also defines the times at which the BOS Server
-automatically restarts processes as part of performance maintenance.
-The file must reside in the B</usr/afs/local> directory on each AFS
-server machine.
+The F<BosConfig> file lists the processes that the Basic OverSeer (BOS)
+Server monitors on its server machine, and thus defines which AFS server
+processes run on the machine. It specifies how the BOS Server reacts when
+a process fails, and also defines the times at which the BOS Server
+automatically restarts processes as part of performance maintenance.  The
+file must reside in the F</usr/afs/local> directory on each AFS server
+machine.
 
-A server process entry in the BosConfig file records the
-following information:
+A server process entry in the F<BosConfig> file records the following
+information:
 
 =over 4
 
 =item *
 
-TheI< entry type>, which is one of the following: 
-L<(1)>
-L<(1)>
-
+The I<entry type>, which is one of the following: 
 
 =over 4
 
-=item cronL<(1)
->
+=item cron
 
 Designates a server process that runs periodically instead of
 continuously. The BOS Server starts a cron process only at specified
 times, not whenever it fails. All standard AFS process entries except
-B<fs> are simple (there are no standard cron processes).
+C<fs> are simple (there are no standard cron processes).
 
-=item fsL<(1)
-L<(1)>
-L<(1)>
-L<(1)>
->
+=item fs
 
-Designates a group of interdependent server processes. If one of
-the processes fails, the BOS Server must coordinate its restart with the
+Designates a group of interdependent server processes. If one of the
+processes fails, the BOS Server must coordinate its restart with the
 restart of the other processes in the group, possibly by stopping them
-first. 
+first.
 
 There is only one standard entry of this type, for which the conventional
-name is B<fs>. It combines three server processes: the
-File Server (B<fileserver> process), the Volume Server
-(B<volserver> process), and the Salvager (B<salvager>
-process). These processes all operate on the same data--the AFS
-data stored on an AFS server machine's B</vicep> partitions and
-mounted in the AFS filespace--but in different ways. Grouping the
+name is C<fs>. It combines three server processes: the File Server
+(B<fileserver> process), the Volume Server (B<volserver> process), and the
+Salvager (B<salvager> process). These processes all operate on the same
+data--the AFS data stored on an AFS server machine's F</vicep> partitions
+and mounted in the AFS filespace--but in different ways. Grouping the
 processes prevents them from attempting to access the same data
-simultaneously, which can cause corruption. 
+simultaneously, which can cause corruption.
 
-During normal operation, the Salvager process is not active. If the
-File Server process fails, however, the BOS Server stops the Volume Server
-process and runs the Salvager process to correct any corruption that resulted
-from the failure. (The administrator can also issue the B<bos
-salvage> command to invoke the Salvager process.) If the Volume
-Server fails, the BOS Server can restart it without stopping the File Server
-or running the Salvager.
+During normal operation, the Salvager process is not active. If the File
+Server process fails, however, the BOS Server stops the Volume Server
+process and runs the Salvager process to correct any corruption that
+resulted from the failure. (The administrator can also issue the B<bos
+salvage> command to invoke the Salvager process.) If the Volume Server
+fails, the BOS Server can restart it without stopping the File Server or
+running the Salvager.
 
-=item simpleL<(1)
->
+=item simple
 
 Designates a server process that runs independently of any other on the
-server machine. If a simple process fails, the BOS Server does not have
-to coordinate its restart with any other process.
+server machine. If a simple process fails, the BOS Server does not have to
+coordinate its restart with any other process.
 
 =back
 
 =item *
 
-The I<entry name>. The conventional name for an entry in the
-B<BosConfig> file and the associated process matches the binary
-filename. When issuing any B<bos> command that takes the
-B<-instance> argument, identify each process by the name used in the
-B<BosConfig> file. For a list of the names, see the B<bos
-create> reference page.
-
+The I<entry name>. The conventional name for an entry in the F<BosConfig>
+file and the associated process matches the binary filename. When issuing
+any B<bos> command that takes the B<-instance> argument, identify each
+process by the name used in the F<BosConfig> file. For a list of the
+names, see the B<bos create> reference page.
 
 =item *
 
-The process's I<status flag>, which determines whether the BOS
-Server attempts to start the process in two cases: each time the BOS
-Server itself restarts, and when the process fails. The
-B<BosConfig> file currently uses a binary notation to indicate whether
-the BOS Server attempts to restart the process as necessary or does not
-monitor it at all. For the sake of clarity, the AFS documentation
-refers to the flags as B<Run> and B<NotRun> instead.
-Only a system administrator, not the BOS Server, can change the flag.
-L<(1)>
-L<(1)>
-
+The process's I<status flag>, which determines whether the BOS Server
+attempts to start the process in two cases: each time the BOS Server
+itself restarts, and when the process fails. The F<BosConfig> file
+currently uses a binary notation to indicate whether the BOS Server
+attempts to restart the process as necessary or does not monitor it at
+all. For the sake of clarity, the AFS documentation refers to the flags as
+C<Run> and C<NotRun> instead.  Only a system administrator, not the BOS
+Server, can change the flag.
 
 =item *
 
-One or more I<command parameters> which the BOS Server invokes to
-start the process or processes associated with the entry: 
-
+One or more I<command parameters> which the BOS Server invokes to start
+the process or processes associated with the entry:
 
 =over 4
 
 =item *
 
-A cron entry has two command parameters, the first the complete
+A C<cron> entry has two command parameters, the first the complete
 pathname to the program, and the second the time at which the BOS Server
 invokes the program.
 
-
 =item *
 
-The fs entry has three command parameters, each the complete
-pathname to the B<fileserver>, B<volserver>, and
-B<salvager> programs, in that order.
-
+The C<fs> entry has three command parameters, each the complete pathname
+to the B<fileserver>, B<volserver>, and B<salvager> programs, in that
+order.
 
 =item *
 
-A simple entry has only one command parameter, the complete
-pathname to the program.
-
+A C<simple> entry has only one command parameter, the complete pathname to
+the program.
 
 =back
 
 =back
 
-In addition to server process entries, the BosConfig file
-specifies the times at which the BOS Server performs two types of automatic
-process restarts:
+In addition to server process entries, the F<BosConfig> file specifies the
+times at which the BOS Server performs two types of automatic process
+restarts:
 
 =over 4
 
 =item *
 
-The I<general restart> time at which the BOS Server restarts itself
-and then each process for which the entry in the B<BosConfig> file has
-status flag B<Run>. The default setting is Sunday at 4:00
-a.m.
-
+The I<general restart> time at which the BOS Server restarts itself and
+then each process for which the entry in the F<BosConfig> file has status
+flag C<Run>. The default setting is Sunday at 4:00 a.m.
 
 =item *
 
-The I<binary restart> time at which the BOS Server restarts any
-server process for which the time stamp on the binary file in the
-B</usr/afs/bin> directory is later than the last restart time for the
-process. The default is 5:00 a.m.
-
+The I<binary restart> time at which the BOS Server restarts any server
+process for which the time stamp on the binary file in the F</usr/afs/bin>
+directory is later than the last restart time for the process. The default
+is 5:00 a.m.
 
 =back
 
-Although the BosConfig file is in ASCII format, do not use a
-text editor to alter it. Its format is subject to change and
-incorrectly formatted entries can prevent server startup in ways that are
-difficult to diagnose. Instead always use the appropriate commands from
-the B<bos> command suite:
+Although the F<BosConfig> file is in ASCII format, do not use a text
+editor to alter it. Its format is subject to change and incorrectly
+formatted entries can prevent server startup in ways that are difficult to
+diagnose. Instead always use the appropriate commands from the B<bos>
+command suite:
 
 =over 4
 
 =item *
 
-The bos create command to create an entry in the file and start
-the associated process
-
+The B<bos create> command to create an entry in the file and start the
+associated process.
 
 =item *
 
-The bos delete command to remove an entry from the file after
-the B<bos stop> command is used to stop the associated process
-
+The B<bos delete> command to remove an entry from the file after the B<bos
+stop> command is used to stop the associated process.
 
 =item *
 
-The bos getrestart command to display the times at which the
-BOS Server performs automatic restarts
-
+The B<bos getrestart> command to display the times at which the BOS Server
+performs automatic restarts.
 
 =item *
 
-The bos setrestart command to set the times at which the BOS
-Server performs automatic process restarts
-
+The B<bos setrestart> command to set the times at which the BOS Server
+performs automatic process restarts.
 
 =item *
 
-The bos start command to change an entry's status flag to
-B<Run> and start the associated process
-
+The B<bos start> command to change an entry's status flag to C<Run> and
+start the associated process.
 
 =item *
 
-The bos status command to display all processes listed in the
-file
-
+The B<bos status> command to display all processes listed in the file.
 
 =item *
 
-The bos stop command to change an entry's status flag to
-B<NotRun> and stop the associated process
-
+The B<bos stop> command to change an entry's status flag to C<NotRun> and
+stop the associated process.
 
 =back
 
-There are also bos commands that start and stop processes
-without changing entries in the B<BosConfig> file. The BOS
-Server reads the B<BosConfig> file only when it starts, transferring
-the information into its memory. Thus a process's status as
-represented in the BOS Server's memory can diverge from its status in the
-B<BosConfig> file. The following commands change a
-process's status in the BOS Server's memory only:
-L<(1)>
-L<(1)>
-L<(1)>
+There are also bos commands that start and stop processes without changing
+entries in the F<BosConfig> file. The BOS Server reads the F<BosConfig>
+file only when it starts, transferring the information into its
+memory. Thus a process's status as represented in the BOS Server's memory
+can diverge from its status in the F<BosConfig> file. The following
+commands change a process's status in the BOS Server's memory only:
 
 =over 4
 
 =item *
 
-The bos restart command restarts a specified set of processes,
-all processes, or all processes other than the BOS Server
-
+The B<bos restart> command restarts a specified set of processes, all
+processes, or all processes other than the BOS Server.
 
 =item *
 
-The bos shutdown command stops a process
-
+The B<bos shutdown> command stops a process.
 
 =item *
 
-The bos startup command starts a process
-
+The B<bos startup> command starts a process.
 
 =back
 
 =head1 SEE ALSO
 
-L<bos_create(1)>,
-L<bos_delete(1)>,
-L<bos_getrestart(1)>,
-L<bos_restart(1)>,
-L<bos_setrestart(1)>,
-L<bos_shutdown(1)>,
-L<bos_start(1)>,
-L<bos_startup(1)>,
-L<bos_status(1)>,
-L<bos_stop(1)>,
-L<bos_salvage(1)>,
-L<fileserver(1)>,
-L<salvager(1)>,
-L<volserver(1)>
+L<bos_create(8)>,
+L<bos_delete(8)>,
+L<bos_getrestart(8)>,
+L<bos_restart(8)>,
+L<bos_setrestart(8)>,
+L<bos_shutdown(8)>,
+L<bos_start(8)>,
+L<bos_startup(8)>,
+L<bos_status(8)>,
+L<bos_stop(8)>,
+L<bos_salvage(8)>,
+L<fileserver(8)>,
+L<salvager(8)>,
+L<volserver(8)>
 
 =head1 COPYRIGHT
 
index 9fa23cf..4195961 100644 (file)
@@ -4,35 +4,32 @@ BosLog - Traces BOS Server operations
 
 =head1 DESCRIPTION
 
-The BosLog file records a trace of Basic OverSeer (BOS) Server
-(B<bosserver> process) operations on the local machine and describes
-any error conditions it encounters.
+The F<BosLog> file records a trace of Basic OverSeer (BOS) Server
+(B<bosserver> process) operations on the local machine and describes any
+error conditions it encounters.
 
-If the BosLog file does not already exist in the
-B</usr/afs/logs> directory when the BOS Server starts, the server
-process creates it and writes initial start-up messages to it. If there
-is an existing file, the BOS server renames it to
-B<BosLog.old>, overwriting the existing
-B<BosLog.old> file if it exists.
+If the F<BosLog> file does not already exist in the F</usr/afs/logs>
+directory when the BOS Server starts, the server process creates it and
+writes initial start-up messages to it. If there is an existing file, the
+BOS server renames it to F<BosLog.old>, overwriting the existing
+F<BosLog.old> file if it exists.
 
 The file is in ASCII format. Administrators listed in the
-B</usr/afs/etc/UserList> file can use the B<bos getlog>
-command to display its contents. Alternatively, log onto the server
-machine and use a text editor or a file display command such as the UNIX
-B<cat> command. By default, the mode bits on the
-B<BosLog> file grant the required B<r> (B<read>)
-permission to all users.
+F</usr/afs/etc/UserList> file can use the B<bos getlog> command to display
+its contents. Alternatively, log onto the server machine and use a text
+editor or a file display command such as the UNIX B<cat> command. By
+default, the mode bits on the F<BosLog> file grant the required C<r>
+(read) permission to all users.
 
 The BOS Server records operations only as it completes them, and cannot
-recover from failures by reviewing the file. The log contents are
-useful for administrative evaluation of process failures and other
-problems.
+recover from failures by reviewing the file. The log contents are useful
+for administrative evaluation of process failures and other problems.
 
 =head1 SEE ALSO
 
-L<UserList(1)>,
-L<bos_getlog(1)>,
-L<bosserver(1)>
+L<UserList(5)>,
+L<bos_getlog(8)>,
+L<bosserver(8)>
 
 =head1 COPYRIGHT
 
diff --git a/doc/man-pages/pod5/CacheItems.pod b/doc/man-pages/pod5/CacheItems.pod
deleted file mode 100644 (file)
index fb121d1..0000000
+++ /dev/null
@@ -1,45 +0,0 @@
-=head1 NAME
-
-CacheItems - Records information about each VI<n> file in a disk cache
-
-=head1 DESCRIPTION
-
-The CacheItems file records information about each file in the
-disk cache on a client machine (each B<V>I<n> file). The
-information includes the file ID number and associated volume version number
-of the AFS file currently stored in the B<V>I<n> file, which
-enables the Cache Manager to determine which B<V>I<n> file
-contains the AFS data it needs to present to an application.
-
-As it initializes, the Cache Manager creates the binary-format
-B<CacheItems> file in the same local disk cache directory as the
-B<V>I<n> files that the B<CacheItems> file describes,
-and it must always remain there. The conventional directory name is
-B</usr/vice/cache>, but it is acceptable to use a directory on a
-partition with more available space.
-
-=head1 CAUTIONS
-
-Editing or removing the CacheItems file can cause a kernel
-panic. If the contents of B<V>I<n> files seem out of
-date, clear the files by using the B<fs flush> or B<fs
-flushvolume> command. If the B<CacheItems> file is
-accidentally modified or deleted, rebooting the machine usually restores
-normal performance.
-
-=head1 SEE ALSO
-
-L<VI<n>(1)>,
-L<VolumeItems(1)>,
-L<cacheinfo(1)>,
-L<afsd(1)>,
-L<fs_flush(1)>,
-L<fs_flushvolume(1)>
-
-=head1 COPYRIGHT
-
-IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
-
-This documentation is covered by the IBM Public License Version 1.0.  It was
-converted from HTML to POD by software written by Chas Williams and Russ
-Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
diff --git a/doc/man-pages/pod5/CellServDB.pod b/doc/man-pages/pod5/CellServDB.pod
new file mode 100644 (file)
index 0000000..2cc7c1e
--- /dev/null
@@ -0,0 +1,202 @@
+=head1 NAME
+
+CellServDB - Lists the database server machines in AFS cells
+
+=head1 DESCRIPTION
+
+There are two versions of the F<CellServDB> file, both of which have the
+same format.  One version is used by an AFS client and lists all of the
+database server machines in the local cell and any foreign cell that is to
+be accessible from the local client machine.  The other version is used on
+servers and lists only the database servers in the local cell.
+
+=head2 Client CellServDB
+
+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, 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
+functions, including:
+
+=over 4
+
+=item *
+
+Fetching files. The Cache Manager contacts the VL Server to learn
+the location of the volume containing a requested file or directory.
+
+=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
+
+The Cache Manager reads the CellServDB file into kernel memory as it
+initializes, and not again until the machine next reboots. To enable users
+on the local machine to continue accessing the cell correctly, update the
+file whenever a database server machine is added to or removed from a
+cell. To update the kernel-resident list of database server machines
+without rebooting, use 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.
+
+The client version of the F<CellServDB> file is distinct from the server
+version, which resides in the F</usr/afs/etc> directory on each AFS server
+machine. The client version lists the database server machines in every
+AFS cell that the cell administrator wants the machine's users to be able
+to access, whereas the server version lists only the local cell's database
+server machines.
+
+=head2 Server CellServDB
+
+The server version of the F<CellServDB> file lists the local cell's
+database server machines. These machines run the Authentication Server,
+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
+order to coordinate replication of changes across the multiple copies of
+each database. The other AFS server processes consult the file to learn
+which machines to contact for information from the databases when they
+need it.
+
+Although the server F<CellServDB> file is in ASCII format, do not use a
+text editor to alter it. Instead always use the appropriate commands from
+the B<bos> command suite:
+
+=over 4
+
+=item *
+
+The B<bos addhost> command to add a machine to the file.
+
+=item *
+
+The B<bos listhosts> command to display the list of machines from the
+file.
+
+=item *
+
+The B<bos removehost> command to remove a machine from the file.
+
+=back
+
+In cells that use the Update Server to distribute the contents of the
+F</usr/afs/etc> directory, it is customary to edit only the copy of the
+file stored on the system control machine. Otherwise, edit the file on
+each server machine individually. For instructions on adding and removing
+database server machine, see the I<IBM AFS Quick Beginnings> chapter on
+installing additional server machines.
+
+=head2 CellServDB Format
+
+Both F<CellServDB> files have the same format:
+
+=over 4
+
+=item *
+
+The first line begins at the left margin with the greater-than character
+(C<< > >>), followed immediately by the cell's name without an intervening
+space. Optionally, a comment can follow any number of spaces and a number
+sign (C<#>), perhaps to identify the organization associated with the
+cell.
+
+=item *
+
+Each subsequent line in the entry identifies one of the cell's database
+server machines, with the indicated information in order:
+
+=over 4
+
+=item *
+
+The database server machine's IP address in dotted-decimal format.
+
+=item *
+
+One or more spaces.
+
+=item *
+
+A number sign (#), followed by the machine's fully qualified hostname
+without an intervening space. This number sign does not indicate that the
+hostname is a comment. It is a required field.
+
+=back
+
+=back
+
+No extra blank lines or newline characters are allowed in the file, even
+after the last entry. Their presence can prevent the Cache Manager from
+reading the file into kernel memory, resulting in an error message.
+
+grand.central.org maintains a list of the database server machines in all
+cells that have registered themselves as receptive to access from foreign
+cells. When a cell's administrators change its database server machines,
+it is customary to register the change with grand.central.org for
+inclusion in this file. The file conforms to the required F<CellServDB>
+format, and so is a suitable basis for the F<CellServDB> file on a client
+machine.  You can download this file from L<http://grand.central.org/>.
+
+=head1 EXAMPLES
+
+The following example shows entries for two cells in a client
+F<CellServDB> file and illustrates the required format.
+
+   >abc.com        # ABC Corporation
+   192.12.105.2                #db1.abc.com
+   192.12.105.3                #db2.abc.com
+   192.12.107.3                #db3.abc.com
+   >test.abc.com   # ABC Corporation Test Cell
+   192.12.108.57        #testdb1.abc.com
+   192.12.108.55        #testdb2.abc.com
+
+=head1 SEE ALSO
+
+L<bos_addhost(8)>,
+L<bos_listhosts(8)>,
+L<bos_removehost(8)>,
+L<bos_setcellname(8)>,
+L<buserver(8)>,
+L<fs_newcell(1)>,
+L<kaserver(8)>,
+L<klog(1)>,
+L<ptserver(8)>,
+L<vlserver(8)>,
+L<upclient(8)>,
+L<upserver(8)>
+
+I<IBM AFS Quick Beginnings>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0.  It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
index eec0499..b1f2dbd 100644 (file)
@@ -4,25 +4,25 @@ FORCESALVAGE - Forces salvage of entire partition
 
 =head1 DESCRIPTION
 
-The FORCESALVAGE file, if present on an AFS server partition
-(that is, in a B</vicep> directory), signals that the Salvager must
-salvage the entire partition. The AFS-modified version of the
-B<fsck> program creates the empty (zero-length) file when it discovers
-corruption on the partition. The Salvager removes the file when it
-completes the salvage operation.
+The F<FORCESALVAGE> file, if present on an AFS server partition (that is,
+in a F</vicep> directory), signals that the Salvager must salvage the
+entire partition. The AFS-modified version of the B<fsck> program creates
+the empty (zero-length) file when it discovers corruption on the
+partition. The Salvager removes the file when it completes the salvage
+operation.
 
 When the File Server detects the presence of the file on a partition on
-which it is attaching volumes, it stops, detaches any volumes that are already
-attached, and exits after recording a message in the
-B</usr/afs/logs/FileLog> file. The Bos Server then invokes the
-Salvager to salvage the partition.
+which it is attaching volumes, it stops, detaches any volumes that are
+already attached, and exits after recording a message in the
+F</usr/afs/logs/FileLog> file. The Bos Server then invokes the Salvager to
+salvage the partition.
 
 =head1 SEE ALSO
 
-L<FileLog(1)>,
-L<bosserver(1)>,
-L<fileserver(1)>,
-L<salvager(1)>
+L<FileLog(5)>,
+L<bosserver(8)>,
+L<fileserver(8)>,
+L<salvager(8)>
 
 =head1 COPYRIGHT
 
index c671346..2e381ba 100644 (file)
@@ -4,35 +4,33 @@ FileLog - Traces File Server operations
 
 =head1 DESCRIPTION
 
-The FileLog file records a trace of File Server
-(B<fileserver> process) operations on the local machine and describes
-any error conditions it encounters.
+The F<FileLog> file records a trace of File Server (B<fileserver> process)
+operations on the local machine and describes any error conditions it
+encounters.
 
-If the FileLog file does not already exist in the
-B</usr/afs/logs> directory when the File Server starts, the server
+If the F<FileLog> file does not already exist in the
+F</usr/afs/logs> directory when the File Server starts, the server
 process creates it and writes initial start-up messages to it. If there
 is an existing file, the File Server renames it to
-B<FileLog.old>, overwriting the existing
-B<FileLog.old> file if it exists.
+F<FileLog.old>, overwriting the existing
+F<FileLog.old> file if it exists.
 
 The file is in ASCII format. Administrators listed in the
-B</usr/afs/etc/UserList> file can use the B<bos getlog>
-command to display its contents. Alternatively, log onto the file
-server machine and use a text editor or a file display command such as the
-UNIX B<cat> command. By default, the mode bits on the
-B<FileLog> file grant the required B<r> (B<read>)
-permission to all users.
+F</usr/afs/etc/UserList> file can use the B<bos getlog> command to display
+its contents. Alternatively, log onto the file server machine and use a
+text editor or a file display command such as the UNIX B<cat> command. By
+default, the mode bits on the F<FileLog> file grant the required C<r>
+(read) permission to all users.
 
 The File Server records operations only as it completes them, and cannot
-recover from failures by reviewing the file. The log contents are
-useful for administrative evaluation of process failures and other
-problems.
+recover from failures by reviewing the file. The log contents are useful
+for administrative evaluation of process failures and other problems.
 
 =head1 SEE ALSO
 
-L<UserList(1)>,
-L<bos_getlog(1)>,
-L<fileserver(1)>
+L<UserList(5)>,
+L<bos_getlog(8)>,
+L<fileserver(8)>
 
 =head1 COPYRIGHT
 
index 1867227..df35f80 100644 (file)
@@ -4,59 +4,54 @@ KeyFile - Defines AFS server encryption keys
 
 =head1 DESCRIPTION
 
-The KeyFile file defines the server encryption keys that the AFS
-server processes running on the machine use to decrypt the tickets presented
-by clients during the mutual authentication process. AFS server
-processes perform privileged actions only for clients that possess a ticket
-encrypted with one of the keys from the file. The file must reside in
-the B</usr/afs/etc> directory on every server machine. For more
-detailed information on mutual authentication and server encryption keys, see
-the I<IBM AFS Administration Guide>.
+The F<KeyFile> file defines the server encryption keys that the AFS server
+processes running on the machine use to decrypt the tickets presented by
+clients during the mutual authentication process. AFS server processes
+perform privileged actions only for clients that possess a ticket
+encrypted with one of the keys from the file. The file must reside in the
+F</usr/afs/etc> directory on every server machine. For more detailed
+information on mutual authentication and server encryption keys, see the
+I<IBM AFS Administration Guide>.
 
 Each key has a corresponding a key version number that distinguishes it
-from the other keys. The tickets that clients present are also marked
-with a key version number to tell the server process which key to use to
-decrypt it. The B<KeyFile> file must always include a key with
-the same key version number and contents as the key currently listed for the
-B<afs> entry in the Authentication Database.
+from the other keys. The tickets that clients present are also marked with
+a key version number to tell the server process which key to use to
+decrypt it. The F<KeyFile> file must always include a key with the same
+key version number and contents as the key currently listed for the C<afs>
+entry in the Authentication Database.
 
-The KeyFile file is in binary format, so always use the
-appropriate commands from the B<bos> command suite to administer
-it:
+The F<KeyFile> file is in binary format, so always use the appropriate
+commands from the B<bos> command suite to administer it:
 
 =over 4
 
 =item *
 
-The bos addkey command to define a new key
-
+The B<bos addkey> command to define a new key.
 
 =item *
 
-The bos listkeys command to display the keys
-
+The B<bos listkeys> command to display the keys.
 
 =item *
 
-The bos removekey command to remove a key from the file
-
+The B<bos removekey> command to remove a key from the file.
 
 =back
 
-In cells that run the United States edition of AFS and use the Update
-Server to distribute the contents of the B</usr/afs/etc> directory, it
-is customary to edit only the copy of the file stored on the system control
-machine. In cells that run the international version of AFS, edit the
-file on each server machine individually.
+In cells that use the Update Server to distribute the contents of the
+F</usr/afs/etc> directory, it is customary to edit only the copy of the
+file stored on the system control machine. Otherwise, edit the file on
+each server machine individually.
 
 =head1 SEE ALSO
 
-L<bos_addkey(1)>,
-L<bos_listkeys(1)>,
-L<bos_removekey(1)>,
-L<kas_setpassword(1)>,
-L<upclient(1)>,
-L<upserver(1)>
+L<bos_addkey(8)>,
+L<bos_listkeys(8)>,
+L<bos_removekey(8)>,
+L<kas_setpassword(8)>,
+L<upclient(8)>,
+L<upserver(8)>
 
 I<IBM AFS Administration Guide>
 
diff --git a/doc/man-pages/pod5/NetInfo.pod b/doc/man-pages/pod5/NetInfo.pod
new file mode 100644 (file)
index 0000000..1e940eb
--- /dev/null
@@ -0,0 +1,101 @@
+=head1 NAME
+
+NetInfo - Defines machine interfaces to register with AFS servers
+
+=head1 DESCRIPTION
+
+There are two F<NetInfo> files, one for an AFS client and one for an AFS
+File Server or database server.  The AFS client F<NetInfo> file specifies
+the IP addresses that the client should register with the File Servers it
+connects to.  The server F<NetInfo> file specifies what interfaces should
+be registered with AFS Database Servers or used to talk to other database
+servers.
+
+=head2 Client NetInfo
+
+The client F<NetInfo> file lists the IP addresses of one or more of the
+local machine's network interfaces. If it exists in the F</usr/vice/etc>
+directory when the Cache Manager initializes, the Cache Manager uses its
+contents as the basis for a list of local interfaces. Otherwise, the Cache
+Manager uses the list of interfaces configured with the operating
+system. It then removes from the list any addresses that appear in the
+F</usr/vice/etc/NetRestrict> file, if it exists. The Cache Manager records
+the resulting list in kernel memory. The first time it establishes a
+connection to a File Server, it registers the list with the File Server.
+
+The File Server uses the addresses when it initiates a remote procedure
+call (RPC) to the Cache Manager (as opposed to responding to an RPC sent
+by the Cache Manager). There are two common circumstances in which the
+File Server initiates RPCs: when it breaks callbacks and when it pings the
+client machine to verify that the Cache Manager is still accessible.
+
+The F<NetInfo> file is in ASCII format. One of the machine's IP addresses
+appears on each line, in dotted decimal format. The File Server initially
+uses the address that appears first in the list. The order of the
+remaining addresses is not significant: if an RPC to the first interface
+fails, the File Server simultaneously sends RPCs to all of the other
+interfaces in the list.  Whichever interface replies first is the one to
+which the File Server then sends pings and RPCs to break callbacks.
+
+To prohibit the Cache Manager absolutely from using one or more addresses,
+list them in the F<NetRestrict> file. To display the addresses the Cache
+Manager is currently registering with File Servers, use the B<fs
+getclientaddrs> command. To replace the current list of interfaces with a
+new one between reboots of the client machine, use the B<fs
+setclientaddrs> command.
+
+=head2 Server NetInfo
+
+The server F<NetInfo> file, if present in the F</usr/afs/local> directory,
+defines the following:
+
+=over 4
+
+=item *
+
+On a file server machine, the local interfaces that the File Server
+(B<fileserver> process) can register in the Volume Location Database
+(VLDB) at initialization time.
+
+=item *
+
+On a database server machine, the local interfaces that the Ubik database
+synchronization library uses when communicating with the database server
+processes running on other database server machines.
+
+=back
+
+If the F<NetInfo> file exists when the File Server initializes, the File
+Server uses its contents as the basis for a list of interfaces to register
+in the VLDB. Otherwise, it uses the list of network interfaces configured
+with the operating system. It then removes from the list any addresses
+that appear in the F</usr/vice/etc/NetRestrict> file, if it exists. The
+File Server records the resulting list in the F</usr/afs/local/sysid> file
+and registers the interfaces in the VLDB. The database server processes
+use a similar procedure when initializing, to determine which interfaces
+to use for communication with the peer processes on other database
+machines in the cell.
+
+The F<NetInfo> file is in ASCII format. One of the machine's IP addresses
+appears on each line, in dotted decimal format. The order of the addresses
+is not significant.
+
+To display the File Server interface addresses registered in the VLDB, use
+the B<vos listaddrs> command.
+
+=head1 SEE ALSO
+
+L<sysid(5)>,
+L<vldb.DB0(5)>,
+L<fileserver(8)>,
+L<fs_getclientaddrs(1)>,
+L<fs_setclientaddrs(1)>,
+L<vos_listaddrs(1)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0.  It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
diff --git a/doc/man-pages/pod5/NetRestrict.pod b/doc/man-pages/pod5/NetRestrict.pod
new file mode 100644 (file)
index 0000000..8d343ec
--- /dev/null
@@ -0,0 +1,94 @@
+=head1 NAME
+
+NetRestrict - Defines interfaces not to register with AFS servers
+
+=head1 DESCRIPTION
+
+There are two F<NetRestrict> files, one for an AFS client and one for an
+AFS File Server or database server.  The AFS client F<NetRestrict> file
+specifies the IP addresses that the client should not register with the
+File Servers it connects to.  The server F<NetInfo> file specifies what
+interfaces should not be registered with AFS Database Servers or used to
+talk to other database servers.
+
+=head2 Client NetRestrict
+
+The F<NetRestrict> file, if present in a client machine's F</usr/vice/etc>
+directory, defines the IP addresses of the interfaces that the local Cache
+Manager does not register with a File Server when first establishing a
+connection to it. For an explanation of how the File Server uses the
+registered interfaces, see L<NetInfo(5)>.
+
+As it initializes, the Cache Manager constructs a list of interfaces to
+register, from the F</usr/vice/etc/NetInfo> file if it exists, or from the
+list of interfaces configured with the operating system otherwise.  The
+Cache Manager then removes from the list any addresses that appear in the
+F<NetRestrict> file, if it exists. The Cache Manager records the resulting
+list in kernel memory.
+
+The F<NetRestrict> file is in ASCII format. One IP address appears on each
+line, in dotted decimal format. The order of the addresses is not
+significant. The value C<255> is a wildcard that represents all possible
+addresses in that field. For example, the value C<192.12.105.255>
+indicates that the Cache Manager does not register any of the addresses in
+the C<192.12.105> subnet.
+
+To display the addresses the Cache Manager is currently registering with
+File Servers, use the B<fs getclientaddrs> command.
+
+=head2 Server NetRestrict
+
+The F<NetRestrict> file, if present in the F</usr/afs/local> directory,
+defines the following:
+
+=over 4
+
+=item *
+
+On a file server machine, the local interfaces that the File Server
+(B<fileserver> process) does not register in the Volume Location Database
+(VLDB) at initialization time.
+
+=item *
+
+On a database server machine, the local interfaces that the Ubik
+synchronization library does not use when communicating with the database
+server processes running on other database server machines.
+
+=back
+
+As it initializes, the File Server constructs a list of interfaces to
+register, from the F</usr/afs/local/NetInfo> file if it exists, or from
+the list of interfaces configured with the operating system otherwise. The
+File Server then removes from the list any addresses that appear in the
+F<NetRestrict> file, if it exists. The File Server records the resulting
+list in the F</usr/afs/local/sysid> file and registers the interfaces in
+the VLDB. The database server processes use a similar procedure when
+initializing, to determine which interfaces to use for communication with
+the peer processes on other database machines in the cell.
+
+The F<NetRestrict> file is in ASCII format. One IP address appears on each
+line, in dotted decimal format. The order of the addresses is not
+significant. The value C<255> is a wildcard that represents all possible
+addresses in that field. For example, the value C<192.12.105.255>
+indicates that the File Server or database server processes do not
+register or use any of the addresses in the C<192.12.105> subnet.
+
+To display the File Server interface addresses registered in the VLDB, use
+the B<vos listaddrs> command.
+
+=head1 SEE ALSO
+
+L<sysid(5)>,
+L<vldb.DB0(5)>,
+L<fileserver(8)>,
+L<fs_getclientaddrs(1)>
+L<vos_listaddrs(1)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0.  It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
index d5b68c8..94c3346 100644 (file)
@@ -4,35 +4,32 @@ NoAuth - Disables authorization checking
 
 =head1 DESCRIPTION
 
-The NoAuth file, if present in a server machine's
-B</usr/afs/local> directory, indicates to the AFS server processes
-running on the machine that it is not necessary to perform authorization
-checking. They perform any action for any user who logs into the
-machine's local file system or issues a remote command that affects the
-machine's AFS server functioning, such as commands from the AFS command
-suites. Because failure to check authorization exposes the
-machine's AFS server functionality to attack, there are normally only two
-circumstances in which the file is present:
+The F<NoAuth> file, if present in a server machine's F</usr/afs/local>
+directory, indicates to the AFS server processes running on the machine
+that it is not necessary to perform authorization checking. They perform
+any action for any user who logs into the machine's local file system or
+issues a remote command that affects the machine's AFS server functioning,
+such as commands from the AFS command suites. Because failure to check
+authorization exposes the machine's AFS server functionality to attack,
+there are normally only two circumstances in which the file is present:
 
 =over 4
 
 =item *
 
-During installation of the machine, as instructed in the I<IBM AFS
-Quick Beginnings>
-
+During installation of the machine, as instructed in the I<IBM AFS Quick
+Beginnings>.
 
 =item *
 
 During correction of a server encryption key emergency, as discussed in
-the I<IBM AFS Administration Guide>
-
+the I<IBM AFS Administration Guide>.
 
 =back
 
 In all other circumstances, the absence of the file means that the AFS
-server processes perform authorization checking, verifying that the issuer of
-a command has the required privilege.
+server processes perform authorization checking, verifying that the issuer
+of a command has the required privilege.
 
 Create the file in one of the following ways:
 
@@ -40,30 +37,26 @@ Create the file in one of the following ways:
 
 =item *
 
-By issuing the bosserver initialization command with the
-B<-noauth> flag, if the Basic OverSeer (BOS) Server is not already
-running
-
+By issuing the bosserver initialization command with the B<-noauth> flag,
+if the Basic OverSeer (BOS) Server is not already running.
 
 =item *
 
-By issuing the B<bos setauth> command with off as the
-value for the B<-authrequired> argument, if the BOS Server is already
-running
-
+By issuing the B<bos setauth> command with off as the value for the
+B<-authrequired> argument, if the BOS Server is already running.
 
 =back
 
-To remove the file, issue the bos setauth command with
-B<on> as the value for the B<-authrequired> argument.
+To remove the file, issue the B<bos setauth> command with C<on> as the
+value for the B<-authrequired> argument.
 
-The file's contents, if any, are ignored; an empty (zero-length)
-file is effective.
+The file's contents, if any, are ignored; an empty (zero-length) file is
+effective.
 
 =head1 SEE ALSO
 
-L<bos_setauth(1)>,
-L<bosserver(1)>
+L<bos_setauth(8)>,
+L<bosserver(8)>
 
 =head1 COPYRIGHT
 
index 6c14901..5fb42c4 100644 (file)
@@ -4,33 +4,32 @@ SALVAGE.fs - Triggers salvaging of AFS server partitions
 
 =head1 DESCRIPTION
 
-The SALVAGE.fs file, if present in a file server
-machine's B</usr/afs/local> directory, indicates to the Basic
-OverSeer (BOS) Server (B<bosserver> process) that it must invoke the
-Salvager (B<salvager> process) during recovery from a failure of the
-File Server (B<fileserver> process).
-
-The BOS Server creates the zero-length file each time it starts or restarts
-the B<fs> process. When the File Server exits normally (for
-example, in response to the B<bos shutdown> or B<bos stop>
-command), the BOS Server removes the file. However, if the File Server
-exits unexpectedly, the file remains in the B</usr/afs/local>
-directory as a signal that the BOS Server must invoke the Salvager process to
-repair any file system inconsistencies possibly introduced during the failure,
-before restarting the File Server and Volume Server processes.
+The F<SALVAGE.fs> file, if present in a file server machine's
+F</usr/afs/local> directory, indicates to the Basic OverSeer (BOS) Server
+(B<bosserver> process) that it must invoke the Salvager (B<salvager>
+process) during recovery from a failure of the File Server (B<fileserver>
+process).
+
+The BOS Server creates the zero-length file each time it starts or
+restarts the C<fs> process. When the File Server exits normally (for
+example, in response to the B<bos shutdown> or B<bos stop> command), the
+BOS Server removes the file. However, if the File Server exits
+unexpectedly, the file remains in the F</usr/afs/local> directory as a
+signal that the BOS Server must invoke the Salvager process to repair any
+file system inconsistencies possibly introduced during the failure, before
+restarting the File Server and Volume Server processes.
 
 Do not create or remove this file. To invoke the Salvager process
 directly, use the B<bos salvage> command or log onto the file server
-machine as the local superuser B<root> and issue the
-B<salvager> command.
+machine as the local superuser C<root> and issue the B<salvager> command.
 
 =head1 SEE ALSO
 
-L<bos_salvage(1)>,
-L<bosserver(1)>,
-L<fileserver(1)>,
-L<salvager(1)>,
-L<volserver(1)>
+L<bos_salvage(8)>,
+L<bosserver(8)>,
+L<fileserver(8)>,
+L<salvager(8)>,
+L<volserver(8)>
 
 =head1 COPYRIGHT
 
index f472cda..679b3bc 100644 (file)
@@ -4,35 +4,32 @@ SalvageLog - Traces Salvager operations
 
 =head1 DESCRIPTION
 
-The SalvageLog file records a trace of Salvager
-(B<salvager> process) operations on the local machine and describes
-any error conditions it encounters.
+The F<SalvageLog> file records a trace of Salvager (B<salvager> process)
+operations on the local machine and describes any error conditions it
+encounters.
 
-If the SalvageLog file does not already exist in the
-B</usr/afs/logs> directory when the Salvager starts, the process
-creates it and writes initial start-up messages to it. If there is an
-existing file, the Salvager renames is to B<SalvageLog.old>,
-overwriting the existing B<SalvageLog.old> file if it
-exists.
+If the F<SalvageLog> file does not already exist in the F</usr/afs/logs>
+directory when the Salvager starts, the process creates it and writes
+initial start-up messages to it. If there is an existing file, the
+Salvager renames is to F<SalvageLog.old>, overwriting the existing
+F<SalvageLog.old> file if it exists.
 
 The file is in ASCII format. Administrators listed in the
-B</usr/afs/etc/UserList> file can use the B<bos getlog>
-command to display its contents. Alternatively, log onto the file
-server machine and use a text editor or a file display command such as the
-UNIX B<cat> command. By default, the mode bits on the
-B<SalvageLog> file grant the required B<r> (B<read>)
-permission to all users.
+F</usr/afs/etc/UserList> file can use the B<bos getlog> command to display
+its contents. Alternatively, log onto the file server machine and use a
+text editor or a file display command such as the UNIX B<cat> command. By
+default, the mode bits on the F<SalvageLog> file grant the required C<r>
+(read) permission to all users.
 
 The Salvager records operations only as it completes them, and cannot
-recover from failures by reviewing the file. The log contents are
-useful for administrative evaluation of process failures and other
-problems.
+recover from failures by reviewing the file. The log contents are useful
+for administrative evaluation of process failures and other problems.
 
 =head1 SEE ALSO
 
-L<UserList(1)>,
-L<bos_getlog(1)>,
-L<salvager(1)>
+L<UserList(5)>,
+L<bos_getlog(8)>,
+L<salvager(8)>
 
 =head1 COPYRIGHT
 
diff --git a/doc/man-pages/pod5/ThisCell.pod b/doc/man-pages/pod5/ThisCell.pod
new file mode 100644 (file)
index 0000000..1dc128c
--- /dev/null
@@ -0,0 +1,105 @@
+=head1 NAME
+
+ThisCell - Defines the local cell name
+
+=head1 DESCRIPTION
+
+The F<ThisCell> file defines the local cell name.  There are two versions
+of this file, one for a AFS client and one for an AFS server.
+
+=head2 Client ThisCell
+
+The client version of the F<ThisCell> file defines the complete Internet
+domain-style name (for example, C<abc.com>) of the cell to which the local
+client machine belongs. It must reside in the F</usr/vice/etc> directory
+on every AFS client machine. To change a client machine's cell membership,
+edit the file and reboot the machine.
+
+The file is in ASCII format and contains a character string on a single
+line. The I<IBM AFS Quick Beginnings> instructs the administrator to
+create it during the installation of each client machine.
+
+The client machine's cell membership determines three defaults important
+to its functioning:
+
+=over 4
+
+=item *
+
+The cell in which the machine's users authenticate by default.  The effect
+is two-fold:
+
+=over 4
+
+=item *
+
+The AFS-modified login utilities and the klog command interpreter contact
+an Authentication Server in the cell named in the F<ThisCell> file (unless
+B<-cell> argument to the B<klog> command specifies an alternate cell).
+
+=item *
+
+The command interpreters combine the cell name with the password that the
+user provides, generating an encryption key from the combination. For
+authentication to succeed, both the cell name and password must match the
+ones used to generate the user's encryption key stored in the
+Authentication Database.
+
+=back
+
+=item *
+
+The cell the Cache Manager considers its local, or home, cell. By default,
+the Cache Manager allows programs that reside in its home cell to run with
+setuid permission, but not programs from foreign cells. For more details,
+see the B<fs getcellstatus> and B<fs setcell> reference pages.
+
+=item *
+
+Which AFS server processes the local AFS command interpreters contact by
+default as they execute commands issued on the machine.
+
+=back
+
+The client version of the F<ThisCell> file is distinct from the server
+version, which resides in the F</usr/afs/etc> directory on each AFS server
+machine. If a server machine also runs as a client, it is acceptable for
+the server and client versions of the file on the same machine to name
+different cells. However, the behavior that results from this
+configuration can be more confusing than useful.
+
+=head2 Server ThisCell
+
+The server version of the F<ThisCell> file defines the complete Internet
+domain-style name (for example, C<abc.com>) of the cell to which the
+server machine belongs. It must reside in the F</usr/afs/etc> directory on
+every AFS server machine.
+
+The file is in ASCII format and contains a character string on a single
+line. The initial version of the file is created with the B<bos
+setcellname> command during the installation of the cell's first file
+server machine, and the I<IBM AFS Quick Beginnings> includes instructions
+for copying it over to additional server machine during their
+installation.
+
+The only reason to edit the file is as part of changing the cell's name,
+which is strongly discouraged because of the large number of configuration
+changes involved. In particular, changing the cell name requires
+rebuilding the entire Authentication Database, because the Authentication
+Server combines the cell name it finds in this file with each user and
+server password and converts the combination into an encryption key before
+recording it in the Database.
+
+=head1 SEE ALSO
+
+L<bos_setcellname(8)>,
+L<fs_getcellstatus(1)>,
+L<fs_setcell(1)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0.  It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
index f5ac45f..268c8c7 100644 (file)
@@ -4,51 +4,46 @@ UserList - Defines privileged administrators
 
 =head1 DESCRIPTION
 
-The UserList file lists the AFS usernames of the system
-administrators authorized to issue privileged B<bos>, B<vos>,
-and B<backup> commands that affect the local server machine or the
-volumes housed on it. It must reside in the B</usr/afs/etc>
-directory on every server machine.
+The F<UserList> file lists the AFS usernames of the system administrators
+authorized to issue privileged B<bos>, B<vos>, and B<backup> commands that
+affect the local server machine or the volumes housed on it. It must
+reside in the F</usr/afs/etc> directory on every server machine.
 
-Although the UserList file is in ASCII format, do not use a text
-editor to alter it. Instead always use the appropriate commands from
-the B<bos> command suite: 
+Although the F<UserList> file is in ASCII format, do not use a text editor
+to alter it. Instead always use the appropriate commands from the B<bos>
+command suite:
 
 =over 4
 
 =item *
 
-The bos adduser command to add a user to the file
-
+The B<bos adduser> command to add a user to the file.
 
 =item *
 
-The bos listusers command to display the contents of the file
-
+The B<bos listusers> command to display the contents of the file.
 
 =item *
 
-The bos removeuser command to remove a user from the file
-
+The B<bos removeuser> command to remove a user from the file.
 
 =back
 
 Although it is theoretically possible to list different administrators in
-the B<UserList> files on different server machines, doing so can cause
-unanticipated authorization failures and is not recommended. In cells
-that run the United States edition of AFS and use the Update Server to
-distribute the contents of the B</usr/afs/etc> directory, it is
-customary to edit only the copy of the file stored on the system control
-machine. In cells that run the international version of AFS, edit the
-file on each server machine individually.
+the F<UserList> files on different server machines, doing so can cause
+unanticipated authorization failures and is not recommended. In cells that
+use the Update Server to distribute the contents of the F</usr/afs/etc>
+directory, it is customary to edit only the copy of the file stored on the
+system control machine. Otherwise, edit the file on each server machine
+individually.
 
 =head1 SEE ALSO
 
-L<bos_adduser(1)>,
-L<bos_listusers(1)>,
-L<bos_removeuser(1)>,
-L<upclient(1)>,
-L<upserver(1)>
+L<bos_adduser(8)>,
+L<bos_listusers(8)>,
+L<bos_removeuser(8)>,
+L<upclient(8)>,
+L<upserver(8)>
 
 =head1 COPYRIGHT
 
index 42ba308..0db9a67 100644 (file)
@@ -4,56 +4,51 @@ VLLog - Traces Volume Location Server operations
 
 =head1 DESCRIPTION
 
-The VLLog file records a trace of Volume Location (VL) Server
-(B<vlserver> process) operations on the local machine and describes
-any error conditions it encounters.
+The F<VLLog> file records a trace of Volume Location (VL) Server
+(B<vlserver> process) operations on the local machine and describes any
+error conditions it encounters.
 
-If the VLLog file does not already exist in the
-B</usr/afs/logs> directory when the VL Server starts, the server
+If the F<VLLog> file does not already exist in the
+F</usr/afs/logs> directory when the VL Server starts, the server
 process creates it and writes initial start-up messages to it. If there
-is an existing file, the VL Server renames it to B<VLLog.old>,
-overwriting the existing B<VLLog.old> file if it exists.
+is an existing file, the VL Server renames it to F<VLLog.old>,
+overwriting the existing F<VLLog.old> file if it exists.
 
 The file is in ASCII format. Administrators listed in the
-B</usr/afs/etc/UserList> file can use the B<bos getlog>
-command to display its contents. Alternatively, log onto the server
-machine and use a text editor or a file display command such as the UNIX
-B<cat> command. By default, the mode bits on the
-B<VLLog> file grant the required B<r> (B<read>)
+F</usr/afs/etc/UserList> file can use the B<bos getlog> command to display
+its contents. Alternatively, log onto the server machine and use a text
+editor or a file display command such as the UNIX B<cat> command. By
+default, the mode bits on the F<VLLog> file grant the required C<r> (read)
 permission to all users.
 
 The VL Server records operations only as it completes them, and cannot
-recover from failures by reviewing the file. The log contents are
-useful for administrative evaluation of process failures and other
-problems.
+recover from failures by reviewing the file. The log contents are useful
+for administrative evaluation of process failures and other problems.
 
-The VL Server can record messages at three levels of detail. By
-default, it records only very rudimentary messages. To increase logging
-to the first level of detail, issue the following command while logged onto
-the database server machine as the local superuser B<root>.
+The VL Server can record messages at three levels of detail. By default,
+it records only very rudimentary messages. To increase logging to the
+first level of detail, issue the following command while logged onto the
+database server machine as the local superuser C<root>.
 
-   # kill -TSTP I<vlserver_pid>
+   # kill -TSTP <vlserver_pid>
 
-where I<vlserver_pid> is the process ID of the vlserver
-process, as reported in the output from the standard UNIX B<ps>
-command. To increase to the second and third levels of detail, repeat
-the command.
+where <vlserver_pid> is the process ID of the vlserver process, as
+reported in the output from the standard UNIX B<ps> command. To increase
+to the second and third levels of detail, repeat the command.
 
 To disable logging, issue the following command.
 
-
-   # kill -HUP I<vlserver_pid>
-   
+   # kill -HUP <vlserver_pid>
 
 To decrease the level of logging, first completely disable it and then
-issue the B<kill -TSTP> command as many times as necessary to reach
-the desired level.
+issue the C<kill -TSTP> command as many times as necessary to reach the
+desired level.
 
 =head1 SEE ALSO
 
-L<UserList(1)>,
-L<bos_getlog(1)>,
-L<vlserver(1)>
+L<UserList(5)>,
+L<bos_getlog(8)>,
+L<vlserver(8)>
 
 =head1 COPYRIGHT
 
index 36b0b52..882e26b 100644 (file)
@@ -4,35 +4,33 @@ VolserLog - Traces Volume Server operations
 
 =head1 DESCRIPTION
 
-The VolserLog file records a trace of Volume Server
-(B<volserver> process) operations on the local machine and describes
-any error conditions it encounters.
+The F<VolserLog> file records a trace of Volume Server (B<volserver>
+process) operations on the local machine and describes any error
+conditions it encounters.
 
-If the VolserLog file does not already exist in the
-B</usr/afs/logs> directory when the Volume Server starts, the server
-process creates it and writes initial start-up messages to it. If there
-is an existing file, the Volume Server renames it to
-B<VolserLog.old>, overwriting the existing
-B<VolserLog.old> file if it exists.
+If the VolserLog file does not already exist in the F</usr/afs/logs>
+directory when the Volume Server starts, the server process creates it and
+writes initial start-up messages to it. If there is an existing file, the
+Volume Server renames it to F<VolserLog.old>, overwriting the existing
+F<VolserLog.old> file if it exists.
 
 The file is in ASCII format. Administrators listed in the
-B</usr/afs/etc/UserList> file can use the B<bos getlog>
-command to display its contents. Alternatively, log onto the file
-server machine and use a text editor or a file display command such as the
-UNIX B<cat> command. By default, the mode bits on the
-B<VolserLog> file grant the required B<r> (B<read>)
-permission to all users.
+F</usr/afs/etc/UserList> file can use the B<bos getlog> command to display
+its contents. Alternatively, log onto the file server machine and use a
+text editor or a file display command such as the UNIX B<cat> command. By
+default, the mode bits on the F<VolserLog> file grant the required C<r>
+(read) permission to all users.
 
 The Volume Server records operations only as it completes them, and so
-cannot recover from failures by reviewing the file. The log contents
-are useful for administrative evaluation of process failures and other
+cannot recover from failures by reviewing the file. The log contents are
+useful for administrative evaluation of process failures and other
 problems.
 
 =head1 SEE ALSO
 
-L<UserList(1)>,
-L<bos_getlog(1)>,
-L<volserver(1)>
+L<UserList(5)>,
+L<bos_getlog(8)>,
+L<volserver(8)>
 
 =head1 COPYRIGHT
 
diff --git a/doc/man-pages/pod5/VolumeItems.pod b/doc/man-pages/pod5/VolumeItems.pod
deleted file mode 100644 (file)
index 2d8e8f7..0000000
+++ /dev/null
@@ -1,41 +0,0 @@
-=head1 NAME
-
-VolumeItems - Records location mappings for volumes accessed by a Cache Manager using a
-disk cache
-
-=head1 DESCRIPTION
-
-The VolumeItems file records the mapping between volume name and
-mount point for each volume that the Cache Manager has accessed since it
-initialized on a client machine using a disk cache. The Cache Manager
-uses the mappings to respond correctly to queries about the current working
-directory, which can come from the operating system or commands such as the
-UNIX B<pwd> command.
-
-As it initializes, the Cache Manager creates the binary-format
-B<VolumeItems> file in the local disk cache directory, and it must
-always remain there. The conventional directory name is
-B</usr/vice/cache>.
-
-=head1 CAUTIONS
-
-Editing or removing the VolumeItems file can cause a kernel
-panic. To refresh the contents of the file, instead use the B<fs
-checkvolumes> command. If the B<VolumeItems> file is
-accidentally modified or deleted, rebooting the machine usually restores
-normal performance.
-
-=head1 SEE ALSO
-
-L<CacheItems(1)>,
-L<cacheinfo(1)>,
-L<afsd(1)>,
-L<fs_checkvolumes(1)>
-
-=head1 COPYRIGHT
-
-IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
-
-This documentation is covered by the IBM Public License Version 1.0.  It was
-converted from HTML to POD by software written by Chas Williams and Russ
-Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
diff --git a/doc/man-pages/pod5/afs.pod b/doc/man-pages/pod5/afs.pod
new file mode 100644 (file)
index 0000000..6d8ffb3
--- /dev/null
@@ -0,0 +1,174 @@
+=head1 NAME
+
+afs - Introduction to AFS files
+
+=head1 DESCRIPTION
+
+A number of files must reside on the local disk of AFS server and client
+machines. They belong to the following general categories:
+
+=over 4
+
+=item *
+
+I<Configuration files> define configuration parameters for specific server
+and kernel processes such as the Backup System Tape Coordinator or the
+Cache Manager.
+
+=item *
+
+I<Administrative files> list information used in administration of server
+machines, such as a list of privileged users or server encryption keys.
+
+=item *
+
+I<Cache-related files> contain cached data or information about cached
+data, on client machines.
+
+=item *
+
+I<Log files> contain tracing messages about the operation of a specific
+process.
+
+=item *
+
+I<Database files> contain database records used to administer the AFS
+cell.
+
+=item *
+
+I<Controller files> control the behavior of a process.
+
+=item *
+
+I<Volume header files> represent AFS volumes on server partitions.
+
+=back
+
+For a description of the format and contents of each file, see its
+reference page.
+
+Note for Windows users: Some files described in this document possibly do
+not exist on machines that run a Windows operating system. Also, Windows
+uses a backslash (C<\>) rather than a forward slash (C</>) to separate the
+elements in a pathname.
+
+=head1 SEE ALSO
+
+Configuration files:
+
+=over 4
+
+=item L<BosConfig(5)>
+
+=item L<CellServDB(5)>
+
+=item L<NetInfo(5)>
+
+=item L<NetRestrict(5)>
+
+=item L<ThisCell(5)>
+
+=item L<butc(5)>
+
+=item L<cacheinfo(5)>
+
+=item L<package(5)>
+
+=item L<sysid(5)>
+
+=item L<tapeconfig(5)>
+
+=item L<uss(5)>
+
+=item L<uss_bulk(5)>
+
+=back
+
+Administrative files:
+
+=over 4
+
+=item L<KeyFile(5)>
+
+=item L<UserList(5)>
+
+=back
+
+Cache-related files:
+
+=over 4
+
+=item L<afs_cache(5)>
+
+=back
+
+Log files:
+
+=over 4
+
+=item L<AuthLog(5)>
+
+=item L<BackupLog(5)>
+
+=item L<BosLog(5)>
+
+=item L<FileLog(5)>
+
+=item L<SalvageLog(5)>
+
+=item L<VLLog(5)>
+
+=item L<VolserLog(5)>
+
+=item L<butc(5)>
+
+=item L<fms.log(5)>
+
+=back
+
+Database files:
+
+=over 4
+
+=item L<bdb.DB0(5)>
+
+=item L<kaserver.DB0(5)>
+
+=item L<kaserverauxdb(5)>
+
+=item L<prdb.DB0(5)>
+
+=item L<vldb.DB0(5)>
+
+=back
+
+Controller files:
+
+=over 4
+
+=item L<FORCESALVAGE(5)>
+
+=item L<NoAuth(5)>
+
+=item L<SALVAGE.fs(5)>
+
+=item L<salvage.lock(5)>
+
+=back
+
+Volume header files:
+
+=over 4
+
+=item L<afs_volume_header(5)>
+
+=back
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0.  It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
diff --git a/doc/man-pages/pod5/afs_cache.pod b/doc/man-pages/pod5/afs_cache.pod
new file mode 100644 (file)
index 0000000..f513970
--- /dev/null
@@ -0,0 +1,128 @@
+=head1 NAME
+
+afs_cache - Format of data stored in an AFS client disk cache
+
+=head1 DESCRIPTION
+
+The disk cache on a client machine is composed of multiple F<VI<n>> files
+that contain the data, a F<CacheItems> file that records index information
+for all of the F<VI<n>> files, and a F<VolumeItems> file that records the
+mapping between volume name and mount point for volumes.
+
+When it initializes, the Cache Manager creates the cache files in the
+configured cache location.  The standard directory name is
+F</usr/vice/cache>, but it is acceptable to use a directory on a partition
+with more available space. To designate a different directory, change the
+value in the second field of the F</usr/vice/etc/cacheinfo> file before
+issuing the B<afsd> command, or include the B<-cachedir> argument to the
+B<afsd> command.
+
+=head2 F<CacheItems>
+
+The CacheItems file records information about each file in the disk cache
+on a client machine (each F<VI<n>> file). The information includes the
+file ID number and associated volume version number of the AFS file
+currently stored in the B<V>I<n> file, which enables the Cache Manager to
+determine which F<VI<n>> file contains the AFS data it needs to present to
+an application.
+
+As it initializes, the Cache Manager creates the binary-format
+F<CacheItems> file in the same local disk cache directory as the F<VI<n>>
+files that the F<CacheItems> file describes, and it must always remain
+there.
+
+=head2 F<VolumeItems>
+
+The F<VolumeItems> file records the mapping between volume name and mount
+point for each volume that the Cache Manager has accessed since it
+initialized on a client machine using a disk cache. The Cache Manager uses
+the mappings to respond correctly to queries about the current working
+directory, which can come from the operating system or commands such as
+the UNIX B<pwd> command.
+
+As it initializes, the Cache Manager creates the binary-format
+F<VolumeItems> file in the local disk cache directory, and it must always
+remain there.
+
+=head2 F<VI<n>>
+
+A F<VI<n>> file can store a chunk of cached AFS data on a client machine
+that is using a disk cache. As the Cache Manager initializes, it verifies
+that the local disk cache directory houses a number of F<VI<n>> files
+equal to the largest of the following:
+
+=over 4
+
+=item *
+
+100
+
+=item *
+
+One and a half times the result of dividing the cache size by the chunk
+size (cachesize/chunksize * 1.5).
+
+=item *
+
+The result of dividing the cache size by 10 MB (10,240).
+
+=back
+
+The Cache Manager determines the cache size from the B<-blocks> argument
+to the B<afsd> command, or if the argument is not included, from the third
+field of the F</usr/vice/etc/cacheinfo> file.  The default chunk size is
+64 KB; use the B<-chunksize> argument to the B<afsd> command to override
+it. To override the default number of chunks resulting from the
+calculation, include the B<-files> argument to the B<afsd>
+command. L<afsd(8)> describes the restrictions on acceptable values for
+each of the arguments.
+
+If the disk cache directory houses fewer F<VI<n>> files than necessary,
+the Cache Manager creates new ones, assigning each a unique integer I<n>
+that distinguishes it from the other files; the integers start with 1 and
+increment by one for each F<VI<n>> file created. The Cache Manager removes
+files if there are more than necessary. The Cache Manager also adds and
+removes F<VI<n>> files in response to the B<fs setcachesize> command,
+which can be used to alter the cache size between reboots.
+
+F<VI<n>> files expand and contract to accommodate the size of the AFS
+directory listing or file they temporarily house. As mentioned, by default
+each F<VI<n>> file holds up to 64 KB (65,536 bytes) of a cached AFS
+element. AFS elements larger than 64 KB are divided among multiple
+B<V>I<n> files. If an element is smaller than 64 KB, the F<VI<n>> file
+expands only to the required size. A F<VI<n>> file accommodates only a
+single element, so if there many small cached elements, it is possible to
+exhaust the available F<VI<n>> files without reaching the maximum cache
+size.
+
+=head1 CAUTIONS
+
+Editing or removing the F<CacheItems> or F<VolumeItems> files or a
+F<VI<n>> file can cause a kernel panic. If the contents of F<VI<n>> files
+seem out of date, clear the files by using the B<fs flush> or B<fs
+flushvolume> command. If any of the cache files are accidentally modified
+or deleted, rebooting the machine usually restores normal performance.
+
+To alter cache size (and thus the number of F<VI<n>> files) between
+reboots, use the B<fs setcachesize> command. Alternatively, alter the
+value of the B<-blocks>, B<-files> or B<-chunksize> arguments to the
+B<afsd> command invoked in the machine's AFS initialization file, and
+reboot. To refresh the contents of one or more F<VI<n>> files, use the
+B<fs flush> or B<fs flushvolume> command.
+
+=head1 SEE ALSO
+
+L<cacheinfo(5)>,
+L<afsd(8)>,
+L<fs_checkvolumes(1)>,
+L<fs_flush(1)>,
+L<fs_flushvolume(1)>,
+L<fs_setcachesize(1)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0.  It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
index 4a221fb..50ac0ed 100644 (file)
@@ -1,21 +1,20 @@
 =head1 NAME
 
-VI<vol_ID>.vol - Represents an AFS volume
+afs_volume_header - Represents an AFS volume
 
 =head1 DESCRIPTION
 
-The B<V>I<vol_ID>.vol file is the header
-file for the AFS volume with volume ID I<vol_ID>. There is one
-such file for each volume stored on an AFS server (B</vicep>)
-partition. The header file stores information that includes the
-volume's name, ID number, type (read/write, read-only, or backup), size
-and status (online, offline, or busy). To display information from the
-header file, use the B<vos listvol> or B<vos examine>
+The F<VI<vol_ID>.vol> file is the header file for the AFS volume with
+volume ID I<vol_ID>. There is one such file for each volume stored on an
+AFS server (F</vicep>) partition. The header file stores information that
+includes the volume's name, ID number, type (read/write, read-only, or
+backup), size and status (online, offline, or busy). To display
+information from the header file, use the B<vos listvol> or B<vos examine>
 command.
 
 The header file points to, but does not contain, the actual data in the
-volume. It is not possible to access the AFS data except by mounting
-the volume in the AFS filespace and reading its contents through the Cache
+volume. It is not possible to access the AFS data except by mounting the
+volume in the AFS filespace and reading its contents through the Cache
 Manager.
 
 =head1 COPYRIGHT
index 97bfc45..da00e43 100644 (file)
 =head1 NAME
 
-afsmonitor Configuration File - Provides instructions for the afsmonitor command
+afsmonitor - Provides instructions for the afsmonitor command
 
 =head1 DESCRIPTION
 
 The afsmonitor configuration file determines which machines the
-B<afsmonitor> command probes for File Server or Cache Manager
-statistics and which statistics it gathers. Use the B<-config>
-argument to the B<afsmonitor> command to identify the configuration
-file to use.
+B<afsmonitor> command probes for File Server or Cache Manager statistics
+and which statistics it gathers. Use the B<-config> argument to the
+B<afsmonitor> command to identify the configuration file to use.
 
-The instructions that can appear in the configuration file are as
-follows:
+The instructions that can appear in the configuration file are as follows:
 
 =over 4
 
-=item C<cm  I<host_name>
->
+=item cm <I<host name>>
 
-Names a client machine for which to display Cache Manager
-statistics. The order of B<cm> lines in the file determines the
-order in which client machines appear from top to bottom on the C<System
-Overview> and C<Cache Managers> output screens.
+Names a client machine for which to display Cache Manager statistics. The
+order of C<cm> lines in the file determines the order in which client
+machines appear from top to bottom on the C<System Overview> and C<Cache
+Managers> output screens.
 
-=item C<fs  I<host_name>
->
+=item fs <I<host name>>
 
 Names a file server machine for which to display File Server
-statistics. The order of B<fs> lines in the file determines the
-order in which file server machines appear from top to bottom on the
-C<System Overview> and C<File Servers> output screens.
-
-=item C<thresh  fs | cm  I<field_name  I<thresh_val> 
-[I<cmd_to_run>]  [I<arg>
-
-Assigns the threshold value I<thresh_val> to the statistic
-I<field_name>, for either a File Server statistic (B<fs>) or a
-Cache Manager statistic (B<cm>). The optional
-I<cmd_to_execute> field names a binary or script to execute each time
-the value of the statistic changes from being below I<thresh_val> to
-being at or above I<thresh_val>. A change between two values that
-both exceed I<thresh_val> does not retrigger the binary or
-script. The optional I<arg>
-The B<afsmonitor> program passes the following parameters to the
-I<cmd_to_execute>&#58;
-
-=item I<host_name fs|cm I<field_name>
-I<threshold_val>
-I<actual_val> [<I<arg>
-
-The parameters B<fs>, cm, I<field_name>,
-I<threshold_val>, and I<arg>
-
-Use the thresh line to set either a global threshold, which
-applies to all file server machines listed on B<fs> lines or client
-machines listed on B<cm> lines in the configuration file, or a
-machine-specific threshold, which applies to only one file server or client
-machine.
+statistics. The order of C<fs> lines in the file determines the order in
+which file server machines appear from top to bottom on the C<System
+Overview> and C<File Servers> output screens.
 
-=over 4
+=item thresh (fs | cm) <I<field>> <I<thresh>> [<I<cmd>>] [<I<arg>> ...]
 
-=item *
+Assigns the threshold value I<thresh> to the statistic I<field>, for
+either a File Server statistic (C<fs>) or a Cache Manager statistic
+(C<cm>). The optional I<cmd> field names a binary or script to execute
+each time the value of the statistic changes from being below I<thresh> to
+being at or above I<thresh>. A change between two values that both exceed
+I<thresh> does not retrigger the binary or script. The optional I<arg>
+fields are additional values that the B<afsmonitor> program passes as
+arguments to the I<cmd> command. If any of them include one or more
+spaces, enclose the entire field in double quotes.
+
+The B<afsmonitor> program passes the following parameters to the I<cmd>:
+
+    <hostname> (fs|cm) <field> <thresh> <actual> [<arg> ...]
 
-To set a global threshold, place the thresh line before any of
-the B<fs> or B<cm> lines in the file.
+The parameters C<fs>, C<cm>, <field>, <thresh>, and <arg> correspond to
+the values with the same name on the thresh line. The <hostname> parameter
+identifies the file server or client machine where the statistic has
+crossed the threshold, and the <actual> parameter is the actual value of
+<field> that exceeds the threshold value.
 
+Use the C<thresh> line to set either a global threshold, which applies to
+all file server machines listed on C<fs> lines or client machines listed
+on C<cm> lines in the configuration file, or a machine-specific threshold,
+which applies to only one file server or client machine.
+
+=over 4
 
 =item *
 
-To set a machine-specific threshold, place the thresh line
-below the corresponding B<fs> or B<cm> line, and above any
-other B<fs> or B<cm> lines. A machine-specific
-threshold value always overrides the corresponding global threshold, if
-set. Do not place a B<thresh fs> line directly after a
-B<cm> line or a B<thresh cm> line directly after a
-B<fs> line.
+To set a global threshold, place the thresh line before any of the C<fs>
+or C<cm> lines in the file.
+
+=item *
 
+To set a machine-specific threshold, place the thresh line below the
+corresponding C<fs> or C<cm> line, and above any other C<fs> or C<cm>
+lines. A machine-specific threshold value always overrides the
+corresponding global threshold, if set. Do not place a C<thresh fs> line
+directly after a C<cm> line or a C<thresh cm> line directly after a C<fs>
+line.
 
 =back
 
-=item C<show  fs | cm  I<field/group/section>
->
+=item show (fs | cm) I<field/group/section>
 
 Specifies which individual statistic, group of statistics, or section of
-statistics to display on the C<File Servers> screen (B<fs>) or
-C<Cache Managers> screen (B<cm>) and the order in which to
-display them. The appendix of B<afsmonitor> statistics in the
-I<IBM AFS Administration Guide> specifies the group and section to
-which each statistic belongs. Include as many B<show> lines as
-necessary to customize the screen display as desired, and place them anywhere
-in the file. The top-to-bottom order of the B<show> lines in
-the configuration file determines the left-to-right order in which the
-statistics appear on the corresponding screen.
-
-If there are no show lines in the configuration file, then the
-screens display all statistics for both Cache Managers and File
-Servers. Similarly, if there are no B<show fs> lines, the
-C<File Servers> screen displays all file server statistics, and if
-there are no B<show cm> lines, the C<Cache Managers> screen
-displays all client statistics.
-
-=item # I<comments
->
-
-Precedes a line of text that the afsmonitor program ignores
-because of the initial number (B<#>) sign, which must appear in the
-very first column of the line.
+statistics to display on the C<File Servers> screen (C<fs>) or C<Cache
+Managers> screen (C<cm>) and the order in which to display them. The
+appendix of B<afsmonitor> statistics in the I<IBM AFS Administration
+Guide> specifies the group and section to which each statistic
+belongs. Include as many C<show> lines as necessary to customize the
+screen display as desired, and place them anywhere in the file. The
+top-to-bottom order of the C<show> lines in the configuration file
+determines the left-to-right order in which the statistics appear on the
+corresponding screen.
+
+If there are no C<show> lines in the configuration file, then the screens
+display all statistics for both Cache Managers and File
+Servers. Similarly, if there are no C<show fs> lines, the C<File Servers>
+screen displays all file server statistics, and if there are no C<show cm>
+lines, the C<Cache Managers> screen displays all client statistics.
+
+=item # I<comments>
+
+Precedes a line of text that the afsmonitor program ignores because of the
+initial number (C<#>) sign, which must appear in the very first column of
+the line.
 
 =back
 
-For a list of the values that can appear in the
-I<field/group/section> field of a B<show> instruction, see the
-B<afsmonitor> statistics appendix to the I<IBM AFS Administration
-Guide>.
+For a list of the values that can appear in the I<field/group/section>
+field of a C<show> instruction, see the B<afsmonitor> statistics appendix
+to the I<IBM AFS Administration Guide>.
 
 =head1 SEE ALSO
 
index 04b2cc8..644ee6b 100644 (file)
@@ -4,20 +4,20 @@ afszcm.cat - Error message catalog for debugging the Cache Manager
 
 =head1 DESCRIPTION
 
-The afszcm.cat file is a message catalog for the Cache
-Manager. The B<fstrace dump> command interpreter uses it in
-conjunction with the standard UNIX catalog utilities to translate Cache
-Manager operation codes into character strings as it writes traces in the
-B<fstrace> trace log, which makes the log more readable.
+The F<afszcm.cat> file is a message catalog for the Cache Manager. The
+B<fstrace dump> command interpreter uses it in conjunction with the
+standard UNIX catalog utilities to translate Cache Manager operation codes
+into character strings as it writes traces in the B<fstrace> trace log,
+which makes the log more readable.
 
-The conventional location for the file is the /usr/vice/etc/C/
-directory. It can be placed in another directory if the NLSPATH and
-LANG environment variables are set appropriately.
+The conventional location for the file is the F</usr/vice/etc/C/>
+directory. It can be placed in another directory if the NLSPATH and LANG
+environment variables are set appropriately.
 
 =head1 SEE ALSO
 
-L<afsd(1)>,
-L<fstrace_dump(1)>
+L<afsd(8)>,
+L<fstrace_dump(8)>
 
 =head1 COPYRIGHT
 
index 89e471c..aa9c3ca 100644 (file)
@@ -1,38 +1,38 @@
 =head1 NAME
 
-bdb.DB0 and bdb.DBSYS1 - Contain the Backup Database and associated log
+bdb.DB0, bdb.DBSYS1 - Contain the Backup Database and associated log
 
 =head1 DESCRIPTION
 
-The bdb.DB0 file contains the Backup Database, which
-records configuration information used by the AFS Backup System along with
-cross-indexed records of the tapes created and volumes dumped using the Backup
-System commands.
-
-The bdb.DBSYS1 file is a log file in which the Backup
-Server (B<buserver> process) logs each database operation before
-performing it. When an operation is interrupted, the Backup Server
-replays the log to complete the operation.
-
-Both files are in binary format and reside in the /usr/afs/db
-directory on each database server machine that runs the Backup Server.
-When the Backup Server starts or restarts on a given machine, it establishes a
-connection with its peers and verifies that its copy of the
-B<bdb.DB0> file matches the copy on the other database server
-machines. If not, the Backup Servers use AFS's distributed
-database technology, Ubik, to distribute to all of the machines the copy of
-the database with the highest version number.
-
-Use the commands in the backup suite to administer the Backup
-Database. It is advisable to create a backup copy of the
-B<bdb.DB0> file on tape on a regular basis, using the UNIX
-B<tar> command or another local disk backup utility.
+The F<bdb.DB0> file contains the Backup Database, which records
+configuration information used by the AFS Backup System along with
+cross-indexed records of the tapes created and volumes dumped using the
+Backup System commands.
+
+The F<bdb.DBSYS1> file is a log file in which the Backup Server
+(B<buserver> process) logs each database operation before performing
+it. When an operation is interrupted, the Backup Server replays the log to
+complete the operation.
+
+Both files are in binary format and reside in the F</usr/afs/db> directory
+on each database server machine that runs the Backup Server.  When the
+Backup Server starts or restarts on a given machine, it establishes a
+connection with its peers and verifies that its copy of the F<bdb.DB0>
+file matches the copy on the other database server machines. If not, the
+Backup Servers use AFS's distributed database technology, Ubik, to
+distribute to all of the machines the copy of the database with the
+highest version number.
+
+Use the commands in the backup suite to administer the Backup Database. It
+is advisable to create a backup copy of the F<bdb.DB0> file on tape on a
+regular basis, using the UNIX B<tar> command or another local disk backup
+utility.
 
 =head1 SEE ALSO
 
-L<backup(1)>,
-L<backup_savedb(1)>,
-L<buserver(1)>
+L<backup(8)>,
+L<backup_savedb(8)>,
+L<buserver(8)>
 
 =head1 COPYRIGHT
 
diff --git a/doc/man-pages/pod5/butc.pod b/doc/man-pages/pod5/butc.pod
new file mode 100644 (file)
index 0000000..1bbc9f9
--- /dev/null
@@ -0,0 +1,674 @@
+=head1 NAME
+
+butc - Defines Tape Coordinator instructions for automated tape devices
+
+=head1 DESCRIPTION
+
+The F<CFG_I<device_name>> file includes instructions that configure a Tape
+Coordinator (B<butc>) for use with automated backup devices such as tape
+stackers and jukeboxes, enable the Tape Coordinator to dump and restore
+data to a I<backup data file> on a local disk device, and enable greater
+automation of other aspects of the backup process.
+
+There is a separate configuration file for each tape device or backup data
+file. Creating the file is optional, and unnecessary if none of the
+instructions it can include pertain to a given tape device. The
+ASCII-format file must reside in the F</usr/afs/backup> directory on the
+Tape Coordinator machine if it exists.
+
+The F<CFG_I<device_name>> file does not replace the
+F</usr/afs/backup/tapeconfig> file, a single copy of which still must
+exist on every Tape Coordinator machine.
+
+To enable the Tape Coordinator to locate the configuration file, construct
+the variable part of the filename, I<device_name>, as follows:
+
+=over 4
+
+=item *
+
+For a tape device, strip off the initial C</dev/> string from the device
+name, and replace any other slashes in the name with underscores. For
+example, F<CFG_rmt_4m> is the appropriate filename for a device called
+F</dev/rmt/4m>.
+
+=item *
+
+For a backup data file, strip off the initial slash (C</>) and replace any
+other slashes in the name with underscores. For example,
+F<CFG_var_tmp_FILE> is the appropriate filename for a backup data file
+called F</var/tmp/FILE>.
+
+=back
+
+The F<CFG_I<device_name>> file lists one or more of the following
+instructions, each on its own line. All are optional, and they can appear
+in any order. A more detailed description of each instruction follows the
+list:
+
+=over 4
+
+=item ASK
+
+Controls whether the Tape Coordinator prompts for guidance when it
+encounters error conditions.
+
+=item AUTOQUERY
+
+Controls whether the Tape Coordinator prompts for the first tape.
+
+=item BUFFERSIZE
+
+Sets the size of the memory buffer the Tape Coordinator uses when
+transferring data.
+
+=item FILE
+
+Controls whether the dump is written to a tape device or a file.
+
+=item MOUNT
+
+Identifies the file that contains routines for inserting tapes into the
+device's drive.
+
+=item NAME_CHECK
+
+Controls whether the Tape Coordinator verifies that a tape's AFS tape
+name matches the dump being written.
+
+=item UNMOUNT
+
+Identifies the file that contains routines for removing tapes from the
+device's drive.
+
+=back
+
+=head2 The ASK Instruction
+
+The C<ASK> instruction takes a boolean value as its argument, in the
+following format:
+
+   ASK (YES | NO)
+
+When the value is C<YES>, the Tape Coordinator generates a prompt in its
+window, requesting a response to the error cases described in the
+following list. This is the default behavior if the C<ASK> instruction
+does not appear in the F<CFG_I<device_name>> file.
+
+When the value is C<NO>, the Tape Coordinator does not prompt in error
+cases, but instead uses the automatic default responses described in the
+following list. The Tape Coordinator also logs the error in the
+F<TE_I<device_name>> file. Suppressing the prompts enables the Tape
+Coordinator to run unattended, though it still prompts for insertion of
+tapes unless the C<MOUNT> instruction is used.
+
+The error cases controlled by this instruction are the following:
+
+=over 4
+
+=item *
+
+The Backup System is unable to dump a volume while running the backup dump
+command. With a C<YES> value, the Tape Coordinator prompts to offer three
+choices: try to dump the volume again immediately, omit the volume from
+the dump but continue the operation, or terminate the operation. With a
+C<NO> value, the Tape Coordinator omits the volume from the dump and
+continues the operation.
+
+=item *
+
+The Backup System is unable to restore a volume while running the B<backup
+diskrestore>, B<backup volrestore>, or B<backup volsetrestore>
+command. With a C<YES> value, the Tape Coordinator prompts to offer two
+choices: omit the volume and continue restoring the other volumes, or
+terminate the operation. With a C<NO> value, it continues the operation
+without prompting, omitting the problematic volume but restoring the
+remaining ones.
+
+=item *
+
+The Backup System cannot determine if the dump set includes any more
+tapes, while running the B<backup scantape> command (the reference page
+for that command discusses possible reasons for this problem).  With a
+C<YES> value, the Tape Coordinator prompts to ask if there are more tapes
+to scan. With a C<NO> value, it proceeds as though there are more tapes
+and invokes the routine named by the C<MOUNT> instruction in the
+configuration file, or prompts the operator to insert the next tape.
+
+=item *
+
+The Backup System determines that the tape contains an unexpired dump
+while running the B<backup labeltape> command. With a C<YES> value, the
+Tape Coordinator prompts to offer two choices: continue or terminate the
+labeling operation. With a C<NO> value, it terminates the operation
+without relabeling the tape.
+
+=back
+
+=head2 The AUTOQUERY Instruction
+
+The C<AUTOQUERY> instruction takes a boolean value as its argument,
+in the following format:
+
+   AUTOQUERY (YES | NO)
+
+When the value is C<YES>, the Tape Coordinator checks for the C<MOUNT>
+instruction in the configuration file when it needs to read the first tape
+involved in an operation. As described for that instruction, it then
+either prompts for the tape or invokes the specified routine to mount the
+tape. This is the default behavior if the C<AUTOQUERY> instruction does
+not appear in the configuration file.
+
+When the value is C<NO>, the Tape Coordinator assumes that the first tape
+required for an operation is already in the drive. It does not prompt the
+operator or invoke the C<MOUNT> routine unless there is an error in
+accessing the first tape. This setting is equivalent in effect to
+including the B<-noautoquery> flag to the B<butc> command.
+
+Note that the setting of the C<AUTOQUERY> instruction controls the Tape
+Coordinator's behavior only with respect to the first tape required for an
+operation. For subsequent tapes, the Tape Coordinator always checks for
+the C<MOUNT> instruction. It also refers to the C<MOUNT> instruction if it
+encounters an error while attempting to access the first tape.
+
+=head2 The BUFFERSIZE Instruction
+
+The C<BUFFERSIZE> instruction takes an integer value, and optionally
+units, in the following format:
+
+   BUFFERSIZE <size>[(k | K | m | M | g | G)]
+
+where <size> specifies the amount of memory the Tape Coordinator allocates
+to use as a buffer during both dump and restore operations.  The default
+unit is bytes, but use C<k> or C<K> to specify kilobytes, C<m> or C<M> for
+megabytes, and C<g> or C<G> for gigabytes. There is no space between the
+<size> value and the units letter.
+
+By default, the Tape Coordinator uses a 16 KB buffer during dump
+operations. As it receives volume data from the Volume Server, the Tape
+Coordinator gathers 16 KB of data in the buffer before transferring the
+entire 16 KB to the tape device or backup data file. Similarly, during a
+restore operation the Tape Coordinator by default buffers 32 KB of data
+from the tape device or backup data file before transferring the entire 32
+KB to the Volume Server for restoration into the file system. Buffering
+makes the volume of data flowing to and from a tape device more even and
+so promotes tape streaming, which is the most efficient way for a tape
+device to operate.
+
+In a normal network configuration, the default buffer sizes are usually
+large enough to promote tape streaming. If the network between the Tape
+Coordinator machine and file server machines is slow, it can help to
+increase the buffer size.
+
+=head2 The FILE Instruction
+
+The C<FILE> instruction takes a boolean value as its argument, in the
+following format:
+
+   FILE (NO | YES)
+
+When the value is C<NO>, the Tape Coordinator writes to a tape device
+during a dump operation and reads from one during a restore
+operation. This is the default behavior if the C<FILE> instruction does
+not appear in the configuration file.
+
+When the value is C<YES>, the Tape Coordinator writes volume data to a
+backup data file on the local disk during a dump operation and reads
+volume data from a file during a restore operation. If the file does not
+exist when the Tape Coordinator attempts to access it to write a dump, the
+Tape Coordinator creates it. For a restore operation to succeed, the file
+must exist and contain volume data previously written to it by a B<backup
+dump> operation.
+
+When the value is C<YES>, the backup data file's complete pathname must
+appear (instead of a tape drive device name) in the third field of the
+corresponding port offset entry in the local F</usr/afs/backup/tapeconfig>
+file. If the field instead refers to a tape device, dump operations appear
+to succeed but are inoperative. It is not possible to restore data that
+was accidently dumped to a tape device while the C<FILE> instruction was
+set to C<YES>. (In the same way, if the C<FILE> instruction is set to
+C<NO>, the F<tapeconfig> entry must refer to an actual tape device.)
+
+Rather than put an actual file pathname in the third field of the
+F<tapeconfig> file, however, the recommended configuration is to create a
+symbolic link in the F</dev> directory that points to the actual file
+pathname, and record the symbolic link in this field. This configuration
+has a couple of advantages:
+
+=over 4
+
+=item *
+
+It makes the I<device_name> portion of the F<CFG_I<device_name>>,
+F<TE_I<device_name>>, and F<TL_I<device_name>> names as short as
+possible. Because the symbolic link is in the F</dev> directory as though
+it were a tape device, the device configuration file's name is constructed
+by stripping off the entire F</dev/> prefix, instead of just the initial
+slash. If, for example, the symbolic link is called F</dev/FILE>, the
+device configuration file name is F<CFG_FILE>, whereas if the actual
+pathname F</var/tmp/FILE> appears in the B<tapeconfig> file, the file's
+name must be F<CFG_var_tmp_FILE>.
+
+=item *
+
+It provides for a more graceful, and potentially automated, recovery if
+the Tape Coordinator cannot write a complete dump into the backup data
+file (because the partition housing the backup data file becomes full, for
+example). The Tape Coordinator's reaction to this problem is to invoke the
+C<MOUNT> script, or to prompt the operator if the C<MOUNT> instruction
+does not appear in the configuration file.
+
+=over 4
+
+=item *
+
+If there is a C<MOUNT> routine, the operator can prepare for this
+situation by adding a subroutine that changes the symbolic link to point
+to another backup data file on a partition where there is space available.
+
+=item *
+
+If there is no C<MOUNT> instruction, the prompt enables the operator
+manually to change the symbolic link to point to another backup data file,
+then press Return to signal that the Tape Coordinator can continue the
+operation.
+
+=back
+
+=back
+
+If the third field in the F<tapeconfig> file names the actual file, there
+is no way to recover from exhausting the space on the partition that
+houses the backup data file. It is not possible to change the
+F<tapeconfig> file in the middle of an operation.
+
+When writing to a backup data file, the Tape Coordinator writes data at 16
+KB offsets. If a given block of data (such as the marker that signals the
+beginning or end of a volume) does not fill the entire 16 KB, the Tape
+Coordinator still skips to the next offset before writing the next
+block. In the output of a B<backup dumpinfo> command issued with the
+B<-id> option, the value in the C<Pos> column is the ordinal of the 16-KB
+offset at which the volume data begins, and so is not generally only one
+higher than the position number on the previous line, as it is for dumps
+to tape.
+
+=head2 The MOUNT Instruction
+
+The C<MOUNT> instruction takes a pathname as its argument, in the
+following format:
+
+   MOUNT <filename>
+
+The referenced executable file must reside on the local disk and contain a
+shell script or program that directs an automated tape device, such as a
+jukebox or stacker, to mount a tape (insert it into the tape reader).  The
+operator must write the routine to invoke the mount command specified by
+the device's manufacturer; AFS does not include any scripts, although an
+example appears in L<EXAMPLES>.  The script or program inherits the Tape
+Coordinator's AFS authentication status.
+
+When the Tape Coordinator needs to mount a tape, it checks the
+configuration file for a C<MOUNT> instruction. If there is no C<MOUNT>
+instruction, the Tape Coordinator prompts the operator to insert a tape
+before it attempts to open the tape device. If there is a C<MOUNT>
+instruction, the Tape Coordinator executes the routine in the referenced
+file. The routine invoked by the C<MOUNT> instruction inherits the local
+identity (UNIX UID) and AFS tokens of the B<butc> command's issuer.
+
+There is an exception to this sequence: if the C<AUTOQUERY NO> instruction
+appears in the configuration file, or the B<-noautoquery> flag was
+included on the B<butc> command, then the Tape Coordinator assumes that
+the operator has already inserted the first tape needed for a given
+operation. It attempts to read the tape immediately, and only checks for
+the C<MOUNT> instruction or prompts the operator if the tape is missing or
+is not the required one.
+
+When the Tape Coordinator invokes the routine indicated by the C<MOUNT>
+instruction, it passes the following parameters to the routine in the
+indicated order:
+
+=over 4
+
+=item *
+
+The tape device or backup data file's pathname, as recorded in the
+F</usr/afs/backup/tapeconfig> file.
+
+=item *
+
+The tape operation, which (except for the exceptions noted in the
+following list) matches the B<backup> command operation code used to
+initiate the operation:
+
+=over 4
+
+=item *
+
+C<appenddump> (when a backup dump command includes the B<-append> flag).
+
+=item *
+
+C<dump> (when a backup dump command does not include the B<-append> flag).
+
+=item *
+
+C<labeltape>
+
+=item *
+
+C<readlabel>
+
+=item *
+
+C<restore> (for a B<backup diskrestore>, backup volrestore, or B<backup
+volsetrestore> command).
+
+=item *
+
+C<restoredb>
+
+=item *
+
+C<savedb>
+
+=item *
+
+C<scantape>
+
+=back
+
+=item *
+
+The number of times the Tape Coordinator has attempted to open the tape
+device or backup data file. If the open attempt returns an error, the Tape
+Coordinator increments this value by one and again invokes the C<MOUNT>
+instruction.
+
+=item *
+
+The tape name. For some operations, the Tape Coordinator passes the string
+C<none>, because it does not know the tape name (when running the B<backup
+scantape> or B<backup readlabel>, for example), or because the tape does
+not necessarily have a name (when running the B<backup labeltape> command,
+for example).
+
+=item *
+
+The tape ID recorded in the Backup Database. As with the tape name, the
+Backup System passes the string C<none> for operations where it does not
+know the tape ID or the tape does not necessarily have an ID.
+
+=back
+
+The routine invoked by the C<MOUNT> instruction must return an exit code
+to the Tape Coordinator:
+
+=over 4
+
+=item *
+
+Code 0 (zero) indicates that the routine successfully mounted the
+tape. The Tape Coordinator continues the backup operation.  If the routine
+invoked by the C<MOUNT> instruction does not return this exit code, the
+Tape Coordinator never calls the C<UNMOUNT> instruction.
+
+=item *
+
+Code 1 (one) indicates that the routine failed to mount the tape. The Tape
+Coordinator terminates the operation.
+
+=item *
+
+Any other code indicates that the routine was not able to access the
+correct tape. The Tape Coordinator prompts the operator to insert the
+correct tape.
+
+=back
+
+If the backup command was issued in interactive mode and the operator
+issues the B<backup kill> command while the C<MOUNT> routine is running,
+the Tape Coordinator passes the termination signal to the routine; the
+entire operation terminates.
+
+=head2 The NAME_CHECK Instruction
+
+The C<NAME_CHECK> instruction takes a boolean value as its argument, in
+the following format:
+
+   NAME_CHECK (YES | NO)
+
+When the value is C<YES> and the tape does not have a permanent name, the
+Tape Coordinator checks the AFS tape name when dumping a volume in
+response to the B<backup dump> command. The AFS tape name must be C<<
+<NULL> >> or match the tape name that the B<backup dump> operation assigns
+based on the volume set and dump level names. This is the default behavior
+if the C<NAME_CHECK> instruction does not appear in the configuration
+file.
+
+When the value is C<NO>, the Tape Coordinator does not check the AFS tape
+name before writing to the tape.
+
+The Tape Coordinator always checks that all dumps on the tape are expired,
+and refuses to write to a tape that contains unexpired dumps.
+
+=head2 The UNMOUNT Instruction
+
+The C<UNMOUNT> instruction takes a pathname as its argument, in the
+following format:
+
+   UNMOUNT <filename>
+
+The referenced executable file must reside on the local disk and contain a
+shell script or program that directs an automated tape device, such as a
+jukebox or stacker, to unmount a tape (remove it from the tape reader).
+The operator must write the routine to invoke the unmount command
+specified by the device's manufacturer; AFS does not include any scripts,
+although an example appears in L<EXAMPLES>.  The script or program
+inherits the Tape Coordinator's AFS authentication status.
+
+After closing a tape device, the Tape Coordinator checks the configuration
+file for an C<UNMOUNT> instruction, whether or not the B<close> operation
+succeeds. If there is no C<UNMOUNT> instruction, the Tape Coordinator
+takes no action, in which case the operator must take the action necessary
+to remove the current tape from the drive before another can be
+inserted. If there is an C<UNMOUNT> instruction, the Tape Coordinator
+executes the referenced file. It invokes the routine only once, passing in
+the following parameters:
+
+=over 4
+
+=item *
+
+The tape device pathname (as specified in the
+F</usr/afs/backup/tapeconfig> file).
+
+=item *
+
+The tape operation (always unmount).
+
+=back
+
+=head1 PRIVILEGE REQUIRED
+
+The file is protected by UNIX mode bits. Creating the file requires the
+C<w> (write) and C<x> (execute) permissions on the F</usr/afs/backup>
+directory. Editing the file requires the C<w> (write) permission on the
+file.
+
+=head1 EXAMPLES
+
+The following example configuration files demonstrate one way to structure
+a configuration file for a stacker or backup dump file. The examples are
+not necessarily appropriate for a specific cell; if using them as models,
+be sure to adapt them to the cell's needs and equipment.
+
+=head2 Example F<CFG_I<device_name>> File for Stackers
+
+In this example, the administrator creates the following entry for a tape
+stacker called C<stacker0.1> in the F</usr/afs/backup/tapeconfig> file. It
+has port offset 0.
+
+   2G   5K   /dev/stacker0.1   0
+
+The administrator includes the following five lines in the
+F</usr/afs/backup/CFG_stacker0.1> file. To review the meaning of each
+instruction, see L<DESCRIPTION>.
+
+   MOUNT /usr/afs/backup/stacker0.1
+   UNMOUNT /usr/afs/backup/stacker0.1
+   AUTOQUERY NO
+   ASK NO
+   NAME_CHECK NO
+
+Finally, the administrator writes the following executable routine in the
+F</usr/afs/backup/stacker0.1> file referenced by the C<MOUNT> and
+C<UNMOUNT> instructions in the F<CFG_stacker0.1> file.
+
+   #! /bin/csh -f
+
+   set devicefile = $1
+   set operation = $2
+   set tries = $3
+   set tapename = $4
+   set tapeid = $5
+     
+   set exit_continue = 0
+   set exit_abort = 1
+   set exit_interactive = 2
+    
+   #--------------------------------------------
+     
+   if (${tries} > 1) then
+      echo "Too many tries"
+      exit ${exit_interactive}
+   endif
+     
+   if (${operation} == "unmount") then
+      echo "UnMount: Will leave tape in drive"
+      exit ${exit_continue}
+   endif
+     
+   if ((${operation} == "dump")     |\
+       (${operation} == "appenddump")     |\
+       (${operation} == "savedb"))  then
+     
+       stackerCmd_NextTape ${devicefile}
+       if (${status} != 0)exit${exit_interactive}
+       echo "Will continue"
+       exit ${exit_continue}
+   endif
+     
+   if ((${operation} == "labeltape")    |\
+       (${operation} == "readlabel")) then
+      echo "Will continue"
+      exit ${exit_continue}
+   endif
+     
+   echo "Prompt for tape"
+   exit ${exit_interactive}
+
+This routine uses two of the parameters passed to it by the Backup System:
+C<tries> and C<operation>. It follows the recommended practice of
+prompting for a tape if the value of the C<tries> parameter exceeds one,
+because that implies that the stacker is out of tapes.
+
+For a B<backup dump> or backup savedb operation, the routine calls the
+example C<stackerCmd_NextTape> function provided by the stacker's
+manufacturer. Note that the final lines in the file return the exit code
+that prompts the operator to insert a tape; these lines are invoked when
+either the stacker cannot load a tape or a the operation being performed
+is not one of those explicitly mentioned in the file (such as a restore
+operation).
+
+=head2 Example F<CFG_I<device_name>> File for Dumping to a Data File
+
+In this example, the administrator creates the following entry for a
+backup data file called F<HSM_device> in the F</usr/afs/backup/tapeconfig>
+file. It has port offset 20.
+
+   1G   0K   /dev/HSM_device   20
+
+The administrator includes the following lines in the
+F</usr/afs/backup/CFG_HSM_device> file. To review the meaning of each
+instruction, see L<DESCRIPTION>.
+
+   MOUNT /usr/afs/backup/file
+   FILE YES
+   ASK NO
+
+Finally, the administrator writes the following executable routine in the
+F</usr/afs/backup/file> file referenced by the C<MOUNT> instruction in the
+F<CFG_HSM_device> file, to control how the Tape Coordinator handles the
+file.
+
+   #! /bin/csh -f
+   set devicefile = $1
+   set operation = $2
+   set tries = $3
+   set tapename = $4
+   set tapeid = $5
+
+   set exit_continue = 0
+   set exit_abort = 1
+   set exit_interactive = 2
+     
+   #--------------------------------------------
+     
+   if (${tries} > 1) then
+      echo "Too many tries"
+      exit ${exit_interactive}
+   endif
+     
+   if (${operation} == "labeltape") then
+      echo "Won't label a tape/file"
+      exit ${exit_abort}
+   endif
+     
+   if ((${operation} == "dump")   |\
+       (${operation} == "appenddump")   |\
+       (${operation} == "restore")   |\
+       (${operation} == "savedb")    |\
+       (${operation} == "restoredb")) then
+     
+      /bin/rm -f ${devicefile}
+      /bin/ln -s /hsm/${tapename}_${tapeid} ${devicefile}
+      if (${status} != 0) exit ${exit_abort}
+   endif
+     
+   exit ${exit_continue}
+
+Like the example routine for a tape stacker, this routine uses the
+C<tries> and C<operation> parameters passed to it by the Backup
+System. The C<tries> parameter tracks how many times the Tape Coordinator
+has attempted to access the file. A value greater than one indicates that
+the Tape Coordinator cannot access it, and the routine returns exit code 2
+(C<exit_interactive>), which results in a prompt for the operator to load
+a tape. The operator can use this opportunity to change the name of the
+backup data file specified in the B<tapeconfig> file.
+
+The primary function of this routine is to establish a link between the
+device file and the file to be dumped or restored. When the Tape
+Coordinator is executing a B<backup dump>, B<backup restore>, B<backup
+savedb>, or B<backup restoredb> operation, the routine invokes the UNIX
+C<ln -s> command to create a symbolic link from the backup data file named
+in the F<tapeconfig> file to the actual file to use (this is the
+recommended method). It uses the value of the C<tapename> and C<tapeid>
+parameters to construct the file name.
+
+=head1 SEE ALSO
+
+L<tapeconfig(5)>,
+L<backup_diskrestore(8)>,
+L<backup_dump(8)>,
+L<backup_restoredb(8)>,
+L<backup_savedb(8)>,
+L<backup_volrestore(8)>,
+L<backup_volsetrestore(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0.  It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
diff --git a/doc/man-pages/pod5/butc_logs.pod b/doc/man-pages/pod5/butc_logs.pod
new file mode 100644 (file)
index 0000000..5ef3d82
--- /dev/null
@@ -0,0 +1,71 @@
+=head1 NAME
+
+butc_logs - Message logs from the Tape Coordinator process
+
+=head1 DESCRIPTION
+
+The Backup System Tape Coordinator (B<butc>) process generates two log
+files per device, one for error messages and one for actions.
+
+=head2 Error Message Log
+
+The F<TE_I<device_name>> file logs error messages generated by the Backup
+System Tape Coordinator that controls the tape device or backup data file
+indicated by I<device_name>.
+
+As the Tape Coordinator initializes, it creates the file in ASCII format
+in the F</usr/afs/backup> directory. If there is an existing file, the
+Tape Coordinator renames it to F<TE_I<device_name>.old>>, overwriting the
+existing F<TE_I<device_name>.old>> file if it exists.
+
+For a tape device, the Tape Coordinator derives the variable
+I<device_name> portion of the filename from the device pathname listed in
+the local F</usr/afs/backup/tapeconfig> file, by stripping off the initial
+C</dev/> string and replacing any other slashes in the name with
+underscores. For example, the filename for a device called F</dev/rmt/4m>
+is F<TE_rmt_4m>. Similarly, for a backup data file the Tape Coordinator
+strips off the initial slash (C</>) and replaces any other slashes in the
+name with underscores. For example, the filename for a backup data file
+called F</var/tmp/FILE> is F<TE_var_tmp_FILE>.
+
+The messages in the file describe the error and warning conditions the
+Tape Coordinator encounters as it operates. For instance, a message can
+list the volumes that are inaccessible during a dump operation, or warn
+that the Tape Coordinator is overwriting a tape or backup data file. The
+messages also appear in the F</usr/afs/backup/TL_I<device_name>> file,
+which traces most of the Tape Coordinator's actions.
+
+=head2 Action Log
+
+The F<TL_I<device_name>> file logs the actions performed by the Backup
+System Tape Coordinator that controls the tape device or backup data file
+indicated by I<device_name>. It also records the same error and warning
+messages written to the F<TE_I<device_name>> file.
+
+As the Tape Coordinator initializes, it creates the file in ASCII format
+in the F</usr/afs/backup> directory. If there is an existing file, the
+Tape Coordinator renames it to F<TL_I<device_name>.old>, overwriting the
+existing F<TL_I<device_name>.old> file if it exists.
+
+For a tape device, the Tape Coordinator derives the variable
+I<device_name> portion of the filename from the device pathname listed in
+the local F</usr/afs/backup/tapeconfig> file, by stripping off the initial
+C</dev/> string and replacing any other slashes in the name with
+underscores. For example, the filename for a device called F</dev/rmt/4m>
+is F<TL_rmt_4m>. Similarly, for a backup data file the Tape Coordinator
+strips off the initial slash (C</>) and replaces any other slashes in the
+name with underscores. For example, the filename for a backup data file
+called F</var/tmp/FILE> is F<TL_var_tmp_FILE>.
+
+=head1 SEE ALSO
+
+L<tapeconfig(5)>,
+L<butc(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0.  It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
index b7adddd..456058b 100644 (file)
@@ -4,71 +4,64 @@ cacheinfo - Defines configuration parameters for the Cache Manager
 
 =head1 DESCRIPTION
 
-The cacheinfo file defines configuration parameters for the
-Cache Manager, which reads the file as it initializes.
+The F<cacheinfo> file defines configuration parameters for the Cache
+Manager, which reads the file as it initializes.
 
 The file contains a single line of ASCII text and must reside in the
-B</usr/vice/etc> directory. Use a text editor to create it
-during initial configuration of the client machine; the required format
-is as follows:
+F</usr/vice/etc> directory. Use a text editor to create it during initial
+configuration of the client machine; the required format is as follows:
 
-   I<mount_dir>:I<cache_dir>:I<cache_size>
+   <mount>:<cache>:<size>
 
 where
 
 =over 4
 
-=item I<mount_dir
->
+=item <mount>
 
 Names the local disk directory at which the Cache Manager mounts the AFS
-namespace. It must exist before the B<afsd> program
-runs. The conventional value is B</afs>. Using any other
-value prevents traversal of pathnames that begin with B</afs> (such as
-pathnames to files in foreign cells that do use the conventional name).
-The B<-mountdir> argument to the B<afsd> command overrides
-this value.
-
-=item I<cache_dir
->
-
-Names the local disk directory to use as a cache. It must exist
-before the B<afsd> program runs. The standard value is
-B</usr/vice/cache>, but it is acceptable to substitute a directory on
-a partition with more available space. Although the Cache Manager
-ignores this field when configuring a memory cache, a value must always appear
-in it. The B<-cachedir> argument to the B<afsd> command
-overrides this value.
-
-=item I<cache_size
->
-
-Specifies the cache size as a number of 1-kilobyte blocks. Larger
-caches generally yield better performance, but a disk cache must not exceed
-90% of the space available on the cache partition (85% for AIX systems), and a
-memory cache must use no more than 25% of available machine memory. 
-
-The B<-blocks> argument to the afsd command overrides
-this value. To reset cache size without rebooting on a machine that
-uses disk caching, use the B<fs setcachesize> command. To
-display the current size of a disk or memory cache between reboots, use the
-B<fs getcacheparms> command.
+namespace. It must exist before the B<afsd> program runs. The conventional
+value is F</afs>. Using any other value prevents traversal of pathnames
+that begin with F</afs> (such as pathnames to files in foreign cells that
+do use the conventional name).  The B<-mountdir> argument to the B<afsd>
+command overrides this value.
+
+=item <cache>
+
+Names the local disk directory to use as a cache. It must exist before the
+B<afsd> program runs. The standard value is F</usr/vice/cache>, but it is
+acceptable to substitute a directory on a partition with more available
+space. Although the Cache Manager ignores this field when configuring a
+memory cache, a value must always appear in it. The B<-cachedir> argument
+to the B<afsd> command overrides this value.
+
+=item <size>
+
+Specifies the cache size as a number of 1-kilobyte blocks. Larger caches
+generally yield better performance, but a disk cache must not exceed 90%
+of the space available on the cache partition (85% for AIX systems), and a
+memory cache must use no more than 25% of available machine memory.
+
+The B<-blocks> argument to the afsd command overrides this value. To reset
+cache size without rebooting on a machine that uses disk caching, use the
+B<fs setcachesize> command. To display the current size of a disk or
+memory cache between reboots, use the B<fs getcacheparms> command.
 
 =back
 
 =head1 EXAMPLES
 
-The following example cacheinfo file mounts the AFS namespace at
-B</afs>, establishes a disk cache in the B</usr/vice/cache>
-directory, and defines cache size as 50,000 1-kilobyte blocks.
+The following example cacheinfo file mounts the AFS namespace at F</afs>,
+establishes a disk cache in the F</usr/vice/cache> directory, and defines
+cache size as 50,000 1-kilobyte blocks.
 
    /afs:/usr/vice/cache:50000
 
 =head1 SEE ALSO
 
-L<afsd(1)>,
-L<fs_getcacheparms(1)>,
-L<fs_setcachesize(1)>
+L<afsd(8)>,
+L<fs_getcacheparms(8)>,
+L<fs_setcachesize(8)>
 
 =head1 COPYRIGHT
 
index 84faac5..39ad0ae 100644 (file)
@@ -4,65 +4,58 @@ fms.log - Records output from the fms command
 
 =head1 DESCRIPTION
 
-The fms.log file records the output generated by the
-B<fms> command. The output includes two numbers that can appear
-in a tape device's entry in the B</usr/afs/backup/tapeconfig>
-file on the Tape Coordinator machine to which the tape device is
-attached:
+The F<fms.log> file records the output generated by the B<fms>
+command. The output includes two numbers that can appear in a tape
+device's entry in the F</usr/afs/backup/tapeconfig> file on the Tape
+Coordinator machine to which the tape device is attached:
 
 =over 4
 
 =item *
 
-The capacity in bytes of the tape in the device
-
+The capacity in bytes of the tape in the device.
 
 =item *
 
 The size in bytes of the end-of-file (EOF) marks (often referred to simply
-as I<filemarks>) that the tape device writes
-
+as I<filemarks>) that the tape device writes.
 
 =back
 
-When transferring the numbers recorded in this file to the
-B<tapeconfig> file, adjust them as specified on the reference page for
-the B<tapeconfig> file, to improve Tape Coordinator performance during
-dump operations.
-
-If the fms.log file does not already exist in the current
-working directory, the B<fms> command interpreter creates it.
-In this case, the directory's mode bits must grant the B<rwx>
-(B<read>, B<write>, and B<execute>) permissions to the
-issuer of the command. If there is an existing file, the command
-interpreter overwrites it, so the file's mode bits need to grant only the
-B<w> permission to the issuer of the B<fms> command.
-The B<fms> command interpreter also writes similar information to the
-standard output stream as it runs.
-
-The file is in ASCII format. To display its contents, log onto the
-client machine and use a text editor or a file display command such as the
-UNIX B<cat> command. By default, the mode bits on the
-B<fms.log> file grant the required B<r> permission only
-to the owner (which is the local superuser B<root> by default).
+When transferring the numbers recorded in this file to the F<tapeconfig>
+file, adjust them as specified in L<tapeconfig(5)>, to improve Tape
+Coordinator performance during dump operations.
+
+If the F<fms.log> file does not already exist in the current working
+directory, the B<fms> command interpreter creates it.  In this case, the
+directory's mode bits must grant the C<rwx> (read, write, and execute)
+permissions to the issuer of the command. If there is an existing file,
+the command interpreter overwrites it, so the file's mode bits need to
+grant only the B<w> permission to the issuer of the B<fms> command.  The
+B<fms> command interpreter also writes similar information to the standard
+output stream as it runs.
+
+The file is in ASCII format. To display its contents, log onto the client
+machine and use a text editor or a file display command such as the UNIX
+B<cat> command. By default, the mode bits on the F<fms.log> file grant the
+required C<r> permission only to the owner (which is the local superuser
+C<root> by default).
 
 =head1 OUTPUT
 
-The first few lines of the file provide a simple trace of the
-B<fms> command interpreter's actions, specifying (for example)
-how many blocks it wrote on the tape. The final two lines in the file
-specify tape capacity and filemark size in bytes, using the following
-format:
+The first few lines of the file provide a simple trace of the B<fms>
+command interpreter's actions, specifying (for example) how many blocks it
+wrote on the tape. The final two lines in the file specify tape capacity
+and filemark size in bytes, using the following format:
 
-   Tape capacity is I<tape_size> bytes
-   File marks are I<filemark_size> bytes
+   Tape capacity is <tape_size> bytes
+   File marks are <filemark_size> bytes
 
 =head1 EXAMPLES
 
-The following example of the fms.log file specifies that
-the tape used during the execution of the B<fms> command had a
-capacity of 2,136,604,672 bytes, and that the tape device writes filemarks of
-size 1,910,220 bytes.
+The following example of the fms.log file specifies that the tape used
+during the execution of the B<fms> command had a capacity of 2,136,604,672
+bytes, and that the tape device writes filemarks of size 1,910,220 bytes.
 
    fms test started
    wrote 130408 blocks
@@ -71,8 +64,8 @@ size 1,910,220 bytes.
 
 =head1 SEE ALSO
 
-L<tapeconfig(1)>,
-L<fms(1)>
+L<tapeconfig(5)>,
+L<fms(8)>
 
 =head1 COPYRIGHT
 
index 63f2718..0cede50 100644 (file)
@@ -1,39 +1,37 @@
 =head1 NAME
 
-kaserver.DB0 and kaserver.DBSYS1 - Contain the Authentication Database and associated log
+kaserver.DB0, kaserver.DBSYS1 - The Authentication Database and associated log
 
 =head1 DESCRIPTION
 
-The kaserver.DB0 file contains the Authentication
-Database, which records server encryption keys and an encrypted form of all
-user passwords. The Authentication Server (B<kaserver> process)
-uses the information in the database to enable secured communications between
-AFS server and client processes.
-
-The kaserver.DBSYS1 file is a log file in which the
-Authentication Server logs each database operation before performing
-it. When an operation is interrupted, the Authentication Server replays
-the log to complete the operation.
-
-Both files are in binary format and reside in the /usr/afs/db
-directory on each of the cell's database server machines. When the
-Authentication Server starts or restarts on a given machine, it establishes a
-connection with its peers and verifies that its copy of the database matches
-the copy on the other database server machines. If not, the
-Authentication Servers call on AFS's distributed database technology,
-Ubik, to distribute to all of the machines the copy of the database with the
-highest version number.
-
-Always use the commands in the kas suite to administer the
-Authentication Database. It is advisable to create an archive copy of
-the database on a regular basis, using a tool such as the UNIX B<tar>
-command.
+The F<kaserver.DB0> file contains the Authentication Database, which
+records server encryption keys and an encrypted form of all user
+passwords. The Authentication Server (B<kaserver> process) uses the
+information in the database to enable secured communications between AFS
+server and client processes.
+
+The F<kaserver.DBSYS1> file is a log file in which the Authentication
+Server logs each database operation before performing it. When an
+operation is interrupted, the Authentication Server replays the log to
+complete the operation.
+
+Both files are in binary format and reside in the F</usr/afs/db> directory
+on each of the cell's database server machines. When the Authentication
+Server starts or restarts on a given machine, it establishes a connection
+with its peers and verifies that its copy of the database matches the copy
+on the other database server machines. If not, the Authentication Servers
+call on AFS's distributed database technology, Ubik, to distribute to all
+of the machines the copy of the database with the highest version number.
+
+Always use the commands in the kas suite to administer the Authentication
+Database. It is advisable to create an archive copy of the database on a
+regular basis, using a tool such as the UNIX B<tar> command.
 
 =head1 SEE ALSO
 
-L<kadb_check(1)>,
-L<kas(1)>,
-L<kaserver(1)>
+L<kadb_check(8)>,
+L<kas(8)>,
+L<kaserver(8)>
 
 =head1 COPYRIGHT
 
index fa64192..dd27600 100644 (file)
@@ -4,34 +4,31 @@ kaserverauxdb - Records failed authentication attempts
 
 =head1 DESCRIPTION
 
-The file kaserverauxdb records failed authentication attempts
-for the local Authentication Server. The server creates it
-automatically in the B</usr/afs/local> directory by default; use
-the B<-localfiles> argument to the B<kaserver> command to
-specify an alternate directory.
-
-The kaserverauxdb file is an internal database used by the
-Authentication Server to prevent access by users who have exceeded the limit
-on failed authentication attempts defined in their Authentication Database
-entry. The Authentication Server refuses further attempts to
-authenticate to an account listed in the database until either an AFS system
-administrator issues the B<kas unlock> command to unlock the account,
-or the timeout period defined in the user's Authentication Database entry
-passes.
-
-The kaserverauxdb file is in binary format, so its contents are
-not directly accessible. However, the output from the B<kas
-examine> command reports an account's maximum number of failed
-attempts, the lockout time, and whether the account is currently
-locked.
+The file F<kaserverauxdb> records failed authentication attempts for the
+local Authentication Server. The server creates it automatically in the
+F</usr/afs/local> directory by default; use the B<-localfiles> argument to
+the B<kaserver> command to specify an alternate directory.
+
+The F<kaserverauxdb> file is an internal database used by the
+Authentication Server to prevent access by users who have exceeded the
+limit on failed authentication attempts defined in their Authentication
+Database entry. The Authentication Server refuses further attempts to
+authenticate to an account listed in the database until either an AFS
+system administrator issues the B<kas unlock> command to unlock the
+account, or the timeout period defined in the user's Authentication
+Database entry passes.
+
+The F<kaserverauxdb> file is in binary format, so its contents are not
+directly accessible. However, the output from the B<kas examine> command
+reports an account's maximum number of failed attempts, the lockout time,
+and whether the account is currently locked.
 
 =head1 SEE ALSO
 
-L<kaserver.DB0 and kaserver.DBSYS1(1)>
-
-L<kas_examine(1)>,
-L<kas_unlock(1)>,
-L<kaserver(1)>
+L<kaserver.DB0(5)>,
+L<kas_examine(8)>,
+L<kas_unlock(8)>,
+L<kaserver(8)>
 
 =head1 COPYRIGHT
 
index 6833d4d..62f9766 100644 (file)
@@ -1,99 +1,82 @@
 =head1 NAME
 
-package Configuration File - Provides instructions for the package command
+package - Provides instructions for the package command
 
 =head1 DESCRIPTION
 
-The package configuration file defines the file system elements
-that the B<package> command creates or alters on the local disk of an
-AFS client machine it is configuring. Use the B<-config> or
-B<-fullconfig> argument to the B<package> command to identify
-the configuration file to use.
+The package configuration file defines the file system elements that the
+B<package> command creates or alters on the local disk of an AFS client
+machine it is configuring. Use the B<-config> or B<-fullconfig> argument
+to the B<package> command to identify the configuration file to use.
 
-Summary of Configuration File Instructions
+=head2 Summary of Configuration File Instructions
 
 The configuration file can include one or more instances of each of the
-following instructions, each on its own line. A more detailed
-description of each instruction's syntax follows this list.
+following instructions, each on its own line. A more detailed description
+of each instruction's syntax follows this list.
 
 =over 4
 
 =item B
 
 Defines a block special device, such as a disk, which deals with input in
-units of multi-byte command blocks
+units of multi-byte command blocks.
 
 =item C
 
 Defines a character special device, such as a terminal or tty, which deals
-with input in single character units
+with input in single character units.
 
 =item D
 
-Creates a directory
+Creates a directory.
 
 =item F
 
-Creates or alters a file to match the contents of a specified source file
+Creates or alters a file to match the contents of a specified source file.
 
 =item L
 
-Creates a symbolic link
+Creates a symbolic link.
 
 =item S
 
 Defines a socket, which is a communications device for UDP and TCP/IP
-connections
+connections.
 
 =item %define
 
-Defines a variable or declares a string as defined
+Defines a variable or declares a string as defined.
 
 =item %ifdef
 
-Specifies an action to perform if a certain string is declared or defined
+Specifies an action to perform if a certain string is declared or defined.
 
 =item %ifndef
 
 Specifies an action to perform if a certain string is not declared or
-defined
+defined.
 
 =item %include
 
-Includes a library file
+Includes a library file.
 
 =item %undef
 
 Declares a string not to be defined, or a variable no longer to have a
-value
+value.
 
 =back
 
-The B and C Instructions for Defining Block and Character Special
-Devices
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-
-The B<B> instruction in a package configuration file
-defines a block special device, such as a disk, that deals with input in units
-of multi-byte command blocks. The B<C> instruction defines a
-character special device, such as a terminal or tty, that deals with input in
-single character units. They share a common syntax:
-
-   {B<B >| C}   I<device_name>  I<major_device>  I<minor_device>  I<owner>  I<group>  I<mode_bits>
+=head2 The B and C Instructions for Defining Special Devices
+
+The C<B> instruction in a package configuration file defines a block
+special device, such as a disk, that deals with input in units of
+multi-byte command blocks. The C<C> instruction defines a character
+special device, such as a terminal or tty, that deals with input in single
+character units. They share a common syntax:
+
+   (B | C) <device> <major> <minor> <owner> <group> <mode>
 
 where
 
@@ -101,79 +84,64 @@ where
 
 =item B
 
-Indicates the definition of a block special device. It must be a
-capital letter.
+Indicates the definition of a block special device. It must be a capital
+letter.
 
 =item C
 
-Indicates the definition of character special device. It must be a
-capital letter.
+Indicates the definition of character special device. It must be a capital
+letter.
 
-=item I<device_name
->
+=item <device>
 
-Names the special device to define. To learn the name format
-appropriate to the machine's system type, consult the hardware or
-operating system documentation.
+Names the special device to define. To learn the name format appropriate
+to the machine's system type, consult the hardware or operating system
+documentation.
 
-=item I<major_device
->
+=item <major>
 
-Specifies the device's major device number in decimal format.
-To learn the correct value for the machine's system type, consult the
-hardware or operating system documentation.
+Specifies the device's major device number in decimal format.  To learn
+the correct value for the machine's system type, consult the hardware or
+operating system documentation.
 
-=item I<minor_device
->
+=item <minor>
 
-Specifies the device's minor device number in one of hexadecimal,
-octal, or decimal format. Precede a hexadecimal number with the string
-B<0x> (zero and the letter B<x>) or an octal number with a
-B<0> (zero). A number without either prefix is interpreted as a
-decimal. To learn the correct value for the machine's system type,
-consult the hardware or operating system documentation.
+Specifies the device's minor device number in one of hexadecimal, octal,
+or decimal format. Precede a hexadecimal number with the string C<0x>
+(zero and the letter C<x>) or an octal number with a C<0> (zero). A number
+without either prefix is interpreted as a decimal. To learn the correct
+value for the machine's system type, consult the hardware or operating
+system documentation.
 
-=item I<owner
->
+=item <owner>
 
 Specifies the username or UNIX user ID (UID) of the user to be designated
-the device's owner in the output from the UNIX B<ls -l>
-command.
+the device's owner in the output from the UNIX C<ls -l> command.
 
-=item I<group
->
+=item <group>
 
 Specifies the group name or UNIX group ID (GID) of the group to be
-designated the device's group in the output from the UNIX B<ls
--lg> command.
+designated the device's group in the output from the UNIX C<ls -lg>
+command.
 
-=item I<mode_bits
->
+=item <mode>
 
-Defines the device's UNIX mode bits. Acceptable values are the
-standard three- or four-digit numbers corresponding to combinations of
-permissions. Examples: B<755> corresponds to
-B<rwxr-xr-x>, and B<644> to B<rw-r--r-->.
+Defines the device's UNIX mode bits. Acceptable values are the standard
+three- or four-digit numbers corresponding to combinations of
+permissions. Examples: C<755> corresponds to C<rwxr-xr-x>, and C<644> to
+C<rw-r--r-->.
 
 =back
 
-The D Instruction for Creating a Directory
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
+=head2 The D Instruction for Creating a Directory
 
-The B<D> instruction in a package configuration file
-creates a directory on the local disk. If a symbolic link, file, or
-other element on the local disk has the same name, it is replaced with a
-directory. If the directory already exists, its owner, group, and mode
-bits are changed if necessary to conform with the instruction. The
-instruction has the following syntax:
+The C<D> instruction in a package configuration file creates a directory
+on the local disk. If a symbolic link, file, or other element on the local
+disk has the same name, it is replaced with a directory. If the directory
+already exists, its owner, group, and mode bits are changed if necessary
+to conform with the instruction. The instruction has the following syntax:
 
-   D[I<update_code>]  I<directory>  I<owner>  I<group>  I<mode_bits>
+   D[I<update_code>] <directory> <owner> <group> <mode>
 
 where
 
@@ -181,22 +149,20 @@ where
 
 =item D
 
-Indicates the creation of a directory. It must be a capital
-letter.
+Indicates the creation of a directory. It must be a capital letter.
 
-=item I<update_code
->
+=item <update_code>
 
-Modulates the directory creation instruction. It is optional and
-follows the letter B<D> directly, without an intervening space.
-Choose one of the two acceptable values: 
+Modulates the directory creation instruction. It is optional and follows
+the letter C<D> directly, without an intervening space.  Choose one of the
+two acceptable values:
 
 =over 4
 
 =item X
 
-Indicates that the directory is a lost+found directory (used by
-the B<fsck> program).
+Indicates that the directory is a lost+found directory (used by the
+B<fsck> program).
 
 =item R
 
@@ -206,57 +172,43 @@ appear in the configuration file.
 
 =back
 
-=item I<directory
->
+=item <directory>
 
 Specifies the full pathname of the directory to create.
 
-=item I<owner
->
+=item <owner>
 
 Specifies the username or UNIX user ID (UID) of the user to be designated
-the directory's owner in the output from the UNIX B<ls -ld>
-command.
+the directory's owner in the output from the UNIX C<ls -ld> command.
 
-=item I<group
->
+=item <group>
 
 Specifies the name or UNIX group ID (GID) of the group to be designated
-the directory's group in the output from the UNIX B<ls -lgd>
-command.
+the directory's group in the output from the UNIX C<ls -lgd> command.
 
-=item I<mode_bits
->
+=item <mode>
 
-Defines the directory's UNIX mode bits. Acceptable values are
-the standard three- or four-digit numbers corresponding to combinations of
-permissions. Examples: B<755> corresponds to
-B<drwxr-xr-x>, and B<644> to B<drw-r--r-->.
+Defines the directory's UNIX mode bits. Acceptable values are the standard
+three- or four-digit numbers corresponding to combinations of
+permissions. Examples: C<755> corresponds to C<drwxr-xr-x>, and C<644> to
+C<drw-r--r-->.
 
 =back
 
-The F Instruction for Creating or Updating a File
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-
-The B<F> instruction in a package configuration file
-creates or updates a file on the local disk by copying in the contents of the
-indicated source file, which can reside in AFS or on the local disk. If
-the B<package> command interpreter cannot access the source file, it
-exits without executing any instruction in the configuration file.
-
-If a file with the same name already exists on disk, the package
-command overwrites it with the contents of the source file, unless the
-B<I> update code is used to prevent that. To add a
-B<.old> extension to the current version of the file, include
-the B<O> update code. To have the machine reboot automatically
-after the B<package> program completes, include the B<Q>
-update code.
+=head2 The F Instruction for Creating or Updating a File
+
+The C<F> instruction in a package configuration file creates or updates a
+file on the local disk by copying in the contents of the indicated source
+file, which can reside in AFS or on the local disk. If the B<package>
+command interpreter cannot access the source file, it exits without
+executing any instruction in the configuration file.
+
+If a file with the same name already exists on disk, the package command
+overwrites it with the contents of the source file, unless the C<I> update
+code is used to prevent that. To add a C<.old> extension to the current
+version of the file, include the C<O> update code. To have the machine
+reboot automatically after the B<package> program completes, include the
+C<Q> update code.
 
 If a symbolic link, directory, or other element on the local disk has the
 same name, it is replaced with the file (a directory's contents are first
@@ -264,7 +216,7 @@ removed as necessary).
 
 The instruction has the following syntax:
 
-   F[I<update_code>]  I<file>  I<source_file>  [I<owner  group  mode_bits>]
+   F[<update_code>] <file> <source> [<owner> <group> <mode>]
 
 where
 
@@ -272,126 +224,102 @@ where
 
 =item F
 
-Indicates the creation or update of a file. It must be a capital
-letter.
+Indicates the creation or update of a file. It must be a capital letter.
 
-=item I<update_code
->
+=item <update_code>
 
-Modulates the file creation instruction. It is optional and follows
-the letter B<F> directly, without an intervening space. Choose
-one or more of the four acceptable values, and list them in any order: 
+Modulates the file creation instruction. It is optional and follows the
+letter C<F> directly, without an intervening space. Choose one or more of
+the four acceptable values, and list them in any order:
 
 =over 4
 
 =item A
 
-Indicates that the pathname in the I<source_file> field is the
-complete pathname of the source file, including the filename. If this
-argument is omitted, the B<package> command appends the pathname in
-the I< file> field to the pathname in the I<source_file> field to
-derive the source file's full name. This code allows the source
-and target filenames to differ.
+Indicates that the pathname in the <source> field is the complete pathname
+of the source file, including the filename. If this argument is omitted,
+the B<package> command appends the pathname in the <file> field to the
+pathname in the <source> field to derive the source file's full name. This
+code allows the source and target filenames to differ.
 
 =item I
 
-Preserves the existing file called I<file>, rather than overwriting
-it.
+Preserves the existing file called <file>, rather than overwriting it.
 
 =item O
 
-Saves the existing version of the file by appending a
-B<.old> extension to it.
+Saves the existing version of the file by appending a C<.old> extension to
+it.
 
 =item Q
 
-Causes the package command to exit with status code
-B<4> if it overwrites the file. If the standard
-B<package>-related changes have been made to the machine's AFS
-initialization file, then status code B<4> causes the machine to
-reboot automatically. Use this code when the machine must reboot if
-updates to the file are to have any effect (for example, if the operating
-system file--B</vmunix> or equivalent--has changed).
+Causes the package command to exit with status code C<4> if it overwrites
+the file. If the standard B<package>-related changes have been made to the
+machine's AFS initialization file, then status code C<4> causes the
+machine to reboot automatically. Use this code when the machine must
+reboot if updates to the file are to have any effect (for example, if the
+operating system file -- F</vmunix> or equivalent -- has changed).
 
 =back
 
-=item I<file
->
+=item <file>
 
 Specifies the complete pathname on the local disk of the file to create or
 update, including the filename as the final element.
 
-=item I<source_file
->
+=item <source>
 
 Specifies the pathname (local or AFS) of the file to copy to the local
 disk.
 
-If the A update code is included, specify the source file's
-complete pathname. Otherwise, the B<package> command derives
-the source file's full name by appending the I<file> pathname to
-this pathname. For example, if the B<A> update code is not
-included and the file B</afs/abc.com/rs_aix42/bin/grep> is the
-source file for the B</bin/grep> binary, the proper value in this
-field is B</afs/abc.com/rs_aix42>.
+If the C<A> update code is included, specify the source file's complete
+pathname. Otherwise, the B<package> command derives the source file's full
+name by appending the I<file> pathname to this pathname. For example, if
+the C<A> update code is not included and the file
+F</afs/abc.com/rs_aix42/bin/grep> is the source file for the F</bin/grep>
+binary, the proper value in this field is F</afs/abc.com/rs_aix42>.
 
-=item I<owner
->
+=item <owner>
 
 Specifies the username or UNIX user ID (UID) of the user to be designated
-the file's owner in the output from the UNIX B<ls -l>
-command. 
+the file's owner in the output from the UNIX C<ls -l> command.
 
 To copy the source file's owner to the target file, leave this field
-empty. In this case, the I<group> and I<mode_bits> fields
-must also be empty.
+empty. In this case, the <group> and <mode> fields must also be empty.
 
-=item I<group
->
+=item <group>
 
 Specifies the name or UNIX group ID (GID) of the group to be designated
-the file's group in the output from the UNIX B<ls -lg>
-command. 
+the file's group in the output from the UNIX C<ls -lg> command.
 
 To copy the source file's group to the target file, leave this field
-empty. In this case, the I< owner> and I<mode_bits> fields
-must also be empty.
+empty. In this case, the <owner> and <mode> fields must also be empty.
 
-=item I<mode_bits
->
+=item <mode>
 
-Defines the file's UNIX mode bits. Acceptable values are the
-standard three- or four-digit numbers corresponding to combinations of
-permissions. Examples: B<755> corresponds to
-B<rwxr-xr-x>, and B<644> to B<rw-r--r-->. 
+Defines the file's UNIX mode bits. Acceptable values are the standard
+three- or four-digit numbers corresponding to combinations of
+permissions. Examples: C<755> corresponds to C<rwxr-xr-x>, and C<644> to
+C<rw-r--r-->.
 
-To copy the source file's mode bits to the target file, leave this
-field empty. In this case, the I<owner> and I<group> fields
-must also be empty.
+To copy the source file's mode bits to the target file, leave this field
+empty. In this case, the <owner> and <group> fields must also be empty.
 
 =back
 
-The L Instruction for Creating a Symbolic Link
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-
-The B<L> instruction in a package configuration file
-creates a symbolic link on the local disk to a directory or file that exists
-either in AFS or elsewhere on the local disk. As with the standard UNIX
-B<ln -s> command, the link is created even if the actual file or
-directory does not exist.
+=head2 The L Instruction for Creating a Symbolic Link
+
+The C<L> instruction in a package configuration file creates a symbolic
+link on the local disk to a directory or file that exists either in AFS or
+elsewhere on the local disk. As with the standard UNIX C<ln -s> command,
+the link is created even if the actual file or directory does not exist.
 
 If a file or directory on the local disk already has the same name, the
 B<package> command replaces it with a symbolic link.
 
 The instruction has the following syntax:
 
-   L[I<update_code>]  I<link>  I<actual_path>  [I<owner  group  mode_bits>]
+   L[I<update_code>] <link> <path> [<owner> <group> <mode>]
 
 where
 
@@ -399,114 +327,92 @@ where
 
 =item L
 
-Indicates the creation of a symbolic link. It must be a capital
-letter.
+Indicates the creation of a symbolic link. It must be a capital letter.
 
-=item I<update_code
->
+=item <update_code>
 
-Modulates the link creation instruction. It is optional and follows
-the letter B<L> directly, without an intervening space. Choose
-one or both of the acceptable values, and list them in any order: 
+Modulates the link creation instruction. It is optional and follows the
+letter C<L> directly, without an intervening space. Choose one or both of
+the acceptable values, and list them in any order:
 
 =over 4
 
 =item A
 
-Indicates that the pathname in the I<actual_path> field is the
-complete pathname of the actual directory or file (including the filename for
-a file). If this argument is omitted, the B<package> command
-appends the value in the I<link> field to the pathname in the
-I<actual_path> field to derive the actual directory or file's full
-name. This code allows the name of the symbolic link and actual
-directory or file to differ.
+Indicates that the pathname in the <path> field is the complete pathname
+of the actual directory or file (including the filename for a file). If
+this argument is omitted, the B<package> command appends the value in the
+<link> field to the pathname in the <path> field to derive the actual
+directory or file's full name. This code allows the name of the symbolic
+link and actual directory or file to differ.
 
 =item I
 
-Preserves the existing symbolic link called I<link>, rather than
+Preserves the existing symbolic link called <link>, rather than
 overwriting it.
 
 =back
 
-=item I<link
->
+=item <link>
 
-Specifies the complete local disk pathname of the symbolic link to
-create.
+Specifies the complete local disk pathname of the symbolic link to create.
 
-=item I<actual_path
->
+=item <path>
 
 Specifies the pathname (local or AFS) of the directory or file to which
-the link refers. If the B<A> update code is included, specify
-the directory or file's complete pathname. Otherwise, the
-B<package> command derives the actual directory or file's full
-name by appending the value in the I<link> field to this
-pathname. For example, if the B<A> update code is not included
-and B</etc/ftpd> is a symbolic link to the file
-B</afs/abc.com/sun4x_56/etc/ftpd>, the proper value in this
-field is B</afs/abc.com/sun4x_56>.
-
-The package command interpreter correctly handles pathnames that
-begin with the B<./> (period, slash) or
-B<../> (two periods, slash) notation, interpreting them
-relative to the current working directory from which the B<package>
-command is invoked.
-
-=item I<owner
->
+the link refers. If the C<A> update code is included, specify the
+directory or file's complete pathname. Otherwise, the B<package> command
+derives the actual directory or file's full name by appending the value in
+the I<link> field to this pathname. For example, if the C<A> update code
+is not included and F</etc/ftpd> is a symbolic link to the file
+F</afs/abc.com/sun4x_56/etc/ftpd>, the proper value in this field is
+F</afs/abc.com/sun4x_56>.
+
+The package command interpreter correctly handles pathnames that begin
+with the C<./> (period, slash) or C<../> (two periods, slash) notation,
+interpreting them relative to the current working directory from which the
+B<package> command is invoked.
+
+=item <owner>
 
 Specifies the username or UNIX user ID (UID) of the user to be designated
-the symbolic link's owner in the output from the UNIX B<ls -l>
-command.
+the symbolic link's owner in the output from the UNIX C<ls -l> command.
 
-To designate the issuer of the package command (usually, the
-local superuser B<root>) as the symbolic link's owner, leave this
-field empty. In this case, the I<group> and I<mode_bits>
-fields must also be empty.
+To designate the issuer of the package command (usually, the local
+superuser C<root>) as the symbolic link's owner, leave this field
+empty. In this case, the <group> and <mode> fields must also be empty.
 
-=item I<group
->
+=item <group>
 
 Specifies the name or UNIX group ID (GID) of the group to be designated
-the link's group in the output from the UNIX B<ls -lg>
-command.
+the link's group in the output from the UNIX C<ls -lg> command.
 
-To have the symbolic link's group match the default group associated
-with the B<package> command's issuer, leave this field
-empty. The issuer is usually the local superuser B<root> and
-the default group is designated in the issuer's entry in the local
-B</etc/passwd> file or equivalent. If this field is left empty,
-the I<owner> and I<mode_bits> fields must also be empty.
+To have the symbolic link's group match the default group associated with
+the B<package> command's issuer, leave this field empty. The issuer is
+usually the local superuser C<root> and the default group is designated in
+the issuer's entry in the local F</etc/passwd> file or equivalent. If this
+field is left empty, the <owner> and <mode> fields must also be empty.
 
-=item I<mode_bits
->
+=item <mode>
 
-Defines the symbolic link's UNIX mode bits. Acceptable values
-are the standard three- or four-digit numbers corresponding to combinations of
-permissions. Examples: B<755> corresponds to
-B<rwxr-xr-x>, and B<644> to B<rw-r--r-->.
+Defines the symbolic link's UNIX mode bits. Acceptable values are the
+standard three- or four-digit numbers corresponding to combinations of
+permissions. Examples: C<755> corresponds to C<rwxr-xr-x>, and C<644> to
+C<rw-r--r-->.
 
-Leaving this field empty sets the symbolic link's mode bits to
-B<777> (B<rwxrwxrwx>). In this case, the I<owner>
-and I<group> fields must also be empty.
+Leaving this field empty sets the symbolic link's mode bits to C<777>
+(C<rwxrwxrwx>). In this case, the <owner> and <group> fields must also be
+empty.
 
 =back
 
-The S Instruction for Creating a Socket
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
+=head2 The S Instruction for Creating a Socket
 
-The B<S> instruction in a package configuration file
-creates a socket (a communications device for UDP or TCP/IP connections) on
-the local disk. The instruction has the following syntax:
+The C<S> instruction in a package configuration file creates a socket (a
+communications device for UDP or TCP/IP connections) on the local
+disk. The instruction has the following syntax:
 
-   S  I<socket> [I<owner  group  mode_bits>]
+   S <socket> [<owner> <group> <mode>]
 
 where
 
@@ -514,101 +420,80 @@ where
 
 =item S
 
-Indicates the creation of a socket. It must be a capital
-letter.
+Indicates the creation of a socket. It must be a capital letter.
 
-=item I<socket
->
+=item <socket>
 
-Names the socket. The proper format depends on the local
-machine's operating system.
+Names the socket. The proper format depends on the local machine's
+operating system.
 
-=item I<owner
->
+=item <owner>
 
 Specifies the username or UNIX user ID (UID) of the user to be designated
-the socket's owner in the output from the UNIX B<ls -l>
-command.
+the socket's owner in the output from the UNIX C<ls -l> command.
 
-To designate the issuer of the package command (usually, the
-local superuser B<root>) as the socket's owner, leave this field
-empty. In this case, the I<group> and I<mode_bits> fields
-must also be empty.
+To designate the issuer of the package command (usually, the local
+superuser C<root>) as the socket's owner, leave this field empty. In this
+case, the <group> and <mode> fields must also be empty.
 
-=item I<group
->
+=item <group>
 
 Specifies the name or UNIX group ID (GID) of the group to be designated
-the socket's group in the output from the UNIX B<ls -lg>
-command.
+the socket's group in the output from the UNIX C<ls -lg> command.
 
-To have the symbolic link's group match the default group associated
-with the B<package> command's issuer, leave this field
-empty. The issuer is usually the local superuser B<root> and
-the default group is designated in the issuer's entry in the local
-B</etc/passwd> file or equivalent. If this field is left empty,
-the I<owner> and I<mode_bits> fields must also be empty.
+To have the symbolic link's group match the default group associated with
+the B<package> command's issuer, leave this field empty. The issuer is
+usually the local superuser C<root> and the default group is designated in
+the issuer's entry in the local F</etc/passwd> file or equivalent. If this
+field is left empty, the <owner> and <mode> fields must also be empty.
 
-=item I<mode_bits
->
+=item <mode>
 
-Defines the socket's UNIX mode bits. Acceptable values are the
-standard three- or four-digit numbers corresponding to combinations of
-permissions. Examples: B<755> corresponds to
-B<rwxr-xr-x>, and B<644> to B<rw-r--r-->.
+Defines the socket's UNIX mode bits. Acceptable values are the standard
+three- or four-digit numbers corresponding to combinations of
+permissions. Examples: C<755> corresponds to C<rwxr-xr-x>, and C<644> to
+C<rw-r--r-->.
 
-Leaving this field empty sets the symbolic link's mode bits to
-B<777> (B<rwxrwxrwx>), modulated by the cell's
-umask. In this case, the I<owner> and I<group> fields must
-also be empty.
+Leaving this field empty sets the symbolic link's mode bits to C<777>
+(C<rwxrwxrwx>), modulated by the cell's umask. In this case, the <owner>
+and <group> fields must also be empty.
 
 =back
 
-The %define or %undef Instructions Declaring or Undeclaring a
-Definition
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
+=head2 The %define or %undef Instructions
 
-The B<%define> instruction in a package configuration
-file declares or defines a variable, depending on its number of
-arguments:
+The C<%define> instruction in a package configuration file declares or
+defines a variable, depending on its number of arguments:
 
 =over 4
 
 =item *
 
 If followed by a single argument, it declares that argument to be
-defined. The argument is then available as a controller when mentioned
-in B<%ifdef> and B<%ifndef> statements, which evaluate to
-B<true> and B<false> respectively.
-
+defined. The argument is then available as a controller when mentioned in
+C<%ifdef> and C<%ifndef> statements, which evaluate to C<true> and
+C<false> respectively.
 
 =item *
 
 If followed by two arguments, it defines the second argument as the value
-of the first. When the first argument appears later in this prototype
-or other prototype or library files as a variable--surrounded by curly
-braces and preceded by a dollar sign, as in the example
-C<${variable}>--the B<package> command interpreter
-substitutes the second argument for it.
-
+of the first. When the first argument appears later in this prototype or
+other prototype or library files as a variable -- surrounded by curly
+braces and preceded by a dollar sign, as in the example C<${variable}> --
+the B<package> command interpreter substitutes the second argument for it.
 
 =back
 
-The %undef statement negates the effect of a previous
-B<%define> statement, declaring its argument to be defined no longer,
-or to have a value no longer if it is a variable.
+The C<%undef> statement negates the effect of a previous C<%define>
+statement, declaring its argument to be defined no longer, or to have a
+value no longer if it is a variable.
 
 The syntax for the two types of instruction are as follows:
 
-   %define  I<declaration>
-   %define  I<variable>  I<value>
-   %undef  I<declaration>
-   %undef  I<variable>
+   %define <declaration>
+   %define <variable> <value>
+   %undef  <declaration>
+   %undef  <variable>
 
 where
 
@@ -622,129 +507,106 @@ Indicates a definition statement.
 
 Indicates a statement that negates a definition.
 
-=item I<declaration
->
+=item <declaration>
 
-Names the string being declared by a %define statement, or
-negated by an B<%undef> statement.
+Names the string being declared by a C<%define> statement, or
+negated by an C<%undef> statement.
 
-=item I<variable
->
+=item <variable>
 
-Specifies the name of the variable that a %define statement is
-defining, or an B<%undef> statement is negating.
+Specifies the name of the variable that a C<%define> statement is
+defining, or an C<%undef> statement is negating.
 
-=item I<value
->
+=item <value>
 
-Specifies the value to substitute for the string in the I<variable>
-field when it appears in the appropriate format (surrounded by curly braces
-and preceded by a dollar sign, as in the example C<${variable}>), in
-this or other prototype and library files. It can include one or more
-words.
+Specifies the value to substitute for the string in the <variable> field
+when it appears in the appropriate format (surrounded by curly braces and
+preceded by a dollar sign, as in the example C<${variable}>), in this or
+other prototype and library files. It can include one or more words.
 
 =back
 
-The %ifdef and %ifndef Instructions for Specifying a Conditional
-Action to Perform
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-
-The B<%ifdef> instruction in a package configuration
-file specifies one or more actions to perform if the indicated string has been
-declared by a single-argument B<%define> statement, or is a variable
-for which a value has been defined by a two-argument B<%define>
-statement.
-
-Similarly, the %ifndef instruction specifies one or more actions
-to perform if the indicated string has not been declared or is a variable
-without a value, either because no B<%define> statement has defined it
-or an B<%undef> statement has undefined it.
-
-In both cases, the optional %else statement specifies one or
-more alternate actions to perform if the first statement evaluates to
-B<false>. (For an B<%ifdef> statement, the
-B<%else> statement is executed if the indicated string has never been
-declared or is a variable without a value, or if an B<%undef>
-statement has undefined either one; for an B<%ifndef> statement,
-it is executed if the string has been declared or is a variable with a
-value.)
-
-It is possible to nest any number of %ifdef and
-B<%ifndef> statements.
+=head2 The %ifdef and %ifndef Instructions
+
+The C<%ifdef> instruction in a package configuration file specifies one or
+more actions to perform if the indicated string has been declared by a
+single-argument C<%define> statement, or is a variable for which a value
+has been defined by a two-argument C<%define> statement.
+
+Similarly, the C<%ifndef> instruction specifies one or more actions to
+perform if the indicated string has not been declared or is a variable
+without a value, either because no C<%define> statement has defined it or
+an C<%undef> statement has undefined it.
+
+In both cases, the optional C<%else> statement specifies one or more
+alternate actions to perform if the first statement evaluates to
+C<false>. (For an C<%ifdef> statement, the C<%else> statement is executed
+if the indicated string has never been declared or is a variable without a
+value, or if an C<%undef> statement has undefined either one; for an
+C<%ifndef> statement, it is executed if the string has been declared or is
+a variable with a value.)
+
+It is possible to nest any number of C<%ifdef> and C<%ifndef> statements.
 
 The two types of statement share a common syntax:
 
-   %ifdef | ifndef   I<declaration> 
-                                  I<action>+
-   [%else [I<declaration>] 
-                  I<alternate_action>+]
-   %endif I<declaration>
+   (%ifdef | %ifndef) <declaration> 
+       <action>+
+   [%else [<declaration>] 
+       <alternate_action>+]
+   %endif <declaration>
 
 where
 
 =over 4
 
-=item ifdef
+=item %ifdef
 
-Indicates that the statement evaluates as true if the string in
-the I<declaration> field is declared or is a variable with a defined
-value.
+Indicates that the statement evaluates as true if the string in the
+<declaration> field is declared or is a variable with a defined value.
 
-=item ifndef
+=item %ifndef
 
-Indicates that the statement evaluates as true if the string in
-the I<declaration> field is not declared or is a variable without a
-defined value.
+Indicates that the statement evaluates as true if the string in the
+<declaration> field is not declared or is a variable without a defined
+value.
 
-=item I<declaration
->
+=item <declaration>
 
 Specifies the string that must be declared or the variable name that must
-have a defined value for an B<%ifdef> statement to evaluate as
-B<true>, which results in the specified action being performed.
-For an B<%ifndef> statement, the string must not be declared or the
-variable must have no defined value for the statement to evaluate as
-B<true>. The first and third occurrences of
-I<declaration> (the latter following the string B<%endif>) are
-required. The second occurrence (following the string B<%else>)
-is optional, serving only to clarify to which B<%ifdef> or
-B<%ifndef> statement the B<%else> statement belongs.
-
-=item I<action
->
-
-Specifies each action to perform if the %ifdef or
-B<%ifndef> statement evaluates as B<true>. Each action
-must appear on a separate line. Acceptable types of actions are other
-statements beginning with a percent sign and definition instructions.
-
-=item I<alternate_action
->
-
-Specifies each action to perform if the %ifdef or
-B<%ifndef> statement evaluates to B<false>. Each action
-must appear on a separate line. Acceptable types of actions are other
-statements beginning with a percent sign and definition instructions.
+have a defined value for an C<%ifdef> statement to evaluate as C<true>,
+which results in the specified action being performed.  For an C<%ifndef>
+statement, the string must not be declared or the variable must have no
+defined value for the statement to evaluate as C<true>. The first and
+third occurrences of <declaration> (the latter following the string
+C<%endif>) are required. The second occurrence (following the string
+C<%else>) is optional, serving only to clarify to which C<%ifdef> or
+C<%ifndef> statement the C<%else> statement belongs.
+
+=item <action>
+
+Specifies each action to perform if the C<%ifdef> or C<%ifndef> statement
+evaluates as C<true>. Each action must appear on a separate
+line. Acceptable types of actions are other statements beginning with a
+percent sign and definition instructions.
+
+=item <alternate_action>
+
+Specifies each action to perform if the C<%ifdef> or C<%ifndef> statement
+evaluates to C<false>. Each action must appear on a separate
+line. Acceptable types of actions are other statements beginning with a
+percent sign and definition instructions.
 
 =back
 
-The %include Instruction for Including a Library File
-L<(1)>
-L<(1)>
-L<(1)>
+=head2 The %include Instruction for Including a Library File
 
-The B<%include> instruction in a package configuration
-file includes the contents of the indicated library file in a configuration
-file that results from the compilation of the prototype file in which the
-B<%include> instruction appears. It has the following
-syntax:
+The C<%include> instruction in a package configuration file includes the
+contents of the indicated library file in a configuration file that
+results from the compilation of the prototype file in which the
+C<%include> instruction appears. It has the following syntax:
 
-   %include  I<pathname>
+   %include <pathname>
 
 where
 
@@ -754,94 +616,83 @@ where
 
 Indicates a library file include statement.
 
-=item I<pathname
->
+=item <pathname>
 
-Specifies the complete pathname of the library file to include. It
-can be in AFS or on the local disk, and can include one or more
-variables.
+Specifies the complete pathname of the library file to include. It can be
+in AFS or on the local disk, and can include one or more variables.
 
 =back
 
 =head1 CAUTIONS
 
-The configuration file must be completely correct. If there are any
-syntax errors or incorrect values, the B<package> command interpreter
-exits without executing any instruction.
+The configuration file must be completely correct. If there are any syntax
+errors or incorrect values, the B<package> command interpreter exits
+without executing any instruction.
 
 =head1 EXAMPLES
 
-The following example B<B> and C instructions define a
-disk B</dev/hd0a> with major and minor device numbers B<1> and
-B<0> and mode bits of B<-rw-r--r-->, and a tty
-B</dev/ttyp5> with major and minor device numbers B<6> and
-B<5> and mode bits of B<-rw-rw-rw>. In both cases, the
-owner is B<root> and the owning group B<wheel>.
+The following example C<B> and C<C> instructions define a disk
+F</dev/hd0a> with major and minor device numbers C<1> and C<0> and mode
+bits of C<-rw-r--r-->, and a tty F</dev/ttyp5> with major and minor device
+numbers C<6> and C<5> and mode bits of C<-rw-rw-rw>. In both cases, the
+owner is C<root> and the owning group C<wheel>.
 
    B /dev/hd0a 1 0 root wheel 644
    C /dev/ttyp5 6 5 root wheel 666
 
-The following example D instruction creates the local
-B</usr> directory with owner B<root> and group
-B<wheel> and mode bits of B<drwxr-xr-x>. The
-B<R> update code removes any files and subdirectories that reside in
-the B</usr> directory (if it already exists) but do not appear in the
+The following example C<D> instruction creates the local F</usr> directory
+with owner C<root> and group C<wheel> and mode bits of C<drwxr-xr-x>. The
+C<R> update code removes any files and subdirectories that reside in the
+F</usr> directory (if it already exists) but do not appear in the
 configuration file.
 
    DR /usr root wheel 755
 
-The following example F instruction, appropriate for a machine
-running AIX 4.2 in the ABC Corporation cell, creates or updates the
-local disk file B</bin/grep>, using
-B</afs/abc.com/rs_aix42/bin/grep> as the source.
+The following example C<F> instruction, appropriate for a machine running
+AIX 4.2 in the ABC Corporation cell, creates or updates the local disk
+file F</bin/grep>, using F</afs/abc.com/rs_aix42/bin/grep> as the source.
 
    F /bin/grep /afs/abc.com/rs_aix42 root wheel 755
 
-The next example F instruction creates the
-B</usr/vice/etc/ThisCell> file and specifies an absolute pathname for
-the source file, as indicated by the B<A> update code. The
-B<Q> code makes the B<package> command return status code 4 as
-it exits, prompting a reboot of the machine if the standard
-B<package>-related changes have been made to the machine's AFS
-initialization file. No values are provided for the owner, group and
-mode bits, so the file inherits them from the source file.
+The next example C<F> instruction creates the F</usr/vice/etc/ThisCell>
+file and specifies an absolute pathname for the source file, as indicated
+by the C<A> update code. The C<Q> code makes the B<package> command return
+status code 4 as it exits, prompting a reboot of the machine if the
+standard B<package>-related changes have been made to the machine's AFS
+initialization file. No values are provided for the owner, group and mode
+bits, so the file inherits them from the source file.
 
    FAQ /usr/vice/etc/ThisCell /afs/abc.com/common/etc/ThisCell
 
-The following example L instruction, appropriate for a machine
-running AIX 4.2 in the ABC Corporation cell, creates a symbolic link
-from B</etc/ftpd> on the local disk to the file
-B</afs/abc.com/rs_aix42/etc/ftpd>.
+The following example C<L> instruction, appropriate for a machine running
+AIX 4.2 in the ABC Corporation cell, creates a symbolic link from
+F</etc/ftpd> on the local disk to the file
+F</afs/abc.com/rs_aix42/etc/ftpd>.
 
    L /etc/ftpd /afs/abc.com/rs_aix42 root wheel 644
 
-The following example S instruction defines the socket
-B</dev/printer>.
-
+The following example S instruction defines the socket F</dev/printer>.
 
    S /dev/printer root wheel 777
-   
 
-The following example %define instruction defines the value for
-the variable C<${diskmode}>. This variable is used elsewhere in
-the template to fill the I<owner_name>, I<group_name>, and
-I<mode_bits> fields in a B<D>, B<F>, or B<L>
+The following example C<%define> instruction defines the value for the
+variable C<${diskmode}>. This variable is used elsewhere in the template
+to fill the <owner>, <group>, and <mode> fields in a C<D>, C<F>, or C<L>
 instruction.
 
    %define diskmode root wheel 644
 
-The following example %undef instruction declares the string
-B<afsd> not to be defined.
+The following example C<%undef> instruction declares the string B<afsd>
+not to be defined.
 
    %undef afsd
 
-The following example %ifdef instruction specifies that if the
-string C<rs_aix42> is currently declared, then when the prototype file
-containing the instruction is compiled the three indicated library files are
-included. There is no alternate action defined. There must be
-B<%define> statements earlier in the prototype file to declare
-B<rs_aix42> and to assign a value to the C<${wsadmin}>
-variable.
+The following example C<%ifdef> instruction specifies that if the string
+C<rs_aix42> is currently declared, then when the prototype file containing
+the instruction is compiled the three indicated library files are
+included. There is no alternate action defined. There must be C<%define>
+statements earlier in the prototype file to declare C<rs_aix42> and to
+assign a value to the C<${wsadmin}> variable.
 
    %ifdef rs_aix42
    %include ${wsadmin}/lib/rs_aix42.readonly
@@ -849,25 +700,24 @@ variable.
    %include ${wsadmin}/lib/rs_aix42.generic.dev
    %endif rs_aix42
 
-The following example %ifndef instruction, appropriate for the
-State University cell, defines C<stateu.edu> as the value of
-the C<${cell}> variable if it does not already have a value.
+The following example C<%ifndef> instruction, appropriate for the State
+University cell, defines C<stateu.edu> as the value of the C<${cell}>
+variable if it does not already have a value.
 
    %ifndef cell
    %define cell stateu.edu
    %endif cell
 
-The following example %include instruction includes the library
-file B<base.generic> from the B<lib> subdirectory of
-the directory in which B<package>-related files reside. The
-C<${wsadmin}> variable resolves to an actual pathname (such as
-B</afs/abc.com/wsadmin>) during compilation.
+The following example C<%include> instruction includes the library file
+C<base.generic> from the F<lib> subdirectory of the directory in which
+B<package>-related files reside. The C<${wsadmin}> variable resolves to an
+actual pathname (such as F</afs/abc.com/wsadmin>) during compilation.
 
    %include ${wsadmin}/lib/base.generic
 
 =head1 SEE ALSO
 
-L<package(1)>
+L<package(8)>
 
 =head1 COPYRIGHT
 
index d0b2bcf..da01cc8 100644 (file)
@@ -1,39 +1,37 @@
 =head1 NAME
 
-prdb.DB0 and prdb.DBSYS1 - Contain the Protection Database and associated log
+prdb.DB0, prdb.DBSYS1 - Contain the Protection Database and associated log
 
 =head1 DESCRIPTION
 
-The prdb.DB0 file contains the Protection Database, which
-maps AFS user, machine, and group names to their respective IDs (AFS UIDs and
-GIDs) and tracks group memberships. The Protection Server
-(B<ptserver> process) uses the information in the database to help the
-File Server grant data access to authorized users.
-
-The prdb.DBSYS1 file is a log file in which the
-Protection Server logs each database operation before performing it.
-When an operation is interrupted, the Protection Server replays the log to
-complete the operation.
-
-Both files are in binary format and reside in the /usr/afs/db
-directory on each of the cell's database server machines. When the
-Protection Server starts or restarts on a given machine, it establishes a
-connection with its peers and verifies that its copy of the database matches
-the copy on the other database server machines. If not, the Protection
-Servers call on AFS's distributed database technology, Ubik, to
-distribute to all of the machines the copy of the database with the highest
-version number.
-
-Always use the commands in the pts suite to administer the
-Protection Database. It is advisable to create an archive copy of the
-database on a regular basis, using a tool such as the UNIX B<tar>
-command.
+The F<prdb.DB0> file contains the Protection Database, which maps AFS
+user, machine, and group names to their respective IDs (AFS UIDs and GIDs)
+and tracks group memberships. The Protection Server (B<ptserver> process)
+uses the information in the database to help the File Server grant data
+access to authorized users.
+
+The F<prdb.DBSYS1> file is a log file in which the Protection Server logs
+each database operation before performing it.  When an operation is
+interrupted, the Protection Server replays the log to complete the
+operation.
+
+Both files are in binary format and reside in the F</usr/afs/db> directory
+on each of the cell's database server machines. When the Protection Server
+starts or restarts on a given machine, it establishes a connection with
+its peers and verifies that its copy of the database matches the copy on
+the other database server machines. If not, the Protection Servers call on
+AFS's distributed database technology, Ubik, to distribute to all of the
+machines the copy of the database with the highest version number.
+
+Always use the commands in the B<pts> suite to administer the Protection
+Database. It is advisable to create an archive copy of the database on a
+regular basis, using a tool such as the UNIX B<tar> command.
 
 =head1 SEE ALSO
 
-L<prdb_check(1)>,
-L<pts(1)>,
-L<ptserver(1)>
+L<prdb_check(8)>,
+L<pts(8)>,
+L<ptserver(8)>
 
 =head1 COPYRIGHT
 
index 83e88f7..f8d4268 100644 (file)
@@ -4,18 +4,17 @@ salvage.lock - Prevents multiple simultaneous salvage operations on a partition
 
 =head1 DESCRIPTION
 
-The salvage.lock file guarantees that only one Salvager
-(B<salvager> process) runs at a time on a file server machine (the
-single process can fork multiple subprocesses to salvage multiple partitions
-in parallel). As the Salvager initializes, it creates the empty
-(zero-length) file in the B</usr/afs/local> directory and invokes the
-B<flock> system call on it. It removes the file when it
-completes the salvage operation. Because the Salvager must lock the
-file to run, only one Salvager can run at a time.
+The F<salvage.lock> file guarantees that only one Salvager (B<salvager>
+process) runs at a time on a file server machine (the single process can
+fork multiple subprocesses to salvage multiple partitions in parallel). As
+the Salvager initializes, it creates the empty (zero-length) file in the
+F</usr/afs/local> directory and invokes the B<flock> system call on it. It
+removes the file when it completes the salvage operation. Because the
+Salvager must lock the file to run, only one Salvager can run at a time.
 
 =head1 SEE ALSO
 
-L<salvager(1)>
+L<salvager(8)>
 
 =head1 COPYRIGHT
 
index 7802bf4..0480276 100644 (file)
@@ -4,48 +4,43 @@ sysid - Lists file server machine interface addresses registered in VLDB
 
 =head1 DESCRIPTION
 
-The sysid file records the network interface addresses that the
-File Server (B<fileserver> process) registers in the Volume Location
-Database (VLDB) for the local file server machine.
+The F<sysid> file records the network interface addresses that the File
+Server (B<fileserver> process) registers in the Volume Location Database
+(VLDB) for the local file server machine.
 
 Each time the File Server restarts, it builds a list of interfaces on the
-local machine by reading the B</usr/afs/local/NetInfo> file, if it
+local machine by reading the F</usr/afs/local/NetInfo> file, if it
 exists. If the file does not exist, the File Server uses the list of
-network interfaces configured with the operating system. It then
-removes from the list any addresses that appear in the
-B</usr/afs/local/NetRestrict> file, if it exists. The File
-Server records the resulting list in the binary-format B<sysid> file
-and registers the interfaces in the VLDB.
+network interfaces configured with the operating system. It then removes
+from the list any addresses that appear in the
+F</usr/afs/local/NetRestrict> file, if it exists. The File Server records
+the resulting list in the binary-format F<sysid> file and registers the
+interfaces in the VLDB.
 
 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.
+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.
 
 =head1 CAUTIONS
 
-The sysid file is unique to each file server machine, and must
-not be copied from one machine to another. If it is a common practice
-in the cell to copy the contents of the B</usr/afs/local> directory
-from an existing file server machine to a newly installed one, be sure to
-remove the B<sysid> file from the new machine before starting the
-B<fs> trio of processes, which includes the B<fileserver>
-process.
+The F<sysid> file is unique to each file server machine, and must not be
+copied from one machine to another. If it is a common practice in the cell
+to copy the contents of the F</usr/afs/local> directory from an existing
+file server machine to a newly installed one, be sure to remove the
+F<sysid> file from the new machine before starting the C<fs> trio of
+processes, which includes the B<fileserver> process.
 
-Some versions of AFS limit how many of a file server machine's
-interface addresses that can be registered. Consult the I<IBM AFS
-Release Notes>.
+Some versions of AFS limit how many of a file server machine's interface
+addresses that can be registered. Consult the I<IBM AFS Release Notes>.
 
 =head1 SEE ALSO
 
-L<NetInfo (server version)(1)>
-
-L<NetRestrict (server version)(1)>
-
-L<vldb.DB0 and vldb.DBSYS1(1)>
-
-L<fileserver(1)>
+L<NetInfo(5)>,
+L<NetRestrict(5)>,
+L<vldb.DB0(5)>,
+L<fileserver(8)>
 
 =head1 COPYRIGHT
 
index b7d0901..7528ad7 100644 (file)
 =head1 NAME
 
-tapeconfig - Defines configuration parameters for all tape devices and backup data files
-on a Tape Coordinator machine
+tapeconfig - Defines parameters for tape devices and backup data files
 
 =head1 DESCRIPTION
 
-The tapeconfig file defines basic configuration parameters for
-all of the tape devices or backup data files available for backup operations
-on a Tape Coordinator machine. The file is in ASCII format and must
-reside in the local F</usr/afs/backup> directory. The
-instruction for each tape device or backup data file appears on its own line
-and each has the following format:
+The F<tapeconfig> file defines basic configuration parameters for all of
+the tape devices or backup data files available for backup operations on a
+Tape Coordinator machine. The file is in ASCII format and must reside in
+the local F</usr/afs/backup> directory. The instruction for each tape
+device or backup data file appears on its own line and each has the
+following format:
 
-   [I<capacity>    I<filemark_size>]    I<device_name>    I<port_offset>
+   [<capacity> <filemark_size>] <device_name> <port_offset>
 
 where
 
 =over 4
 
-=item I<capacity
+=item <capacity>
 
 Specifies the capacity of the tapes used with a tape device, or the amount
-of data to write into a backup data file. The Tape Coordinator refers
-to this value in two circumstances: 
+of data to write into a backup data file. The Tape Coordinator refers to
+this value in two circumstances:
 
 =over 4
 
 =item *
 
-When the capacity field of a tape or backup data file's label is
-empty (because the tape has never been labeled). The Tape Coordinator
-records this value on the label and uses it when determining how much data it
-can write to the tape or file during a B<backup dump> or B<backup
-savedb> operation. If there is already a capacity value on the
-label, the Tape Coordinator uses it instead.
+When the capacity field of a tape or backup data file's label is empty
+(because the tape has never been labeled). The Tape Coordinator records
+this value on the label and uses it when determining how much data it can
+write to the tape or file during a B<backup dump> or B<backup savedb>
+operation. If there is already a capacity value on the label, the Tape
+Coordinator uses it instead.
 
 =item *
 
-When the -size argument is omitted the first time the
-B<backup labeltape> command is used on a given tape or file.
-The Tape Coordinator copies this value into the label's capacity
-field.
+When the B<-size> argument is omitted the first time the B<backup
+labeltape> command is used on a given tape or file.  The Tape Coordinator
+copies this value into the label's capacity field.
 
 =back
 
 The Tape Coordinator uses this capacity value or the one on the Backup
-System tape label to track how much space remains as it writes data to a tape
-or backup data file. The appropriate value to record for a tape depends
-on the size of the tapes usually used in the device and whether it has a
-compression mode; for suggested values, see the I<IBM AFS
-Administration Guide> chapter on configuring the Backup System. If
-using a value obtained from the B<fms> command, reduce it by 10% to
-15% before recording it in the file.
+System tape label to track how much space remains as it writes data to a
+tape or backup data file. The appropriate value to record for a tape
+depends on the size of the tapes usually used in the device and whether it
+has a compression mode; for suggested values, see the I<IBM AFS
+Administration Guide> chapter on configuring the Backup System. If using a
+value obtained from the B<fms> command, reduce it by 10% to 15% before
+recording it in the file.
 
 For a backup data file, it is best to provide a value that helps the Tape
-Coordinator avoid reaching the end-of-file (EOF) unexpectedly. Make it
-at least somewhat smaller than the amount of space available on the partition
+Coordinator avoid reaching the end-of-file (EOF) unexpectedly. Make it at
+least somewhat smaller than the amount of space available on the partition
 housing the file when the dump operation begins, and never larger than the
 maximum file size allowed by the operating system.
 
 Specify a (positive) integer or decimal value followed by a letter than
 indicates units, with no intervening space. In a decimal number, the
-number of digits after the decimal point must not translate to fractions of
-bytes. The maximum acceptable value is 2048 GB (2 TB). The
-acceptable units letters are as follows; if the letter is omitted, the
-default is kilobytes.
+number of digits after the decimal point must not translate to fractions
+of bytes. The maximum acceptable value is 2048 GB (2 TB). The acceptable
+units letters are as follows; if the letter is omitted, the default is
+kilobytes.
 
 =over 4
 
 =item *
 
-B<k>or K for kilobytes (KB)
+C<k> or C<K> for kilobytes (KB).
 
 =item *
 
-B<m> or M for megabytes (MB)
+C<m> or C<M> for megabytes (MB).
 
 =item *
 
-B<g> or G for gigabytes (GB)
+C<g> or C<G> for gigabytes (GB).
 
 =item *
 
-B<t> or T for terabytes (TB)
+C<t> or C<T> for terabytes (TB).
 
 =back
 
 If this field is omitted, the Tape Coordinator uses the maximum acceptable
 value (2048 GB or 2 TB). Either leave both this field and the
-I<filemark_size> field empty, or provide a value in both of them.
+<filemark_size> field empty, or provide a value in both of them.
 
-=item I<filemark_size
+=item <filemark_size>
 
-Specifies the size of a tape device's filemarks (also called
-end-of-file or EOF marks), which is set by the device's
-manufacturer. In a dump to tape, the Tape Coordinator inserts filemarks
-at the boundary between the data from each volume, so the filemark size
-affects how much space is available for actual data. 
+Specifies the size of a tape device's filemarks (also called end-of-file
+or EOF marks), which is set by the device's manufacturer. In a dump to
+tape, the Tape Coordinator inserts filemarks at the boundary between the
+data from each volume, so the filemark size affects how much space is
+available for actual data.
 
-The appropriate value to record for a tape depends on the size of the tapes
-usually used in the device and whether it has a compression mode; for
-suggested values, see the I<IBM AFS Administration Guide> chapter on
-configuring the Backup System. If using a value obtained from the
-B<fms> command, increase it by 10% to 15% before recording it in the
-file.
+The appropriate value to record for a tape depends on the size of the
+tapes usually used in the device and whether it has a compression mode;
+for suggested values, see the I<IBM AFS Administration Guide> chapter on
+configuring the Backup System. If using a value obtained from the B<fms>
+command, increase it by 10% to 15% before recording it in the file.
 
-For backup data files, record a value of 0 (zero). The
-Tape Coordinator actually ignores this field for backup data files, because it
-does not use filemarks when writing to a file.
+For backup data files, record a value of 0 (zero). The Tape Coordinator
+actually ignores this field for backup data files, because it does not use
+filemarks when writing to a file.
 
-Use the same notation as for the I<capacity> field, but note that the
-default units is bytes rather than kilobytes. The maximum acceptable
-value is 2048 GB.
+Use the same notation as for the <capacity> field, but note that the
+default units is bytes rather than kilobytes. The maximum acceptable value
+is 2048 GB.
 
 If this field is empty, the Tape Coordinator uses the value 0
-(zero). Either leave both this field and the I<capacity> field
-empty, or provide a value in both of them.
+(zero). Either leave both this field and the <capacity> field empty, or
+provide a value in both of them.
 
-=item I<device_name
+=item <device_name>
 
 Specifies the complete pathname of the tape device or backup data
-file. The format of tape device names depends on the operating system,
-but on UNIX systems device names generally begin with the string
-F</dev/>. For a backup data file, this field defines the
-complete pathname; for a discussion of suggested naming conventions see
-the description of the B<FILE> instruction in L<CFG_I<device_name>(1)>.
+file. The format of tape device names depends on the operating system, but
+on UNIX systems device names generally begin with the string F</dev/>. For
+a backup data file, this field defines the complete pathname; for a
+discussion of suggested naming conventions see the description of the
+C<FILE> instruction in L<butc(5)>.
 
-=item I<port_offset
+=item <port_offset>
 
 Specifies the port offset number associated with this combination of Tape
-Coordinator and tape device or backup data file. 
-
-Acceptable values are the integers C<0> through 58510
-(the Backup System can track a maximum of 58,511 port offset numbers).
-Each value must be unique among the cell's Tape Coordinators, but any
-number of them can be associated with a single machine. Port offset
-numbers need not be assigned sequentially, and can appear in any order in the
-B<tapeconfig> file. Assign port offset C<0> to the Tape
-Coordinator for the tape device or backup data file used most often for backup
-operations; doing so will allow the operator to omit the
-B<-portoffset> argument from the largest possible number of
-B<backup> commands.
+Coordinator and tape device or backup data file.
+
+Acceptable values are the integers C<0> through C<58510> (the Backup
+System can track a maximum of 58,511 port offset numbers).  Each value
+must be unique among the cell's Tape Coordinators, but any number of them
+can be associated with a single machine. Port offset numbers need not be
+assigned sequentially, and can appear in any order in the F<tapeconfig>
+file. Assign port offset C<0> to the Tape Coordinator for the tape device
+or backup data file used most often for backup operations; doing so will
+allow the operator to omit the B<-portoffset> argument from the largest
+possible number of B<backup> commands.
 
 =back
 
 =head1 PRIVILEGE REQUIRED
 
-Creating the file requires UNIX B<w> (write) and
-B<x> (B<execute>) permissions on the
-F</usr/afs/backup> directory. Editing the file requires UNIX
-B<w> (B<write>) permission on the file.
+Creating the file requires UNIX C<w> (write) and C<x> (execute)
+permissions on the F</usr/afs/backup> directory. Editing the file requires
+UNIX C<w> (write) permission on the file.
 
 =head1 EXAMPLES
 
-The following example tapeconfig file configures three tape
-devices and a backup data file. The first device has device name
-F</dev/rmt/0h>, and is assigned port offset C<0> because it
-will be the most frequently used device for all backup operations in the
-cell. Its default tape capacity is 2 GB and filemark size is 1
-MB. The F</dev/rmt/3h> drive has half the capacity but a much
-smaller filemark size; its port offset is C<3>. The third
-device listed, F</dev/rmt/4h>, has the same capacity and filemark size
-as the first device and is assigned port offset C<2>. Port
-offset C<4> is assigned to the backup data file F</dev/FILE>,
-which is actually a symbolic link to the actual file located elsewhere on the
-local disk. The Tape Coordinator writes up to 1.5 GB into the
-file; as recommended, the filemark size is set to zero.
+The following example tapeconfig file configures three tape devices and a
+backup data file. The first device has device name F</dev/rmt/0h>, and is
+assigned port offset C<0> because it will be the most frequently used
+device for all backup operations in the cell. Its default tape capacity is
+2 GB and filemark size is 1 MB. The F</dev/rmt/3h> drive has half the
+capacity but a much smaller filemark size; its port offset is C<3>. The
+third device listed, F</dev/rmt/4h>, has the same capacity and filemark
+size as the first device and is assigned port offset C<2>. Port offset
+C<4> is assigned to the backup data file F</dev/FILE>, which is actually a
+symbolic link to the actual file located elsewhere on the local disk. The
+Tape Coordinator writes up to 1.5 GB into the file; as recommended, the
+filemark size is set to zero.
 
    2G 1M /dev/rmt/0h 0
    1g 4k /dev/rmt/3h 3
@@ -178,8 +172,8 @@ L<backup_addhost(8)>,
 L<backup_dump(8)>,
 L<backup_labeltape(8)>,
 L<backup_savedb(8)>,
-L<butc(1)>,
-L<fms(1)>
+L<butc(8)>,
+L<fms(8)>
 
 =head1 COPYRIGHT
 
index bec37e5..dcf9618 100644 (file)
 =head1 NAME
 
-uss Template File - Provides instructions for the uss add command
+uss - Provides instructions for the uss add command
 
 =head1 DESCRIPTION
 
-The uss template file defines the components of an AFS user
-account that the B<uss add> command (or B<add> instruction in
-a B<uss> bulk input file) creates. Use the B<-template>
-argument to the B<uss add> or B<uss bulk> command to identify
-the template file.
+The uss template file defines the components of an AFS user account that
+the B<uss add> command (or B<add> instruction in a B<uss> bulk input file)
+creates. Use the B<-template> argument to the B<uss add> or B<uss bulk>
+command to identify the template file.
 
-Summary of Template File Instructions
+=head2 Summary of Template File Instructions
 
 The template file can include the following instructions, each on its own
-line. A more detailed description of each instruction's syntax
-follows this list.
+line. A more detailed description of each instruction's syntax follows
+this list.
 
 =over 4
 
 =item A
 
-Imposes restrictions on user passwords and authentication attempts
+Imposes restrictions on user passwords and authentication attempts.
 
 =item D
 
-Creates a directory
+Creates a directory.
 
 =item E
 
-Creates a single-line file
+Creates a single-line file.
 
 =item F
 
-Creates a file by copying a prototype
+Creates a file by copying a prototype.
 
 =item G
 
 Defines a directory that is one of a set of parent directories into which
 the B<uss> command interpreter evenly distributes newly created home
-directories
+directories.
 
 =item L
 
-Creates a hard link
+Creates a hard link.
 
 =item S
 
-Creates a symbolic link
+Creates a symbolic link.
 
 =item V
 
 Creates a volume, mounts it in the file space and sets the ACL on the
-mount point
+mount point.
 
 =item X
 
-Executes a command
+Executes a command.
 
 =back
 
-If the template file is empty (zero-length), the uss add command
-or B<add> instruction in a bulk input file only creates an entry in
-the Protection and Authentication Databases, naming them according to the name
-specified with the B<uss add> command's B<-user>
-argument, or in the bulk input file B<add> instruction's
-I<username> field.
-
-The A Instruction for Setting the Default Treatment of Volumes
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-
-The B<A> instruction in a uss template file enhances
-cell security by imposing the following restrictions on users' password
-choice and authentication attempts. For further information on these
-limits, see the I<IBM AFS Administration Guide> and the B<kas
-setfields> reference page.
+If the template file is empty (zero-length), the B<uss add> command or
+C<add> instruction in a bulk input file only creates an entry in the
+Protection and Authentication Databases, naming them according to the name
+specified with the B<uss add> command's B<-user> argument, or in the bulk
+input file C<add> instruction's I<username> field.
+
+=head2 The A Instruction for Setting the Default Treatment of Volumes
+
+The C<A> instruction in a uss template file enhances cell security by
+imposing the following restrictions on users' password choice and
+authentication attempts. For further information on these limits, see the
+I<IBM AFS Administration Guide> and the B<kas setfields> reference page.
 
 =over 4
 
 =item *
 
-Limiting the user's password lifetime. When the lifetime
-expires, the user can no longer authenticate using that password, and must
-change it.
-
+Limiting the user's password lifetime. When the lifetime expires, the user
+can no longer authenticate using that password, and must change it.
 
 =item *
 
-Prohibiting the reuse of the user's 20 most recently used
-passwords.
-
+Prohibiting the reuse of the user's 20 most recently used passwords.
 
 =item *
 
 Limiting the number of consecutive times that a user can provide an
-incorrect password during authentication, and for how long the Authentication
-Server refuses further authentication attempts after the limit is exceeded
-(referred to as an I<account lockout>). For regular user
-accounts in most cells, the recommended limit is nine and lockout time is 25
-minutes.
-
+incorrect password during authentication, and for how long the
+Authentication Server refuses further authentication attempts after the
+limit is exceeded (referred to as an I<account lockout>). For regular user
+accounts in most cells, the recommended limit is nine and lockout time is
+25 minutes.
 
 =back
 
 The instruction has the following syntax:
 
-   A  I<username>  I<password_lifetime>  I<password_reuse>  I<failures>  I<locktime>
+   A <username> <lifetime> <reuse> <failures> <locktime>
 
 where
 
@@ -118,20 +103,16 @@ where
 
 =item A
 
-Indicates a security-enhancing instruction. It must be a capital
-letter.
+Indicates a security-enhancing instruction. It must be a capital letter.
 
-=item I<username
->
+=item <username>
 
 Names the Authentication Database entry on which to impose security
-restrictions. Specify the value B<$USER> to read in the
-username from the B<uss add> command's B<-user> argument,
-or from the I<username> field of an B<add> instruction in a bulk
-input file.
+restrictions. Specify the value $USER to read in the username from the
+B<uss add> command's B<-user> argument, or from the I<username> field of
+an C<add> instruction in a bulk input file.
 
-=item I<password_lifetime
->
+=item <lifetime>
 
 Sets the number of days after the user's password is changed that it
 remains valid. When the password becomes invalid (expires), the user is
@@ -139,118 +120,96 @@ unable to authenticate, but has 30 more days in which to issue the
 B<kpasswd> command to change the password (after that, only an
 administrator can change it).
 
-Specify an integer from the range B<1> through 254 to
-specify the number of days until expiration, the value B<0> to
-indicate that the password never expires, or the value B<$PWEXPIRES>
-to read in the number of days from the B<uss add> or B<uss
-bulk> command's B<-pwexpires> argument. If the
-B<A> instruction does not appear in the template file, the default is
-for the user's password never to expire.
+Specify an integer from the range C<1> through C<254> to specify the
+number of days until expiration, the value C<0> to indicate that the
+password never expires, or the value $PWEXPIRES to read in the number
+of days from the B<uss add> or B<uss bulk> command's B<-pwexpires>
+argument. If the C<A> instruction does not appear in the template file,
+the default is for the user's password never to expire.
 
-=item I<password_reuse
->
+=item <reuse>
 
 Determines whether or not the user can change his or her password (using
-the B<kpasswd> or B<kas setpassword> command) to one that is
-similar to any of the last twenty passwords. The acceptable values are
-B<reuse> to allow reuse and B<noreuse> to prohibit it.
-If the B<A> instruction does not appear in the template file, the
-default is to allow password reuse.
+the B<kpasswd> or B<kas setpassword> command) to one that is similar to
+any of the last twenty passwords. The acceptable values are C<reuse> to
+allow reuse and C<noreuse> to prohibit it.  If the C<A> instruction does
+not appear in the template file, the default is to allow password reuse.
 
-=item I<failures
->
+=item <failures>
 
 Sets the number of consecutive times the user can provide an incorrect
 password during authentication (using the B<klog> command or a login
 utility that grants AFS tokens). When the user exceeds the limit, the
-Authentication Server rejects further authentication attempts for the amount
-of time specified in the I<locktime> field.
+Authentication Server rejects further authentication attempts for the
+amount of time specified in the <locktime> field.
 
-Specify an integer from the range B<1> through 254 to
-specify the number of failures permitted, or the value B<0> to
-indicate that there is no limit to the number of unsuccessful attempts.
-If the B<A> instruction does not appear in the template file, the
-default is to allow an unlimited number of failures.
+Specify an integer from the range C<1> through C<254> to specify the
+number of failures permitted, or the value C<0> to indicate that there is
+no limit to the number of unsuccessful attempts.  If the C<A> instruction
+does not appear in the template file, the default is to allow an unlimited
+number of failures.
 
-=item I<locktime
->
+=item <locktime>
 
 Specifies how long the Authentication Server refuses authentication
 attempts from a user who has exceeded the failure limit set in the
-I<failures> field.
-
-Specify a number of hours and minutes (I<hh:mm>) or minutes
-only (I<mm>), from the range B<01> (one minute) through
-B<36:00> (36 hours). The Authentication Server
-automatically reduces any larger value to B<36:00> and also
-rounds up any non-zero value to the next higher multiple of 8.5
-minutes. A value of B<0> (zero) sets an infinite lockout
-time; an administrator must always issue the B<kas unlock>
-command to unlock the account.
+<failures> field.
+
+Specify a number of hours and minutes (I<hh:mm>) or minutes only (I<mm>),
+from the range C<01> (one minute) through C<36:00> (36 hours). The
+Authentication Server automatically reduces any larger value to C<36:00>
+and also rounds up any non-zero value to the next higher multiple of 8.5
+minutes. A value of C<0> (zero) sets an infinite lockout time; an
+administrator must always issue the B<kas unlock> command to unlock the
+account.
 
 =back
 
-The D Instruction for Creating a Directory
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-
-The B<D> instruction in a uss template file creates a
-directory. Its intended use is to create a subdirectory in the user
-home directory created by the B<V> instruction in the template
-file.
-
-Any number of D instructions can appear in the template
-file. If any variables in the instruction take their values from the
-B<V> instruction (notably, the $MTPT variable), the instruction must
-follow the B<V> instruction in the file.
-
-Although it is possible to use the D instruction to create a
-directory on the local disk of the machine where the B<uss> command is
-issued, it is not recommended. The preferred method for automated
-creation of directories on a local disk is the B<package>
-program. Two complications arise if the I<pathname> field refers
-to a local disk directory:
+=head2 The D Instruction for Creating a Directory
 
-=over 4
+The C<D> instruction in a uss template file creates a directory. Its
+intended use is to create a subdirectory in the user home directory
+created by the C<V> instruction in the template file.
 
-=item *
+Any number of C<D> instructions can appear in the template file. If any
+variables in the instruction take their values from the C<V> instruction
+(notably, the $MTPT variable), the instruction must follow the C<V>
+instruction in the file.
 
-The uss command prints a warning message because it cannot
-associate an access control list (ACL) with a local disk directory. It
-creates the directory nonetheless, and some syntactically correct value must
-appear in the instruction's I<ACL> field.
+Although it is possible to use the C<D> instruction to create a directory
+on the local disk of the machine where the B<uss> command is issued, it is
+not recommended. The preferred method for automated creation of
+directories on a local disk is the B<package> program. Two complications
+arise if the <pathname> field refers to a local disk directory:
 
+=over 4
 
 =item *
 
-To designate any user other than the issuer as the new directory's
-owner, the issuer must log onto the machine as the local superuser
-B<root>. For local disk directories, only the local superuser
-B<root> is allowed to issue the UNIX B<chown> command that the
-B<uss> command interpreter invokes to change the owner from the
-default value (the directory's creator, which in this case is the issuer
-of the B<uss> command). The issuer must then also use the
-B<-admin> argument to the B<uss add> or B<uss bulk>
-command to authenticate as a privileged AFS administrator, which is required
-for creating the Authentication Database and Protection Database entries that
-the B<uss> command interpreter always creates for a new
-account.
+The B<uss> command prints a warning message because it cannot associate an
+access control list (ACL) with a local disk directory. It creates the
+directory nonetheless, and some syntactically correct value must appear in
+the instruction's <ACL> field.
+
+=item *
 
+To designate any user other than the issuer as the new directory's owner,
+the issuer must log onto the machine as the local superuser C<root>. For
+local disk directories, only the local superuser C<root> is allowed to
+issue the UNIX B<chown> command that the B<uss> command interpreter
+invokes to change the owner from the default value (the directory's
+creator, which in this case is the issuer of the B<uss> command). The
+issuer must then also use the B<-admin> argument to the B<uss add> or
+B<uss bulk> command to authenticate as a privileged AFS administrator,
+which is required for creating the Authentication Database and Protection
+Database entries that the B<uss> command interpreter always creates for a
+new account.
 
 =back
 
 The instruction has the following syntax:
 
-   D  I<pathname>  I<mode_bits>  I<owner>  I<ACL>
+   D <pathname> <mode> <owner> <ACL>
 
 where
 
@@ -258,116 +217,97 @@ where
 
 =item D
 
-Indicates a directory creation instruction. It must be a capital
-letter.
+Indicates a directory creation instruction. It must be a capital letter.
 
-=item I<pathname
->
+=item <pathname>
 
-Specifies the directory's full pathname. It can include
-variables.
+Specifies the directory's full pathname. It can include variables.
 
 Specify the read/write path to the directory, to avoid the failure that
 results from attempting to create a new directory in a read-only
 volume. By convention, the read/write path is indicated by placing a
 period before the cell name at the pathname's second level (for example,
-B</afs/.abc.com>). For further discussion of the
-concept of read/write and read-only paths through the filespace, see the
-reference page for the B<fs mkmount> command.
-
-=item I<mode_bits
->
-
-Sets the directory's UNIX mode bits. Acceptable values are the
-standard three- or four-digit numbers corresponding to combinations of
-permissions. Examples: B<755> corresponds to
-B<rwxr-xr-x>, and B<644> to B<rw-r--r-->. The
-first (owner) B<x> bit must be turned on to enable access to a
-directory.
+F</afs/.abc.com>). For further discussion of the concept of read/write and
+read-only paths through the filespace, see the reference page for the B<fs
+mkmount> command.
+
+=item <mode>
 
-=item I<owner
->
+Sets the directory's UNIX mode bits. Acceptable values are the standard
+three- or four-digit numbers corresponding to combinations of
+permissions. Examples: C<755> corresponds to C<rwxr-xr-x>, and C<644> to
+C<rw-r--r-->. The first (owner) C<x> bit must be turned on to enable
+access to a directory.
+
+=item <owner>
 
 Specifies the username or UNIX user ID (UID) of the user to be designated
-the directory's owner in the output from the UNIX B<ls -ld>
-command. If the directory resides in AFS, place the $UID variable in
-this field. If the directory resides on the local disk, this field must
-be the username or UID of the B<uss> command's issuer, unless the
-issuer is logged in as the local superuser B<root>.
+the directory's owner in the output from the UNIX C<ls -ld> command. If
+the directory resides in AFS, place the $UID variable in this field. If
+the directory resides on the local disk, this field must be the username
+or UID of the B<uss> command's issuer, unless the issuer is logged in as
+the local superuser C<root>.
 
-=item I<ACL
->
+=item <ACL>
 
 Sets the ACL on the new directory. It must appear even if the new
-directory resides on the local disk rather than in AFS, but is ignored in that
-case. Provide one or more paired values, each pair consisting of an AFS
-username or group name and the desired permissions, in that order.
-Separate the two parts of the pair, and each pair, with a space. The
-B<fs setacl> reference page describes the available
-permissions.
-
-For an AFS directory, grant all permissions to the directory's owner
-at least. Usually that is the new user, in which case the appropriate
-value is B<$USER all>.
-
-It is not possible to grant any permissions to the issuer of the
-B<uss> command. As the last step in account creation, the
-B<uss> command interpreter automatically deletes that person from any
-ACLs set during the creation process.
+directory resides on the local disk rather than in AFS, but is ignored in
+that case. Provide one or more paired values, each pair consisting of an
+AFS username or group name and the desired permissions, in that order.
+Separate the two parts of the pair, and each pair, with a space. The B<fs
+setacl> reference page describes the available permissions.
 
-=back
+For an AFS directory, grant all permissions to the directory's owner at
+least. Usually that is the new user, in which case the appropriate value
+is C<$USER all>.
 
-The E Instruction for Creating a Single-line File
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-
-The B<E> instruction in a uss template file creates a
-file by echoing a specified character string into it. Its intended use
-is to create files in the user home directory created by the B<V>
-instruction in the template file, or in a subdirectory created by a
-B<D> instruction.
-
-Any number of E instructions can appear in the template
-file. If the file resides in a directory created by a B<D>
-instruction, the B<E> instruction must follow the B<D>
-instruction in the file.
+It is not possible to grant any permissions to the issuer of the B<uss>
+command. As the last step in account creation, the B<uss> command
+interpreter automatically deletes that person from any ACLs set during the
+creation process.
 
-The B<E> and F instructions have complementary
-advantages. The character string echoed into the file by an
-B<E> instruction can be customized for each user, because it can
-include the standard variables for which the B<uss> command
-interpreter substitutes the values specified by arguments to the B<uss
-add> command or fields in a bulk input file B<add>
-instruction. In contrast, a file created using the B<F>
-instruction cannot include variables and so has the same content for all
-users. However, a file created by an B<E> instruction can be a
-single line only, because no carriage returns (newline characters) are allowed
-in the character string.
-
-Although it is possible to use the E instruction to create a
-file on the local disk of the machine where the B<uss> command is
-issued, it is not recommended. The preferred method for automated
-creation of files on a local disk is the B<package> program.
-The main complication is that designating any user other than the issuer as
-the new file's owner requires logging onto the machine as the local
-superuser B<root>. For local disk files, only the local
-superuser B<root> is allowed to issue the UNIX B<chown>
-command that the B<uss> command interpreter invokes to change the
-owner from the default value (the file's creator, which in this case is
-the issuer of the B<uss> command). The issuer must then also
-use the B<-admin> argument to the B<uss add> or B<uss
-bulk> command to authenticate as a privileged AFS administrator, which is
-required for creating the Authentication Database and Protection Database
-entries that the B<uss> command interpreter always creates for a new
-account.
+=back
+
+=head2 The E Instruction for Creating a Single-line File
+
+The C<E> instruction in a uss template file creates a file by echoing a
+specified character string into it. Its intended use is to create files in
+the user home directory created by the C<V> instruction in the template
+file, or in a subdirectory created by a C<D> instruction.
+
+Any number of C<E> instructions can appear in the template file. If the
+file resides in a directory created by a C<D> instruction, the C<E>
+instruction must follow the C<D> instruction in the file.
+
+The C<E> and C<F> instructions have complementary advantages. The
+character string echoed into the file by an C<E> instruction can be
+customized for each user, because it can include the standard variables
+for which the B<uss> command interpreter substitutes the values specified
+by arguments to the B<uss add> command or fields in a bulk input file
+B<add> instruction. In contrast, a file created using the C<F> instruction
+cannot include variables and so has the same content for all
+users. However, a file created by an C<E> instruction can be a single line
+only, because no carriage returns (newline characters) are allowed in the
+character string.
+
+Although it is possible to use the C<E> instruction to create a file on
+the local disk of the machine where the B<uss> command is issued, it is
+not recommended. The preferred method for automated creation of files on a
+local disk is the B<package> program.  The main complication is that
+designating any user other than the issuer as the new file's owner
+requires logging onto the machine as the local superuser C<root>. For
+local disk files, only the local superuser C<root> is allowed to issue the
+UNIX B<chown> command that the B<uss> command interpreter invokes to
+change the owner from the default value (the file's creator, which in this
+case is the issuer of the B<uss> command). The issuer must then also use
+the B<-admin> argument to the B<uss add> or B<uss bulk> command to
+authenticate as a privileged AFS administrator, which is required for
+creating the Authentication Database and Protection Database entries that
+the B<uss> command interpreter always creates for a new account.
 
 The instruction has the following syntax:
 
-   E  I<pathname>  I<mode_bits>  I<owner>  "I<contents>"
+   E <pathname> <mode> <owner> "<contents>"
 
 where
 
@@ -375,100 +315,82 @@ where
 
 =item E
 
-Indicates a file creation instruction. It must be a capital
-letter.
+Indicates a file creation instruction. It must be a capital letter.
 
-=item I<pathname
->
+=item <pathname>
 
-Specifies the file's full pathname. It can include
-variables.
+Specifies the file's full pathname. It can include variables.
 
 Specify the read/write path to the file, to avoid the failure that results
-from attempting to create a new file in a read-only volume. By
-convention, the read/write path is indicated by placing a period before the
-cell name at the pathname's second level (for example,
-B</afs/.abc.com>). For further discussion of the
-concept of read/write and read-only paths through the filespace, see the
-reference page for the B<fs mkmount> command.
+from attempting to create a new file in a read-only volume. By convention,
+the read/write path is indicated by placing a period before the cell name
+at the pathname's second level (for example, F</afs/.abc.com>). For
+further discussion of the concept of read/write and read-only paths
+through the filespace, see the reference page for the B<fs mkmount>
+command.
 
-=item I<mode_bits
->
+=item <mode>
 
-Sets the file's UNIX mode bits. Acceptable values are the
-standard three- or four-digit numbers corresponding to combinations of
-permissions. Examples: B<755> corresponds to
-B<rwxr-xr-x>, and B<644> to B<rw-r--r-->.
+Sets the file's UNIX mode bits. Acceptable values are the standard three-
+or four-digit numbers corresponding to combinations of
+permissions. Examples: C<755> corresponds to C<rwxr-xr-x>, and C<644> to
+C<rw-r--r-->.
 
-=item I<owner
->
+=item <owner>
 
 Specifies the username or UNIX user ID (UID) of the user to be designated
-the file's owner in the output from the UNIX B<ls -l>
-command. If the file resides in AFS, place the $UID variable in this
-field. If the file resides on the local disk, specify the username or
-UID of the B<uss> command's issuer; otherwise, the account
-creation operation halts immediately.
+the file's owner in the output from the UNIX C<ls -l> command. If the file
+resides in AFS, place the $UID variable in this field. If the file
+resides on the local disk, specify the username or UID of the B<uss>
+command's issuer; otherwise, the account creation operation halts
+immediately.
 
-=item I<contents
->
+=item <contents>
 
 Specifies the one-line character string to write into the new file.
 Surround it with double quotes if it contains one or more spaces. It
 cannot contain the newline character, but can contain any of the standard
-variables, which the command interpreter resolves as it creates the
-file.
+variables, which the command interpreter resolves as it creates the file.
 
 =back
 
-L<(1)>The F Instruction for Creating a File
-from a Prototype
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-
-The B<F> instruction in a uss template file creates a
-file by copying the contents of an existing file (the I<prototype>)
-into it. Its intended use is to create files in the user home directory
-created by the B<V> instruction in the template file, or in a
-subdirectory created by a B<D> instruction.
-
-Any number of F instructions can appear in the template
-file. If the file resides in a directory created by a B<D>
-instruction, the B<F> instruction must follow the B<D>
-instruction in the file.
+=head2 The F Instruction for Creating a File from a Prototype
 
-The B<E> and F instructions have complementary
-advantages. A file created using the B<F> instruction has the
-same content for all users, whereas a file created by an B<E>
-instruction can be customized for each user if it includes variables.
-However, a file created by an B<E> instruction can be a single line
-only, whereas the prototype file copied by an B<F> instruction can be
-any length.
-
-Although it is possible to use the F instruction to create a
-file on the local disk of the machine where the B<uss> command is
-issued, it is not recommended. The preferred method for automated
-creation of files on a local disk is the B<package> program.
-The main complication is that designating any user other than the issuer as
-the new file's owner requires logging onto the machine as the local
-superuser B<root>. For local disk files, only the local
-superuser B<root> is allowed to issue the UNIX B<chown>
-command that the B<uss> command interpreter invokes to change the
-owner from the default value (the file's creator, which in this case is
-the issuer of the B<uss> command). The issuer must then also
-use the B<-admin> argument to the B<uss add> or B<uss
-bulk> command to authenticate as a privileged AFS administrator, which is
-required for creating the Authentication Database and Protection Database
-entries that the B<uss> command interpreter always creates for a new
-account.
+The C<F> instruction in a uss template file creates a file by copying the
+contents of an existing file (the <prototype>) into it. Its intended use
+is to create files in the user home directory created by the C<V>
+instruction in the template file, or in a subdirectory created by a C<D>
+instruction.
+
+Any number of C<F> instructions can appear in the template file. If the
+file resides in a directory created by a C<D> instruction, the C<F>
+instruction must follow the C<D> instruction in the file.
+
+The C<E> and C<F> instructions have complementary advantages. A file
+created using the C<F> instruction has the same content for all users,
+whereas a file created by an C<E> instruction can be customized for each
+user if it includes variables.  However, a file created by an C<E>
+instruction can be a single line only, whereas the prototype file copied
+by an C<F> instruction can be any length.
+
+Although it is possible to use the C<F> instruction to create a file on
+the local disk of the machine where the B<uss> command is issued, it is
+not recommended. The preferred method for automated creation of files on a
+local disk is the B<package> program.  The main complication is that
+designating any user other than the issuer as the new file's owner
+requires logging onto the machine as the local superuser C<root>. For
+local disk files, only the local superuser C<root> is allowed to issue the
+UNIX B<chown> command that the B<uss> command interpreter invokes to
+change the owner from the default value (the file's creator, which in this
+case is the issuer of the B<uss> command). The issuer must then also use
+the B<-admin> argument to the B<uss add> or B<uss bulk> command to
+authenticate as a privileged AFS administrator, which is required for
+creating the Authentication Database and Protection Database entries that
+the B<uss> command interpreter always creates for a new account.
 
 The instruction has the following syntax:
 
-   F  I<pathname>  I<mode_bits>  I<owner>  I<prototype_file>
+   F <pathname> <mode> <owner> <prototype_file>
 
 where
 
@@ -476,84 +398,72 @@ where
 
 =item F
 
-Indicates a file creation instruction. It must be a capital
-letter.
+Indicates a file creation instruction. It must be a capital letter.
 
-=item I<pathname
->
+=item <pathname>
 
 Specifies the full pathname of the file to create, including the
 filename. It can include variables.
 
 Specify the read/write path to the file, to avoid the failure that results
-from attempting to create a new file in a read-only volume. By
-convention, the read/write path is indicated by placing a period before the
-cell name at the pathname's second level (for example,
-B</afs/.abc.com>). For further discussion of the
-concept of read/write and read-only paths through the filespace, see the
-reference page for the B<fs mkmount> command.
+from attempting to create a new file in a read-only volume. By convention,
+the read/write path is indicated by placing a period before the cell name
+at the pathname's second level (for example, F</afs/.abc.com>). For
+further discussion of the concept of read/write and read-only paths
+through the filespace, see the reference page for the B<fs mkmount>
+command.
 
-=item I<mode_bits
->
+=item <mode>
 
-Sets the file's UNIX mode bits. Acceptable values are the
-standard three- or four-digit numbers corresponding to combinations of
-permissions. Examples: B<755> corresponds to
-B<rwxr-xr-x>, and B<644> to B<rw-r--r-->.
+Sets the file's UNIX mode bits. Acceptable values are the standard three-
+or four-digit numbers corresponding to combinations of
+permissions. Examples: C<755> corresponds to C<rwxr-xr-x>, and C<644> to
+C<rw-r--r-->.
 
-=item I<owner
->
+=item <owner>
 
 Specifies the username or UNIX user ID (UID) of the user to be designated
-the file's owner in the output from the UNIX B<ls -l>
-command. If the file resides in AFS, place the $UID variable in this
-field. If the file resides on the local disk, specify the username or
-UID of the B<uss> command's issuer; otherwise, the account
-creation operation halts immediately.
+the file's owner in the output from the UNIX C<ls -l> command. If the file
+resides in AFS, place the $UID variable in this field. If the file
+resides on the local disk, specify the username or UID of the B<uss>
+command's issuer; otherwise, the account creation operation halts
+immediately.
 
-=item I<prototype_file
->
+=item <prototype_file>
 
 Names the AFS or local disk directory that houses the prototype file to
-copy. The prototype file's name must match the final element in
-the I<pathname> field.
+copy. The prototype file's name must match the final element in the
+<pathname> field.
 
 =back
 
-L<(1)>The G Instruction for Facilitating Even
-Distribution of Home Directories
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-
-The B<G> instruction in a uss template file creates a
-directory as one of the set of directories from which the B<uss>
-command interpreter selects when choosing a new user home directory's
-parent directory. More specifically, when the $AUTO variable appears in
-the I<mount_point> field of a B<V> instruction, the command
-interpreter substitutes for it the directory defined by a B<G>
-instruction that currently has the fewest entries.
-
-The instruction's intended use is to distribute user accounts evenly
-among several directories, rather than using directories that reflect
-divisions such as departmental affiliation. Distributing home
-directories in this fashion is useful mainly in very large cells where storing
-all user home directories under a single parent directory potentially slows
-directory lookup, or where a workplace-based division results in unevenly
-sized directories such that some users consistently experience slower
-directory lookup than others. See the chapter on B<uss> in the
-I<IBM AFS Administration Guide> for more information.
-
-Any number of G instructions can appear in the template
-file. If the B<V> instruction includes the $AUTO variable, it
-must appear after all of the B<G> instructions in the file.
+=head2 The G Instruction for Even Distribution of Home Directories
+
+The C<G> instruction in a uss template file creates a directory as one of
+the set of directories from which the B<uss> command interpreter selects
+when choosing a new user home directory's parent directory. More
+specifically, when the $AUTO variable appears in the <mount_point>
+field of a C<V> instruction, the command interpreter substitutes for it
+the directory defined by a C<G> instruction that currently has the fewest
+entries.
+
+The instruction's intended use is to distribute user accounts evenly among
+several directories, rather than using directories that reflect divisions
+such as departmental affiliation. Distributing home directories in this
+fashion is useful mainly in very large cells where storing all user home
+directories under a single parent directory potentially slows directory
+lookup, or where a workplace-based division results in unevenly sized
+directories such that some users consistently experience slower directory
+lookup than others. See the chapter on B<uss> in the I<IBM AFS
+Administration Guide> for more information.
+
+Any number of C<G> instructions can appear in the template file. If the
+C<V> instruction includes the $AUTO variable, it must appear after all
+of the C<G> instructions in the file.
 
 The instruction has the following syntax:
 
-   G  I<directory>
+   G <directory>
 
 where
 
@@ -564,68 +474,51 @@ where
 Indicates an instruction that creates a directory to be considered as a
 value for the $AUTO variable. It must be a capital letter.
 
-=item I<directory
->
+=item <directory>
 
-Specifies the directory's name as either a complete pathname or only
-the directory name. The choice determines the appropriate format for
-the I<mount_point> field of a B<V> instruction, as discussed in
-the following example.
+Specifies the directory's name as either a complete pathname or only the
+directory name. The choice determines the appropriate format for the
+<mount_point> field of a C<V> instruction, as discussed in the following
+example.
 
 Specify the read/write path to the directory, to avoid the failure that
-results from attempting to create a new mount point in a read-only volume when
-the $AUTO variable is used in a B<V> instruction's
-I<mount_point> field. By convention, the read/write path is
-indicated by placing a period before the cell name at the pathname's
-second level (for example, B</afs/.abc.com>). For
-further discussion of the concept of read/write and read-only paths through
-the filespace, see the reference page for the B<fs mkmount>
-command.
+results from attempting to create a new mount point in a read-only volume
+when the $AUTO variable is used in a C<V> instruction's <mount_point>
+field. By convention, the read/write path is indicated by placing a period
+before the cell name at the pathname's second level (for example,
+F</afs/.abc.com>). For further discussion of the concept of read/write and
+read-only paths through the filespace, see the reference page for the B<fs
+mkmount> command.
 
 =back
 
-The L and S Instructions for Creating a Link
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-
-The B<L> instruction in a uss template file creates a
-hard link between two files, as achieved by the standard UNIX B<ln>
-command. The B<S> instruction creates a symbolic link between
-two files, as achieved by the standard UNIX B<ln -s> command. A
-full explanation of links is beyond the scope of this document, but the basic
-effect is to create a second name for an existing file, enabling access via
-either name. Creating a link does not create a second copy of the
-file.
+=head2 The L and S Instructions for Creating a Link
+
+The C<L> instruction in a uss template file creates a hard link between
+two files, as achieved by the standard UNIX B<ln> command. The C<S>
+instruction creates a symbolic link between two files, as achieved by the
+standard UNIX C<ln -s> command. A full explanation of links is beyond the
+scope of this document, but the basic effect is to create a second name
+for an existing file, enabling access via either name. Creating a link
+does not create a second copy of the file.
 
 AFS allows hard links only if the linked files reside in the same
-directory, because it becomes difficult to determine which access control list
-(ACL) applies to the file if the two copies reside in directories with
-different ACLs. AFS allows symbolic links between two files that reside
-in different directories, or even different volumes. The File Server
-uses the ACL associated with the actual file rather than the link.
-
-Any number of B<L> and S instructions can appear in the
-template file. If the existing file or link is to reside in a directory
-created by a B<D> instruction, or if the existing file was created by
-an B<E> or B<F> instruction, the B<L> or B<S>
-instruction must follow the B<D>, B<E>, or B<F>
-instruction.
+directory, because it becomes difficult to determine which access control
+list (ACL) applies to the file if the two copies reside in directories
+with different ACLs. AFS allows symbolic links between two files that
+reside in different directories, or even different volumes. The File
+Server uses the ACL associated with the actual file rather than the link.
+
+Any number of C<L> and C<S> instructions can appear in the template
+file. If the existing file or link is to reside in a directory created by
+a C<D> instruction, or if the existing file was created by an C<E> or C<F>
+instruction, the C<L> or C<S> instruction must follow the C<D>, C<E>, or
+C<F> instruction.
 
 The instructions share the following syntax:
 
-   L  I<existing_file>  I<link>
-   S  I<existing_file>  I<link>
+   L <existing_file> <link>
+   S <existing_file> <link>
 
 where
 
@@ -633,75 +526,50 @@ where
 
 =item L
 
-Indicates a hard link creation instruction. It must be a capital
-letter.
+Indicates a hard link creation instruction. It must be a capital letter.
 
 =item S
 
-Indicates a symbolic link creation instruction. It must be a
-capital letter.
+Indicates a symbolic link creation instruction. It must be a capital
+letter.
 
-=item I<existing_file
->
+=item <existing_file>
 
 Specifies the complete pathname of the existing file.
 
-=item I<link
->
+=item <link>
 
 Specifies the complete pathname of the second name for the file.
 
 Specify the read/write path to the link, to avoid the failure that results
-from attempting to create a new link in a read-only volume. By
-convention, the read/write path is indicated by placing a period before the
-cell name at the pathname's second level (for example,
-B</afs/.abc.com>). For further discussion of the
-concept of read/write and read-only paths through the filespace, see the
-reference page for the B<fs mkmount> command.
+from attempting to create a new link in a read-only volume. By convention,
+the read/write path is indicated by placing a period before the cell name
+at the pathname's second level (for example, F</afs/.abc.com>). For
+further discussion of the concept of read/write and read-only paths
+through the filespace, see the reference page for the B<fs mkmount>
+command.
 
 =back
 
-L<(1)>The V Instruction for Creating and
-Mounting a Volume
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
-
-The B<V> instruction in a uss template file creates a
-volume on a specified file server machine and partition and creates an entry
-for it in the Volume Location Database (VLDB). It mounts the volume at
-a location in the AFS file space that becomes the user's home directory,
-then designates the directory's owner and sets its access control list
-(ACL).
-
-Only one V instruction can appear in the template file, and one
-must appear if the template file contains any instructions at all (is not
-empty). All other instructions are optional, except that the template
-must include B<G> instructions if the $AUTO variable appears in
-it. (The B<V> instruction is not necessarily the first line in
-the template. If the template includes the $AUTO variable, then the
-B<G> instructions which provide values for the variable must precede
-it in the file.)
+=head2 The V Instruction for Creating and Mounting a Volume
+
+The C<V> instruction in a uss template file creates a volume on a
+specified file server machine and partition and creates an entry for it in
+the Volume Location Database (VLDB). It mounts the volume at a location in
+the AFS file space that becomes the user's home directory, then designates
+the directory's owner and sets its access control list (ACL).
+
+Only one C<V> instruction can appear in the template file, and one must
+appear if the template file contains any instructions at all (is not
+empty). All other instructions are optional, except that the template must
+include C<G> instructions if the $AUTO variable appears in it. (The
+C<V> instruction is not necessarily the first line in the template. If the
+template includes the $AUTO variable, then the C<G> instructions which
+provide values for the variable must precede it in the file.)
 
 The instruction has the following syntax:
 
-   V  I<volume_name>  I<server>  I<partition>  I<quota>  I<mount_point> I<owner>  I<ACL>
+   V <vname> <server> <partition> <quota> <mount_point> <owner> <ACL>
 
 where
 
@@ -709,127 +577,111 @@ where
 
 =item V
 
-Indicates a volume creation instruction. It must be a capital
-letter.
+Indicates a volume creation instruction. It must be a capital letter.
 
-=item I<volume_name
->
+=item <name>
 
-Specifies the volume's name. To follow the convention for AFS
-user volume names, specify the value B<user.$USER>.
-Provide a value for the $USER variable via the B<uss add>
-command's B<-user> argument or the I<username> field in the
-bulk input file B<add> instruction.
+Specifies the volume's name. To follow the convention for AFS user volume
+names, specify the value C<user.$USER>.  Provide a value for the $USER
+variable via the B<uss add> command's B<-user> argument or the <username>
+field in the bulk input file B<add> instruction.
 
-=item I<server
->
+=item <server>
 
-Names the file server machine on which to create the new user's
-volume. It is best to provide the fully-qualified hostname (for
-example, B<fs1.abc.com>), but an abbreviated form is
-acceptable provided that the cell's naming service is available to
-resolve it at the time the volume is created. To read in the value from
-the B<uss add> command's B<-server> argument, specify the
-value B<$SERVER>.
+Names the file server machine on which to create the new user's volume. It
+is best to provide the fully-qualified hostname (for example,
+C<fs1.abc.com>), but an abbreviated form is acceptable provided that the
+cell's naming service is available to resolve it at the time the volume is
+created. To read in the value from the B<uss add> command's B<-server>
+argument, specify the value $SERVER.
 
-=item I<partition
->
+=item <partition>
 
-Specifies the partition on which to create the user's volume; it
-must be on the file server machine named in the I<server> field.
-Identify the partition by its complete name (for example, B</vicepa>)
-or use or use one of the following abbreviations. 
+Specifies the partition on which to create the user's volume; it must be
+on the file server machine named in the <server> field.  Identify the
+partition by its complete name (for example, F</vicepa>) or use or use one
+of the following abbreviations.
 
-   B</vicepa>     =     B<vicepa>      =      B<a>      =      0
-   B</vicepb>     =     B<vicepb>      =      B<b>      =      1
+   /vicepa     =     vicepa      =      a      =      0
+   /vicepb     =     vicepb      =      b      =      1
 
-After /vicepz (for which the index is 25) comes 
+After F</vicepz> (for which the index is 25) comes 
 
-   B</vicepaa>    =     B<vicepaa>     =      B<aa>     =      26
-   B</vicepab>    =     B<vicepab>     =      B<ab>     =      27
+   /vicepaa    =     vicepaa     =      aa     =      26
+   /vicepab    =     vicepab     =      ab     =      27
 
 and so on through 
 
-   B</vicepiv>    =     B<vicepiv>     =      B<iv>     =      255
+   /vicepiv    =     vicepiv     =      iv     =      255
 
-To read in the value from the uss add command's
-B<-partition> argument, specify the value B<$PART>.
+To read in the value from the B<uss add> command's B<-partition> argument,
+specify the value $PART.
 
-=item I<quota
->
+=item <quota>
 
 Sets the maximum number of kilobyte blocks the volume can occupy on the
-file server machine's disk. Specify an integer constant if all
-volumes have the same quota (B<1024> equals a megabyte), or use one of
-the number variables ($1 through $9) to assign different values to different
-volumes.
+file server machine's disk. Specify an integer constant if all volumes
+have the same quota (C<1024> equals a megabyte), or use one of the number
+variables ($1 through $9) to assign different values to different volumes.
 
-=item I<mount_point
->
+=item <mount_point>
 
-Creates a mount point for the volume, which serves as the volume's
-root directory. Include the $USER variable as part of the pathname to
-follow the convention that user home directory names include the
-username.
+Creates a mount point for the volume, which serves as the volume's root
+directory. Include the $USER variable as part of the pathname to follow
+the convention that user home directory names include the username.
 
 Specify the read/write path to the mount point, to avoid the failure that
 results from attempting to create a new mount point in a read-only
 volume. By convention, the read/write path is indicated by placing a
 period before the cell name at the pathname's second level (for example,
-B</afs/.abc.com>). If the $AUTO variable appears
-in this field, the directories named by each B<G> instruction possibly
-already indicate the read/write path. For further discussion of the
-concept of read/write and read-only paths through the filespace, see the
-reference page for the B<fs mkmount> command..
+F</afs/.abc.com>). If the $AUTO variable appears in this field, the
+directories named by each C<G> instruction possibly already indicate the
+read/write path. For further discussion of the concept of read/write and
+read-only paths through the filespace, see the reference page for the B<fs
+mkmount> command.
 
-=item I<owner
->
+=item <owner>
 
 Specifies the username or UNIX user ID (UID) of the user to be designated
-the mount point's owner in the output from the UNIX B<ls -ld>
-command. To follow the convention for home directory ownership, place
-the value B<$UID> in this field.
+the mount point's owner in the output from the UNIX C<ls -ld> command. To
+follow the convention for home directory ownership, place the value
+$UID in this field.
 
-=item I<ACL
->
+=item <ACL>
 
-Sets the ACL on the new directory. Provide one or more paired
-values, each pair consisting of an AFS username or group name and the desired
-permissions, in that order. Separate the two parts of the pair, and
-each pair, with a space. The B<fs setacl> reference page
-describes the available permissions.
+Sets the ACL on the new directory. Provide one or more paired values, each
+pair consisting of an AFS username or group name and the desired
+permissions, in that order. Separate the two parts of the pair, and each
+pair, with a space. The B<fs setacl> reference page describes the
+available permissions.
 
 Grant all permissions to the new user at least. The appropriate
-value is B<$USER all>.
+value is C<$USER all>.
 
-AFS automatically grants the system:administrators group
-all permissions as well. It is not possible to grant any permissions to
-the issuer of the B<uss> command. As the last step in account
-creation, the B<uss> command interpreter automatically deletes that
-user from any ACLs set during the creation process.
+AFS automatically grants the system:administrators group all permissions
+as well. It is not possible to grant any permissions to the issuer of the
+B<uss> command. As the last step in account creation, the B<uss> command
+interpreter automatically deletes that user from any ACLs set during the
+creation process.
 
 =back
 
-L<(1)>The X Instruction for Running a
-Command
-L<(1)>
-L<(1)>
-L<(1)>
+=head2 The X Instruction for Running a Command
 
-The B<X> instruction in a uss template file runs the
-indicated command, which can be a standard UNIX or AFS command. It can
-include any variables from the template file, which the B<uss> command
-interpreter resolves before passing the command on to the appropriate other
-command interpreter. It must be a single line only, however (cannot
-contain carriage returns or newline characters).
+The C<X> instruction in a uss template file runs the indicated command,
+which can be a standard UNIX or AFS command. It can include any variables
+from the template file, which the B<uss> command interpreter resolves
+before passing the command on to the appropriate other command
+interpreter. It must be a single line only, however (cannot contain
+carriage returns or newline characters).
 
-Any number of X instructions can appear in the template
-file. If an instruction manipulates an element created by another
-instruction, it must follow that instruction in the file.
+Any number of C<X> instructions can appear in the template file. If an
+instruction manipulates an element created by another instruction, it must
+follow that instruction in the file.
 
 The instruction has the following syntax:
 
-   B<X ">I<command>"
+   X "<command>"
 
 where
 
@@ -837,111 +689,102 @@ where
 
 =item X
 
-Indicates a command execution instruction. It must be a capital
-letter.
+Indicates a command execution instruction. It must be a capital letter.
 
-=item I<command
->
+=item <command>
 
-Specifies the command to run. Surround it with double quotes as
-shown if it contains one or more spaces. It can contain any variables
-from the template file, but not newline characters.
+Specifies the command to run. Surround it with double quotes as shown if
+it contains one or more spaces. It can contain any variables from the
+template file, but not newline characters.
 
 =back
 
 =head1 EXAMPLES
 
-The following example A instruction sets a password lifetime of
-254 days, prohibits password reuse, limits the number of consecutive failed
+The following example A instruction sets a password lifetime of 254 days,
+prohibits password reuse, limits the number of consecutive failed
 authentication attempts to nine and sets the corresponding locktime to
-25:30 minutes (which is a multiple of 8.5 minutes). The
-username is read in from the B<-user> argument to the B<uss
-add> command or from the I<username> field in each B<add>
-instruction in a bulk input file.
+25:30 minutes (which is a multiple of 8.5 minutes). The username is read
+in from the B<-user> argument to the B<uss add> command or from the
+I<username> field in each C<add> instruction in a bulk input file.
 
    A $USER 254 noreuse 9 25:30
 
-The following example D instruction creates a directory called
-I<public> in a new user's home directory, designates the user as
-the directory's owner, and grants him or her all ACL permissions.
+The following example C<D> instruction creates a directory called
+F<public> in a new user's home directory, designates the user as the
+directory's owner, and grants him or her all ACL permissions.
 
    D $MTPT/public 0755 $UID $USER all 
 
-The following example E instruction creates a file in the
-current working directory called
-I<username>.B<etcp>. The contents are an entry
-suitable for incorporating into the cell's global
-B</etc/password> file.
+The following example C<E> instruction creates a file in the current
+working directory called F<I<username>.etcp>. The contents are an entry
+suitable for incorporating into the cell's global F</etc/password> file.
 
    E  $USER.etcp  0644 root "$USER:X:$UID:10:$NAME:$MTPT:/bin/csh"
 
-The following example F instruction, appropriate for the ABC
-Corporation cell, copies a prototype B<.login> file into the
-user's home directory.
+The following example C<F> instruction, appropriate for the ABC
+Corporation cell, copies a prototype F<.login> file into the user's home
+directory.
 
    F $MTPT/.login 0644 $UID /afs/abc.com/common/uss/skel/.login 
 
 In the following example, the State University cell's administrators
 have decided to distribute user home directories evenly into three
-directories. They define three B<G> instructions:
+directories. They define three C<G> instructions:
 
    G usr1
    G usr2
    G usr3
 
-and then put the following value in the I<mount_point> field of the
-B<V> instruction:
+and then put the following value in the <mount_point> field of the C<V>
+instruction:
 
    /afs/stateu.edu/$AUTO/$USER
 
-Alternatively, if they include the entire directory pathname in the
-B<G> instruction:
+Alternatively, if they include the entire directory pathname in the C<G>
+instruction:
 
    G /afs/stateu.edu/usr1
    G /afs/stateu.edu/usr2
    G /afs/stateu.edu/usr3
 
-then the I<mount_point> field of the V instruction
-specifies only the following:
+then the <mount_point> field of the C<V> instruction specifies only the
+following:
 
    $AUTO/$USER
 
-The following example L instruction creates a hard link between
-the files B<mail> and B<mbox> in the user's home
-directory.
+The following example C<L> instruction creates a hard link between the
+files F<mail> and F<mbox> in the user's home directory.
 
    L $MTPT/mbox $MTPT/mail
 
-The following example S instruction, appropriate for the ABC
-Corporation cell, links the file B<Mail/outgoing> in the user's
-home directory to the file
-B</afs/abc.com/common/mail/outgoing>.
+The following example C<S> instruction, appropriate for the ABC
+Corporation cell, links the file F<Mail/outgoing> in the user's home
+directory to the file F</afs/abc.com/common/mail/outgoing>.
 
    S /afs/abc.com/common/mail/outgoing $MTPT/Mail/outgoing
 
-The following example V instruction creates a volume called
-B<user.>I<username> on the B</vicepa> partition
-of the specified file server machine, assigning it a quota of 3000 kilobyte
-blocks. The mount point is under B</afs/abc.com/usr> and
-matches the username (the value of the $USER variable). The user owns
-the home directory and has all access rights to it. The instruction
-appears on two lines only for legibility; it must appear on a single line
-in the template file.
+The following example C<V> instruction creates a volume called
+C<user.I<username>> on the F</vicepa> partition of the specified file
+server machine, assigning it a quota of 3000 kilobyte blocks. The mount
+point is under F</afs/abc.com/usr> and matches the username (the value of
+the $USER variable). The user owns the home directory and has all
+access rights to it. The instruction appears on two lines only for
+legibility; it must appear on a single line in the template file.
 
-   V user.$USER $SERVER.abc.com /vicepa 3000   \
+   V user.$USER $SERVER.abc.com /vicepa 3000 \
            /afs/abc.com/usr/$USER $UID $USER all 
 
-The following example X instruction mounts the backup version of
-the user's volume at the B<OldFiles> subdirectory.
+The following example C<X> instruction mounts the backup version of the
+user's volume at the F<OldFiles> subdirectory.
 
    X "fs mkm /afs/abc.com/usr/$USER/OldFiles   user.$USER.backup"
 
 =head1 SEE ALSO
 
-L<uss Bulk Input File(1)>
-
+L<uss_bulk(5)>,
 L<fs_mkmount(1)>,
-L<uss_add(1)>
+L<uss_add(8)>
 
 =head1 COPYRIGHT
 
index 213f502..6a9fd5e 100644 (file)
@@ -1,37 +1,34 @@
 =head1 NAME
 
-uss Bulk Input File - Provides instructions for the uss bulk command
+uss_bulk - Provides instructions for the uss bulk command
 
 =head1 DESCRIPTION
 
-The uss bulk input file lists instructions for the
-B<uss> command interpreter to execute when running the B<uss
-bulk> command. If the file includes B<add> instructions
-that reference a B<uss> template file, then the template file must
-also exist.
+The uss bulk input file lists instructions for the B<uss> command
+interpreter to execute when running the B<uss bulk> command. If the file
+includes C<add> instructions that reference a B<uss> template file, then
+the template file must also exist.
 
-Summary of Bulk Input File Instructions
+=head2 Summary of Bulk Input File Instructions
 
-The bulk input file can include the following instructions, each on its own
-line. A more detailed description of each instruction's syntax
-follows this list.
+The bulk input file can include the following instructions, each on its
+own line. A more detailed description of each instruction's syntax follows
+this list.
 
 =over 4
 
 =item add
 
-Creates a user account. Equivalent to the uss add
-command.
+Creates a user account. Equivalent to the B<uss add> command.
 
 =item delete
 
-Deletes a user account. Equivalent to the uss delete
-command.
+Deletes a user account. Equivalent to the B<uss delete> command.
 
 =item delvolume
 
 Removes the volume and VLDB entry for each account referenced by a
-B<delete> instruction that follows this instruction in the bulk input
+C<delete> instruction that follows this instruction in the bulk input
 file.
 
 =item exec
@@ -41,339 +38,298 @@ Executes a command.
 =item savevolume
 
 Preserves the volume and VLDB entry for each account referenced by a
-B<delete> instruction that follows this instruction in the bulk input
+C<delete> instruction that follows this instruction in the bulk input
 file.
 
 =back
 
-The add Instruction for Creating an Account
-L<(1)>
-L<(1)>
+=head2 The add Instruction for Creating an Account
 
-The add instruction creates a user account. Each instance
-in the bulk input file is equivalent in effect to a B<uss add> command
-issued on the command line. The order of the instruction's fields
-matches the order of arguments to the B<uss add> command, although
-some arguments do not have a corresponding field. Like the B<uss
-add> command's arguments, many of the fields correspond to (provide
-a value for) a variable in the B<uss> template file, as indicated in
-the following description of each field.
+The C<add> instruction creates a user account. Each instance in the bulk
+input file is equivalent in effect to a B<uss add> command issued on the
+command line. The order of the instruction's fields matches the order of
+arguments to the B<uss add> command, although some arguments do not have a
+corresponding field. Like the B<uss add> command's arguments, many of the
+fields correspond to (provide a value for) a variable in the B<uss>
+template file, as indicated in the following description of each field.
 
-The instruction's syntax is as follows. It appears on multiple
-lines here only for the sake of legibility--each B<add>
-instruction must appear on a single line in the bulk input file.
+The instruction's syntax is as follows. It appears on multiple lines here
+only for the sake of legibility -- each C<add> instruction must appear on
+a single line in the bulk input file.
 
-   add I<username>[:I<full_name>][:I<initial_password>][:I<password_expires>]
-       [:I<file_server>][:I<partition>][:I<mount_point>][:I<uid>][:I<var1>][:I<var2>]
-       [:I<var3>][:I<var4>][:I<var5>][:I<var6>][:I<var7>][:I<var8>][:I<var9>][:]
+   add <username>[:<full_name>][:<password>][:<expires>]
+       [:<file_server>][:<partition>][:<mount_point>][:<uid>]
+       [:<var1>][:<var2>][:<var3>][:<var4>][:<var5>][:<var6>][:<var7>]
+       [:<var8>][:<var9>][:]
 
 To omit a value for a field (presumably because it is optional or the
 template specifies a constant value for it), type nothing between the two
 colons that surround it. After the last argument provided, end the line
 with either a colon and carriage return, or a carriage return alone.
 
-The meaning of, and acceptable values for, each field are as
-follows.
+The meaning of, and acceptable values for, each field are as follows.
 
 =over 4
 
-=item I<username
->
+=item <username>
 
 Names the user's Authentication Database and Protection Database
-entries. It can include up to eight alphanumeric characters, but not
-the B<:> (colon), B<.> (period), or B<@>
-(at-sign) characters. Because it becomes the username (the name under
-which a user logs in), it is best not to include shell metacharacters and to
-obey the restrictions that many operating systems impose on usernames
-(usually, to contain no more than eight lowercase letters).
-
-Corresponding argument to the uss add command:
-B<-user>. Corresponding variable in the template file:
-$USER.
-
-=item I<full_name
->
-
-Specifies the user's full name. Do not surround it with double
-quotes (""), even if it contains spaces. If not provided, it defaults
-to the username in the I<username> field. 
-
-Corresponding argument to the uss add command:
-B<-realname>. Corresponding variable in the template
-file: $NAME. Many operating systems include a field for the full
-name in a user's entry in the local password file (B</etc/passwd>
-or equivalent), and this variable can be used to pass a value to be used in
-that field.
-
-=item I<initial_password
->
-
-Specifies the user's initial password. Although the AFS
-commands that handle passwords accept strings of virtually unlimited length,
-it is best to use a password of eight characters or less, which is the maximum
-length that many applications and utilities accept. If not provided,
-this argument defaults to the string B<changeme>.
-
-Corresponding argument to the uss add command:
-B<-pass>. Corresponding variable in the template file:
-none.
-
-=item I<password_expires
->
-
-Sets the number of days after a user's password is changed that it
-remains valid. Provide an integer from the range B<1> through
-B<254> to specify the number of days until expiration, or the value
-B<0> to indicate that the password never expires (the default).
+entries. It can include up to eight alphanumeric characters, but not the
+C<:> (colon), C<.> (period), or C<@> (at-sign) characters. Because it
+becomes the username (the name under which a user logs in), it is best not
+to include shell metacharacters and to obey the restrictions that many
+operating systems impose on usernames (usually, to contain no more than
+eight lowercase letters).
+
+Corresponding argument to the B<uss add> command: B<-user>. Corresponding
+variable in the template file: $USER.
+
+=item <full_name>
+
+Specifies the user's full name. Do not surround it with double quotes
+(C<"">), even if it contains spaces. If not provided, it defaults to the
+username in the <username> field.
+
+Corresponding argument to the B<uss add> command: B<-realname>.
+Corresponding variable in the template file: $NAME. Many operating systems
+include a field for the full name in a user's entry in the local password
+file (F</etc/passwd> or equivalent), and this variable can be used to pass
+a value to be used in that field.
+
+=item <password>
+
+Specifies the user's initial password. Although the AFS commands that
+handle passwords accept strings of virtually unlimited length, it is best
+to use a password of eight characters or less, which is the maximum length
+that many applications and utilities accept. If not provided, this
+argument defaults to the string C<changeme>.
+
+Corresponding argument to the B<uss add> command: B<-pass>. Corresponding
+variable in the template file: none.
+
+=item <expires>
+
+Sets the number of days after a user's password is changed that it remains
+valid. Provide an integer from the range C<1> through C<254> to specify
+the number of days until expiration, or the value C<0> to indicate that
+the password never expires (the default).
 
 When the password becomes invalid (expires), the user is unable to
 authenticate, but has 30 more days in which to issue the B<kpasswd>
-command to change the password (after that, only an administrator can change
-it).
+command to change the password (after that, only an administrator can
+change it).
 
-Corresponding argument to the uss add command:
-B<-pwexpires>. Corresponding variable in the template
-file: $PWEXPIRES.
+Corresponding argument to the B<uss add> command: B<-pwexpires>.
+Corresponding variable in the template file: $PWEXPIRES.
 
-=item I<file_server
->
+=item <file_server>
 
-Names the file server machine on which to create the new user's
-volume. It is best to provide a fully-qualified hostname (for example,
-B<fs1.abc.com>), but an abbreviated form is acceptable
-provided that the cell's naming service is available to resolve it at the
-time the volume is created.
+Names the file server machine on which to create the new user's volume. It
+is best to provide a fully-qualified hostname (for example,
+C<fs1.abc.com>), but an abbreviated form is acceptable provided that the
+cell's naming service is available to resolve it at the time the volume is
+created.
 
-Corresponding argument to the uss add command:
-B<-server>. Corresponding variable in the template file:
-$SERVER.
+Corresponding argument to the B<uss add> command: B<-server>.
+Corresponding variable in the template file: $SERVER.
 
-=item I<partition
->
+=item <partition>
 
-Specifies the partition on which to create the user's volume; it
-must reside on the file server machine named in the I<file_server>
+Specifies the partition on which to create the user's volume; it must
+reside on the file server machine named in the <file_server>
 field. Identify the partition by its complete name (for example,
-B</vicepa>, or use one of the following abbreviations: 
+F</vicepa>, or use one of the following abbreviations:
 
-   B</vicepa>     =     B<vicepa>      =      B<a>      =      0
-   B</vicepb>     =     B<vicepb>      =      B<b>      =      1
+   /vicepa     =     vicepa      =      a      =      0
+   /vicepb     =     vicepb      =      b      =      1
 
-After /vicepz (for which the index is 25) comes 
+After F</vicepz> (for which the index is 25) comes 
 
-   B</vicepaa>    =     B<vicepaa>     =      B<aa>     =      26
-   B</vicepab>    =     B<vicepab>     =      B<ab>     =      27
+   /vicepaa    =     vicepaa     =      aa     =      26
+   /vicepab    =     vicepab     =      ab     =      27
 
 and so on through 
 
-   B</vicepiv>    =     B<vicepiv>     =      B<iv>     =      255
+   /vicepiv    =     vicepiv     =      iv     =      255
 
-Corresponding argument to the uss add command:
-B<-partition>. Corresponding variable in template:
-$PART.
+Corresponding argument to the B<uss add> command: B<-partition>.
+Corresponding variable in template: $PART.
 
-=item I<mount_point
->
+=item <mount_point>
 
 Specifies the complete pathname for the user's home directory.
 
-Corresponding argument to the uss add command:
-B<-mount>.
-
-Corresponding variable in template: $MTPT, but in the template
-file's B<V> instruction only. Occurrences of the $MTPT
-variable in template instructions that follow the B<V> instruction
-take their value from the B<V> instruction's I<mount_point>
-field. Thus the value of this command line argument becomes the value
-for the $MTPT variable in instructions that follow the B<V>
-instruction only if the string $MTPT appears alone in the B<V>
-instruction's I<mount_point> field.
-
-=item I<uid
->
-
-Specifies a positive integer other than 0 (zero) to assign as
-the user's AFS UID. If this argument is omitted, the Protection
-Server assigns an AFS UID that is one greater than the current value of the
-C<max> C<user> C<id> counter (use the B<pts
-listmax> command to display the counter). If including this
-argument, first use the B<pts examine> command to verify that no
-existing account already has the desired AFS UID; if one does, the
+Corresponding argument to the B<uss add> command: B<-mount>.
+
+Corresponding variable in template: $MTPT, but in the template file's C<V>
+instruction only. Occurrences of the $MTPT variable in template
+instructions that follow the C<V> instruction take their value from the
+C<V> instruction's <mount_point> field. Thus the value of this command
+line argument becomes the value for the $MTPT variable in instructions
+that follow the C<V> instruction only if the string $MTPT appears alone in
+the C<V> instruction's <mount_point> field.
+
+=item <uid>
+
+Specifies a positive integer other than C<0> (zero) to assign as the
+user's AFS UID. If this argument is omitted, the Protection Server assigns
+an AFS UID that is one greater than the current value of the C<max user
+id> counter (use the B<pts listmax> command to display the counter). If
+including this argument, first use the B<pts examine> command to verify
+that no existing account already has the desired AFS UID; if one does, the
 account-creation process terminates with an error.
 
-Corresponding argument to the uss add command:
-B<-uid>. Corresponding variable in template: $UID.
+Corresponding argument to the B<uss add> command: B<-uid>. Corresponding
+variable in template: $UID.
 
-=item I<var1 through I<var9>
->
+=item <var1> through <var9>
 
 Specifies values for each of the number variables $1 through $9 that can
-appear in the template file. The number variables allow the
-administrator to provide values for variables other than the set defined by
-the B<uss> command suite.
+appear in the template file. The number variables allow the administrator
+to provide values for variables other than the set defined by the B<uss>
+command suite.
 
-Corresponding argument to the uss add command:
-B<-var>. Corresponding variables in template: $1 through
-$9.
+Corresponding argument to the B<uss add> command: B<-var>. Corresponding
+variables in template: $1 through $9.
 
 If providing a value in any of the fields, then in every field that
 precedes it either provide an actual value or indicate an empty field by
-putting nothing between two colons. It is acceptable, but not
-necessary, to indicate empty fields by putting colons after the last field
-that contains an actual value.
+putting nothing between two colons. It is acceptable, but not necessary,
+to indicate empty fields by putting colons after the last field that
+contains an actual value.
 
 =back
 
-The delete Instruction for Deleting an Account
-L<(1)>
-L<(1)>
+=head2 The delete Instruction for Deleting an Account
 
-The delete instruction deletes a user account from the
-system. Each instance in the bulk input file is equivalent in effect to
-a B<uss delete> command issued on the command line. The order
-of the instruction's fields matches the order of arguments to the
-B<uss delete> command:
+The C<delete> instruction deletes a user account from the system. Each
+instance in the bulk input file is equivalent in effect to a B<uss delete>
+command issued on the command line. The order of the instruction's fields
+matches the order of arguments to the B<uss delete> command:
 
-   delete I<username>:I<mount_point_path>[:{ savevolume | delvolume }][:]
+   delete <username>:<mount_point>[:( savevolume | delvolume )][:]
 
 where
 
 =over 4
 
-=item I<username
->
+=item <username>
 
 Names the entry to delete from the Protection and Authentication
 Databases.
 
-=item I<mount_point_path
->
+=item <mount_point>
 
-Specifies the complete pathname to the user's home directory, which
-is deleted from the filespace. By default, the volume mounted there is
-also deleted from the file server machine where it resides, as is its record
-from the Volume Location Database (VLDB). To prevent deletion, include
-the B<savevolume> string in the instruction's third field, or
-precede this B<delete> instruction with a B<savevolume>
-instruction. Partial pathnames are interpreted relative to the current
-working directory.
+Specifies the complete pathname to the user's home directory, which is
+deleted from the filespace. By default, the volume mounted there is also
+deleted from the file server machine where it resides, as is its record
+from the Volume Location Database (VLDB). To prevent deletion, include the
+C<savevolume> string in the instruction's third field, or precede this
+C<delete> instruction with a C<savevolume> instruction. Partial pathnames
+are interpreted relative to the current working directory.
 
 =item savevolume
 
 Retains the volume on its file server machine, and the corresponding entry
-in the VLDB. Provide this value or B<delvolume> in the third
-field, or omit both values to treat the volume according to the prevailing
-default, which is set by a preceding B<savevolume> or
-B<delvolume> instruction in the bulk input file.
+in the VLDB. Provide this value or C<delvolume> in the third field, or
+omit both values to treat the volume according to the prevailing default,
+which is set by a preceding C<savevolume> or C<delvolume> instruction in
+the bulk input file.
 
 =item delvolume
 
 Removes the volume from its file server machine, and the corresponding
-entry from the VLDB. Provide this value or B<savevolume> in the
-third field, or omit both values to treat the volume according to the
-prevailing default, which is set by a preceding B<savevolume> or
-B<delvolume> instruction in the bulk input file.
+entry from the VLDB. Provide this value or C<savevolume> in the third
+field, or omit both values to treat the volume according to the prevailing
+default, which is set by a preceding C<savevolume> or C<delvolume>
+instruction in the bulk input file.
 
 =back
 
 After the last argument provided, end the line with either a colon and
 carriage return or a carriage return alone.
 
-The exec Instruction for Executing a Command
+=head2 The exec Instruction for Executing a Command
 
-The exec instruction executes the specified command, which can
-be a UNIX shell script or command, a program, or an AFS command. The
-B<uss> command interpreter must have the necessary privileges in AFS
-and the local file system; it assumes the AFS and local identities of the
-issuer of the B<uss bulk> command.
+The C<exec> instruction executes the specified command, which can be a
+UNIX shell script or command, a program, or an AFS command. The B<uss>
+command interpreter must have the necessary privileges in AFS and the
+local file system; it assumes the AFS and local identities of the issuer
+of the B<uss bulk> command.
 
 The instruction's syntax is as follows:
 
-   exec I<command>
+   exec <command>
 
-The delvolume and savevolume Instructions for Setting the Default
-Treatment of Volumes
-L<(1)>
-L<(1)>
-L<(1)>
-L<(1)>
+=head2 The delvolume and savevolume Instructions
 
-The B<savevolume> and delvolume instructions determine
-the default treatment of volumes referenced by the B<delete>
-instructions that follow them in the bulk input file. Their syntax is
-as follows:
+The C<savevolume> and C<delvolume> instructions determine the default
+treatment of volumes referenced by the C<delete> instructions that follow
+them in the bulk input file. Their syntax is as follows:
 
    savevolume
    delvolume
 
-The savevolume instruction prevents the removal of the volume
-and VLDB entry for all B<delete> instruction that follow it in the
-bulk input file, and the B<delvolume> instruction removes the volume
-and VLDB entry for all subsequent B<delete> instructions.
-Either setting persists until its opposite appears in the file, or until the
-end of the bulk file.
+The C<savevolume> instruction prevents the removal of the volume and VLDB
+entry for all C<delete> instruction that follow it in the bulk input file,
+and the C<delvolume> instruction removes the volume and VLDB entry for all
+subsequent C<delete> instructions.  Either setting persists until its
+opposite appears in the file, or until the end of the bulk file.
 
 If neither line appears in the bulk input file, the default is to remove
-the volume and the VLDB entry; B<delete> instructions that appear
-before the first B<savevolume> instruction are also subject to this
-default. If a B<delete> instruction's third field
-specifies either B<savevolume> or B<delvolume>, that setting
-overrides the default.
+the volume and the VLDB entry; C<delete> instructions that appear before
+the first C<savevolume> instruction are also subject to this default. If a
+C<delete> instruction's third field specifies either C<savevolume> or
+C<delvolume>, that setting overrides the default.
 
 =head1 EXAMPLES
 
-The following example add instruction creates an
-authentication-only account. The user's initial password is
-B<changeme> (the default).
+The following example add instruction creates an authentication-only
+account. The user's initial password is C<changeme> (the default).
 
    add anderson
 
-The following example add instructions refer to the indicated
-B<V> instruction in a template file (which must appear on a single
-line in the template file). 
+The following example add instructions refer to the indicated C<V>
+instruction in a template file (which must appear on a single line in the
+template file).
 
    add smith:John Smith:::fs1:a:::::marketing 
    add jones:Pat Jones:::fs3:c:::::finance
    V user.$USER $SERVER.abc.com /vicep$PART 2000 \
        /afs/abc.com/usr/$3/$USER $UID $USER all
 
-The first add instruction creates an account called
-B<smith> in the Protection and Authentication Databases, with an
-initial password B<changeme> and a value for $UID provided by the
-Protection Server. The volume B<user.smith> resides on
-partition B</vicepa> of file server machine
-B<fs1.abc.com> and is mounted at
-B</afs/abc.com/usr/marketing/smith>. He owns his home
-directory and has all access permissions on its root directory's access
-control list (ACL). The account for B<jones> is similar, except
-that the volume resides on partition B</vicepc> of file server machine
-B<fs3.abc.com> and is mounted at
-B</afs/abc.com/usr/finance/jones>.
+The first add instruction creates an account called C<smith> in the
+Protection and Authentication Databases, with an initial password
+C<changeme> and a value for $UID provided by the Protection Server. The
+volume C<user.smith> resides on partition F</vicepa> of file server
+machine C<fs1.abc.com> and is mounted at
+F</afs/abc.com/usr/marketing/smith>. He owns his home directory and has
+all access permissions on its root directory's access control list
+(ACL). The account for C<jones> is similar, except that the volume resides
+on partition F</vicepc> of file server machine C<fs3.abc.com> and is
+mounted at F</afs/abc.com/usr/finance/jones>.
 
 Notice that the fields corresponding to the volume mount point, UID, $1
-variable, and $2 variable are empty (between C<a> and
-C<marketing> on the first example line), because their corresponding
-variables do not appear in the template file. The initial password
-field is also empty.
+variable, and $2 variable are empty (between C<a> and C<marketing> on the
+first example line), because their corresponding variables do not appear
+in the template file. The initial password field is also empty.
 
-The following add instructions are equivalent in effect to the
-preceding example, but explicitly indicate empty fields for all of the number
+The following add instructions are equivalent in effect to the preceding
+example, but explicitly indicate empty fields for all of the number
 variables that don't have a value:
 
    add smith:John Smith:::fs1:a:::::marketing::::::
    add jones:Pat Jones:::fs3:c:::::finance::::::
 
 The following example shows a complete bulk file containing a set of
-B<delete> instructions combined with a B<savevolume>
-instruction. Because the B<delete> instruction for users
-B<smith>, B<pat>, and B<rogers> appear before the
-B<savevolume> instruction and the third field is blank in each, the
-corresponding home volumes are removed. The volume for user
-B<terry> is retained because the default established by the
-B<savevolume> instruction applies to it, but user
-B<johnson>'s volume is removed because the third field of her
-B<delete> instruction overrides the current default.
+C<delete> instructions combined with a C<savevolume> instruction. Because
+the C<delete> instruction for users C<smith>, C<pat>, and C<rogers> appear
+before the C<savevolume> instruction and the third field is blank in each,
+the corresponding home volumes are removed. The volume for user C<terry>
+is retained because the default established by the C<savevolume>
+instruction applies to it, but user C<johnson>'s volume is removed because
+the third field of her C<delete> instruction overrides the current
+default.
 
    delete smith:/afs/abc.com/usr/smith
    delete pat:/afs/abc.com/usr/pat
@@ -382,21 +338,19 @@ B<delete> instruction overrides the current default.
    delete terry:/afs/abc.com/usr/terry
    delete johnson:/afs/abc.com/usr/johnson:delvolume
 
-The following example exec instruction appears between sets of
-B<add> and B<delete> instructions in a bulk input file.
-A message appears in the command shell where the B<uss bulk> command
-is issued, to indicate when the additions are finished and the deletions
-beginning.
+The following example exec instruction appears between sets of C<add> and
+C<delete> instructions in a bulk input file.  A message appears in the
+command shell where the B<uss bulk> command is issued, to indicate when
+the additions are finished and the deletions beginning.
 
    exec echo "Additions completed; beginning deletions..."
 
 =head1 SEE ALSO
 
-L<uss Template File(1)>
-
-L<uss_add(1)>,
-L<uss_bulk(1)>,
-L<uss_delete(1)>
+L<uss(5)>,
+L<uss_add(8)>,
+L<uss_bulk(8)>,
+L<uss_delete(8)>
 
 =head1 COPYRIGHT
 
index 915d5d6..a9d3abc 100644 (file)
@@ -1,35 +1,35 @@
 =head1 NAME
 
-vldb.DB0 and vldb.DBSYS1 - Contain the Volume Location Database and associated log
+vldb.DB0, vldb.DBSYS1 - Contain the Volume Location Database and associated log
 
 =head1 DESCRIPTION
 
-The file vldb.DB0 contains the Volume Location Database
-(VLDB), which tracks the location of all AFS volumes stored on file server
-machines in the cell. The Volume Location (VL) Server
-(B<vlserver> process) provides information from the database to Cache
-Managers when they need to access AFS data.
+The file F<vldb.DB0> contains the Volume Location Database (VLDB), which
+tracks the location of all AFS volumes stored on file server machines in
+the cell. The Volume Location (VL) Server (B<vlserver> process) provides
+information from the database to Cache Managers when they need to access
+AFS data.
 
-The file vldb.DBSYS1 is a log file in which the VL Server
-logs each database operation before performing it. When an operation is
-interrupted, the VL Server replays the log to complete the operation.
+The file F<vldb.DBSYS1> is a log file in which the VL Server logs each
+database operation before performing it. When an operation is interrupted,
+the VL Server replays the log to complete the operation.
 
-Both files are in binary format and reside in the /usr/afs/db
-directory on each of the cell's database server machines. When the
-VL Server starts or restarts on a given machine, it establishes a connection
-with its peers and verifies that its copy of the database matches the copy on
-the other database server machines. If not, the VL Servers call on
-AFS's distributed database technology, Ubik, to distribute to all of the
-machines the copy of the database with the highest version number.
+Both files are in binary format and reside in the F</usr/afs/db> directory
+on each of the cell's database server machines. When the VL Server starts
+or restarts on a given machine, it establishes a connection with its peers
+and verifies that its copy of the database matches the copy on the other
+database server machines. If not, the VL Servers call on AFS's distributed
+database technology, Ubik, to distribute to all of the machines the copy
+of the database with the highest version number.
 
-Always use the commands in the vos suite to administer the
-VLDB. It is advisable to create an archive copy of the database on a
-regular basis, using a tool such as the UNIX B<tar> command.
+Always use the commands in the B<vos> suite to administer the VLDB. It is
+advisable to create an archive copy of the database on a regular basis,
+using a tool such as the UNIX B<tar> command.
 
 =head1 SEE ALSO
 
-L<vldb_check(1)>,
-L<vlserver(1)>,
+L<vldb_check(8)>,
+L<vlserver(8)>,
 L<vos(1)>
 
 =head1 COPYRIGHT
index 4491921..c93f522 100644 (file)
@@ -156,7 +156,7 @@ Sets the size of each cache I<chunk>, and by implication the amount of
 data that the Cache Manager requests at a time from the File Server (how
 much data per fetch RPC, since AFS uses partial file transfer).
 
-For a disk cache, a chunk is a F<< VIZ<><n> >> file and this parameter
+For a disk cache, a chunk is a F<VI<n>> file and this parameter
 sets the maximum size to which each one can expand; the default is 64
 KB. For a memory cache, each chunk is a collection of contiguous memory
 blocks; the default is size is 8 KB.
@@ -171,7 +171,7 @@ the number of dcache entries, resulting in a slightly smaller cache.
 
 Sets the number of chunks in the cache. For a memory cache, the number of
 chunks is equal to the cache size divided by the chunk size.  For a disk
-cache, the number of chunks (F<< VIZ<><n> >> files) is set to the largest
+cache, the number of chunks (F<VI<n>> files) is set to the largest
 of the following unless the B<-files> argument is used to set the value
 explicitly:
 
@@ -198,7 +198,7 @@ Sets the number of I<dcache entries> allocated in machine memory for
 storing information about the chunks in the cache.
 
 For a disk cache, the F</usr/vice/cache/CacheItems> file contains one
-entry for each F<< VIZ<><n> >> file. By default, one half the number of
+entry for each F<VI<n>> file. By default, one half the number of
 these entries (but not more that 2,000) are duplicated as dcache entries
 in machine memory for quicker access.
 
@@ -360,9 +360,9 @@ doing so can possibly result in a chunk size that is not an exponent of 2.
 
 =item B<-files> <I<files in cache>>
 
-Specifies the number of F<< VIZ<><n> >> files to create in the cache
+Specifies the number of F<VI<n>> files to create in the cache
 directory for a disk cache, overriding the default that is calculated as
-described in L<DESCRIPTION>. Each F<< VIZ<><n> >> file accommodates a
+described in L<DESCRIPTION>. Each F<VI<n>> file accommodates a
 chunk of data, and can grow to a maximum size of 64 KB by default. Do not
 combine this argument with the B<-memcache> argument.
 
@@ -451,7 +451,7 @@ requires that the issuer calculate the cache size that results.
 
 Sets the number of dcache entries in memory, which are used to store
 information about cache chunks. For a disk cache, this overrides the
-default, which is 50% of the number of F<< VIZ<><n> >> files (cache
+default, which is 50% of the number of F<VI<n>> files (cache
 chunks). For a memory cache, this argument effectively sets the number of
 cache chunks, but its use is not recommended, because it requires the
 issuer to calculate the resulting total cache size (derived by multiplying
@@ -550,7 +550,7 @@ The issuer must be logged in as the local superuser root.
 
 =head1 SEE ALSO
 
-L<CacheItems(5)>,
+L<afs_cache(5)>,
 L<CellServDB(5)>,
 L<cacheinfo(5)>
 
index f5ad974..c199d90 100644 (file)
@@ -248,6 +248,7 @@ L<CellServDB(5)>,
 L<KeyFile(5)>,
 L<ThisCell(5)>,
 L<UserList(5)>,
+L<butc(5)>,
 L<tapeconfig(5)>,
 L<backup_adddump(8)>,
 L<backup_addhost(8)>,
index e59e6e8..c1b6183 100644 (file)
@@ -256,6 +256,7 @@ server machine as the local superuser C<root>.
 
 =head1 SEE ALSO
 
+L<butc(5)>,
 L<backup(8)>,
 L<backup_dump(8)>,
 L<backup_volrestore(8)>,
index 617f516..3edbbf5 100644 (file)
@@ -498,6 +498,7 @@ server machine as the local superuser C<root>.
 
 =head1 SEE ALSO
 
+L<butc(5)>,
 L<backup(8)>,
 L<backup_adddump(8)>,
 L<backup_addvolentry(8)>,
index 1b8a7be..66f2a62 100644 (file)
@@ -401,6 +401,7 @@ included.
 
 =head1 SEE ALSO
 
+L<butc(5)>,
 L<backup(8)>,
 L<backup_deletedump(8)>
 
index 54b1418..a172e96 100644 (file)
@@ -199,6 +199,7 @@ included.
 
 =head1 SEE ALSO
 
+L<butc(5)>,
 L<backup(8)>,
 L<backup_readlabel(8)>,
 L<butc(1)>
index 6c9d8d6..af700f9 100644 (file)
@@ -221,6 +221,7 @@ included.
 
 =head1 SEE ALSO
 
+L<butc(5)>,
 L<backup(8)>,
 L<backup_labeltape(8)>,
 L<butc(8)>
index b415deb..81f3a51 100644 (file)
@@ -103,6 +103,7 @@ included.
 
 =head1 SEE ALSO
 
+L<butc(5)>,
 L<backup(8)>,
 L<backup_dbverify(8)>,
 L<backup_savedb(8)>,
index 23e8dc3..705380b 100644 (file)
@@ -140,6 +140,7 @@ included.
 
 =head1 SEE ALSO
 
+L<butc(5)>,
 L<backup(8)>,
 L<backup_dbverify(8)>,
 L<backup_restoredb(8)>,
index 0d65f8e..5ef3ded 100644 (file)
@@ -333,6 +333,7 @@ included.
 
 =head1 SEE ALSO
 
+L<butc(5)>,
 L<backup(8)>,
 L<backup_dump(8)>,
 L<backup_dumpinfo(8)>,
index a4c5371..be3bfc0 100644 (file)
@@ -290,6 +290,7 @@ server machine as the local superuser C<root>.
 
 =head1 SEE ALSO
 
+L<butc(5)>,
 L<backup(8)>,
 L<backup_dump(8)>,
 L<backup_diskrestore(8)>,
index 031ab79..6f7aa2d 100644 (file)
@@ -383,6 +383,7 @@ server machine as the local superuser C<root>.
 
 =head1 SEE ALSO
 
+L<butc(5)>,
 L<backup(8)>,
 L<backup_addvolentry(8)>,
 L<backup_addvolset(8)>,
index dc386c4..6bcd4fe 100644 (file)
@@ -203,6 +203,8 @@ configuration files in the local F</usr/afs/backup> directory.
 L<KeyFile(5)>,
 L<ThisCell(5)>,
 L<UserList(5)>,
+L<butc(5)>,
+L<butc_logs(5)>,
 L<tapeconfig(5)>,
 L<backup_addhost(8)>