Administration Reference
- ![[Return to Library]](../books.gif)
![[Table of Contents]](../toc.gif)
![[Bottom of Topic]](../bot.gif)
![[Next Topic]](../next.gif)
![[Index]](../index.gif)
- AFS
- Administration Reference
-
Version 3.6 -
Document Number GC09-4562-00 -
-
-
First Edition (April 2000) -
This edition applies to: -
-
-
- IBM AFS for AIX, Version 3.6
-
- IBM AFS for Digital Unix, Version 3.6 -
- IBM AFS for HP-UX, Version 3.6 -
- IBM AFS for Linux, Version 3.6 -
- IBM AFS for SGI IRIX, Version 3.6 -
- IBM AFS for Solaris, Version 3.6 -
- IBM AFS for Digital Unix, Version 3.6 -
and to all subsequent releases and modifications until otherwise indicated - in new editions. -
This softcopy version is based on the printed edition of this book. - Some formatting amendments have been made to make this information more - suitable for softcopy. -
Order publications through your IBM representative or through the IBM - branch office serving your locality. -
-
![[Top of Topic]](../top.gif)
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf002.htm diff -c openafs/doc/html/AdminReference/auarf002.htm:1.1 openafs/doc/html/AdminReference/auarf002.htm:removed *** openafs/doc/html/AdminReference/auarf002.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf002.htm Fri Jul 18 12:42:14 2008 *************** *** 1,314 **** - - -
Administration Reference
- ![[Previous Topic]](../prev.gif)
-
Table of Contents
-Tables
-
Index
-
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf003.htm diff -c openafs/doc/html/AdminReference/auarf003.htm:1.1 openafs/doc/html/AdminReference/auarf003.htm:removed *** openafs/doc/html/AdminReference/auarf003.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf003.htm Fri Jul 18 12:42:14 2008 *************** *** 1,29 **** - - -
Administration Reference
-
-
-
Tables
- -
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf004.htm diff -c openafs/doc/html/AdminReference/auarf004.htm:1.1 openafs/doc/html/AdminReference/auarf004.htm:removed *** openafs/doc/html/AdminReference/auarf004.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf004.htm Fri Jul 18 12:42:14 2008 *************** *** 1,28 **** - - -
Administration Reference
-
-
-
About This Manual
-This chapter describes the purpose, organization, and conventions of this - document. -
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf005.htm diff -c openafs/doc/html/AdminReference/auarf005.htm:1.1 openafs/doc/html/AdminReference/auarf005.htm:removed *** openafs/doc/html/AdminReference/auarf005.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf005.htm Fri Jul 18 12:42:14 2008 *************** *** 1,32 **** - - -
Administration Reference
-
-
Audience and Purpose
-This reference manual details the syntax of each - AFS(R) command and is intended for the experienced AFS - administrator, programmer, or user. -
In general, this document does not explain when to use a command or its - place in the sequence of commands that make up a complete procedure. - For that type of information, refer to the IBM AFS Administration - Guide. -
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf006.htm diff -c openafs/doc/html/AdminReference/auarf006.htm:1.1 openafs/doc/html/AdminReference/auarf006.htm:removed *** openafs/doc/html/AdminReference/auarf006.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf006.htm Fri Jul 18 12:42:14 2008 *************** *** 1,55 **** - - -
Administration Reference
-
-
Organization
-This document presents AFS files and commands in separate - sections, with the files or commands in alphabetical order. -
The following sections of each reference page provide the indicated type of - information: -
-
-
- Purpose briefly describes the command's function. -
- Synopsis displays the complete syntax statement for a command, - which specifies the required order for all options, using the same notation as - the AFS online help. If abbreviating the command name and option names - is acceptable, as it is for most commands, a second statement specifies the - shortest acceptable abbreviation of each name. If the command has an - alias, it also appears in this section. -
- Description describes the file or command's function in - detail. -
- Cautions describes restrictions, requirements, and potential - complications in use of the command. It appears only when - necessary. -
- Options describes the function and required form of each - argument and flag. -
- Output describes any output the command writes to the standard - output stream. This section does not appear if the command does not - produce output or if the only output is a message confirming the - command's success. -
- Examples provides one or more sample commands and resulting - output. -
- Privilege Required lists each privilege required to perform the - command. -
- Related Information lists related commands and files, if - any. -
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf007.htm diff -c openafs/doc/html/AdminReference/auarf007.htm:1.1 openafs/doc/html/AdminReference/auarf007.htm:removed *** openafs/doc/html/AdminReference/auarf007.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf007.htm Fri Jul 18 12:42:14 2008 *************** *** 1,28 **** - - -
Administration Reference
-
-
How to Use This Document
-Refer to this document when you need detailed information - about a specific command. For a description of all the steps in a - procedure, refer to the IBM AFS Administration Guide. -
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf008.htm diff -c openafs/doc/html/AdminReference/auarf008.htm:1.1 openafs/doc/html/AdminReference/auarf008.htm:removed *** openafs/doc/html/AdminReference/auarf008.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf008.htm Fri Jul 18 12:42:14 2008 *************** *** 1,56 **** - - -
Administration Reference
-
-
Related Documents
-The following documents are included in the AFS documentation - set. -
IBM AFS Administration Guide -
This guide describes the concepts and procedures that a system - administrator must know to manage an AFS cell. It assumes familiarity - with UNIX, but requires no previous knowledge of AFS. -
The first chapters of the IBM AFS Administration Guide present - basic concepts and guidelines. Understanding them is crucial to - successful administration of an AFS cell. The remaining chapters in the - guide provide step-by-step instructions for specific administrative tasks, - along with discussions of the concepts important to that particular - task. -
IBM AFS Quick Beginnings -
This guide provides instructions for installing AFS server and client - machines. It is assumed that the installer is an experienced UNIX - (R) system administrator. -
For predictable performance, machines must be installed and configured in - accordance with the instructions in this guide. -
IBM AFS Release Notes -
This document provides information specific to each release of AFS, such as - a list of new features and commands, a list of requirements and limitations, - and instructions for upgrading server and client machines. -
IBM AFS User Guide -
This guide presents the basic concepts and procedures necessary for using - AFS effectively. It assumes that the reader has some experience with - UNIX, but does not require familiarity with networking or AFS. -
The guide explains how to perform basic functions, including - authenticating, changing a password, protecting AFS data, creating groups, and - troubleshooting. It provides illustrative examples for each function - and describes some of the differences between the UNIX file system and - AFS. -
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf009.htm diff -c openafs/doc/html/AdminReference/auarf009.htm:1.1 openafs/doc/html/AdminReference/auarf009.htm:removed *** openafs/doc/html/AdminReference/auarf009.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf009.htm Fri Jul 18 12:42:14 2008 *************** *** 1,57 **** - - -
Administration Reference
-
-
Typographical Conventions
-This document uses the following typographical - conventions: -
-
-
- Command and option names appear in bold type in syntax - definitions, examples, and running text. Names of directories, files, - machines, partitions, volumes, and users also appear in bold - type. -
- Variable information appears in italic type. This - includes user-supplied information on command lines and the parts of prompts - that differ depending on who issues the command. New terms also appear - in italic type. -
- Examples of screen output and file contents appear in monospace - type. -
In addition, the following symbols appear in command syntax definitions, - both in the documentation and in AFS online help statements. When - issuing a command, do not type these symbols. -
-
-
- Square brackets [ ] surround optional items. -
- Angle brackets < > surround user-supplied values in AFS - commands. -
- A superscripted plus sign + follows an argument that accepts - more than one value. -
- The percent sign % represents the regular command shell - prompt. Some operating systems possibly use a different character for - this prompt. -
- The number sign # represents the command shell prompt for the - local superuser root. Some operating systems possibly use a - different character for this prompt. -
- The pipe symbol | in a command syntax statement separates - mutually exclusive values for an argument. -
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf010.htm diff -c openafs/doc/html/AdminReference/auarf010.htm:1.1 openafs/doc/html/AdminReference/auarf010.htm:removed *** openafs/doc/html/AdminReference/auarf010.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf010.htm Fri Jul 18 12:42:14 2008 *************** *** 1,26 **** - - -
Administration Reference
-
-
AFS System Files
--
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf011.htm diff -c openafs/doc/html/AdminReference/auarf011.htm:1.1 openafs/doc/html/AdminReference/auarf011.htm:removed *** openafs/doc/html/AdminReference/auarf011.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf011.htm Fri Jul 18 12:42:14 2008 *************** *** 1,124 **** - - -
Administration Reference
-
-
-
afs_file_intro
-Purpose -
Introduction to AFS files -
Description -
A number of files must reside on the local disk of AFS server and client - machines. They belong to the following general categories: -
-
-
- Configuration files define configuration parameters for - specific server and kernel processes such as the Backup System Tape - Coordinator or the Cache Manager -
- Administrative files list information used in administration of - server machines, such as a list of privileged users or server encryption keys -
- Cache-related files contain cached data or information about - cached data, on client machines -
- Log files contain tracing messages about the operation of a - specific process -
- Database files contain database records used to administer the - AFS cell -
- Controller files control the behavior of a process -
- Volume header files represent AFS volumes on server partitions -
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 - ( \ ) rather than a forward slash - ( / ) to separate the elements in a - pathname. -
Related Information -
- --
-
Vn -
Controller files: -
-
-
NoAuth -
Volume header files: -
-
-
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf012.htm diff -c openafs/doc/html/AdminReference/auarf012.htm:1.1 openafs/doc/html/AdminReference/auarf012.htm:removed *** openafs/doc/html/AdminReference/auarf012.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf012.htm Fri Jul 18 12:42:14 2008 *************** *** 1,57 **** - - -
Administration Reference
-
-
-
AuthLog
-Traces Authentication Server operations -
Description -
The AuthLog file records a trace of Authentication Server - (kaserver process) operations on the local machine and describes - any error conditions it encounters. -
If the AuthLog file does not exist in the - /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 - AuthLog.old, overwriting the existing - AuthLog.old file if it exists. -
The file is in ASCII format. Administrators listed in the - /usr/afs/etc/UserList file can use the 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 - cat command. By default, the mode bits on the - AuthLog file grant the required 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. -
Related Information -
UserList -
kaserver -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf013.htm diff -c openafs/doc/html/AdminReference/auarf013.htm:1.1 openafs/doc/html/AdminReference/auarf013.htm:removed *** openafs/doc/html/AdminReference/auarf013.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf013.htm Fri Jul 18 12:42:14 2008 *************** *** 1,49 **** - - -
Administration Reference
-
-
-
AuthLog.dir, AuthLog.pag
-Records privileged operations performed by the Authentication Server -
Description -
The AuthLog.dir and AuthLog.pag files - record a trace of privileged operations performed by the Authentication Server - (kaserver process) on the local machine. If the files do not - exist when the Authentication Server starts, it creates them in the - /usr/afs/logs directory as necessary. -
The files are in binary format. To display their contents, use the - kdb command, which requires being logged in to the local machine as - the local superuser root. -
Cautions -
The Authentication Server is possibly unable to create these files on some - operating systems that AFS otherwise supports, making the kdb - command inoperative. See the IBM AFS Release Notes for - details. -
Related Information -
kaserver -
kdb -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf014.htm diff -c openafs/doc/html/AdminReference/auarf014.htm:1.1 openafs/doc/html/AdminReference/auarf014.htm:removed *** openafs/doc/html/AdminReference/auarf014.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf014.htm Fri Jul 18 12:42:14 2008 *************** *** 1,57 **** - - -
Administration Reference
-
-
-
BackupLog
-Traces Backup Server operations -
Description -
The BackupLog file records a trace of Backup Server - (buserver process) operations on the local machine and describes - any error conditions it encounters. -
If the BackupLog file does not already exist in the - /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 - BackupLog.old, overwriting the existing - BackupLog.old file if it exists. -
The file is in ASCII format. Administrators listed in the - /usr/afs/etc/UserList file can use the 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 - cat command. By default, the mode bits on the - BackupLog file grant the required 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 - problems. -
Related Information -
UserList -
buserver -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf015.htm diff -c openafs/doc/html/AdminReference/auarf015.htm:1.1 openafs/doc/html/AdminReference/auarf015.htm:removed *** openafs/doc/html/AdminReference/auarf015.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf015.htm Fri Jul 18 12:42:14 2008 *************** *** 1,57 **** - - -
Administration Reference
-
-
-
BosLog
-Traces BOS Server operations -
Description -
The BosLog file records a trace of Basic OverSeer (BOS) Server - (bosserver process) operations on the local machine and describes - any error conditions it encounters. -
If the BosLog file does not already exist in the - /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 - BosLog.old, overwriting the existing - BosLog.old file if it exists. -
The file is in ASCII format. Administrators listed in the - /usr/afs/etc/UserList file can use the 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 - cat command. By default, the mode bits on the - BosLog file grant the required 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. -
Related Information -
UserList -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf016.htm diff -c openafs/doc/html/AdminReference/auarf016.htm:1.1 openafs/doc/html/AdminReference/auarf016.htm:removed *** openafs/doc/html/AdminReference/auarf016.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf016.htm Fri Jul 18 12:42:14 2008 *************** *** 1,179 **** - - -
Administration Reference
-
-
-
BosConfig
-Defines server processes for the BOS Server to monitor -
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 /usr/afs/local directory on each AFS - server machine. -
A server process entry in the BosConfig file records the - following information: -
-
-
- The entry type, which is one of the following:
-
-
-
-
-
- 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 - fs are simple (there are no standard cron processes). -
- fs - - - - -
- 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.
-
There is only one standard entry of this type, for which the conventional - name is fs. It combines three server processes: the - File Server (fileserver process), the Volume Server - (volserver process), and the Salvager (salvager - process). These processes all operate on the same data--the AFS - data stored on an AFS server machine's /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. -
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 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. -
- 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. -
- The entry name. The conventional name for an entry in the - BosConfig file and the associated process matches the binary - filename. When issuing any bos command that takes the - -instance argument, identify each process by the name used in the - BosConfig file. For a list of the names, see the bos - create reference page. -
- The process's 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 - 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 Run and NotRun instead. - Only a system administrator, not the BOS Server, can change the flag. - - -
- One or more command parameters which the BOS Server invokes to
- start the process or processes associated with the entry:
-
-
-
- A 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. -
- The fs entry has three command parameters, each the complete - pathname to the fileserver, volserver, and - salvager programs, in that order. -
- A simple entry has only one command parameter, the complete - pathname to the program. -
In addition to server process entries, the BosConfig file - specifies the times at which the BOS Server performs two types of automatic - process restarts: -
-
-
- The general restart time at which the BOS Server restarts itself - and then each process for which the entry in the BosConfig file has - status flag Run. The default setting is Sunday at 4:00 - a.m. -
- The binary restart time at which the BOS Server restarts any - server process for which the time stamp on the binary file in the - /usr/afs/bin directory is later than the last restart time for the - process. The default is 5:00 a.m. -
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 bos command suite: -
-
-
- The bos create command to create an entry in the file and start - the associated process -
- The bos delete command to remove an entry from the file after - the bos stop command is used to stop the associated process -
- The bos getrestart command to display the times at which the - BOS Server performs automatic restarts -
- The bos setrestart command to set the times at which the BOS - Server performs automatic process restarts -
- The bos start command to change an entry's status flag to - Run and start the associated process -
- The bos status command to display all processes listed in the - file -
- The bos stop command to change an entry's status flag to - NotRun and stop the associated process -
There are also bos commands that start and stop processes - without changing entries in the BosConfig file. The BOS - Server reads the 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 - BosConfig file. The following commands change a - process's status in the BOS Server's memory only: - - - -
-
-
- The bos restart command restarts a specified set of processes, - all processes, or all processes other than the BOS Server -
- The bos shutdown command stops a process -
- The bos startup command starts a process -
Related Information -
bos stop -
salvager -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf017.htm diff -c openafs/doc/html/AdminReference/auarf017.htm:1.1 openafs/doc/html/AdminReference/auarf017.htm:removed *** openafs/doc/html/AdminReference/auarf017.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf017.htm Fri Jul 18 12:42:14 2008 *************** *** 1,59 **** - - -
Administration Reference
-
-
-
CacheItems
-Records information about each Vn file in a disk cache -
Description -
The CacheItems file records information about each file in the - disk cache on a client machine (each Vn file). The - information includes the file ID number and associated volume version number - of the AFS file currently stored in the Vn file, which - enables the Cache Manager to determine which Vn file - contains the AFS data it needs to present to an application. -
As it initializes, the Cache Manager creates the binary-format - CacheItems file in the same local disk cache directory as the - Vn files that the CacheItems file describes, - and it must always remain there. The conventional directory name is - /usr/vice/cache, but it is acceptable to use a directory on a - partition with more available space. -
Cautions -
Editing or removing the CacheItems file can cause a kernel - panic. If the contents of Vn files seem out of - date, clear the files by using the fs flush or fs - flushvolume command. If the CacheItems file is - accidentally modified or deleted, rebooting the machine usually restores - normal performance. -
Related Information -
Vn -
afsd -
fs flush -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf018.htm diff -c openafs/doc/html/AdminReference/auarf018.htm:1.1 openafs/doc/html/AdminReference/auarf018.htm:removed *** openafs/doc/html/AdminReference/auarf018.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf018.htm Fri Jul 18 12:42:14 2008 *************** *** 1,565 **** - - -
Administration Reference
-
-
-
CFG_device_name
-Defines Tape Coordinator configuration instructions for automated tape - devices -
Description -
The CFG_device_name file includes instructions that - configure a Tape Coordinator for use with automated backup devices such as - tape stackers and jukeboxes, enable the Tape Coordinator to dump and restore - data to a 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 /usr/afs/backup directory on - the Tape Coordinator machine if it exists. -
The CFG_device_name file does not replace the - /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, device_name, as follows: -
-
-
- For a tape device, strip off the initial /dev/ string from the - device name, and replace any other slashes in the name with - underscores. For example, CFG_rmt_4m is the appropriate - filename for a device called /dev/rmt/4m. -
- For a backup data file, strip off the initial slash (/) and replace any - other slashes in the name with underscores. For example, - CFG_var_tmp_FILE is the appropriate filename for a backup data file - called /var/tmp/FILE. -
The CFG_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: -
-
-
- ASK -
- Controls whether the Tape Coordinator prompts for guidance when it - encounters error conditions -
- AUTOQUERY -
- Controls whether the Tape Coordinator prompts for the first tape -
- BUFFERSIZE -
- Sets the size of the memory buffer the Tape Coordinator uses when - transferring data -
- FILE -
- Controls whether the dump is written to a tape device or a file -
- MOUNT -
- Identifies the file that contains routines for inserting tapes into the - device's drive -
- NAME_CHECK -
- Controls whether the Tape Coordinator verifies that a tape's AFS tape - name matches the dump being written -
- UNMOUNT -
- Identifies the file that contains routines for removing tapes from the - device's drive -
The ASK Instruction -
The ASK instruction takes a boolean value as its argument, in - the following format: -
ASK {YES | NO}
-
-
- When the value is 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 ASK instruction - does not appear in the CFG_device_name file. -
When the value is 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 - TE_device_name file. Suppressing the prompts - enables the Tape Coordinator to run unattended, though it still prompts for - insertion of tapes unless the MOUNT instruction is used. -
The error cases controlled by this instruction are the following: -
-
-
- The Backup System is unable to dump a volume while running the backup - dump command. With a 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 NO value, the Tape - Coordinator omits the volume from the dump and continues the operation. -
- The Backup System is unable to restore a volume while running the - backup diskrestore, backup volrestore, or backup - volsetrestore command. With a 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 - NO value, it continues the operation without prompting, omitting - the problematic volume but restoring the remaining ones. -
- The Backup System cannot determine if the dump set includes any more - tapes, while running the backup scantape command (the reference - page for that command discusses possible reasons for this problem). - With a YES value, the Tape Coordinator prompts to ask if there are - more tapes to scan. With a NO value, it proceeds as though - there are more tapes and invokes the routine named by the MOUNT - instruction in the configuration file, or prompts the operator to insert the - next tape. -
- The Backup System determines that the tape contains an unexpired dump - while running the backup labeltape command. With a - YES value, the Tape Coordinator prompts to offer two choices: - continue or terminate the labeling operation. With a NO - value, it terminates the operation without relabeling the tape. -
The AUTOQUERY Instruction -
The AUTOQUERY instruction takes a boolean value as its argument, - in the following format: -
AUTOQUERY {YES | NO}
-
-
- When the value is YES, the Tape Coordinator checks for the - 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 - AUTOQUERY instruction does not appear in the configuration - file. -
When the value is 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 MOUNT routine unless there is - an error in accessing the first tape. This setting is equivalent in - effect to including the -noautoquery flag to the butc - command. -
Note that the setting of the 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 MOUNT instruction. It also refers to the - MOUNT instruction if it encounters an error while attempting to - access the first tape. - -
The BUFFERSIZE Instruction -
The 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 k or K to specify - kilobytes, m or M for megabytes, and g or - G for gigabytes. There is no space between the - sizevalue 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. - -
The FILE Instruction -
The FILE instruction takes a boolean value as its argument, in - the following format: -
FILE {NO | YES}
-
-
- When the value is 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 FILE - instruction does not appear in the configuration file. -
When the value is 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 - backup dump operation. -
When the value is 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 - /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 FILE instruction was set to - YES. (In the same way, if the FILE instruction is - set to NO, the tapeconfig entry must refer to an actual - tape device.) -
Rather than put an actual file pathname in the third field of the - tapeconfig file, however, the recommended configuration is to - create a symbolic link in the /dev directory that points to the - actual file pathname, and record the symbolic link in this field. This - configuration has a couple of advantages: -
-
-
- It makes the device_name portion of the - CFG_device_name, TE_device_name, and - TL_device_name names as short as possible. Because - the symbolic link is in the /dev directory as though it were a tape - device, the device configuration file's name is constructed by stripping - off the entire /dev/ prefix, instead of just the initial - slash. If, for example, the symbolic link is called - /dev/FILE, the device configuration file name is - CFG_FILE, whereas if the actual pathname /var/tmp/FILE - appears in the tapeconfig file, the file's name must be - CFG_var_tmp_FILE. -
- 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 MOUNT script, or to prompt the operator if the
- MOUNT instruction does not appear in the configuration file.
-
-
-
- If there is a 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. -
- If there is no 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. -
If the third field in the 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 - 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 backup dumpinfo command issued - with the -id option, the value in the 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. - -
The MOUNT Instruction -
The 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 the following Examples - section. 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 MOUNT instruction. If there is no - MOUNT instruction, the Tape Coordinator prompts the operator to - insert a tape before it attempts to open the tape device. If there is a - MOUNT instruction, the Tape Coordinator executes the routine in the - referenced file. The routine invoked by the MOUNT - instruction inherits the local identity (UNIX UID) and AFS tokens of the - butc command's issuer. -
There is an exception to this sequence: if the AUTOQUERY - NO instruction appears in the configuration file, or the - -noautoquery flag was included on the 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 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 - MOUNT instruction, it passes the following parameters to the - routine in the indicated order: -
-
-
- The tape device or backup data file's pathname, as recorded in the - /usr/afs/backup/tapeconfig file. -
- The tape operation, which (except for the exceptions noted in the
- following list) matches the backup command operation code used to
- initiate the operation:
-
-
-
- appenddump (when a backup dump command includes the - -append flag) -
- dump (when a backup dump command does not include - the -append flag) -
- labeltape -
- readlabel -
- restore (for a backup diskrestore, backup - volrestore, or backup volsetrestore command) -
- restoredb -
- savedb -
- scantape -
- 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 - MOUNT instruction. -
- The tape name. For some operations, the Tape Coordinator passes the - string none, because it does not know the tape name (when running - the backup scantape or backup readlabel, for example), - or because the tape does not necessarily have a name (when running the - backup labeltape command, for example). -
- The tape ID recorded in the Backup Database. As with the tape name, - the Backup System passes the string none for operations where it - does not know the tape ID or the tape does not necessarily have an ID. -
The routine invoked by the MOUNT instruction must return an exit - code to the Tape Coordinator: -
-
-
- Code 0 (zero) indicates that the routine successfully mounted - the tape. The Tape Coordinator continues the backup operation. - If the routine invoked by the MOUNT instruction does not return - this exit code, the Tape Coordinator never calls the UNMOUNT - instruction. -
- Code 1 (one) indicates that the routine failed to mount the - tape. The Tape Coordinator terminates the operation. -
- 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. -
If the backup command was issued in interactive mode and the - operator issues the (backup) kill command while the - MOUNT routine is running, the Tape Coordinator passes the - termination signal to the routine; the entire operation - terminates. - -
The NAME_CHECK Instruction -
The NAME_CHECK instruction takes a boolean value as its - argument, in the following format: -
NAME_CHECK {YES | NO}
-
-
- When the value is 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 backup dump command. The AFS tape name must - be <NULL> or match the tape name that the backup dump - operation assigns based on the volume set and dump level names. This is - the default behavior if the NAME_CHECK instruction does not appear - in the configuration file. -
When the value is 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. - -
The UNMOUNT Instruction -
The 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 the following Examples - section. 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 UNMOUNT instruction, whether or not the - close operation succeeds. If there is no 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 UNMOUNT - instruction, the Tape Coordinator executes the referenced file. It - invokes the routine only once, passing in the following parameters: -
-
-
- The tape device pathname (as specified in the - /usr/afs/backup/tapeconfig file) -
- The tape operation (always unmount) -
Privilege Required -
The file is protected by UNIX mode bits. Creating the file requires - the w (write) and x (execute) - permissions on the /usr/afs/backup directory. Editing the - file requires the w (write) permission on the - file. -
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. -
Example CFG_device_name File for - Stackers -
In this example, the administrator creates the following entry for a tape - stacker called stacker0.1 in the - /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 - /usr/afs/backup/CFG_stacker0.1 file. To review the - meaning of each instruction, see the preceding Description - section. -
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 - /usr/afs/backup/stacker0.1 file referenced by the - MOUNT and UNMOUNT instructions in the - 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: tries and operation. It follows the - recommended practice of prompting for a tape if the value of the - tries parameter exceeds one, because that implies that the stacker - is out of tapes. -
For a backup dump or backup savedb operation, the - routine calls the example 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). -
Example CFG_device_name File for Dumping to a - Backup Data File -
In this example, the administrator creates the following entry for a backup - data file called HSM_device in the - /usr/afs/backup/tapeconfig file. It has port offset - 20. -
1G 0K /dev/HSM_device 20 - --
The administrator includes the following lines in the - /usr/afs/backup/CFG_HSM_device file. To review the meaning - of each instruction, see the preceding Description section. -
MOUNT /usr/afs/backup/file - FILE YES - ASK NO - --
Finally, the administrator writes the following executable routine in the - /usr/afs/backup/file file referenced by the MOUNT - instruction in the 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 - tries and operation parameters passed to it by the - Backup System. The 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 (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 - 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 backup dump, backup restore, - backup savedb, or backup restoredb operation, the - routine invokes the UNIX ln -s command to create a symbolic link - from the backup data file named in the tapeconfig file to the - actual file to use (this is the recommended method). It uses the value - of the tapename and tapeid parameters to construct the - file name. -
Related Information -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf019.htm diff -c openafs/doc/html/AdminReference/auarf019.htm:1.1 openafs/doc/html/AdminReference/auarf019.htm:removed *** openafs/doc/html/AdminReference/auarf019.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf019.htm Fri Jul 18 12:42:14 2008 *************** *** 1,120 **** - - -
Administration Reference
-
-
-
CellServDB (client version)
-Lists the database server machines in all cells accessible from the machine -
Description -
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 kaserver, buserver, - ptserver, and 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: -
-
-
- Fetching files. The Cache Manager contacts the VL Server to learn - the location of the volume containing a requested file or directory. -
- Authenticating users. Client-side authentication programs (such as - an AFS-modified login utility or the 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. -
- Creating protection groups. The pts command interpreter - contacts the Protection Server when users create protection groups or request - information from the Protection Database. -
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 fs newcell command. -
The CellServDB file is in ASCII format and must reside in the - /usr/vice/etc directory on each AFS client machine. Use a - text editor to create and maintain it. Each cell's entry must have - the following format: -
-
-
- The first line begins at the left margin with the greater-than character - (>), followed immediately by the cell's name without an - intervening space. Optionally, a comment can follow any number of - spaces and a number sign (#), perhaps to identify the organization - associated with the cell. -
- Each subsequent line in the entry identifies one of the cell's
- database server machines, with the indicated information in order:
-
-
-
- The database server machine's IP address in dotted-decimal - format. -
- One or more spaces. -
- 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. -
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. -
The AFS Product Support group 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 the AFS - Product Support group for inclusion in this file. The file conforms to - the required CellServDB format, and so is a suitable basis for the - CellServDB file on a client machine. Contact the AFS Product - Support group for directions on accessing the file. -
The client version of the CellServDB file is distinct from the - server version, which resides in the /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. -
Examples -
The following example shows entries for two cells in a client - 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 - --
Related Information -
klog -
-
- -
-
© IBM Corporation 2000. All Rights Reserved - - - - --- 0 ---- Index: openafs/doc/html/AdminReference/auarf020.htm diff -c openafs/doc/html/AdminReference/auarf020.htm:1.1 openafs/doc/html/AdminReference/auarf020.htm:removed *** openafs/doc/html/AdminReference/auarf020.htm:1.1 Wed Jun 6 14:09:11 2001 --- openafs/doc/html/AdminReference/auarf020.htm Fri Jul 18 12:42:14 2008 *************** *** 1,91 **** - - -